code-auditor-mcp 3.6.0 → 3.8.0

package/dist/analyzers/universal/UniversalDRYAnalyzer.js

@@ -17,7 +17,21 @@ export const DEFAULT_DRY_CONFIG = {
     // R3.2: floor raised from 5 → 15
     minLineThreshold: 15,
     similarityThreshold: 0.85,
-    excludePatterns: ['**/*.test.ts', '**/*.spec.ts'],
+    // Test files and test directories are excluded by convention in any language:
+    // `.test.*`/`.spec.*` in TS/TSX/JS/JSX, plus `test/` and `tests/` directories.
+    // Expected-output fixtures and repeated setup are not production duplication,
+    // and a JS library (knex) names its tests `.js` under `test/`, which the
+    // earlier TS-only patterns missed (132 fixture-object findings). `__tests__/`
+    // is deliberately NOT excluded: this very repo keeps analyzable source
+    // fixtures under `__tests__/fixtures/`, and Jest's `__tests__` files are
+    // still `.test.*`/`.spec.*` named, so the filename patterns cover them.
+    excludePatterns: [
+        '**/*.test.ts', '**/*.spec.ts',
+        '**/*.test.tsx', '**/*.spec.tsx',
+        '**/*.test.js', '**/*.spec.js',
+        '**/*.test.jsx', '**/*.spec.jsx',
+        '**/test/**', '**/tests/**',
+    ],
     // R4.1: sub-rules disabled by default
     checkImports: false,
     checkStrings: false,
@@ -25,6 +39,15 @@ export const DEFAULT_DRY_CONFIG = {
     ignoreWhitespace: true,
     // R4.2: structural similarity off by default
     checkStructuralSimilarity: false,
+    // #132: expression similarity ON by default. Fluent library/builder chains
+    // (query builders, schema builders, Zod validators, commander, promises, DOM
+    // and stdlib method chains) are filtered out of the signal — they are the
+    // library's API surface, not duplicated logic — and unrelated schema literals
+    // are excluded by requiring object literals to target the same identifier. So
+    // the rule fires on real duplication — `resultSummary` built twice — without
+    // flooding a default audit.
+    checkExpressionSimilarity: true,
+    minShapeNames: 4,
 };
 // ── R3.1: Span-overlap helpers ──────────────────────────────────────
 /**
@@ -86,6 +109,248 @@ function deduplicateBlocks(blocks) {
     }
     return result;
 }
+/** True when `outer`'s span fully contains `inner`'s span in the same file. */
+function shapeSpansContain(outer, inner) {
+    if (outer.file !== inner.file)
+        return false;
+    const startLte = outer.start.line < inner.start.line ||
+        (outer.start.line === inner.start.line && outer.start.column <= inner.start.column);
+    const endGte = outer.end.line > inner.end.line ||
+        (outer.end.line === inner.end.line && outer.end.column >= inner.end.column);
+    return startLte && endGte;
+}
+/**
+ * Drop nested fragments, keeping the outermost. A fluent chain visits its outer
+ * call first, then each suffix chain (`a().b()` vs `a().b().c()` share a start
+ * position but the outer span is longer); a nested object literal is fully
+ * contained in its parent. Sort puts the widest span first so the inner suffix
+ * is skipped as contained.
+ */
+function dedupeShapeFragments(fragments) {
+    const sorted = [...fragments].sort((a, b) => {
+        if (a.file !== b.file)
+            return a.file.localeCompare(b.file);
+        if (a.start.line !== b.start.line)
+            return a.start.line - b.start.line;
+        if (a.start.column !== b.start.column)
+            return a.start.column - b.start.column;
+        // Same start → outermost (largest end) first.
+        if (a.end.line !== b.end.line)
+            return b.end.line - a.end.line;
+        return b.end.column - a.end.column;
+    });
+    const kept = [];
+    for (const f of sorted) {
+        if (!kept.some((k) => shapeSpansContain(k, f)))
+            kept.push(f);
+    }
+    return kept;
+}
+/** Strip one layer of quotes from a string-literal object key. */
+function bareKeyName(key, getText) {
+    let t = getText(key).trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        t = t.slice(1, -1);
+    }
+    return t;
+}
+/**
+ * Field names of an object literal, in source order. Handles `{ a: 1 }`
+ * (`pair` → key child) and `{ a }` (`shorthand_property_identifier`).
+ */
+function objectFieldNames(node, getText) {
+    const names = [];
+    for (const child of node.children ?? []) {
+        if (child.type === 'pair') {
+            const key = child.children?.[0];
+            if (key) {
+                const name = bareKeyName(key, getText);
+                if (name)
+                    names.push(name);
+            }
+        }
+        else if (child.type === 'shorthand_property_identifier') {
+            const name = getText(child).trim();
+            if (name)
+                names.push(name);
+        }
+    }
+    return names;
+}
+/**
+ * Method names of a fluent call chain (`db.update().set().where().returning()`),
+ * in call order. Walks `call_expression` → `member_expression` callee chain,
+ * collecting each `.method` name and recursing into the chain's receiver until
+ * a bare identifier is reached. Returns [] for a bare (non-member) call.
+ */
+function callChainMethodNames(node, getText) {
+    const names = [];
+    let current = node;
+    while (current && current.type === 'call_expression') {
+        const callee = current.children?.[0];
+        if (!callee)
+            break;
+        if (callee.type === 'member_expression') {
+            const prop = callee.children?.find((c) => c.type === 'property_identifier');
+            if (!prop)
+                break;
+            names.push(getText(prop).trim());
+            current = callee.children?.[0];
+        }
+        else if (callee.type === 'call_expression') {
+            current = callee; // curried/IIFE — skip the anonymous level, keep walking
+        }
+        else {
+            break; // bare identifier callee — end of the chain
+        }
+    }
+    return names.reverse();
+}
+/**
+ * Method names from well-known fluent APIs. A chain built from these verbs is
+ * "structurally similar by design" — it is the library's public surface, not
+ * duplicated domain logic — so the default-on rule stays quiet on it.
+ *
+ * The first version excluded only `select`/`selectDistinct` on the theory that
+ * read queries are idiomatic but mutation chains (`update().set().where()`)
+ * are the real signal. Corpus measurement disproved that theory: the chains
+ * that actually fire are Zod validators (`string().trim().min().max()`),
+ * query/schema builders (`insert().onConflict().ignore()`,
+ * `integer().unsigned().references()`), commander registrations
+ * (`command().option().action()`), promise flows (`then().then().catch()`),
+ * DOM/JQuery traversal (`closest().find().first().text()`), and stdlib
+ * array/string method chains — all library API, none duplicated logic. The
+ * object-literal half of the rule (a *specific* object built twice, keyed by
+ * target) is where the real signal lives and is unaffected by this exclusion.
+ */
+const FLUENT_CHAIN_METHODS = new Set([
+    // SQL query builders (knex, Kysely, Drizzle, …)
+    'select', 'selectDistinct', 'from', 'where', 'andWhere', 'orWhere', 'whereRaw',
+    'whereIn', 'whereNotIn', 'whereNull', 'whereNotNull', 'whereExists', 'whereBetween',
+    'orderBy', 'groupBy', 'having', 'join', 'innerJoin', 'leftJoin', 'rightJoin',
+    'crossJoin', 'fullOuterJoin', 'limit', 'offset', 'distinct', 'count', 'sum', 'avg',
+    'first', 'pluck', 'forUpdate', 'forShare', 'skipLocked', 'union', 'unionAll',
+    'insert', 'update', 'del', 'delete', 'into', 'returning', 'onConflict', 'ignore',
+    'merge', 'increment', 'decrement', 'transacting', 'using', 'updateFrom', 'testSql',
+    'toSQL', 'toQuery', 'raw', 'table', 'schemaBuilder', 'queryBuilder', 'partitionBy',
+    // Schema builders (knex `table.integer().unsigned().references()`)
+    'createTable', 'alterTable', 'dropTable', 'dropTableIfExists', 'renameTable',
+    'renameColumn', 'dropColumn', 'integer', 'bigInteger', 'text', 'boolean', 'float',
+    'double', 'decimal', 'date', 'dateTime', 'timestamp', 'timestamps', 'time',
+    'binary', 'json', 'jsonb', 'uuid', 'unsigned', 'references', 'inTable', 'defaultTo',
+    'index', 'unique', 'primary', 'comment', 'foreign', 'onDelete', 'onUpdate',
+    'deferrable', 'withKeyName', 'notNullable', 'collate', 'check',
+    // Zod / Valibot schema validators
+    'trim', 'min', 'max', 'length', 'int', 'positive', 'nonnegative', 'negative',
+    'regex', 'email', 'url', 'datetime', 'optional', 'nullish', 'nullable', 'default',
+    'describe', 'refine', 'superRefine', 'transform', 'safeParse', 'parse', 'array',
+    'object', 'enum', 'record', 'union', 'intersection', 'tuple', 'literal', 'number',
+    'string', 'nativeEnum', 'lazy', 'preprocess', 'brand',
+    // commander / CLI builders
+    'command', 'description', 'option', 'requiredOption', 'action', 'argument',
+    'version', 'usage', 'name', 'alias', 'allowUnknownOption', 'exitOverride',
+    // Promises
+    'then', 'catch', 'finally',
+    // DOM / jQuery traversal and JS stdlib array/string method chains
+    'closest', 'find', 'text', 'map', 'filter', 'reduce', 'forEach', 'slice', 'split',
+    'join', 'replace', 'replaceAll', 'toLowerCase', 'toUpperCase', 'flatMap', 'concat',
+]);
+/** True when the chain is a fluent library/builder API (not duplicated logic). */
+function isFluentChain(names) {
+    return names.some((n) => FLUENT_CHAIN_METHODS.has(n));
+}
+/**
+ * Extract shape fragments (object literals + fluent call chains) from the AST.
+ *
+ * Object literals are only collected as the *direct value* of a declaration
+ * (`const x = {...}`) or assignment (`info.resultSummary = {...}`), and carry
+ * that target. Two literals must target the same identifier to be compared —
+ * this keeps `pgTable('users', {...})` / `pgTable('orders', {...})` (different
+ * targets, shared `id`/`createdAt` column names) out of the "built twice" set.
+ *
+ * Chains are collected from every `call_expression`, excluding fluent
+ * library/builder APIs. Fragments are filtered to `minShapeNames` names and
+ * deduplicated to the outermost span.
+ */
+function extractShapeFragments(ctx, minShapeNames) {
+    const fragments = [];
+    const getText = (node) => ctx.adapter.getNodeText(node, ctx.sourceCode);
+    const collectObject = (node, target) => {
+        const names = objectFieldNames(node, getText);
+        if (names.length < minShapeNames)
+            return;
+        fragments.push({
+            file: ctx.ast.filePath,
+            start: node.location.start,
+            end: node.location.end,
+            kind: 'object',
+            target,
+            names,
+            text: getText(node),
+        });
+    };
+    walkAST(ctx.ast.root, (node) => {
+        if (node.type === 'variable_declarator') {
+            // `const name: T = value` — target is the declarator name, value the last child.
+            const name = node.children?.[0];
+            const value = node.children?.[node.children.length - 1];
+            if (name && value?.type === 'object')
+                collectObject(value, getText(name));
+        }
+        else if (node.type === 'assignment_expression') {
+            // `target = value` — target is the left-hand side, value the last child.
+            const left = node.children?.[0];
+            const value = node.children?.[node.children.length - 1];
+            if (left && value?.type === 'object')
+                collectObject(value, getText(left));
+        }
+        else if (node.type === 'call_expression') {
+            const names = callChainMethodNames(node, getText);
+            if (names.length < minShapeNames || isFluentChain(names))
+                return;
+            fragments.push({
+                file: ctx.ast.filePath,
+                start: node.location.start,
+                end: node.location.end,
+                kind: 'chain',
+                names,
+                text: getText(node),
+            });
+        }
+    });
+    return dedupeShapeFragments(fragments);
+}
+/**
+ * Longest common subsequence of two string arrays, returned as the actual
+ * shared sequence (so the violation message can name the shared fields/methods).
+ */
+function longestCommonSubsequence(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] + 1 : Math.max(dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    const seq = [];
+    let i = m;
+    let j = n;
+    while (i > 0 && j > 0) {
+        if (a[i - 1] === b[j - 1]) {
+            seq.push(a[i - 1]);
+            i--;
+            j--;
+        }
+        else if (dp[i - 1][j] >= dp[i][j - 1]) {
+            i--;
+        }
+        else {
+            j--;
+        }
+    }
+    return seq.reverse();
+}
 // ── R3.3: Structural similarity helpers ──────────────────────────────
 /**
  * Group blocks by a key field into a map of key→blocks[].
@@ -216,7 +481,13 @@ function computePairFingerprint(original, block) {
  * Find a node by its location via BFS.
  */
 function findNodeByLocation(root, location) {
-    const queue = [root];
+    // Search from the root's children, never the root itself. The root is a
+    // whole-file wrapper (`program`/`source_file`) whose start location collides
+    // with its first top-level child (a non-`export`ed declaration starts at
+    // column 1, the same as the wrapper). Returning the wrapper for the first
+    // top-level declaration made `deduplicateBlocks` absorb it as an outer block,
+    // silently dropping the file's first declaration from comparison.
+    const queue = [...(root.children ?? [])];
     while (queue.length > 0) {
         const node = queue.shift();
         if (node.location.start.line === location.line &&
@@ -230,13 +501,48 @@ function findNodeByLocation(root, location) {
     return null;
 }
 /**
- * Check whether a file path matches any of the given glob-ish exclude patterns.
+ * Translate a minimal glob (`*`, `**`, `?`) to an anchored regex. A globstar
+ * (`**`) matches any run of characters including the path separator, and a
+ * globstar followed by a slash becomes an optional segment prefix so it also
+ * matches zero path segments (e.g. `test/` at the root of a relative path).
+ * `*` and `?` match within a single segment.
  */
+function globToRegExp(pattern) {
+    const out = ['^'];
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                i += 1; // consume the second `*`
+                if (pattern[i + 1] === '/') {
+                    i += 1; // fold a trailing `/` into the globstar
+                    out.push('(?:.*/)?');
+                }
+                else {
+                    out.push('.*');
+                }
+            }
+            else {
+                out.push('[^/]*');
+            }
+        }
+        else if (ch === '?') {
+            out.push('[^/]');
+        }
+        else if ('^$\\.+?()[]{}|'.includes(ch)) {
+            out.push('\\', ch);
+        }
+        else {
+            out.push(ch);
+        }
+    }
+    out.push('$');
+    return new RegExp(out.join(''));
+}
+/** Check whether a file path matches any of the given glob-ish exclude patterns. */
 function isExcluded(filePath, patterns) {
-    return patterns.some(pattern => {
-        const regex = new RegExp(pattern.replace(/\*/g, '.*'));
-        return regex.test(filePath);
-    });
+    const normalized = filePath.replace(/\\/g, '/');
+    return patterns.some(pattern => globToRegExp(pattern).test(normalized));
 }
 /**
  * Walk the AST depth-first, invoking the callback on every node.
@@ -269,8 +575,9 @@ function createCodeBlock(ctx, node) {
         return null;
     const normalizedText = normalizeCode(text, ctx.config);
     const lineCount = countLines(text);
-    // R3.3: Compute structural hash from token-kind sequence
-    const structuralHash = hashCode(normalizeCodeForStructure(text, ctx.config));
+    // R3.3: Compute structural hash + skeleton from token-kind sequence
+    const structuralSkeleton = normalizeCodeForStructure(text, ctx.config);
+    const structuralHash = hashCode(structuralSkeleton);
     return {
         file: ctx.ast.filePath,
         start: node.location.start,
@@ -279,6 +586,7 @@ function createCodeBlock(ctx, node) {
         normalizedText,
         hash: hashCode(normalizedText),
         structuralHash,
+        structuralSkeleton,
         nodeType: node.type,
         lineCount
     };
@@ -353,7 +661,12 @@ export class UniversalDRYAnalyzer extends UniversalAnalyzer {
         const deduped = deduplicateBlocks(blocks);
         this.reportExactDuplicates(deduped, violations);
         if (finalConfig.checkStructuralSimilarity) {
-            this.reportStructuralDuplicates(deduped, violations);
+            this.reportStructuralDuplicates(deduped, finalConfig, violations);
+        }
+        // #132: near-identical object literals and fluent call chains
+        if (finalConfig.checkExpressionSimilarity) {
+            const fragments = extractShapeFragments(ctx, finalConfig.minShapeNames || 4);
+            this.reportExpressionSimilarities(fragments, finalConfig, violations);
         }
         this.reportCrossFileDuplicates(blocks, finalConfig, violations);
         // Check for duplicate string literals if enabled
@@ -404,39 +717,114 @@ export class UniversalDRYAnalyzer extends UniversalAnalyzer {
         });
     }
     /**
-     * Report token-kind-identical duplicates (dry/structural-similarity, suggestion).
+     * Report structurally-similar duplicates (dry/structural-similarity, suggestion).
+     *
+     * Compares every pair of blocks by the Jaccard similarity of their token-kind
+     * skeletons (identifiers→ID, literals→LIT) and reports those at or above
+     * `similarityThreshold`. This is the honest version of the rule: it detects
+     * "≥ N% structurally similar" (as the registry's `{similarity}%` message and
+     * `similarityThreshold` claim), not merely "structurally identical" — and it
+     * reports the structural percentage, not a text percentage computed over the
+     * raw identifiers/literals.
      */
