// lib/review/rule-catalogue.mjs
// Canonical rule catalogue for /trekreview v1.0.
//
// 12 rule keys, 4-tier severity (matches brief contract).
// llm-security 5-tier alignment is a v1.1 candidate.

export const SEVERITY_VALUES = Object.freeze(['BLOCKER', 'MAJOR', 'MINOR', 'SUGGESTION']);

export const CATEGORY_VALUES = Object.freeze([
  'conformance',
  'correctness',
  'scope',
  'tests',
  'security',
  'maintenance',
]);

export const RULE_CATALOGUE = Object.freeze([
  Object.freeze({
    rule_key: 'MISSING_BRIEF_REF',
    severity: 'MAJOR',
    category: 'conformance',
    description: 'Finding lacks brief_ref pointing to the brief section it traces back to.',
  }),
  Object.freeze({
    rule_key: 'UNIMPLEMENTED_CRITERION',
    severity: 'BLOCKER',
    category: 'conformance',
    description: 'A brief Success Criterion has no corresponding implementation in the delivered code.',
  }),
  Object.freeze({
    rule_key: 'SCOPE_CREEP_BUILT',
    severity: 'MAJOR',
    category: 'scope',
    description: 'Code implements features beyond what the brief requested.',
  }),
  Object.freeze({
    rule_key: 'NON_GOAL_VIOLATED',
    severity: 'BLOCKER',
    category: 'scope',
    description: 'Code implements something the brief explicitly listed as a Non-Goal.',
  }),
  Object.freeze({
    rule_key: 'MISSING_TEST',
    severity: 'MAJOR',
    category: 'tests',
    description: 'Delivered behavior has no automated test coverage.',
  }),
  Object.freeze({
    rule_key: 'SECURITY_INJECTION',
    severity: 'BLOCKER',
    category: 'security',
    description: 'Code path constructs commands, queries, or templates from untrusted input without sanitization.',
  }),
  Object.freeze({
    rule_key: 'PLACEHOLDER_IN_CODE',
    severity: 'MAJOR',
    category: 'maintenance',
    description: 'Committed code contains TBD/TODO/FIXME/XXX/console.log/debugger placeholders.',
  }),
  Object.freeze({
    rule_key: 'MISSING_ERROR_HANDLING',
    severity: 'MINOR',
    category: 'correctness',
    description: 'Code path can fail silently (uncaught promise, unchecked return, missing try/catch on I/O).',
  }),
  Object.freeze({
    rule_key: 'UNDECLARED_DEPENDENCY',
    severity: 'MAJOR',
    category: 'maintenance',
    description: 'Code imports or invokes something not declared in package.json / not bundled / not present in PATH.',
  }),
  Object.freeze({
    rule_key: 'PLAN_EXECUTE_DRIFT',
    severity: 'MAJOR',
    category: 'conformance',
    description: 'Delivered code diverges from what the plan said would be built (different file, different approach, different API).',
  }),
  Object.freeze({
    rule_key: 'BROKEN_SUCCESS_CRITERION',
    severity: 'BLOCKER',
    category: 'conformance',
    description: 'A brief Success Criterion is implemented but the verification command/test fails or is structurally incorrect.',
  }),
  Object.freeze({
    rule_key: 'COVERAGE_SILENT_SKIP',
    severity: 'MAJOR',
    category: 'tests',
    description: 'Triage gate skipped a file without recording it in the Coverage section of review.md (hidden truncation).',
  }),
]);

export const RULE_KEYS = Object.freeze(new Set(RULE_CATALOGUE.map((r) => r.rule_key)));

/**
 * Look up a rule entry by its key.
 * @param {string} key
 * @returns {object|null} the frozen entry, or null if not found
 */
export function getRule(key) {
  if (typeof key !== 'string') return null;
  for (const entry of RULE_CATALOGUE) {
    if (entry.rule_key === key) return entry;
  }
  return null;
}