code-auditor-mcp 4.1.1 → 5.0.1

package/dist/phase/rules/documentation.js

@@ -0,0 +1,340 @@
+/**
+ * Spec 68 §3.2 — the documentation rules, migrated to `analyze(ctx)`.
+ *
+ * These five rules (`function-documentation`, `parameter-documentation`,
+ * `return-documentation`, `class-documentation`, `method-documentation`) were
+ * the per-file AST checks inside `UniversalDocumentationAnalyzer`; now they read
+ * the `file-symbols` fact and do pure comparison over plain data. The tree died
+ * with the file — the producer pre-computed the two skip signals a rule cannot
+ * derive from symbol fields (`isAnonymousOrCallback`, `isNonPublic`) where the
+ * parent chain and method node still existed.
+ *
+ * `file-documentation` is *not* here: it is a file-level rule (a leading
+ * header comment), not a symbol-level one, and reads a fact kind
+ * (`file-symbols` carries symbols, not files) the migration map dispositions
+ * RENEW. It stays on the legacy path until its own fact lands.
+ *
+ * Config resolution mirrors the legacy analyzer's `{...DEFAULT, ...config}`
+ * merge, but the defaults are re-declared here (the legacy class is deleted in
+ * §15, and the rule must not reach across the phase boundary to import it). The
+ * §10 bridge (`resolvePhaseThresholds`) already merges the same default into
+ * `ctx.thresholds`, so the merge is idempotent in production and load-bearing
+ * only for the parity test, which passes raw config to both sides.
+ *
+ * The three rules read only their tuning thresholds; §10 removed the
+ * `requireParamDocs` / `requireReturnDocs` opt-in gates — these rules now fire
+ * unconditionally, so the two booleans are gone from this config surface.
+ */
+import { RULE_REGISTRY } from '../../analyzers/ruleRegistry.js';
+/**
+ * The documentation defaults, re-declared from
+ * `DEFAULT_DOCUMENTATION_CONFIG` (UniversalDocumentationAnalyzer.ts). The full
+ * object carries fields these rules do not read (`requireFileDocs`,
+ * `fileHeaders`, `headerSkipGlobs`, `checkExportedOnly`, `minDescriptionLength`);
+ * only the finding-relevant subset is reproduced, with the `exemptPatterns`
+ * list verbatim so the file-level skip matches the legacy analyzer exactly.
+ */
+const DOCUMENTATION_DEFAULTS = {
+    requireFunctionDocs: true,
+    requireClassDocs: true,
+    scope: 'public',
+    docsMinLines: 5,
+    exemptPatterns: [
+        '\\.test\\.',
+        '\\.spec\\.',
+        '\\.d\\.ts$',
+        'mock',
+        'fixture',
+        '__tests__',
+        '/tests?/',
+        '\\.tsx$',
+        '\\.jsx$',
+        '/(page|layout|loading|error|route|template|not-found|default|middleware)\\.(ts|tsx|js|jsx|mjs|cjs)$',
+    ],
+};
+/** Merge the (default-merged) thresholds onto the documentation defaults. */
+function resolveConfig(t) {
+    const merged = { ...DOCUMENTATION_DEFAULTS, ...t };
+    return {
+        ...merged,
+        scope: merged.scope ?? 'public',
+        docsMinLines: typeof merged.docsMinLines === 'number' ? merged.docsMinLines : 5,
+    };
+}
+/** One finding, in the unified shape §7 converges on. The `ruleId`/`severity`
+ *  string literals sit at every emit site so the severity-ledger conformance
+ *  scan (which pairs `ruleId:`/`severity:` object literals) sees them — the six
+ *  documentation rules all ship at `high`. */
+function finding(f) {
+    return f;
+}
+const META = RULE_REGISTRY;
+// ── R1 file-level skip (config-driven, per-symbol since each symbol carries its file) ─
+/**
+ * True when a file path matches any exempt pattern (case-insensitive regex).
+ *
+ * @param name - The file path to test.
+ * @param patterns - The exempt regex patterns.
+ * @returns True when `name` matches at least one pattern.
+ */
+export function isExempt(name, patterns) {
+    return patterns.some((pattern) => {
+        const regex = new RegExp(pattern, 'i');
+        return regex.test(name);
+    });
+}
+// ── Spec-49 documentation substance (re-homed; the legacy analyzer is deleted in §15) ─
+const PLACEHOLDER_DOC_PATTERN = /^@?\s*(TODO|FIXME|XXX|TBD|WIP|STUB|PLACEHOLDER)\b/i;
+const DOC_STOP_WORDS = new Set([
+    'the', 'a', 'an', 'this', 'that', 'these', 'those', 'and', 'or', 'of', 'to',
+    'in', 'on', 'for', 'with', 'is', 'are', 'was', 'were', 'be', 'been', 'by',
+    'as', 'at', 'from', 'it', 'its',
+]);
+/** True when the doc comment contains substantive descriptive prose. */
+function isSubstantiveDoc(doc) {
+    const raw = doc
+        .replace(/\/\*\*?|\*\//g, ' ')
+        .replace(/^\s*\*+\s?/gm, ' ');
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return false;
+    if (PLACEHOLDER_DOC_PATTERN.test(trimmed))
+        return false;
+    const prose = trimmed
+        .replace(/@\w+\s*(\{[^}]*\})?/g, ' ')
+        .replace(/[^A-Za-z0-9]+/g, ' ')
+        .toLowerCase();
+    const words = prose.split(/\s+/).filter((w) => w.length >= 2 && !DOC_STOP_WORDS.has(w));
+    return words.length > 0;
+}
+/** True when `name` is a plain identifier (valid @param target). */
+function isPlainIdentifierName(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name);
+}
+/** Which parameters are missing documentation. */
+function checkParameterDocumentation(doc, paramNames) {
+    const missingParams = [];
+    for (const param of paramNames) {
+        if (!isPlainIdentifierName(param))
+            continue;
+        const paramRegex = new RegExp(`@param\\s+(?:\\{[^}]+\\}\\s+)?${param}\\b`, 'i');
+        if (!paramRegex.test(doc)) {
+            missingParams.push(param);
+        }
+    }
+    return missingParams;
+}
+/** True when the doc comment carries a @returns/@return tag. */
+function hasReturnDocumentation(doc) {
+    return /@returns?\b/i.test(doc);
+}
+function tagEligibleItems(symbols, cfg) {
+    const out = [];
+    for (const s of symbols) {
+        if (isExempt(s.file, cfg.exemptPatterns))
+            continue;
+        if (s.kind === 'function') {
+            const f = s;
+            if (f.isAnonymousOrCallback)
+                continue;
+            if (cfg.scope === 'public' && !f.isExported)
+                continue;
+            if (f.lineCount < cfg.docsMinLines)
+                continue;
+            const doc = f.jsDoc || '';
+            if (!isSubstantiveDoc(doc))
+                continue;
+            out.push({ name: f.name, file: f.file, line: f.line, column: f.column, parameterNames: f.parameterNames, returnType: f.returnType, jsDoc: doc });
+        }
+        else if (s.kind === 'class') {
+            const cls = s;
+            for (const m of cls.methods) {
+                if (cfg.scope === 'public' && (m.isNonPublic || !cls.isExported))
+                    continue;
+                if (m.lineCount < cfg.docsMinLines)
+                    continue;
+                const doc = m.jsDoc || '';
+                if (!isSubstantiveDoc(doc))
+                    continue;
+                out.push({ name: m.name, file: cls.file, line: m.line, column: m.column, parameterNames: m.parameterNames, returnType: m.returnType, jsDoc: doc });
+            }
+        }
+    }
+    return out;
+}
+// ── function-documentation ───────────────────────────────────────────────────
+const functionDocumentation = {
+    id: 'function-documentation',
+    analyzer: 'documentation',
+    needs: { formats: ['typescript', 'tsx', 'javascript'], facts: ['file-symbols'] },
+    severity: 'high',
+    message: META['function-documentation'].message,
+    docs: META['function-documentation'].docs,
+    thresholds: META['function-documentation'].thresholds,
+    samples: META['function-documentation'].samples,
+    analyze(ctx) {
+        const cfg = resolveConfig(ctx.thresholds);
+        if (!cfg.requireFunctionDocs)
+            return [];
+        const out = [];
+        for (const s of ctx.facts['file-symbols']) {
+            if (s.kind !== 'function')
+                continue;
+            const f = s;
+            if (isExempt(f.file, cfg.exemptPatterns))
+                continue;
+            if (f.isAnonymousOrCallback)
+                continue;
+            if (cfg.scope === 'public' && !f.isExported)
+                continue;
+            if (f.lineCount < cfg.docsMinLines)
+                continue;
+            if (isSubstantiveDoc(f.jsDoc || ''))
+                continue;
+            const reason = f.isExported
+                ? `exported function '${f.name}' lacks a documentation comment`
+                : `function '${f.name}' lacks a documentation comment`;
+            out.push(finding({ ruleId: 'function-documentation', severity: 'high', message: reason, file: f.file, line: f.line, column: f.column, symbol: f.name }));
+        }
+        return out;
+    },
+};
+// ── parameter-documentation ──────────────────────────────────────────────────
+const parameterDocumentation = {
+    id: 'parameter-documentation',
+    analyzer: 'documentation',
+    needs: { formats: ['typescript', 'tsx', 'javascript'], facts: ['file-symbols'] },
+    severity: 'high',
+    message: META['parameter-documentation'].message,
+    docs: META['parameter-documentation'].docs,
+    thresholds: META['parameter-documentation'].thresholds,
+    samples: META['parameter-documentation'].samples,
+    analyze(ctx) {
+        const cfg = resolveConfig(ctx.thresholds);
+        const out = [];
+        for (const item of tagEligibleItems(ctx.facts['file-symbols'], cfg)) {
+            for (const param of checkParameterDocumentation(item.jsDoc, item.parameterNames)) {
+                out.push(finding({
+                    ruleId: 'parameter-documentation',
+                    severity: 'high',
+                    message: `Function '${item.name}' missing documentation for parameter '${param}'`,
+                    file: item.file, line: item.line, column: item.column, symbol: item.name,
+                }));
+            }
+        }
+        return out;
+    },
+};
+// ── return-documentation ─────────────────────────────────────────────────────
+const returnDocumentation = {
+    id: 'return-documentation',
+    analyzer: 'documentation',
+    needs: { formats: ['typescript', 'tsx', 'javascript'], facts: ['file-symbols'] },
+    severity: 'high',
+    message: META['return-documentation'].message,
+    docs: META['return-documentation'].docs,
+    thresholds: META['return-documentation'].thresholds,
+    samples: META['return-documentation'].samples,
+    analyze(ctx) {
+        const cfg = resolveConfig(ctx.thresholds);
+        const out = [];
+        for (const item of tagEligibleItems(ctx.facts['file-symbols'], cfg)) {
+            if (!item.returnType || item.returnType === 'void')
+                continue;
+            if (hasReturnDocumentation(item.jsDoc))
+                continue;
+            out.push(finding({
+                ruleId: 'return-documentation',
+                severity: 'high',
+                message: `Function '${item.name}' missing return value documentation`,
+                file: item.file, line: item.line, column: item.column, symbol: item.name,
+            }));
+        }
+        return out;
+    },
+};
+// ── class-documentation ──────────────────────────────────────────────────────
+const classDocumentation = {
+    id: 'class-documentation',
+    analyzer: 'documentation',
+    needs: { formats: ['typescript', 'tsx', 'javascript'], facts: ['file-symbols'] },
+    severity: 'high',
+    message: META['class-documentation'].message,
+    docs: META['class-documentation'].docs,
+    thresholds: META['class-documentation'].thresholds,
+    samples: META['class-documentation'].samples,
+    analyze(ctx) {
+        const cfg = resolveConfig(ctx.thresholds);
+        if (!cfg.requireClassDocs)
+            return [];
+        const out = [];
+        for (const s of ctx.facts['file-symbols']) {
+            if (s.kind !== 'class')
+                continue;
+            const cls = s;
+            if (isExempt(cls.file, cfg.exemptPatterns))
+                continue;
+            if (cfg.scope === 'public' && !cls.isExported)
+                continue;
+            if (isSubstantiveDoc(cls.jsDoc || ''))
+                continue;
+            out.push(finding({
+                ruleId: 'class-documentation',
+                severity: 'high',
+                message: `Class '${cls.name}' lacks a documentation comment`,
+                file: cls.file, line: cls.line, column: cls.column, symbol: cls.name,
+            }));
+        }
+        return out;
+    },
+};
+// ── method-documentation ─────────────────────────────────────────────────────
+const methodDocumentation = {
+    id: 'method-documentation',
+    analyzer: 'documentation',
+    needs: { formats: ['typescript', 'tsx', 'javascript'], facts: ['file-symbols'] },
+    severity: 'high',
+    message: META['method-documentation'].message,
+    docs: META['method-documentation'].docs,
+    thresholds: META['method-documentation'].thresholds,
+    samples: META['method-documentation'].samples,
+    analyze(ctx) {
+        const cfg = resolveConfig(ctx.thresholds);
+        // method-documentation is gated by requireFunctionDocs (matching the legacy
+        // `checkClassMethodDocumentation`), not requireClassDocs.
+        if (!cfg.requireFunctionDocs)
+            return [];
+        const out = [];
+        for (const s of ctx.facts['file-symbols']) {
+            if (s.kind !== 'class')
+                continue;
+            const cls = s;
+            if (isExempt(cls.file, cfg.exemptPatterns))
+                continue;
+            if (cfg.scope === 'public' && !cls.isExported)
+                continue;
+            for (const m of cls.methods) {
+                if (cfg.scope === 'public' && m.isNonPublic)
+                    continue;
+                if (isSubstantiveDoc(m.jsDoc || ''))
+                    continue;
+                out.push(finding({
+                    ruleId: 'method-documentation',
+                    severity: 'high',
+                    message: `public method '${cls.name}.${m.name}' lacks a documentation comment`,
+                    file: cls.file, line: m.line, column: m.column, symbol: `${cls.name}.${m.name}`,
+                }));
+            }
+        }
+        return out;
+    },
+};
+/** The five documentation rules this slice migrates, in registry order. */
+export const documentationRules = [
+    functionDocumentation,
+    parameterDocumentation,
+    returnDocumentation,
+    classDocumentation,
+    methodDocumentation,
+];
+//# sourceMappingURL=documentation.js.map

