@lifeaitools/rdc-skills 0.34.0 → 0.35.0

package/scripts/lib/clean-code-scoring.mjs

@@ -0,0 +1,258 @@
+/**
+ * Clean Code scoring — pure functions over a `NormalizedUnit`
+ * (see language-plugin.mjs), same discipline as solid-scoring.mjs: no
+ * ts-morph, no language-specific parser. Every fact these rules read was
+ * computed once, in `lib/plugins/typescript.mjs`, from the real AST.
+ *
+ * Detection logic (thresholds, patterns, what counts as a violation) is
+ * ported/adapted from architecture-toolkit's REAL implementation —
+ * github.com/OnSightTeam/architecture-toolkit (MIT), specifically
+ * `src/agents/clean-code-analyzer/tools/{naming,function,code-smell}-validator.ts`
+ * — reuse of their real detection logic explicitly approved by the operator
+ * mid-task, 2026-08-20. Their checks run whole-file text regexes with an
+ * occurrence-count threshold to suppress false positives (e.g. "flag only if
+ * more than 3 single-letter assignments appear"); ours walks the real AST
+ * per declared binding, so context is known directly (a for-loop counter vs.
+ * a badly-named field, a magic number vs. a named const) and no threshold is
+ * needed to separate signal from regex noise — every real occurrence is its
+ * own finding. Each rule function below cites the specific architecture-
+ * toolkit file:line it corroborates or adapts.
+ *
+ * Rules NOT implemented here (N3, N5, N6, C1-C5, G5, G14, G16, G28) are
+ * intentionally absent — see skills/clean-code-analyzer/SKILL.md for why
+ * each one stays a dispatched-judgment call instead of a fake mechanical
+ * check.
+ */
+
+export const NOT_IMPLEMENTED = ['N3', 'N5', 'N6', 'C1', 'C2', 'C3', 'C4', 'C5', 'G5', 'G14', 'G16', 'G28'];
+
+function loc(unit, memberName, line) {
+  return line === undefined ? `${unit.name}#${memberName}` : `${unit.name}#${memberName}:${line}`;
+}
+
+// ── N1 — single-letter / cryptic variable names ────────────────────────────
+// architecture-toolkit's real check: naming-validator.ts:46-47 flags
+// single-letter assignments (`\b[a-z]\s*=`) once there are MORE THAN 3 in
+// the whole file, and naming-validator.ts:63-64 does the same for two-letter
+// names at a threshold of 5 — both exist only to suppress the regex's own
+// false-positive rate (any `x = 5` matches, including inside strings). Our
+// AST version reads the real declared-binding name directly, so every
+// genuine one-or-two-letter local (outside the loop-counter/well-known
+// exceptions the task specifies) is reported on its own — no threshold.
+const LOOP_COUNTER_WHITELIST = new Set(['i', 'j', 'k']);
+const SHORT_NAME_WHITELIST = new Set(['fn', 'cb', 'ok', 'id', 'db', 'ui', 'io']);
+
+export function n1CrypticNames(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    for (const d of m.declaredNames ?? []) {
+      if (d.name.length === 1 && !LOOP_COUNTER_WHITELIST.has(d.name)) {
+        findings.push({ location: loc(unit, m.name, d.line), detail: `single-letter name '${d.name}' (not a conventional loop counter)` });
+      } else if (d.name.length === 2 && !SHORT_NAME_WHITELIST.has(d.name.toLowerCase())) {
+        findings.push({ location: loc(unit, m.name, d.line), detail: `cryptic two-letter name '${d.name}'` });
+      }
+    }
+  }
+  return { ruleId: 'N1', findings, confidence: 'high' };
+}
+
+// ── N2 — meaningless distinctions (heuristic, low confidence) ─────────────
+// architecture-toolkit's real check at naming-validator.ts:98-99 flags
+// number-suffixed names (`\w+\d+\s*=`, e.g. name1/name2) at a >2 occurrence
+// threshold — that pattern (data1/data2) is adapted directly, per-occurrence,
+// no threshold. Its co-located data/info regex (naming-validator.ts:82) is
+// whole-file text co-occurrence and doesn't translate to a per-binding AST
+// check, so it's replaced here with a small noise-word set applied to the
+// SAME declared-binding facts N1 uses.
+const NOISE_WORDS = new Set(['data', 'info', 'temp', 'tmp', 'foo', 'bar', 'val', 'obj', 'thing']);
+const NUMERIC_SUFFIX_RE = /^[A-Za-z_$][A-Za-z0-9_$]*[0-9]+$/;
+
+export function n2MeaninglessNames(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    for (const d of m.declaredNames ?? []) {
+      if (NOISE_WORDS.has(d.name.toLowerCase())) {
+        findings.push({ location: loc(unit, m.name, d.line), detail: `heuristic: noise-word name '${d.name}' carries no distinguishing meaning` });
+      } else if (NUMERIC_SUFFIX_RE.test(d.name)) {
+        findings.push({ location: loc(unit, m.name, d.line), detail: `heuristic: numeric-suffix name '${d.name}' (data1/data2 pattern) — name by role, not sequence` });
+      }
+    }
+  }
+  return { ruleId: 'N2', findings, confidence: 'low' };
+}
+
+// ── N4 — magic numbers ─────────────────────────────────────────────────────
+// architecture-toolkit's real check (naming-validator.ts:139, `\b\d{2,}\b`
+// at a >3-occurrence threshold) is whole-file text and blind to declaration
+// context — it cannot tell a bare `86400` from a `const DAY_MS = 86400`.
+// Our AST version reads `magicNumbers` computed in typescript.mjs, which
+// already excludes 0/1/-1 and any literal that IS the direct initializer of
+// a `const` or an enum member — the exact context distinction a regex can't
+// make. Findings are the raw fact list; this function just packages them.
+export function n4MagicNumbers(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    for (const n of m.magicNumbers ?? []) {
+      findings.push({ location: loc(unit, m.name, n.line), detail: `magic number ${n.value} used outside a const/enum declaration` });
+    }
+  }
+  return { ruleId: 'N4', findings, confidence: 'high' };
+}
+
+// ── N7 — generic class/function names ──────────────────────────────────────
+// architecture-toolkit's real check at naming-validator.ts:219
+// (`/class\s+(Manager|Processor|Data|Info)\b/`) matches only the WHOLE class
+// name, prefix position, and only 4 words. Our task spec's word list is
+// {Manager, Handler, Processor, Helper, Util} and explicitly wants the SOLE
+// SUFFIX form too (e.g. `UserDataManager`), so this extends their mechanism
+// (name-against-known-set) rather than reusing the regex verbatim.
+const GENERIC_NAME_WORDS = ['Manager', 'Handler', 'Processor', 'Helper', 'Util'];
+function isGenericName(name) {
+  return GENERIC_NAME_WORDS.some((w) => name === w || name.endsWith(w));
+}
+
+export function n7GenericNames(unit) {
+  const findings = [];
+  if (unit.kind === 'class' && isGenericName(unit.name)) {
+    findings.push({ location: unit.name, detail: `generic class name '${unit.name}' (whole name or sole suffix is a generic word)` });
+  }
+  for (const m of unit.members) {
+    if (isGenericName(m.name)) {
+      findings.push({ location: loc(unit, m.name), detail: `generic function/method name '${m.name}' (whole name or sole suffix is a generic word)` });
+    }
+  }
+  return { ruleId: 'N7', findings, confidence: 'high' };
+}
+
+// ── F1 — long methods (over 20 statements) ─────────────────────────────────
+// Corroborated, not just copied: architecture-toolkit's real threshold at
+// function-validator.ts:52 (`if (avgLinesPerFunction > 20)`) independently
+// lands on the SAME number our task spec names, for lines-per-function
+// rather than statement count. Their metric is an average over the whole
+// file (blind to which specific function is long); ours is per-member and
+// counts real statement nodes (flattened across nesting), so a 21-statement
+// method is named directly instead of averaged away by short neighbors.
+export function f1LongMethods(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    if ((m.statementCount ?? 0) > 20) {
+      findings.push({ location: loc(unit, m.name), detail: `${m.statementCount} statements (over 20)` });
+    }
+  }
+  return { ruleId: 'F1', findings, confidence: 'high' };
+}
+
+// ── F2 — too many parameters (over 3) ──────────────────────────────────────
+// Exact match to architecture-toolkit's real threshold at
+// function-validator.ts:82 (`if (paramCount > 3)`). `paramCount` is already
+// part of the base NormalizedMember contract (solid-scoring.mjs's ISP reads
+// the same field) — no new fact needed here.
+export function f2TooManyParams(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    if (m.paramCount > 3) {
+      findings.push({ location: loc(unit, m.name), detail: `${m.paramCount} parameters (over 3)` });
+    }
+  }
+  return { ruleId: 'F2', findings, confidence: 'high' };
+}
+
+// ── E1 — empty catch blocks ─────────────────────────────────────────────────
+// Exact match to architecture-toolkit's real pattern at
+// code-smell-validator.ts:160 (`/catch\s*\([^)]+\)\s*{\s*}/i`). AST form is
+// strictly stronger: a comment-only catch block (`catch(e) { /* ignore */ }`)
+// is exactly as silent as a truly empty one but does NOT match their regex
+// (comment text isn't whitespace); the AST's statement count is 0 either way.
+export function e1EmptyCatchBlocks(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    for (const c of m.emptyCatches ?? []) {
+      findings.push({ location: loc(unit, m.name, c.line), detail: 'empty catch block — exception swallowed silently' });
+    }
+  }
+  return { ruleId: 'E1', findings, confidence: 'high' };
+}
+
+// ── E2 — unguarded risky operations (missing try/catch) ────────────────────
+// New rule, not ported from architecture-toolkit -- confirmed no E2/E3/E4
+// exist in their source or in this repo's own clean-code-analyzer/SKILL.md
+// "not implemented" table before adding this (this file's own header
+// requires that check before claiming coverage). Built to close ATF's
+// R3 "error-handling coverage" gap (LADDER-ARCHITECTURE.md, 2026-08-22) --
+// E1 already caught the swallowed-exception half; this catches the OTHER
+// real defect in the same chapter, an operation with no error handling at
+// all. Conservative on purpose: `await` and a small named list of
+// known-throwing sync calls, not every function call.
+export function e2UnguardedRiskyOps(unit) {
+  const findings = [];
+  for (const m of unit.members) {
+    for (const op of m.unguardedRiskyOps ?? []) {
+      findings.push({ location: loc(unit, m.name, op.line), detail: `unguarded ${op.kind} — no enclosing try/catch` });
+    }
+  }
+  return { ruleId: 'E2', findings, confidence: 'high' };
+}
+
+// ── G9 — dead code (two independent halves) ────────────────────────────────
+// architecture-toolkit's ACTUAL G9 (code-smell-validator.ts:115,
+// `/if\s*\(\s*false\s*\)|if\s*\(\s*true\s*\)/`) is constant-conditional
+// UNREACHABLE code — a different sub-smell than the unused-EXPORT dead code
+// this repo's own clean-code-analyzer/SKILL.md already specced under the
+// same G9 id. Both are legitimate readings of Clean Code's G9 "Dead Code"
+// chapter, so this ships BOTH:
+//   - unreachable half: `deadConditionals` (if(true)/if(false)/while(false)),
+//     computed per-member in typescript.mjs, always measured.
+//   - unused-export half: `deadExportsFacts`, computed by the OPTIONAL
+//     plugin.deadExportsOf(filePath, projectFilePaths) — a REAL cross-file
+//     reference-graph walk (ts-morph findReferencesAsNodes), not a text grep.
+//     Pass `[]` (the default) when that scan hasn't been run; this function
+//     never treats "wasn't scanned" as "found nothing" — confidence drops to
+//     'medium' and says so, rather than silently reporting zero findings for
+//     unmeasured evidence.
+//
+// POSITIVE CONTROL is the caller's responsibility (see
+// scripts/clean-code-score.mjs): before trusting any `referenceCount === 0`
+// finding from a `deadExportsOf` scan, confirm a KNOWN-used export in the
+// same scan comes back non-zero. A scan that returns zero for everything is
+// broken, not a clean project.
+export function g9DeadCode(unit, deadExportsFacts = []) {
+  const findings = [];
+  for (const m of unit.members) {
+    for (const dc of m.deadConditionals ?? []) {
+      findings.push({ location: loc(unit, m.name, dc.line), detail: `unreachable code — constant-conditional '${dc.kind}' never takes the live branch` });
+    }
+  }
+  for (const f of deadExportsFacts) {
+    if (f.referenceCount === 0) {
+      findings.push({ location: loc(unit, f.name, f.line), detail: `exported '${f.name}' has zero reference sites anywhere in the scanned project — dead export` });
+    }
+    // referenceCount === -1 ("declaration kind unsupported by the reference
+    // finder") is deliberately NOT reported as a finding — see DeadExportFact
+    // in language-plugin.mjs. It is neither used nor unused; it is unmeasured.
+  }
+  return { ruleId: 'G9', findings, confidence: deadExportsFacts.length ? 'high' : 'medium' };
+}
+
+/**
+ * @param {import('./language-plugin.mjs').NormalizedUnit} unit
+ * @param {import('./language-plugin.mjs').DeadExportFact[]|null} deadExportsFacts
+ *   Pass the result of `plugin.deadExportsOf(filePath, projectFilePaths)` when
+ *   available; omit (or pass `null`) to score everything except G9's
+ *   unused-export half, which then reports at 'medium' confidence using only
+ *   its unreachable-code half.
+ */
+export function cleanCodeScore(unit, deadExportsFacts = null) {
+  const rules = {
+    n1: n1CrypticNames(unit),
+    n2: n2MeaninglessNames(unit),
+    n4: n4MagicNumbers(unit),
+    n7: n7GenericNames(unit),
+    f1: f1LongMethods(unit),
+    f2: f2TooManyParams(unit),
+    e1: e1EmptyCatchBlocks(unit),
+    e2: e2UnguardedRiskyOps(unit),
+    g9: g9DeadCode(unit, deadExportsFacts ?? []),
+  };
+  const totalFindings = Object.values(rules).reduce((n, r) => n + r.findings.length, 0);
+  return { unit: unit.name, kind: unit.kind, rules, totalFindings, notImplemented: NOT_IMPLEMENTED };
+}

