// lib/parsers/finding-id.mjs
// Stable finding-ID for /trekreview v1.0.
//
// id = sha1(file:line:rule_key) → 40-char hex; a second finding on the same
// triplet gets it over `rule_key#2` (computeFindingIds).
// 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');
}

/**
 * The ids of a list of findings, in order. The first finding on a
 * (file, line, rule_key) gets computeFindingId of it, as always; the k-th
 * (k >= 2) gets it over `${rule_key}#k`, the form critic-diff.mjs already uses,
 * so two different findings one reviewer put on one triplet keep a row each
 * (voyage-lekerepo trial 5, finding 7).
 * @param {Array<{file: string, line: number|string, rule_key: string}>} findings
 * @param {(index: number, error: Error) => void} [onError] - when given, a
 *   finding whose id cannot be computed gets null and is reported here;
 *   without it the TypeError is thrown
 * @returns {Array<string|null>} one id per finding
 */
export function computeFindingIds(findings, onError) {
  const seen = new Map();
  return findings.map((f, i) => {
    const key = `${f?.file}:${f?.line}:${f?.rule_key}`;
    const k = (seen.get(key) ?? 0) + 1;
    seen.set(key, k);
    try {
      // A missing rule_key must still throw, never become "undefined#2".
      const ruleKey = k === 1 || typeof f?.rule_key !== 'string' || f.rule_key === '' ? f?.rule_key : `${f.rule_key}#${k}`;
      return computeFindingId(f?.file, f?.line, ruleKey);
    } catch (e) {
      if (!onError) throw e;
      onError(i, e);
      return null;
    }
  });
}

/**
 * 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) };
}