feat(ultraplan-local): add lib/parsers/finding-id.mjs (stable SHA1)

plugins/ultraplan-local/lib/parsers/finding-id.mjs

@@ -0,0 +1,54 @@
+// lib/parsers/finding-id.mjs
+// Stable finding-ID for /ultrareview-local v1.0.
+//
+// id = sha1(file:line:rule_key) → 40-char hex.
+// Same input always produces same output (determinism floor SC4).
+// node:crypto is built-in (zero-deps invariant).
+
+import { createHash } from 'node:crypto';
+
+const HEX_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * Compute a stable 40-char hex finding-ID.
+ * @param {string} filePath — relative path (caller normalizes if needed)
+ * @param {number|string} line — 1-based line number; coerced to string
+ * @param {string} ruleKey — must be a non-empty string from RULE_KEYS
+ * @returns {string} 40-char lowercase hex
+ * @throws {TypeError} on bad input
+ */
+export function computeFindingId(filePath, line, ruleKey) {
+  if (typeof filePath !== 'string' || filePath.length === 0) {
+    throw new TypeError('computeFindingId: filePath must be a non-empty string');
+  }
+  if (line === null || line === undefined) {
+    throw new TypeError('computeFindingId: line must be a number or numeric string');
+  }
+  if (typeof line === 'number') {
+    if (!Number.isFinite(line)) {
+      throw new TypeError('computeFindingId: line must be finite');
+    }
+  } else if (typeof line === 'string') {
+    if (line.length === 0) {
+      throw new TypeError('computeFindingId: line must not be empty string');
+    }
+  } else {
+    throw new TypeError('computeFindingId: line must be a number or numeric string');
+  }
+  if (typeof ruleKey !== 'string' || ruleKey.length === 0) {
+    throw new TypeError('computeFindingId: ruleKey must be a non-empty string');
+  }
+
+  const composite = `${filePath}:${line}:${ruleKey}`;
+  return createHash('sha1').update(composite).digest('hex');
+}
+
+/**
+ * Validate a finding-ID's shape (40-char lowercase hex).
+ * @param {string} id
+ * @returns {{valid: boolean}}
+ */
+export function parseFindingId(id) {
+  if (typeof id !== 'string') return { valid: false };
+  return { valid: HEX_RE.test(id) };
+}