package/scripts/lib/duplication-scoring.mjs

@@ -0,0 +1,238 @@
+/**
+ * G5 — Duplicate Code detection via token-shingle Rabin-Karp matching.
+ *
+ * This is the rule the original Clean Code port (2026-08-20, commit e159ada)
+ * incorrectly filed as "needs judgment, not mechanical" — see
+ * clean-code-scoring.mjs's own header, and skills/clean-code-analyzer/SKILL.md's
+ * "Not implemented" table, row G5: "a per-unit, per-file scorer is the wrong
+ * shape for a cross-file structural-clone problem." That reasoning is correct
+ * about WHY clean-code-scoring.mjs's per-unit shape can't do this — it is
+ * wrong that the problem itself needs judgment. It has a well-established
+ * deterministic solution: token-based clone detection via Rabin-Karp rolling
+ * hash, the same algorithm jscpd (github.com/kucherenko/jscpd) and PMD's CPD
+ * (pmd.github.io/pmd/pmd_userdocs_cpd.html) both use in production, 20+ years
+ * of prior art. This file is a real, independent implementation of that
+ * algorithm — not a wrapper around either tool — operating at REPO scope
+ * (across every file passed in), not per-file, which is why it lives here as
+ * its own module rather than as an eighth rule inside clean-code-scoring.mjs's
+ * per-unit contract.
+ *
+ * No ts-morph, no NormalizedUnit dependency — plain text tokenization, same
+ * discipline as package-metrics.mjs and architecture-scoring.mjs. Works on
+ * any language whose comments/whitespace can be stripped by a language-aware
+ * comment-stripping table (below); token SHAPE (identifiers, literals,
+ * operators) is language-agnostic once comments are stripped.
+ */
+
+import { readFileSync } from 'node:fs';
+
+/** Comment-stripping regexes, keyed by extension. Line + block comments only —
+ *  string/template literals are deliberately NOT stripped, since a literal's
+ *  content is real duplicated text if it repeats. */
+const COMMENT_STRIP = {
+  '.js': [/\/\/.*$/gm, /\/\*[\s\S]*?\*\//g],
+  '.mjs': [/\/\/.*$/gm, /\/\*[\s\S]*?\*\//g],
+  '.cjs': [/\/\/.*$/gm, /\/\*[\s\S]*?\*\//g],
+  '.ts': [/\/\/.*$/gm, /\/\*[\s\S]*?\*\//g],
+  '.tsx': [/\/\/.*$/gm, /\/\*[\s\S]*?\*\//g],
+  '.jsx': [/\/\/.*$/gm, /\/\*[\s\S]*?\*\//g],
+  '.py': [/#.*$/gm],
+};
+
+/** Token pattern: identifiers/keywords, numbers, string literals (as one
+ *  opaque token — content ignored, only "a string literal was here" matters,
+ *  matching CPD's own "ignore literals" default OFF-by-default behavior; we
+ *  keep literal content since a repeated literal string IS real duplication),
+ *  and single-char operators/punctuation. */
+const TOKEN_RE = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`|[A-Za-z_$][A-Za-z0-9_$]*|\d+(?:\.\d+)?|[{}()[\];,.<>=+\-*/%!&|^~?:]/g;
+
+/**
+ * Tokenize one file's text into {token, line}[] — comments stripped, string
+ * literals collapsed to their raw text (not a placeholder — real content
+ * still counts as duplication if it repeats), whitespace/newlines used only
+ * to track line numbers, not as tokens themselves.
+ */
+export function tokenizeSource(text, ext) {
+  const strips = COMMENT_STRIP[ext] || [];
+  let stripped = text;
+  for (const re of strips) stripped = stripped.replace(re, (m) => m.replace(/[^\n]/g, ' '));
+
+  const tokens = [];
+  let line = 1;
+  let lastIndex = 0;
+  TOKEN_RE.lastIndex = 0;
+  let match;
+  while ((match = TOKEN_RE.exec(stripped)) !== null) {
+    // count newlines between lastIndex and match.index to keep line tracking accurate
+    for (let i = lastIndex; i < match.index; i++) if (stripped[i] === '\n') line++;
+    lastIndex = match.index;
+    tokens.push({ token: match[0], line });
+  }
+  return tokens;
+}
+
+/**
+ * Rabin-Karp rolling hash over a token-shingle window of length k.
+ * Base/modulus chosen to keep hashes in safe-integer range for k up to ~200.
+ */
+const BASE = 257n;
+const MOD = 1_000_000_007n;
+
+function hashWindow(tokens, start, k) {
+  let h = 0n;
+  for (let i = 0; i < k; i++) {
+    h = (h * BASE + BigInt(simpleStringHash(tokens[start + i].token))) % MOD;
+  }
+  return h.toString();
+}
+
+function simpleStringHash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (h * 31 + s.charCodeAt(i)) >>> 0;
+  return h;
+}
+
+/**
+ * Rolling update: given the hash of window [start, start+k), compute the
+ * hash of window [start+1, start+1+k) in O(1) using the outgoing/incoming
+ * token — the actual Rabin-Karp technique (not re-hashing the whole window
+ * each slide, which would make this O(n*k) instead of O(n)).
+ */
+function rollHash(prevHash, outgoingTok, incomingTok, k) {
+  const highOrder = powMod(BASE, BigInt(k - 1));
+  let h = (prevHash - BigInt(simpleStringHash(outgoingTok)) * highOrder % MOD + MOD * MOD) % MOD;
+  h = (h * BASE + BigInt(simpleStringHash(incomingTok))) % MOD;
+  return h;
+}
+
+function powMod(base, exp) {
+  let r = 1n, b = base % MOD, e = exp;
+  while (e > 0n) {
+    if (e & 1n) r = (r * b) % MOD;
+    b = (b * b) % MOD;
+    e >>= 1n;
+  }
+  return r;
+}
+
+/**
+ * Find duplicate token-shingle windows of length >= minTokens across all
+ * supplied files. Matches jscpd/CPD's default shape: a "duplicate" is
+ * >= minTokens contiguous matching tokens appearing in 2+ distinct
+ * (file, position) locations, with overlapping windows from the SAME
+ * location merged into one finding rather than reported once per slide.
+ *
+ * @param {{file: string, text: string, ext: string}[]} files
+ * @param {number} minTokens - default 50, matches CPD's default token threshold
+ * @returns {{duplicates: Array<{tokenCount: number, occurrences: Array<{file:string, startLine:number, endLine:number}>}>}}
+ */
+export function findDuplicates(files, minTokens = 50) {
+  const fileTokens = files.map((f) => ({
+    file: f.file,
+    tokens: tokenizeSource(f.text, f.ext),
+  })).filter((f) => f.tokens.length >= minTokens);
+
+  // hash -> [{fileIdx, start}]
+  const hashIndex = new Map();
+
+  for (let fi = 0; fi < fileTokens.length; fi++) {
+    const { tokens } = fileTokens[fi];
+    if (tokens.length < minTokens) continue;
+    let h = hashWindow(tokens, 0, minTokens);
+    recordHash(hashIndex, h, fi, 0);
+    for (let start = 1; start <= tokens.length - minTokens; start++) {
+      h = rollHash(BigInt(h), tokens[start - 1].token, tokens[start + minTokens - 1].token, minTokens).toString();
+      recordHash(hashIndex, h, fi, start);
+    }
+  }
+
+  // Every hash bucket with >=2 occurrences is a matching WINDOW pair, not a
+  // duplicate BLOCK yet — a real duplicated region of length L > minTokens
+  // produces (L - minTokens + 1) consecutive matching window-pairs, one per
+  // slide position, all at the SAME offset between the two locations. The
+  // real algorithm (same technique CPD/jscpd use) is to pair up occurrences,
+  // group pairs by (fileA, fileB, start diff constant), then merge
+  // consecutive starts within each group into ONE maximal match — that
+  // collapses N sliding-window hits into 1 real finding.
+  //
+  // pairKey -> { fileA, fileB, starts: Set<number> } where starts holds the
+  // fileA-side start of every matching window against a fixed fileB anchor
+  // at the SAME relative offset.
+  const pairGroups = new Map();
+  for (const [, occ] of hashIndex) {
+    if (occ.length < 2) continue;
+    const sorted = occ.slice().sort((a, b) => a.fileIdx - b.fileIdx || a.start - b.start);
+    for (let i = 0; i < sorted.length; i++) {
+      for (let j = i + 1; j < sorted.length; j++) {
+        const a = sorted[i], b = sorted[j];
+        if (a.fileIdx === b.fileIdx && a.start === b.start) continue;
+        const key = `${a.fileIdx}:${b.fileIdx}:${b.start - a.start}`;
+        if (!pairGroups.has(key)) pairGroups.set(key, { fileA: a.fileIdx, fileB: b.fileIdx, delta: b.start - a.start, starts: new Set() });
+        pairGroups.get(key).starts.add(a.start);
+      }
+    }
+  }
+
+  // Within each (fileA, fileB, delta) group, merge consecutive fileA starts
+  // into maximal runs. A run [s, e] of consecutive starts (step 1) means a
+  // real duplicated block spanning tokens [s, e + minTokens - 1].
+  const rawFindings = [];
+  for (const { fileA, fileB, delta, starts } of pairGroups.values()) {
+    const sortedStarts = [...starts].sort((a, b) => a - b);
+    let runStart = sortedStarts[0];
+    let prev = sortedStarts[0];
+    const flush = (end) => {
+      // Skip a same-file, zero-offset-adjacent run entirely inside itself
+      // (fileA === fileB, delta < minTokens means the two "occurrences" are
+      // really the same physical block overlapping its own rolling window,
+      // not a second copy).
+      if (fileA === fileB && Math.abs(delta) < minTokens) return;
+      rawFindings.push({ fileA, fileB, aStart: runStart, aEnd: end, bStart: runStart + delta, bEnd: end + delta });
+    };
+    for (let i = 1; i < sortedStarts.length; i++) {
+      if (sortedStarts[i] === prev + 1) {
+        prev = sortedStarts[i];
+        continue;
+      }
+      flush(prev);
+      runStart = sortedStarts[i];
+      prev = sortedStarts[i];
+    }
+    flush(prev);
+  }
+
+  // Dedupe (a finding and its mirror-image (fileB,fileA,-delta) are the same
+  // physical duplicate reported twice) and convert to file:line.
+  const seen = new Set();
+  const duplicates = [];
+  for (const f of rawFindings) {
+    const tokenCount = f.aEnd - f.aStart + minTokens;
+    const locA = { fileIdx: f.fileA, start: f.aStart, end: f.aEnd + minTokens - 1 };
+    const locB = { fileIdx: f.fileB, start: f.bStart, end: f.bEnd + minTokens - 1 };
+    const sig = [locA, locB].map((l) => `${l.fileIdx}:${l.start}:${l.end}`).sort().join('|');
+    if (seen.has(sig)) continue;
+    seen.add(sig);
+    const occurrences = [locA, locB].map((l) => {
+      const { file, tokens } = fileTokens[l.fileIdx];
+      return { file, startLine: tokens[l.start].line, endLine: tokens[Math.min(l.end, tokens.length - 1)].line };
+    });
+    duplicates.push({ tokenCount, occurrences });
+  }
+
+  // Sort deterministically: by first occurrence file, then line — required
+  // for ATF golden-capture (byte-identical output across runs).
+  for (const d of duplicates) {
+    d.occurrences.sort((a, b) => a.file.localeCompare(b.file) || a.startLine - b.startLine);
+  }
+  duplicates.sort((a, b) => {
+    const fa = a.occurrences[0], fb = b.occurrences[0];
+    return fa.file.localeCompare(fb.file) || fa.startLine - fb.startLine || b.tokenCount - a.tokenCount;
+  });
+
+  return { duplicates, filesScanned: fileTokens.length, minTokens };
+}
+
+function recordHash(index, hash, fileIdx, start) {
+  if (!index.has(hash)) index.set(hash, []);
+  index.get(hash).push({ fileIdx, start });
+}

package/scripts/lib/language-plugin.mjs

@@ -0,0 +1,82 @@
+/**
+ * The language-plugin contract for solid-score.
+ *
+ * Everything downstream of this file — the five SOLID scorers and the Clean
+ * Architecture boundary check — reads ONLY a `NormalizedUnit`. No scoring
+ * function may import ts-morph, a Python AST module, or any language-specific
+ * parser. That boundary is the whole point: the first version of this tool
+ * had `srp()`/`ocp()`/`lsp()`/`isp()`/`dip()` walking ts-morph `SyntaxKind`
+ * nodes directly, which is the exact god-object-orchestrator shape this
+ * scorer exists to catch, just relocated into the scorer itself. A Python
+ * plugin must be addable by writing ONE new file that implements
+ * `extractUnits`, touching nothing under scoring/.
+ *
+ * @typedef {object} NormalizedMember
+ * @property {string} name
+ * @property {number} paramCount
+ * @property {string[]} fieldAccess       - names of instance-scope fields this member reads/writes (e.g. `this.x`, `self.x`)
+ * @property {string[]} calls             - names this member calls (bare names, receiver stripped)
+ * @property {number} branchHits          - switch-cases + instanceof/typeof-equivalent checks + if-else-if chain links
+ * @property {boolean} isPublic
+ * @property {object|null} override        - present only if this member overrides a base-class member
+ * @property {number} override.baseParamCount
+ * @property {boolean} override.callsSuper
+ * @property {string|null} override.returnType
+ * @property {string|null} override.baseReturnType
+ * @property {number} statementCount      - total statement-kind descendants (flattened, all nesting depths) — clean-code F1 (long method)
+ * @property {{name: string, line: number}[]} declaredNames - parameter + local `let`/`const`/`var` bindings with simple (non-destructured) names — clean-code N1/N2 (naming)
+ * @property {{value: number, line: number}[]} magicNumbers - numeric literals other than 0/1/-1 that are NOT the direct initializer of a `const` variable declaration or an enum member — clean-code N4
+ * @property {{line: number}[]} emptyCatches - `catch` blocks with zero statements — clean-code E1
+ * @property {{line: number, kind: 'if-true'|'if-false'|'while-false'}[]} deadConditionals - `if(true)`/`if(false)`/`while(false)` constant-conditional branches — clean-code G9 (unreachable-code half)
+ * @property {{line: number, kind: string}[]} unguardedRiskyOps - `await` expressions and named risky sync calls (JSON.parse, fs.readFileSync/writeFileSync) with no enclosing try-block — clean-code E2 (new rule, not ported from architecture-toolkit). ADDED for the ATF ladder's R3 error-handling-coverage gap (2026-08-22), additive-only.
+ * @property {{text: string, line: number}[]} statementTexts - whitespace-normalized text of every statement-kind descendant (same STATEMENT_KINDS as statementCount), filtered to text longer than 10 chars — refactoring consolidate-duplicate-code. ADDED for refactoring-scoring.mjs (2026-08-20), additive-only.
+ * @property {{line: number}[]} nullChecks - `if` statements whose condition contains a top-level `=== null` / `!== null` comparison, one entry per matching `if` (deduplicated per-if, not per-comparison) — refactoring null-object-transform. ADDED for refactoring-scoring.mjs (2026-08-20), additive-only.
+ * @property {{line: number, hasBehaviorCall: boolean, hasTypeCreation: boolean}[]} switchStatements - every `switch` statement, flagged for behavior-dispatch shape (case bodies call something matching /calculate|process|validate|format/i — refactoring strategy-transform) and type-based-construction shape (discriminant text contains "type" AND the switch body contains a `new X()` — refactoring factory-transform). ADDED for refactoring-scoring.mjs (2026-08-20), additive-only.
+ * @property {{line: number, length: number}[]} complexConditionals - `if` statement conditions whose source text is >= 50 chars — refactoring decompose-conditional. ADDED for refactoring-scoring.mjs (2026-08-20), additive-only.
+ * @property {number|null} switchBehaviorCallLine - line of the first `switch` statement in this member whose text matches /calculate|process|execute|validate|format/i — pattern-advisor Strategy signal (behavioral-pattern-analyzer.ts:44's exact word list; a superset of `switchStatements[].hasBehaviorCall`'s list above, which omits "execute" and is ported from a different toolkit file — kept as a separate fact rather than edited in place). `null` if no switch in this member matches. ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ * @property {string[]} constructorNewCallTargets - ALL `new X(...)` target names anywhere in this member's body, UNFILTERED (includes stdlib) — pattern-advisor Factory Method "scattered instantiation" signal (creational-pattern-analyzer.ts:68-83: >5 total, >3 unique). Distinct from `concreteInstantiations` on NormalizedUnit, which is local-classes-only and would under-count this check. ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ * @property {number|null} conditionalFeatureCallLine - line of the first `if` statement in this member whose THEN block calls a function whose bare name matches /wrap|add|extend|enhance/i — pattern-advisor Decorator signal (structural-pattern-analyzer.ts:39-43). `null` if none. ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ * @property {number} deepChainCallCount - count of call expressions shaped `a.b.c(...)` (callee is a property access whose own receiver is itself a property access) — pattern-advisor Facade signal (structural-pattern-analyzer.ts:104-105, threshold >5). ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ * @property {string[]} calleeNames - bare trailing call name (receiver stripped entirely, not just `this.`) for every call expression in this member — pattern-advisor Adapter/Observer/Command/Template Method keyword scans. Distinct from `calls` above, which keeps `this.`-stripped but otherwise full receiver-qualified text. ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ *
+ * @typedef {object} NormalizedUnit
+ * @property {string} name
+ * @property {'class'|'module'} kind
+ * @property {NormalizedMember[]} members
+ * @property {boolean} hasBaseClass       - true if this unit extends/inherits from something
+ * @property {number} concreteInstantiations - count of `new <LocalClass>()`-equivalent constructions of project-local types
+ * @property {number} totalDependencies   - concreteInstantiations + count of distinct imported/injected names used
+ * @property {string[]} staticPropertyNames - names of static properties declared directly on this class; always `[]` for a module — pattern-advisor Singleton signal (creational-pattern-analyzer.ts:124-146). ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ * @property {boolean} hasGetInstanceMethod - true if any member (class method or top-level module function) is named exactly 'getInstance' — pattern-advisor Singleton signal, paired with `staticPropertyNames`. ADDED for pattern-scoring.mjs (2026-08-20), additive-only.
+ *
+ * @typedef {object} DeadExportFact
+ * @property {string} name
+ * @property {number} line
+ * @property {number} referenceCount      - reference sites found anywhere in the scanned project, EXCLUDING the declaration's own name occurrence. -1 means "declaration kind not supported by the reference finder", never treat -1 as zero.
+ * @property {string} kind                - ts-morph declaration kind name, for diagnostics
+ *
+ * @typedef {object} LanguagePlugin
+ * @property {string} id
+ * @property {(filePath: string) => boolean} canHandle
+ * @property {(filePath: string, sourceText?: string) => NormalizedUnit[]} extractUnits
+ * @property {(filePath: string, sourceText?: string) => string[]} importsOf   - module specifiers this file imports, for the boundary check
+ * @property {(filePath: string, projectFilePaths?: string[]) => DeadExportFact[]} [deadExportsOf] - OPTIONAL. Cross-file reference count per exported symbol in `filePath`, resolved against the full set of `projectFilePaths` (a real reference-graph walk, not a text grep). Absent on a plugin that hasn't implemented it — a caller MUST treat a missing method as "G9 export-usage half unmeasured", never as "zero dead exports".
+ * @property {(filePath: string, exportName: string, projectFilePaths?: string[]) => {referenceCount: number, files: string[], kind: string|null}} [referenceSitesOf] - OPTIONAL. ADDED for refactoring-scoring.mjs (2026-08-20), additive-only. Same `findReferencesAsNodes()` walk as `deadExportsOf`, targeted at ONE named export, returning both the count and the deduplicated list of file paths that reference it (declaration's own occurrence excluded) — refactoring effort estimation's call-site-count and package-boundary-crossing criteria. `referenceCount: -1` means "declaration kind unsupported by the reference finder", never treat -1 as zero. Absent on a plugin that hasn't implemented it — a caller MUST treat a missing method as "effort unmeasured", never as "0 call sites".
+ */
+
+/** @type {LanguagePlugin[]} */
+const REGISTRY = [];
+
+/** @param {LanguagePlugin} plugin */
+export function registerPlugin(plugin) {
+  REGISTRY.push(plugin);
+}
+
+/** @returns {LanguagePlugin|null} */
+export function pluginFor(filePath) {
+  return REGISTRY.find((p) => p.canHandle(filePath)) ?? null;
+}
+
+export function registeredPlugins() {
+  return [...REGISTRY];
+}