ktg-plugin-marketplace/plugins/ultraplan-local/lib/parsers/finding-id.mjs

// lib/parsers/finding-id.mjs
// Stable finding-ID for /trekreview 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) };
}