-    reportStructuralDuplicates(deduped, violations) {
-        const structuralHashmap = groupByHash(deduped, 'structuralHash');
-        for (const [, group] of structuralHashmap) {
-            if (group.length < 2)
-                continue;
-            const sorted = [...group].sort(byFileAndLine);
-            const original = sorted[0];
-            for (let i = 1; i < sorted.length; i++) {
-                const block = sorted[i];
-                // Skip if these are already exact duplicates (reported above)
-                if (original.hash === block.hash)
-                    continue;
-                // R3.1: Span-overlap check
-                if (spansOverlap(original, block))
+    reportStructuralDuplicates(deduped, config, violations) {
+        withRuleTiming('dry/structural-similarity', () => {
+            const threshold = config.similarityThreshold ?? 0.85;
+            // deduped is sorted by (file, line); iterate the upper triangle so each
+            // pair is considered exactly once, earlier block first.
+            for (let i = 0; i < deduped.length; i++) {
+                const original = deduped[i];
+                for (let j = i + 1; j < deduped.length; j++) {
+                    const block = deduped[j];
+                    // Skip if these are already exact duplicates (reported above)
+                    if (original.hash === block.hash)
+                        continue;
+                    // R3.1: Span-overlap check
+                    if (spansOverlap(original, block))
+                        continue;
+                    // Structural Jaccard over the token-kind skeletons — the percentage the
+                    // registry message promises, and the gate the similarityThreshold sets.
+                    const similarity = computeJaccardSimilarity(original.structuralSkeleton, block.structuralSkeleton);
+                    if (similarity < threshold)
+                        continue;
+                    const violation = this.createViolation(block.file, block.start, `Structurally similar code block detected (${Math.round(similarity * 100)}% similar). ` +
+                        `First occurrence at ${original.file}:${original.start.line}`, { severity: 'suggestion', rule: 'dry/structural-similarity', symbol: block.hash } // R7
+                    );
+                    violation.fix = {
+                        oldText: block.text,
+                        newText: `// Consider extracting to a shared function`
+                    };
+                    violations.push(violation);
+                    // Spec 13 R5 — seed pair for diverging-clone tracking
+                    this.seedPair(original, block, similarity, 'dry/structural-similarity');
+                }
+            }
+        });
+    }
+    /**
+     * Report near-identical expression shapes (dry/similar-expression, suggestion).
+     *
+     * Two fragments are "near-identical" when their field/method-name sequence
+     * shares a common subsequence of at least `minShapeNames` names — the same
+     * `resultSummary` object built twice, the same `.update().set().where()`
+     * chain repeated across switch arms. Each later fragment is reported at most
+     * once, against the earliest fragment it resembles.
+     */
+    reportExpressionSimilarities(fragments, config, violations) {
+        withRuleTiming('dry/similar-expression', () => {
+            const min = config.minShapeNames || 4;
+            const reported = new Set();
+            for (let j = 1; j < fragments.length; j++) {
+                if (reported.has(j))
                     continue;
-                // Compute the Jaccard similarity up front so the message can render the
-                // actual percentage ({similarity}% in the registry template), rather
-                // than a line count standing in for it.
-                const jaccardSim = computeJaccardSimilarity(original.normalizedText, block.normalizedText);
-                const violation = this.createViolation(block.file, block.start, `Structurally similar code block detected (${Math.round(jaccardSim * 100)}% similar). ` +
-                    `First occurrence at ${original.file}:${original.start.line}`, { severity: 'suggestion', rule: 'dry/structural-similarity', symbol: block.hash } // R7
-                );
-                violation.fix = {
-                    oldText: block.text,
-                    newText: `// Consider extracting to a shared function`
-                };
-                violations.push(violation);
-                // Spec 13 R5 — seed pair for diverging-clone tracking
-                this.seedPair(original, block, jaccardSim, 'dry/structural-similarity');
+                for (let i = 0; i < j; i++) {
+                    // Only compare like-with-like: a field list and a method chain are
+                    // different shapes and should never be flagged as "near-identical".
+                    if (fragments[i].kind !== fragments[j].kind)
+                        continue;
+                    // Object literals must target the same identifier (`info.resultSummary`
+                    // built twice), not merely two unrelated literals that share column
+                    // names. Chains have no target (undefined === undefined).
+                    if (fragments[i].target !== fragments[j].target)
+                        continue;
+                    const shared = longestCommonSubsequence(fragments[i].names, fragments[j].names);
+                    if (shared.length < min)
+                        continue;
+                    violations.push(this.buildSimilarityViolation(fragments[j], fragments[i], shared));
+                    reported.add(j);
+                    break;
+                }
             }
-        }
+        });
+    }
+    /**
+     * Build the `dry/similar-expression` violation for `fragment` (the later
+     * fragment) resembling `first` (the earliest).
+     */
+    buildSimilarityViolation(fragment, first, shared) {
+        const isObject = fragment.kind === 'object';
+        const label = isObject ? 'object literal' : 'call chain';
+        const unit = isObject ? 'fields' : 'methods';
+        const targetClause = isObject && fragment.target
+            ? ` built for "${fragment.target}"`
+            : '';
+        const violation = this.createViolation(fragment.file, fragment.start, `Near-identical ${label}${targetClause} detected (${shared.length} shared ${unit}: ${shared.join(', ')}). ` +
+            `First occurrence at ${first.file}:${first.start.line}`, {
+            severity: 'suggestion',
+            rule: 'dry/similar-expression',
+            symbol: shared.join('.'),
+            resolution: {
+                action: 'extract-shared-expression',
+                summary: `Extract the shared ${isObject ? 'field list' : 'method chain'} (${shared.join(', ')}) into a shared helper, builder, or constant both sites use.`,
+                files: [fragment.file, first.file],
+                lines: [fragment.start.line, first.start.line],
+            },
+        });
+        violation.fix = {
+            oldText: fragment.text,
+            newText: `// Consider extracting the shared ${unit} into a shared helper`,
+        };
+        return violation;
     }
     /**
      * Report blocks that duplicate a function body from the full codebase index.
@@ -531,18 +919,19 @@ export class UniversalDRYAnalyzer extends UniversalAnalyzer {
      */
     checkDuplicateImports(ast, adapter) {
         const violations = [];
-        const importMap = new Map();
+        // source → locations of every import of that source, in encounter order.
+        const importLocs = new Map();
         // Find all import statements
         const imports = adapter.extractImports(ast);
         for (const imp of imports) {
-            const count = importMap.get(imp.source) || 0;
-            importMap.set(imp.source, count + 1);
+            const locs = importLocs.get(imp.source) ?? [];
+            locs.push(imp.location.start);
+            importLocs.set(imp.source, locs);
         }
-        // Report duplicates
-        for (const [source, count] of importMap) {
-            if (count > 1) {
-                violations.push(this.createViolation(ast.filePath, { line: 1, column: 1 }, // Import section is typically at the top
-                `Module "${source}" is imported ${count} times`, { severity: 'warning', rule: 'duplicate-import', symbol: source }));
+        // Report duplicates at the real first-import location (not a fabricated 1:1).
+        for (const [source, locs] of importLocs) {
+            if (locs.length > 1) {
+                violations.push(this.createViolation(ast.filePath, locs[0], `Module "${source}" is imported ${locs.length} times`, { severity: 'warning', rule: 'duplicate-import', symbol: source }));
             }
         }
         return violations;