@booyaka/mcp-vet 0.2.0

package/dist/reporters.js

@@ -0,0 +1,253 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportTerminal = reportTerminal;
+exports.renderMarkdown = renderMarkdown;
+exports.writeMarkdown = writeMarkdown;
+exports.toPublicFinding = toPublicFinding;
+exports.renderJson = renderJson;
+exports.writeJson = writeJson;
+exports.printGithubAnnotations = printGithubAnnotations;
+exports.renderSarif = renderSarif;
+exports.writeSarif = writeSarif;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const chalk_1 = __importDefault(require("chalk"));
+const types_1 = require("./types");
+const rules_1 = require("./rules");
+const constants_1 = require("./constants");
+function makeChalk(color) {
+    // color === true -> force on; false -> force off; undefined -> auto-detect
+    if (color === true)
+        return new chalk_1.default.Instance({ level: 1 });
+    if (color === false)
+        return new chalk_1.default.Instance({ level: 0 });
+    return new chalk_1.default.Instance({});
+}
+function indent(text, pad) {
+    return text
+        .split('\n')
+        .map((l) => pad + l)
+        .join('\n');
+}
+function countBySeverity(findings) {
+    const breaking = findings.filter((f) => f.severity === 'BREAKING').length;
+    return { breaking, deprecated: findings.length - breaking };
+}
+/** (a) Terminal report — red for BREAKING, yellow for DEPRECATED, compiler-style. */
+function reportTerminal(result, opts = {}) {
+    const c = makeChalk(opts.color);
+    const { findings } = result;
+    if (result.pythonMode === 'none') {
+        console.error(c.yellow(`warning: ${result.pythonFilesFound} Python file(s) found but no Python interpreter was available and --no-py-fallback was set — .py files were not scanned.`));
+    }
+    else if (result.pythonMode === 'regex') {
+        console.error(c.yellow(`warning: no Python interpreter found — scanned ${result.pythonFilesFound} .py file(s) with the regex fallback (reduced precision).`));
+    }
+    for (const rel of result.skippedLargeFiles) {
+        console.error(c.yellow(`warning: skipped large file ${rel} (exceeds --max-file-size).`));
+    }
+    if (findings.length === 0) {
+        const suffix = result.suppressedCount > 0 ? ` (${result.suppressedCount} suppressed)` : '';
+        console.log(c.green('✔ mcp-vet: no matching 2026-07-28 breaking or deprecated patterns found') +
+            c.gray(` — ${result.filesScanned} file(s) scanned${suffix}`));
+        return;
+    }
+    let currentFile = '';
+    for (const f of findings) {
+        if (f.file !== currentFile) {
+            currentFile = f.file;
+            console.log('');
+            console.log(c.underline(f.file));
+        }
+        const sev = f.severity === 'BREAKING' ? c.red.bold('BREAKING') : c.yellow.bold('DEPRECATED');
+        const loc = c.cyan(`${f.file}:${f.line}${f.column ? ':' + f.column : ''}`);
+        const conf = c.gray(`[${f.confidence}]`);
+        console.log(`${loc}  ${sev}  ${c.bold(f.patternId)} ${conf}`);
+        console.log(indent(f.explanation, '    '));
+        console.log(c.gray('    — before:'));
+        console.log(indent(f.before, '      '));
+        console.log(c.gray('    + after:'));
+        console.log(c.green(indent(f.after, '      ')));
+    }
+    console.log('');
+    const { breaking, deprecated } = countBySeverity(findings);
+    const summary = `${findings.length} finding(s): ${breaking} BREAKING, ${deprecated} DEPRECATED`;
+    const suppressed = result.suppressedCount > 0 ? c.gray(` (${result.suppressedCount} suppressed)`) : '';
+    console.log((breaking > 0 ? c.red.bold(summary) : c.yellow.bold(summary)) + suppressed);
+    console.log(c.gray(`See ${constants_1.SPEC_URL}`));
+}
+function mdEscape(s) {
+    return s.replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+/** (b) Markdown table report. */
+function renderMarkdown(result) {
+    const { findings } = result;
+    const { breaking, deprecated } = countBySeverity(findings);
+    const lines = [];
+    lines.push('# mcp-vet report');
+    lines.push('');
+    lines.push(`Scan for patterns that break under the [MCP 2026-07-28 spec release candidate](${constants_1.SPEC_URL}) (ships final **${constants_1.SPEC_DATE}**).`);
+    lines.push('');
+    lines.push(`**${findings.length} finding(s):** ${breaking} BREAKING, ${deprecated} DEPRECATED` +
+        (result.suppressedCount ? ` · ${result.suppressedCount} suppressed` : '') +
+        `.`);
+    lines.push('');
+    lines.push('| File | Line | Pattern | Severity | Confidence | Explanation |');
+    lines.push('| --- | ---: | --- | --- | --- | --- |');
+    for (const f of findings) {
+        lines.push(`| \`${mdEscape(f.file)}\` | ${f.line} | ${f.patternId} | ${f.severity} | ${f.confidence} | ${mdEscape(f.explanation)} |`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function writeMarkdown(result, outDir) {
+    const outPath = path.join(outDir, 'mcp-vet-report.md');
+    fs.writeFileSync(outPath, renderMarkdown(result), 'utf8');
+    return outPath;
+}
+/** Public projection of a finding for serialized output (drops internal fields). */
+function toPublicFinding(f) {
+    return {
+        file: f.file,
+        line: f.line,
+        column: f.column ?? null,
+        endColumn: f.endColumn ?? null,
+        patternId: f.patternId,
+        patternLabel: f.patternLabel,
+        severity: f.severity,
+        confidence: f.confidence,
+        explanation: f.explanation,
+        docUrl: f.docUrl,
+        source: f.source ?? null,
+        before: f.before,
+        after: f.after,
+    };
+}
+/** (c) Structured JSON array of all findings. */
+function renderJson(result) {
+    return JSON.stringify(result.findings.map(toPublicFinding), null, 2);
+}
+function writeJson(result, outDir) {
+    const outPath = path.join(outDir, 'mcp-vet-results.json');
+    fs.writeFileSync(outPath, renderJson(result), 'utf8');
+    return outPath;
+}
+/** (d) GitHub Actions native annotations. ::error for BREAKING, ::warning for DEPRECATED. */
+function printGithubAnnotations(findings) {
+    for (const f of findings) {
+        const level = f.severity === 'BREAKING' ? 'error' : 'warning';
+        const msg = `${f.patternId} - ${f.explanation}`.replace(/\r?\n/g, ' ');
+        const col = f.column ? `,col=${f.column}` : '';
+        console.log(`::${level} file=${f.file},line=${f.line}${col}::${msg}`);
+    }
+}
+function sarifLevel(sev) {
+    return sev === 'BREAKING' ? 'error' : 'warning';
+}
+/** (e) SARIF 2.1.0 for GitHub code scanning / other SARIF consumers. */
+function renderSarif(result) {
+    const cwd = process.cwd();
+    const rules = types_1.ALL_PATTERN_IDS.map((id) => {
+        const r = rules_1.RULES[id];
+        return {
+            id,
+            name: r.label.replace(/\s+/g, ''),
+            shortDescription: { text: r.label },
+            fullDescription: { text: r.explanation },
+            helpUri: constants_1.SPEC_URL,
+            defaultConfiguration: { level: sarifLevel(r.severity) },
+            properties: { severity: r.severity },
+        };
+    });
+    const results = result.findings.map((f) => {
+        // Prefer a cwd-relative posix uri; if the file lives outside cwd (relative
+        // path escapes with "..") fall back to the scan-root-relative path, which
+        // GitHub code scanning accepts.
+        let uri = f.file;
+        if (f.absPath) {
+            const relToCwd = toPosix(path.relative(cwd, f.absPath));
+            if (relToCwd && !relToCwd.startsWith('..'))
+                uri = relToCwd;
+        }
+        const region = { startLine: f.line };
+        if (f.column)
+            region.startColumn = f.column;
+        if (f.endColumn)
+            region.endColumn = f.endColumn;
+        return {
+            ruleId: f.patternId,
+            level: sarifLevel(f.severity),
+            message: { text: `${f.patternId}: ${f.explanation}` },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: { uri },
+                        region,
+                    },
+                },
+            ],
+            properties: { confidence: f.confidence, severity: f.severity },
+        };
+    });
+    const sarif = {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'mcp-vet',
+                        informationUri: constants_1.SPEC_URL,
+                        version: (0, constants_1.getVersion)(),
+                        rules,
+                    },
+                },
+                results,
+            },
+        ],
+    };
+    return JSON.stringify(sarif, null, 2);
+}
+function writeSarif(result, outPath) {
+    fs.writeFileSync(outPath, renderSarif(result), 'utf8');
+    return outPath;
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}