package/dist/phase/rules/documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.js","sourceRoot":"","sources":["../../../src/phase/rules/documentation.ts"],"names":[],"mappings":"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"}

package/dist/phase/rules/dry.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Spec 68 §3.2 — the DRY rules, migrated to `analyze(ctx)`.
+ *
+ * `duplicate-import` re-homes `UniversalDRYAnalyzer.checkDuplicateImports`:
+ * group the `imports` fact by `(file, source)` and flag any source imported more
+ * than once within a single file, anchored at the first import's location. The
+ * legacy detector ran per AST, so the `(file, …)` grouping is load-bearing — two
+ * files importing the same module once are not duplicates. The message and the
+ * first-import anchoring are verbatim from `checkDuplicateImports`; `symbol`
+ * carries the module source exactly as the legacy `createViolation` set
+ * `functionName` to it.
+ *
+ * `duplicate-string-literal` re-homes `checkDuplicateStrings`: group the
+ * `string-literals` fact by `(file, value)` and flag any raw string text that
+ * appears more than twice within a single file, anchored at the first
+ * occurrence. The same per-file grouping holds here (the legacy detector ran
+ * per AST), and `value` is the raw `getNodeText` (quotes included) so a
+ * `'…'` and `"…"` literal are distinct values — the same key the legacy code
+ * compared.
+ *
+ * The three block rules (`dry/duplicate`, `dry/structural-similarity`,
+ * `dry/similar-expression`) read the `code-block` fact — blocks and shape
+ * fragments the `codeBlocks.ts` producer extracted from the AST. They re-home
+ * `reportExactDuplicates` / `reportStructuralDuplicates` /
+ * `reportExpressionSimilarities` over the projected data. The legacy
+ * `analyzeAST` ran **once per file**, so each rule partitions the corpus fact by
+ * `file` and runs its filter → dedupe → compare within one file (a block in file
+ * A is never compared against a block in file B).
+ *
+ * `dry/diverging-clone` is the cross-run pair-tracking pass (Spec 13 R5): it
+ * reads the `clone-pair-history` fact — the `dry_pair_history` similarity series
+ * the DRY bundle seeds each run — and flags a pair whose similarity has fallen by
+ * `divergenceThreshold` for `divergenceRuns` consecutive runs. It re-homes the
+ * legacy auditRunner Phase 2 divergence pass verbatim, over the grouped fact.
+ */
+import type { RuleDefinition, CodeBlockFact, ThresholdValues } from '../types.js';
+/** The shared declaration for the one import-servable DRY rule. */
+type DryNeeds = {
+    readonly formats: readonly ['typescript', 'tsx', 'javascript'];
+    readonly facts: readonly ['imports'];
+};
+/** The declaration for the string-literal-servable DRY rule. */
+type StringLiteralNeeds = {
+    readonly formats: readonly ['typescript', 'tsx', 'javascript'];
+    readonly facts: readonly ['string-literals'];
+};
+/** The declaration for the three code-block-servable DRY rules. */
+type CodeBlockNeeds = {
+    readonly formats: readonly ['typescript', 'tsx', 'javascript'];
+    readonly facts: readonly ['code-block'];
+};
+/** The declaration for the clone-pair-history-servable DRY rule. */
+type ClonePairNeeds = {
+    readonly formats: readonly ['typescript', 'tsx', 'javascript'];
+    readonly facts: readonly ['clone-pair-history'];
+};
+/** Config surface the three block rules read (subset of `DRYAnalyzerConfig`). */
+export interface DryBlockConfig {
+    minLineThreshold?: number;
+    similarityThreshold?: number;
+    excludePatterns?: string[];
+    checkStructuralSimilarity?: boolean;
+    checkExpressionSimilarity?: boolean;
+    minShapeNames?: number;
+}
+/** Merge the (default-merged) thresholds onto the block defaults. */
+export declare function resolveBlockConfig(t: ThresholdValues): DryBlockConfig;
+/** One duplicate/structure pair seeded into `dry_pair_history`, re-homing the
+ *  legacy `UniversalDRYAnalyzer.seedPair` output. `rule` is the legacy tag
+ *  (`dry/duplicate` | `dry/structural-similarity`) and is not written to the
+ *  table — the writer reads only the ten anchor/hash/similarity fields. */
+export interface DryPairSeed {
+    pairFingerprint: string;
+    file1: string;
+    symbol1: string;
+    line1: number;
+    contentHash1: string;
+    file2: string;
+    symbol2: string;
+    line2: number;
+    contentHash2: string;
+    similarity: number;
+    rule: string;
+}
+/**
+ * Seed the `dry_pair_history` rows the legacy `createDryVisitor` accumulated,
+ * from the phase `code-block` fact. This re-homes the pair half of the legacy
+ * `analyzeAST` — per-file filter → dedupe → compare — over the projected data,
+ * and writes the *legacy* gates:
+ *
+ *   - exact-duplicate pairs (`dry/duplicate`, similarity 1.0) always seed;
+ *   - structural pairs (`dry/structural-similarity`) seed only when
+ *     `checkStructuralSimilarity` is true, with the legacy bare-token-set Jaccard
+ *     (not the migrated rule's bigram) and the legacy `similarityThreshold`.
+ *
+ * The three block *rules* re-apply `minLineThreshold`/`similarityThreshold` in
+ * `detectExactDuplicates`/`detectStructuralDuplicates`; the seed repeats the
+ * same per-file filter/dedupe so the written `(fingerprint, contentHash, line)`
+ * tuple is byte-identical to what the legacy visitor accumulated.
+ *
+ * @param codeBlocks - The assembled `code-block` corpus fact.
+ * @param config - The default-merged dry config (the rule's `resolveBlockConfig`).
+ * @returns The seeded pairs, in per-file walk order.
+ */
+export declare function seedDryPairs(codeBlocks: readonly CodeBlockFact[], config: DryBlockConfig): DryPairSeed[];
+/** The DRY rules, in registry order. */
+export declare const dryRules: readonly RuleDefinition<DryNeeds | StringLiteralNeeds | CodeBlockNeeds | ClonePairNeeds>[];
+export {};
+//# sourceMappingURL=dry.d.ts.map

