code-auditor-mcp 4.1.1 → 5.0.1

package/dist/analyzers/applicability.js

@@ -20,6 +20,7 @@
  * from it, so firing and applicability can never read different tier sets.
  */
 import { buildOrgFilterTierSet, hasDeclaredTenancy, } from './orgFilterTiers.js';
+import { buildDeclaredScale, hasDeclaredScale, } from './universal/styleScale.js';
 /**
  * Spec 52 R3 — the whole-program rule class. These rules draw a global
  * conclusion ("table X is never read", "table Y is unknown", "no validator is
@@ -62,6 +63,9 @@ export const WHOLE_PROGRAM_RULES = [
  * on a scoped run. Returns an empty map when the run is unscoped — whole-program
  * rules run normally on a full corpus. Extracted as a pure function so the
  * scoped-suppression wiring is unit-testable without spinning up a full pipeline.
+ * @param isScoped Whether this run is scoped to a subset of files.
+ * @param fileCount The number of files in the scoped run.
+ * @returns A map of rule id to `notApplicable` verdicts, or an empty map when unscoped.
  */
 export function scopedWholeProgramApplicability(isScoped, fileCount) {
     const map = new Map();
@@ -101,6 +105,76 @@ export function evaluateRuleApplicability(ruleId, dataAccessConfig, ddlTableColu
     }
     return null;
 }