package/dist/rules.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULES = void 0;
+exports.applyRules = applyRules;
+const constants_1 = require("./constants");
+/**
+ * Canonical metadata for each of the 7 patterns. The `after` strings are the
+ * corrected 2026-07-28 patterns, authored from the official RC post
+ * (blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate) and the
+ * tokenmix protocol changelog.
+ */
+exports.RULES = {
+    MCP_SESSION_ID: {
+        id: 'MCP_SESSION_ID',
+        label: 'Mcp-Session-Id',
+        severity: 'BREAKING',
+        explanation: 'The Mcp-Session-Id header and protocol-level sessions are removed on 2026-07-28; client info and capabilities now travel in per-request _meta.',
+        after: [
+            "// 2026-07-28: sessions removed — stop reading/writing the 'Mcp-Session-Id' header.",
+            '// Client info & capabilities now arrive in each request’s params._meta.',
+            'function handle(req) { const meta = req.params?._meta ?? {}; /* route on meta, not a session id */ }',
+        ].join('\n'),
+    },
+    INITIALIZE_HANDLER: {
+        id: 'INITIALIZE_HANDLER',
+        label: 'initialize handshake',
+        severity: 'BREAKING',
+        explanation: 'The initialize/notifications-initialized handshake is removed on 2026-07-28; protocolVersion, clientInfo and capabilities now travel in _meta on every request.',
+        after: [
+            '// 2026-07-28: no initialize / notifications/initialized handshake.',
+            '// Read handshake data from _meta on every request instead of registering an initialize handler.',
+            'function handle(req) { const { protocolVersion, clientInfo, capabilities } = req.params?._meta ?? {}; }',
+        ].join('\n'),
+    },
+    ERROR_CODE_32002: {
+        id: 'ERROR_CODE_32002',
+        label: 'error code -32002',
+        severity: 'BREAKING',
+        explanation: 'The missing-resource error code changes from the MCP-custom -32002 to the JSON-RPC standard -32602 (Invalid Params).',
+        after: "return { error: { code: -32602, message: 'Invalid params' } }; // was -32002",
+    },
+    TASKS_LEGACY: {
+        id: 'TASKS_LEGACY',
+        label: 'legacy Tasks method',
+        severity: 'BREAKING',
+        explanation: 'The experimental Tasks API is redesigned to a handle-based lifecycle on 2026-07-28; tasks/get, tasks/update and tasks/cancel argument shapes change and need manual review.',
+        after: [
+            '// 2026-07-28: Tasks is now a handle-based extension.',
+            '// tools/call returns a task handle; drive it with tasks/get | tasks/update | tasks/cancel',
+            '// using the NEW argument shapes — review your params against the RC schema.',
+        ].join('\n'),
+    },
+    ROOTS_CAP: {
+        id: 'ROOTS_CAP',
+        label: 'roots capability',
+        severity: 'DEPRECATED',
+        explanation: 'The roots capability is deprecated with a 12-month grace period; it still works but should not be used in new code.',
+        after: "// 'roots' capability is deprecated (≥12-month grace). Avoid new use; plan removal.",
+    },
+    SAMPLING_CAP: {
+        id: 'SAMPLING_CAP',
+        label: 'sampling capability',
+        severity: 'DEPRECATED',
+        explanation: 'The sampling capability is deprecated with a 12-month grace period; prefer direct provider APIs.',
+        after: "// 'sampling' capability is deprecated (≥12-month grace). Prefer direct provider APIs.",
+    },
+    LOGGING_CAP: {
+        id: 'LOGGING_CAP',
+        label: 'logging capability',
+        severity: 'DEPRECATED',
+        explanation: 'The logging capability is deprecated with a 12-month grace period; use stderr or OpenTelemetry.',
+        after: "// 'logging' capability is deprecated (≥12-month grace). Use stderr or OpenTelemetry.",
+    },
+};
+const CAP_RE = /capabilities/i;
+const CAP_NAMES = {
+    roots: 'ROOTS_CAP',
+    sampling: 'SAMPLING_CAP',
+    logging: 'LOGGING_CAP',
+};
+function snippet(lines, line) {
+    const idx = line - 1;
+    const out = [];
+    if (lines[idx] !== undefined)
+        out.push(`${line}: ${lines[idx].trim()}`);
+    if (lines[idx + 1] !== undefined)
+        out.push(`${line + 1}: ${lines[idx + 1].trim()}`);
+    return out.join('\n');
+}
+/**
+ * Apply the enabled detection rules to the tokens of a single file, producing
+ * findings with a confidence score.
+ */
+function applyRules(relPath, lines, tokens, opts) {
+    const findings = [];
+    const seen = new Set();
+    const { enabled } = opts;
+    // Lines that mention "capabilities" — drive the medium-confidence heuristic
+    // for the DEPRECATED capability rules (5-7).
+    const capLines = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (CAP_RE.test(lines[i]))
+            capLines.push(i + 1);
+    }
+    const nearCapabilities = (line) => capLines.some((cl) => Math.abs(cl - line) <= 5);
+    const push = (id, t, confidence) => {
+        if (!enabled.has(id))
+            return;
+        const key = `${t.line}|${t.col ?? 0}|${id}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        const m = exports.RULES[id];
+        const column = t.col;
+        findings.push({
+            file: relPath,
+            line: t.line,
+            column,
+            endColumn: column !== undefined ? column + t.value.length : undefined,
+            patternId: id,
+            patternLabel: m.label,
+            severity: m.severity,
+            confidence,
+            explanation: m.explanation,
+            docUrl: constants_1.SPEC_URL,
+            before: snippet(lines, t.line),
+            after: m.after,
+            absPath: opts.absPath,
+            source: opts.source,
+        });
+    };
+    for (const t of tokens) {
+        const v = t.value;
+        const lower = v.toLowerCase();
+        // Rule 1 — Mcp-Session-Id (string literal, header key, or variable name)
+        if ((t.kind === 'string' || t.kind === 'name' || t.kind === 'key') &&
+            (lower.includes('mcp-session-id') || lower.includes('mcpsessionid'))) {
+            push('MCP_SESSION_ID', t, 'high');
+        }
+        // Rule 2 — initialize handshake (exact method-name string literal)
+        if (t.kind === 'string' && (v === 'initialize' || v === 'notifications/initialized')) {
+            push('INITIALIZE_HANDLER', t, t.registration ? 'high' : 'low');
+        }
+        // Rule 3 — legacy error code -32002 (numeric literal)
+        if (t.kind === 'number' && v === '-32002') {
+            push('ERROR_CODE_32002', t, 'high');
+        }
+        // Rule 4 — legacy Tasks methods (exact string literals)
+        if (t.kind === 'string' &&
+            (v === 'tasks/get' || v === 'tasks/update' || v === 'tasks/cancel')) {
+            push('TASKS_LEGACY', t, 'high');
+        }
+        // Rules 5-7 — deprecated capabilities.
+        // High confidence when structurally inside a `capabilities` object (AST);
+        // medium when only within 5 lines of a "capabilities" mention.
+        if ((t.kind === 'key' || t.kind === 'string') && CAP_NAMES[v]) {
+            if (t.inCapabilities)
+                push(CAP_NAMES[v], t, 'high');
+            else if (nearCapabilities(t.line))
+                push(CAP_NAMES[v], t, 'medium');
+        }
+    }
+    return findings.sort((a, b) => a.line - b.line ||
+        (a.column ?? 0) - (b.column ?? 0) ||
+        a.patternId.localeCompare(b.patternId));
+}

package/dist/scanner.js

@@ -0,0 +1,235 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanError = void 0;
+exports.scan = scan;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const rules_1 = require("./rules");
+const ts_analyzer_1 = require("./ts-analyzer");
+const py_analyzer_1 = require("./py-analyzer");
+const py_fallback_1 = require("./py-fallback");
+const suppress_1 = require("./suppress");
+const SKIP_DIRS = new Set(['node_modules', '.git', '__pycache__', 'dist', 'build']);
+const TS_EXT = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
+const PY_EXT = new Set(['.py']);
+const CONF_RANK = { low: 1, medium: 2, high: 3 };
+class ScanError extends Error {
+}
+exports.ScanError = ScanError;
+/** Strip a leading UTF-8 BOM so line 1 and AST parsing behave correctly. */
+function stripBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+function classify(name) {
+    const ext = path.extname(name).toLowerCase();
+    if (TS_EXT.has(ext))
+        return 'ts';
+    if (PY_EXT.has(ext))
+        return 'py';
+    return null;
+}
+function walk(root, ignore) {
+    const files = [];
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            const rel = toPosix(path.relative(root, full));
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                if (ignore.matches(rel))
+                    continue;
+                stack.push(full);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            const lang = classify(e.name);
+            if (!lang)
+                continue;
+            if (ignore.matches(rel))
+                continue;
+            files.push({ abs: full, rel, lang });
+        }
+    }
+    return files;
+}
+function collectFiles(roots, ignore) {
+    const all = [];
+    const seen = new Set();
+    for (const root of roots) {
+        const abs = path.resolve(root);
+        let stat;
+        try {
+            stat = fs.statSync(abs);
+        }
+        catch {
+            throw new ScanError(`path does not exist: ${root}`);
+        }
+        let found;
+        if (stat.isFile()) {
+            const lang = classify(abs);
+            found = lang ? [{ abs, rel: path.basename(abs), lang }] : [];
+        }
+        else {
+            found = walk(abs, ignore);
+        }
+        for (const f of found) {
+            const key = path.normalize(f.abs).toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            all.push(f);
+        }
+    }
+    all.sort((a, b) => a.rel.localeCompare(b.rel));
+    return all;
+}
+function scan(roots, opts) {
+    const files = collectFiles(roots, opts.ignore);
+    const maxBytes = opts.maxFileSizeKb > 0 ? opts.maxFileSizeKb * 1024 : Infinity;
+    const skippedLargeFiles = [];
+    const readText = (f) => {
+        try {
+            if (Number.isFinite(maxBytes)) {
+                const size = fs.statSync(f.abs).size;
+                if (size > maxBytes) {
+                    skippedLargeFiles.push(f.rel);
+                    return null;
+                }
+            }
+            return stripBom(fs.readFileSync(f.abs, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    };
+    const rawFindings = [];
+    let suppressedCount = 0;
+    const emitForFile = (f, lines, tokens, source) => {
+        const found = (0, rules_1.applyRules)(f.rel, lines, tokens, {
+            enabled: opts.enabled,
+            absPath: f.abs,
+            source: source,
+        });
+        if (found.length === 0)
+            return;
+        const supp = (0, suppress_1.parseSuppressions)(lines);
+        for (const finding of found) {
+            if (supp.isSuppressed(finding.line, finding.patternId)) {
+                suppressedCount++;
+                continue;
+            }
+            rawFindings.push(finding);
+        }
+    };
+    // TypeScript / JavaScript
+    for (const f of files) {
+        if (f.lang !== 'ts')
+            continue;
+        const text = readText(f);
+        if (text === null)
+            continue;
+        const lines = text.split(/\r?\n/);
+        let tokens = [];
+        try {
+            tokens = (0, ts_analyzer_1.analyzeTs)(f.abs, text);
+        }
+        catch {
+            tokens = [];
+        }
+        emitForFile(f, lines, tokens, 'ts-morph');
+    }
+    // Python
+    const pyFiles = files.filter((f) => f.lang === 'py');
+    let pythonMode = 'n/a';
+    if (pyFiles.length) {
+        const hasPython = (0, py_analyzer_1.pythonAvailable)();
+        if (hasPython) {
+            pythonMode = 'ast';
+            const batch = (0, py_analyzer_1.analyzePyBatch)(pyFiles.map((f) => f.abs));
+            for (const f of pyFiles) {
+                const text = readText(f);
+                if (text === null)
+                    continue;
+                const lines = text.split(/\r?\n/);
+                emitForFile(f, lines, batch[f.abs] || [], 'python-ast');
+            }
+        }
+        else if (opts.pythonFallback) {
+            pythonMode = 'regex';
+            for (const f of pyFiles) {
+                const text = readText(f);
+                if (text === null)
+                    continue;
+                const lines = text.split(/\r?\n/);
+                emitForFile(f, lines, (0, py_fallback_1.regexFallbackTokens)(text), 'regex');
+            }
+        }
+        else {
+            pythonMode = 'none';
+        }
+    }
+    // Confidence filter
+    const minRank = CONF_RANK[opts.minConfidence];
+    const findings = rawFindings
+        .filter((fnd) => CONF_RANK[fnd.confidence] >= minRank)
+        .sort((a, b) => a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        (a.column ?? 0) - (b.column ?? 0) ||
+        a.patternId.localeCompare(b.patternId));
+    return {
+        findings,
+        filesScanned: files.length,
+        pythonFilesFound: pyFiles.length,
+        pythonMode,
+        suppressedCount,
+        skippedLargeFiles,
+        roots,
+    };
+}