package/dist/phase/rules/dry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dry.d.ts","sourceRoot":"","sources":["../../../src/phase/rules/dry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EACV,cAAc,EAId,aAAa,EAIb,eAAe,EAChB,MAAM,aAAa,CAAC;AAWrB,mEAAmE;AACnE,KAAK,QAAQ,GAAG;IACd,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CACtC,CAAC;AAEF,gEAAgE;AAChE,KAAK,kBAAkB,GAAG;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,iBAAiB,CAAC,CAAC;CAC9C,CAAC;AAEF,mEAAmE;AACnE,KAAK,cAAc,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,YAAY,CAAC,CAAC;CACzC,CAAC;AAEF,oEAAoE;AACpE,KAAK,cAAc,GAAG;IACpB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,CAAC;CACjD,CAAC;AA4HF,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAyBD,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,eAAe,GAAG,cAAc,CAErE;AAgXD;;;2EAG2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAgCD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,EAAE,cAAc,GAAG,WAAW,EAAE,CA4DxG;AAwKD,wCAAwC;AACxC,eAAO,MAAM,QAAQ,EAAE,SAAS,cAAc,CAAC,QAAQ,GAAG,kBAAkB,GAAG,cAAc,GAAG,cAAc,CAAC,EAO9G,CAAC"}