+/**
+ * Spec 66 follow-up — the three security rules are *sink-scoped*: each inspects
+ * a specific construct (a shell/process invocation, a require/import, an HTML
+ * sink) and cannot fire when that construct is absent from the corpus. The
+ * UniversalSecurityAnalyzer reports, per file, which constructs it saw; those
+ * fold corpus-wide into `security` facts. A rule whose construct never appeared
+ * reads `notApplicable` ("no input to check") rather than `clean` ("input
+ * present, nothing wrong") — the same `clean`-must-mean-could-have-fired
+ * contract as `missing-org-filter`'s `hasDeclaredTenancy`, but keyed on AST
+ * presence instead of declared config.
+ *
+ * @param securityFacts The corpus-wide `security` fact object emitted by the
+ *   security visitor (`{ shellProcessSeen, dynamicRequireSeen, htmlSinkSeen }`,
+ *   each present only when ≥1 file contained the construct).
+ * @returns A map of rule id to `notApplicable` verdicts for each absent construct.
+ */
+export function securityInputApplicability(securityFacts) {
+    const map = new Map();
+    if (securityFacts?.shellProcessSeen !== true) {
+        map.set('command-injection-risk', {
+            applicable: false,
+            kind: 'notApplicable',
+            reason: 'no shell/process invocation (execSync/exec/spawn/fork) in corpus',
+        });
+    }
+    if (securityFacts?.dynamicRequireSeen !== true) {
+        map.set('dynamic-require-of-project-path', {
+            applicable: false,
+            kind: 'notApplicable',
+            reason: 'no require()/import()/createRequire() invocation in corpus',
+        });
+    }
+    if (securityFacts?.htmlSinkSeen !== true) {
+        map.set('unescaped-html-interpolation', {
+            applicable: false,
+            kind: 'notApplicable',
+            reason: 'no HTML sink (res.send/innerHTML/dangerouslySetInnerHTML/v-html) in corpus',
+        });
+    }
+    return map;
+}
+/**
+ * Spec 66 follow-up (#253) — `styles/off-scale` is scale-scoped: it judges
+ * spacing/font-size values against the project's *declared* design scale, and
+ * cannot fire when the project declares no scale. That reads `notApplicable`
+ * with a reason that names the fix ("declare a scale and this rule can check
+ * it"), rather than `clean` ("input present, nothing wrong") — the same
+ * `clean`-must-mean-could-have-fired contract as `missing-org-filter`, but keyed
+ * on declared token presence instead of declared config.
+ *
+ * The scale definition is {@link buildDeclaredScale} from `styleScale.ts`, the
+ * same function the analyzer uses to judge raw values — so "declares a scale"
+ * for applicability is byte-identical to "declares a scale" for firing, and the
+ * two consumers cannot drift.
+ *
+ * @param tokens The corpus-wide `style_tokens` rows (name/value/file_path). When
+ *   the index is unavailable the caller passes `[]`, and the rule reads
+ *   `notApplicable` (it had no evidence of a declared scale).
+ * @returns A `notApplicable` verdict when no scale family is declared, or `null`
+ *   when at least one is (the rule runs unconditionally, exactly as before).
+ */
+export function offScaleApplicability(tokens) {
+    if (hasDeclaredScale(buildDeclaredScale(tokens)))
+        return null;
+    return {
+        applicable: false,
+        kind: 'notApplicable',
+        reason: 'no design tokens found; declare a scale and this rule can check it',
+    };
+}
 /**
  * Spec 44 bucket 2 — rules that are structurally unreachable: their predicate
  * reads a field no extractor populates (or they are a legacy alias with no

package/dist/analyzers/applicability.js.map

@@ -1 +1 @@
-{"version":3,"file":"applicability.js","sourceRoot":"","sources":["../../src/analyzers/applicability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,qBAAqB,EACrB,kBAAkB,GAEnB,MAAM,qBAAqB,CAAC;AAe7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA0B;IACxD,iCAAiC;IACjC,iCAAiC;IACjC,qCAAqC;IACrC,eAAe;IACf,uBAAuB;CACxB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAAiB,EACjB,SAAiB;IAEjB,MAAM,GAAG,GAAG,IAAI,GAAG,EAA6B,CAAC;IACjD,IAAI,CAAC,QAAQ;QAAE,OAAO,GAAG,CAAC;IAC1B,KAAK,MAAM,MAAM,IAAI,mBAAmB,EAAE,CAAC;QACzC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE;YACd,UAAU,EAAE,KAAK;YACjB,IAAI,EAAE,eAAe;YACrB,MAAM,EAAE,2DAA2D,SAAS,UAAU;SACvF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAcD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAc,EACd,gBAAqD,EACrD,eAAqD;IAErD,IAAI,MAAM,KAAK,oBAAoB,EAAE,CAAC;QACpC,OAAO,qCAAqC,CAAC,gBAAgB,EAAE,eAAe,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,gBAAgB,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IAC9E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAgC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;AAE1E;;;;;;;;;;;;;;GAcG;AACH,SAAS,qCAAqC,CAC5C,gBAAqD,EACrD,eAAqD;IAErD,MAAM,OAAO,GAAG,qBAAqB,CAAC,gBAA+C,EAAE,eAAe,CAAC,CAAC;IACxG,IAAI,kBAAkB,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAE7D,OAAO;QACL,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,iDAAiD;KAC1D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"applicability.js","sourceRoot":"","sources":["../../src/analyzers/applicability.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/cross-language/APIContractAnalyzer.js

@@ -152,18 +152,7 @@ function extractTypeScriptAPICall(entity) {
         entity.purpose?.includes('axios') ||
         entity.name.toLowerCase().includes('api') ||
         entity.name.toLowerCase().includes('request')) {
-        const method = extractCallMethodFromTypeScript(entity);
-        const url = extractUrlFromTypeScript(entity);
-        if (method && url) {
-            return {
-                id: entity.id,
-                method,
-                url,
-                language: 'typescript',
-                file: entity.file,
-                line: entity.startLine || 0,
-            };
-        }
+        return buildApiCall(entity, 'typescript', extractCallMethodFromTypeScript(entity), extractUrlFromTypeScript(entity));
     }
     return null;
 }
@@ -172,21 +161,26 @@ function extractGoAPICall(entity) {
     if (entity.signature?.includes('http.Client') ||
         entity.purpose?.includes('HTTP') ||
         entity.name.toLowerCase().includes('request')) {
-        const method = extractCallMethodFromGo(entity);
-        const url = extractUrlFromGo(entity);
-        if (method && url) {
-            return {
-                id: entity.id,
-                method,
-                url,
-                language: 'go',
-                file: entity.file,
-                line: entity.startLine || 0,
-            };
-        }
+        return buildApiCall(entity, 'go', extractCallMethodFromGo(entity), extractUrlFromGo(entity));
     }
     return null;
 }
+/** Assemble an `APICall` from a method/url pair, or `null` when either is
+ *  missing. The TS and Go extractors share this tail (the two `if (method &&
+ *  url)` guards and the identical object shape); only the language literal
+ *  differs, which each caller passes in. */
+function buildApiCall(entity, language, method, url) {
+    if (!method || !url)
+        return null;
+    return {
+        id: entity.id,
+        method,
+        url,
+        language,
+        file: entity.file,
+        line: entity.startLine || 0,
+    };
+}
 // Helper functions for extracting HTTP info from code patterns
 function extractMethodFromGo(entity) {
     const name = entity.name.toLowerCase();

package/dist/analyzers/cross-language/APIContractAnalyzer.js.map

@@ -1 +1 @@
-{"version":3,"file":"APIContractAnalyzer.js","sourceRoot":"","sources":["../../../src/analyzers/cross-language/APIContractAnalyzer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+BH;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,gBAAgB,CACpB,UAAyB,EACzB,MAAiB;QAEjB,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,8EAA8E;AAC9E,gEAAgE;AAChE,8EAA8E;AAC9E,EAAE;AACF,gFAAgF;AAChF,uEAAuE;AACvE,mDAAmD;AAEnD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAe;IAC9C,MAAM,SAAS,GAAkB,EAAE,CAAC;IAEpC,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,iCAAiC;QACjC,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC3D,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;YAC3C,IAAI,QAAQ;gBAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;QAED,gDAAgD;QAChD,IAAI,MAAM,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACnE,MAAM,QAAQ,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;YACnD,IAAI,QAAQ;gBAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;QAED,0CAA0C;QAC1C,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/D,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;YAC/C,IAAI,QAAQ;gBAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,QAAe;IAC7C,MAAM,KAAK,GAAc,EAAE,CAAC;IAE5B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,uDAAuD;QACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,YAAY,IAAI,MAAM,CAAC,QAAQ,KAAK,YAAY,CAAC,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACzG,MAAM,IAAI,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAED,mCAAmC;QACnC,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC3D,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,IAAI;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,iBAAiB,CAAC,MAAW;IACpC,uCAAuC;IACvC,IAAI,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,aAAa,CAAC;QACzC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,cAAc,CAAC;QAC1C,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAEtD,yDAAyD;QACzD,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAEvC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,MAAM,EAAE,MAAa;gBACrB,IAAI;gBACJ,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;gBAC3B,qDAAqD;aACtD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,yBAAyB,CAAC,MAAW;IAC5C,4CAA4C;IAC5C,IAAI,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACpF,MAAM,MAAM,GAAG,2BAA2B,CAAC,MAAM,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,yBAAyB,CAAC,MAAM,CAAC,CAAC;QAE/C,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,MAAM,EAAE,MAAa;gBACrB,IAAI;gBACJ,QAAQ,EAAE,YAAY;gBACtB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;aAC5B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,qBAAqB,CAAC,MAAW;IACxC,kCAAkC;IAClC,IAAI,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAChD,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QAEnD,MAAM,MAAM,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAE3C,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;YACnB,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,MAAM,EAAE,MAAa;gBACrB,IAAI;gBACJ,QAAQ,EAAE,QAAQ;gBAClB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;aAC5B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,wBAAwB,CAAC,MAAW;IAC3C,gCAAgC;IAChC,IAAI,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;QACjC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAElD,MAAM,MAAM,GAAG,+BAA+B,CAAC,MAAM,CAAC,CAAC;QACvD,MAAM,GAAG,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAAC;QAE7C,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClB,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,MAAM;gBACN,GAAG;gBACH,QAAQ,EAAE,YAAY;gBACtB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;aAC5B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAW;IACnC,gCAAgC;IAChC,IAAI,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,aAAa,CAAC;QACzC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAElD,MAAM,MAAM,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAErC,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAClB,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,EAAE;gBACb,MAAM;gBACN,GAAG;gBACH,QAAQ,EAAE,IAAI;gBACd,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,SAAS,IAAI,CAAC;aAC5B,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,+DAA+D;AAE/D,SAAS,mBAAmB,CAAC,MAAW;IACtC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACvC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IACzC,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC7C,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,iBAAiB,CAAC,MAAW;IACpC,2DAA2D;IAC3D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACzB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAChE,OAAO,IAAI,QAAQ,MAAM,CAAC;IAC5B,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,GAAG,CAAC;QACvD,OAAO,IAAI,QAAQ,EAAE,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,2BAA2B,CAAC,MAAW;IAC9C,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACnD,CAAC;AAED,SAAS,yBAAyB,CAAC,MAAW;IAC5C,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACjD,CAAC;AAED,SAAS,uBAAuB,CAAC,MAAW;IAC1C,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACnD,CAAC;AAED,SAAS,qBAAqB,CAAC,MAAW;IACxC,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACjD,CAAC;AAED,SAAS,+BAA+B,CAAC,MAAW;IAClD,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACnD,CAAC;AAED,SAAS,wBAAwB,CAAC,MAAW;IAC3C,wCAAwC;IACxC,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,uBAAuB,CAAC,MAAW;IAC1C,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACnD,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAW;IACnC,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;AACjD,CAAC"}
+{"version":3,"file":"APIContractAnalyzer.js","sourceRoot":"","sources":["../../../src/analyzers/cross-language/APIContractAnalyzer.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/cross-language/DependencyGraphBuilder.d.ts

@@ -58,24 +58,26 @@ declare class DependencyGraphBuilderCore {
      */
     protected countStronglyConnectedComponents(nodes: DependencyNode[], edges: DependencyEdge[]): number;
     /**
-     * Find tightly coupled clusters
-     */
-    protected findTightlyCoupledClusters(graph: DependencyGraph): {
-        nodes: string[];
-        coupling: number;
-    }[];
-    /**
-     * Find hub nodes with too many dependencies.
+     * Find tightly coupled clusters.
      *
-     * Returns each hub together with its out-degree so the reducer can render the
-     * degree in the finding — the previous signature dropped it, forcing the
-     * message to read "Found N hub nodes" with no way to see which node or how
-     * dependent it was.
-     */
-    protected findHubNodes(graph: DependencyGraph): Array<{
-        node: DependencyNode;
-        outDegree: number;
-    }>;
+     * Tight coupling is a property of a *pair* of modules, not of one module: two
+     * packages are tightly coupled when their mutual edges dominate the edges that
+     * stay inside either package — the pair is more entangled with each other than
+     * with itself, so neither can change without the other. The prior metric
+     * measured a single cluster's *cohesion* (`internalEdges / incidentEdges`) and
+     * reported it as coupling, which inverted the concept — a package whose nodes
+     * mostly call each other is cohesive (good design), not coupled — and flagged
+     * every well-factored package. See `specs/spec70-worklist.md` §4.
+     *
+     * Coupling here is `cross / (cross + within)` for each unordered pair of
+     * distinct clusters, where `cross` = aToB + bToA (edges spanning the
+     * boundary) and `within` = edges that stay inside either cluster. A pair is
+     * flagged only when edges flow in *both* directions (a one-directional
+     * fan-in — three functions in A calling a shared utility in B — is a
+     * dependency, not coupling), the pair has at least three cross edges, and
+     * the ratio exceeds the coupling threshold.
+     */
+    protected findTightlyCoupledClusters(graph: DependencyGraph): TightlyCoupledCluster[];
     /**
      * Find orphaned nodes with no dependencies.
      *
@@ -163,10 +165,8 @@ export declare class DependencyGraphBuilder extends DependencyGraphBuilderTraver
     }>;
     /** Record the circular-dependency check (cycles rendered node-by-node). */
     private recordCycleCheck;
-    /** Record the tight-coupling check (clusters rendered with their coupling %). */
+    /** Record the tight-coupling check (cluster pairs rendered with their coupling %). */
     private recordClusterCheck;
-    /** Record the hub-node check. */
-    private recordHubCheck;
     /**
      * Build the scope-aware name-reference index for orphan detection.
      *
@@ -188,17 +188,24 @@ interface ReferenceIndex {
     byFile: Map<string, Set<string>>;
     globalFiles: Map<string, Set<string>>;
 }
+/** A tightly-coupled cluster pair: the two cluster keys, their union of nodes, and the coupling ratio. */
+interface TightlyCoupledCluster {
+    nodes: string[];
+    coupling: number;
+    /** The two cluster (package) keys whose shared boundary the coupling measures. */
+    clusters: [string, string];
+}
 export interface DependencyIssue {
-    type: 'circular-dependency' | 'tight-coupling' | 'hub-nodes' | 'orphaned-nodes';
+    type: 'circular-dependency' | 'tight-coupling' | 'orphaned-nodes';
     severity: 'critical' | 'severe' | 'high';
     description: string;
     affectedNodes: string[];
     impact: 'high' | 'medium' | 'low';
-    /** Structured resolution data (cycle paths, cluster coupling, hub degrees, orphan names). */
+    /** Structured resolution data (cycle paths, cluster coupling, orphan names). */
     details?: Record<string, unknown>;
 }
 export interface DependencySuggestion {
-    type: 'break-cycles' | 'reduce-coupling' | 'split-responsibilities' | 'review-orphans';
+    type: 'break-cycles' | 'reduce-coupling' | 'review-orphans';
     priority: 'high' | 'medium' | 'low';
     description: string;
     implementation: string;

package/dist/analyzers/cross-language/DependencyGraphBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DependencyGraphBuilder.d.ts","sourceRoot":"","sources":["../../../src/analyzers/cross-language/DependencyGraphBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DependencyGraphBuilder.d.ts","sourceRoot":"","sources":["../../../src/analyzers/cross-language/DependencyGraphBuilder.ts"],"names":[],"mappings":"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"}

package/dist/analyzers/cross-language/DependencyGraphBuilder.js

@@ -186,7 +186,24 @@ class DependencyGraphBuilderCore {
         return sccCount;
     }
     /**
-     * Find tightly coupled clusters
+     * Find tightly coupled clusters.
+     *
+     * Tight coupling is a property of a *pair* of modules, not of one module: two
+     * packages are tightly coupled when their mutual edges dominate the edges that
+     * stay inside either package — the pair is more entangled with each other than
+     * with itself, so neither can change without the other. The prior metric
+     * measured a single cluster's *cohesion* (`internalEdges / incidentEdges`) and
+     * reported it as coupling, which inverted the concept — a package whose nodes
+     * mostly call each other is cohesive (good design), not coupled — and flagged
+     * every well-factored package. See `specs/spec70-worklist.md` §4.
+     *
+     * Coupling here is `cross / (cross + within)` for each unordered pair of
+     * distinct clusters, where `cross` = aToB + bToA (edges spanning the
+     * boundary) and `within` = edges that stay inside either cluster. A pair is
+     * flagged only when edges flow in *both* directions (a one-directional
+     * fan-in — three functions in A calling a shared utility in B — is a
+     * dependency, not coupling), the pair has at least three cross edges, and
+     * the ratio exceeds the coupling threshold.
      */
     findTightlyCoupledClusters(graph) {
         const clusters = new Map();
@@ -199,66 +216,67 @@ class DependencyGraphBuilderCore {
             else
                 clusters.set(cluster, [node.id]);
         }
+        const clusterOf = new Map();
+        for (const [cluster, ids] of clusters) {
+            for (const id of ids)
+                clusterOf.set(id, cluster);
+        }
+        // Single pass over edges: bucket each as internal (both endpoints in one
+        // cluster) or cross-cluster, split by direction. The coupling ratio is then
+        // per-pair, and the scan is O(V + E + P), not O(P · E) for P cluster pairs.
+        const withinByCluster = new Map();
+        const crossEdges = new Map();
+        const pair = (lo, hi) => {
+            let inner = crossEdges.get(lo);
+            if (!inner) {
+                inner = new Map();
+                crossEdges.set(lo, inner);
+            }
+            let counts = inner.get(hi);
+            if (!counts) {
+                counts = { aToB: 0, bToA: 0 };
+                inner.set(hi, counts);
+            }
+            return counts;
+        };
+        for (const edge of graph.edges) {
+            const a = clusterOf.get(edge.from);
+            const b = clusterOf.get(edge.to);
+            if (a === undefined || b === undefined)
+                continue; // endpoint outside the node set
+            if (a === b) {
+                withinByCluster.set(a, (withinByCluster.get(a) ?? 0) + 1);
+            }
+            else {
+                const [lo, hi] = a < b ? [a, b] : [b, a];
+                const counts = pair(lo, hi);
+                if (a < b)
+                    counts.aToB++;
+                else
+                    counts.bToA++;
+            }
+        }
         const tightlyCoupled = [];
-        for (const nodeIds of clusters.values()) {
-            if (nodeIds.length < 3)
-                continue; // coupling over a tiny cluster is meaningless
-            const member = new Set(nodeIds);
-            // Cohesion: the fraction of a cluster's incident edges that stay internal.
-            // A raw internal-density threshold (internalEdges / N×(N−1) > 0.7) is
-            // unreachable for any real sparse graph — it would require ~70% of all
-            // possible edges to exist — so tight-coupling never fired. Cohesion
-            // instead flags clusters whose nodes mostly talk to each other, which is
-            // what "tightly coupled" actually means.
-            let internalEdges = 0;
-            let incidentEdges = 0;
-            for (const edge of graph.edges) {
-                const fromIn = member.has(edge.from);
-                const toIn = member.has(edge.to);
-                if (fromIn && toIn) {
-                    internalEdges++;
-                    incidentEdges++;
-                }
-                else if (fromIn || toIn) {
-                    incidentEdges++;
+        for (const [a, inner] of crossEdges) {
+            for (const [b, counts] of inner) {
+                if (counts.aToB === 0 || counts.bToA === 0)
+                    continue; // one-directional dependency, not coupling
+                const cross = counts.aToB + counts.bToA;
+                if (cross < 3)
+                    continue; // a lone edge is a dependency, not tight coupling
+                const aIds = clusters.get(a);
+                const bIds = clusters.get(b);
+                if (aIds.length + bIds.length < 3)
+                    continue; // coupling over a tiny pair is meaningless
+                const within = (withinByCluster.get(a) ?? 0) + (withinByCluster.get(b) ?? 0);
+                const coupling = cross / (cross + within);
+                if (coupling > 0.7) {
+                    tightlyCoupled.push({ nodes: [...aIds, ...bIds], coupling, clusters: [a, b] });
                 }
             }
-            if (incidentEdges === 0)
-                continue;
-            const coupling = internalEdges / incidentEdges;
-            if (coupling > 0.7) {
-                tightlyCoupled.push({ nodes: nodeIds, coupling });
-            }
         }
         return tightlyCoupled;
     }
-    /**
-     * Find hub nodes with too many dependencies.
-     *
-     * Returns each hub together with its out-degree so the reducer can render the
-     * degree in the finding — the previous signature dropped it, forcing the
-     * message to read "Found N hub nodes" with no way to see which node or how
-     * dependent it was.
-     */
-    findHubNodes(graph) {
-        const outDegree = new Map();
-        for (const edge of graph.edges) {
-            outDegree.set(edge.from, (outDegree.get(edge.from) || 0) + 1);
-        }
-        // Derive the hub threshold from the actual out-degree distribution rather
-        // than a fixed fraction of corpus size. The old `max(5, N×0.1)` required
-        // >830 outgoing edges on an ~8306-node corpus — effectively unreachable, so
-        // hub-nodes could never fire (and when it did, only via name collisions).
-        // A hub is an outlier: out-degree above a small multiple of the mean.
-        const degrees = [...outDegree.values()];
-        const mean = degrees.length
-            ? degrees.reduce((sum, d) => sum + d, 0) / degrees.length
-            : 0;
-        const threshold = Math.max(10, Math.ceil(mean * 3));
-        return graph.nodes
-            .map(node => ({ node, outDegree: outDegree.get(node.id) || 0 }))
-            .filter(({ outDegree: d }) => d > threshold);
-    }
     /**
      * Find orphaned nodes with no dependencies.
      *
@@ -284,6 +302,12 @@ class DependencyGraphBuilderCore {
             // interfaces on a corpus whose actual signal was ~139 functions.
             if (node.type === 'interface' || node.type === 'struct')
                 return false;
+            // `_`-prefixed declarations are unused by convention — compile-time check
+            // seeds (seeded-defects.ts's `_notSerializable`) or unused markers. An
+            // orphaned-node finding means "dead code to delete", which does not apply
+            // to a name the author already marked as intentionally unused.
+            if (node.name.startsWith('_'))
+                return false;
             // Methods are invoked via `this.` / receiver / prototype dispatch, which a
             // name-only call graph cannot model. Class-prefixed names (`Client.formatter`,
             // Go `Foo.Bar`) never resolve — the reference resolver matches a bare callee
@@ -410,6 +434,7 @@ class DependencyGraphBuilderTraversal extends DependencyGraphBuilderCore {
         const visited = new Set();
         const recursionStack = new Set();
         const adjList = this.buildAdjacencyList(edges);
+        const fileById = new Map(nodes.map(n => [n.id, n.file]));
         // Shared mutable path (push/pop) + an index map for O(1) cycle-start lookup.
         // Avoids the previous `[...path]` snapshot on every recursion — that made a
         // deep graph O(E · path-length) and re-allocated a path array per edge.
@@ -422,6 +447,13 @@ class DependencyGraphBuilderTraversal extends DependencyGraphBuilderCore {
             path.push(nodeId);
             const neighbors = adjList.get(nodeId) || [];
             for (const neighbor of neighbors) {
+                // A self-edge is a function calling itself — recursion, not a module
+                // cycle. The graph models function-call references, so a recursive
+                // function (`dfs` calling `dfs`) would otherwise be reported as a
+                // single-node "circular dependency", which mislabels the graph's
+                // granularity as module-level when it is function-level.
+                if (neighbor === nodeId)
+                    continue;
                 if (!visited.has(neighbor)) {
                     dfs(neighbor);
                 }
@@ -429,6 +461,12 @@ class DependencyGraphBuilderTraversal extends DependencyGraphBuilderCore {
                     // Found a cycle
                     const cycleStart = pathIndex.get(neighbor) ?? 0;
                     const cycleNodes = path.slice(cycleStart);
+                    // A cycle whose nodes all share one file is mutual recursion, not a
+                    // module dependency cycle — see {@link spansMultipleFiles}. Only a
+                    // cycle crossing a file (module) boundary is a reportable
+                    // circular-dependency.
+                    if (!spansMultipleFiles(cycleNodes, fileById))
+                        continue;
                     cycles.push({
                         nodes: cycleNodes,
                         severity: 'severe',
@@ -561,8 +599,7 @@ export class DependencyGraphBuilder extends DependencyGraphBuilderTraversal {
         const sink = { issues, suggestions };
         const idToName = new Map(graph.nodes.map(n => [n.id, n.name]));
         this.recordCycleCheck(sink, graph, idToName);
-        this.recordClusterCheck(sink, graph, idToName);
-        this.recordHubCheck(sink, graph);
+        this.recordClusterCheck(sink, graph);
         this.recordOrphanCheck(sink, graph);
         return {
             healthScore: this.calculateHealthScore(graph, issues),
@@ -583,32 +620,17 @@ export class DependencyGraphBuilder extends DependencyGraphBuilderTraversal {
             },
         });
     }
-    /** Record the tight-coupling check (clusters rendered with their coupling %). */
-    recordClusterCheck(sink, graph, idToName) {
-        const label = (ids) => ids.map(id => idToName.get(id) ?? id);
+    /** Record the tight-coupling check (cluster pairs rendered with their coupling %). */
+    recordClusterCheck(sink, graph) {
         const clusters = this.findTightlyCoupledClusters(graph);
         this.recordCheck(sink, clusters.length, clusters.flatMap(c => c.nodes), {
             issueType: 'tight-coupling', severity: 'high', impact: 'medium',
-            issueDesc: () => clusters.map(c => `${label(c.nodes).join(', ')} (${(c.coupling * 100).toFixed(0)}%)`).join('; '),
+            issueDesc: () => clusters.map(c => `${c.clusters[0]} ↔ ${c.clusters[1]} (${(c.coupling * 100).toFixed(0)}%)`).join('; '),
             suggestionType: 'reduce-coupling', priority: 'medium',
             suggestionDesc: 'Reduce coupling between modules using interfaces and abstractions',
             implementation: 'Extract common interfaces and use dependency injection',
             details: {
-                clusters: clusters.map(c => ({ nodes: c.nodes, coupling: c.coupling })),
-            },
-        });
-    }
-    /** Record the hub-node check. */
-    recordHubCheck(sink, graph) {
-        const hubNodes = this.findHubNodes(graph);
-        this.recordCheck(sink, hubNodes.length, hubNodes.map(h => h.node.id), {
-            issueType: 'hub-nodes', severity: 'high', impact: 'medium',
-            issueDesc: () => hubNodes.map(h => `${h.node.name} (${h.outDegree})`).join(', '),
-            suggestionType: 'split-responsibilities', priority: 'medium',
-            suggestionDesc: 'Split large modules to reduce their dependency burden',
-            implementation: 'Apply Single Responsibility Principle to break down large modules',
-            details: {
-                hubs: hubNodes.map(h => ({ id: h.node.id, name: h.node.name, outDegree: h.outDegree })),
+                clusters: clusters.map(c => ({ clusters: c.clusters, coupling: c.coupling })),
             },
         });
     }
@@ -683,6 +705,21 @@ export class DependencyGraphBuilder extends DependencyGraphBuilderTraversal {
     }
 }
 // Supporting interfaces
+/**
+ * Whether a detected cycle crosses a file (module) boundary.
+ *
+ * The graph models function-call references, so a cycle whose nodes all live in
+ * one file is mutual recursion — a validator's `validateAgainstSchema` ⇄
+ * `checkArrayConstraints`, a parser's `evaluate` ⇄ `evalObject` — normal
+ * recursive-descent structure, not a module dependency cycle. `circular-dependency`
+ * is a module-level concept (file A imports file B imports file A); a same-file
+ * call cycle never crosses a module boundary, so it must not be reported as one.
+ * This is the N-node generalization of the self-edge skip in {@link detectCycles}
+ * (a self-edge is the 1-node case of the same phenomenon).
+ */
+function spansMultipleFiles(cycleNodes, fileById) {
+    return new Set(cycleNodes.map(id => fileById.get(id))).size > 1;
+}
 /**
  * Scope-aware name resolution for orphan detection, mirroring the reference
  * resolver's order: same file → same directory → unique global. A node is