vibecodedshit 0.0.0-stage → 0.3.0

package/dist/measure/ts/tsconfig.js

@@ -0,0 +1,179 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+import { trackedPaths } from '../../scope/tracked.js';
+const STRICT_FAMILY = [
+    'noImplicitAny',
+    'strictNullChecks',
+    'strictFunctionTypes',
+    'strictBindCallApply',
+    'strictPropertyInitialization',
+    'noImplicitThis',
+    'useUnknownInCatchVariables',
+    'alwaysStrict',
+];
+const LEVEL_ORDER = ['none', 'partial', 'strict', 'strict_plus'];
+const posix = (p) => p.split(path.sep).join('/');
+const host = {
+    ...ts.sys,
+    onUnRecoverableConfigFileDiagnostic: () => undefined,
+};
+/** Parse one tsconfig or jsconfig with `extends` resolved by the TypeScript API. JSON only, nothing is executed. */
+function loadTsConfig(file, cache) {
+    const key = posix(file);
+    if (cache.has(key))
+        return cache.get(key);
+    let info;
+    const parsed = ts.getParsedCommandLineOfConfigFile(file, {}, host);
+    if (parsed) {
+        const raw = parsed.raw;
+        const references = (parsed.projectReferences ?? []).map((ref) => {
+            const resolved = ts.resolveProjectReferencePath(ref);
+            return posix(resolved);
+        });
+        const missingExtends = [];
+        for (const error of parsed.errors) {
+            if (error.code !== 6053)
+                continue; // File '{0}' not found.
+            const match = /'([^']+)'/.exec(ts.flattenDiagnosticMessageText(error.messageText, '\n'));
+            if (match?.[1])
+                missingExtends.push(match[1]);
+        }
+        info = {
+            file: key,
+            options: parsed.options,
+            fileNames: new Set(parsed.fileNames.map(posix)),
+            references,
+            solution: Array.isArray(raw?.files) && raw.files.length === 0 && references.length > 0,
+            missingExtends,
+        };
+    }
+    cache.set(key, info);
+    return info;
+}
+/** The level a set of compiler options declares: every flag is its explicit value, else `strict`, else false. */
+export function levelOf(options) {
+    const bag = options;
+    const strict = bag.strict === true;
+    const effective = (flag) => (typeof bag[flag] === 'boolean' ? bag[flag] === true : strict);
+    const turnedOff = STRICT_FAMILY.some((flag) => bag[flag] === false);
+    if (strict && !turnedOff)
+        return options.noUncheckedIndexedAccess === true ? 'strict_plus' : 'strict';
+    return STRICT_FAMILY.some(effective) ? 'partial' : 'none';
+}
+export function lowestLevel(levels) {
+    return levels.reduce((low, level) => (LEVEL_ORDER.indexOf(level) < LEVEL_ORDER.indexOf(low) ? level : low), 'strict_plus');
+}
+function reachable(root, cache) {
+    const seen = new Set([root.file]);
+    const out = [];
+    const queue = [...root.references];
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (next === undefined || seen.has(next))
+            continue;
+        seen.add(next);
+        const info = loadTsConfig(next, cache);
+        if (!info)
+            continue;
+        out.push(info);
+        queue.push(...info.references);
+    }
+    return out;
+}
+function covers(config, files) {
+    for (const file of config.fileNames)
+        if (files.has(file))
+            return true;
+    return false;
+}
+function configIn(dir) {
+    for (const name of ['tsconfig.json', 'jsconfig.json']) {
+        const candidate = path.join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The configs that apply to one unit: the package's own `tsconfig.json`, else its `jsconfig.json`,
+ * else the nearest ancestor config up to the repository root, kept only if it (or a config it
+ * references) covers a logic file of the unit. A solution-style config is replaced by the configs
+ * reachable through its `references` that cover a logic file of the unit (the config itself if none do).
+ */
+export function unitConfigs(repoPath, packageDir, logicFiles, cache) {
+    const files = new Set(logicFiles.map((f) => posix(path.resolve(repoPath, f))));
+    const root = path.resolve(repoPath);
+    const start = path.resolve(repoPath, packageDir);
+    let chosen = configIn(start);
+    let ancestor = false;
+    if (!chosen) {
+        ancestor = true;
+        for (let dir = path.dirname(start);; dir = path.dirname(dir)) {
+            if (dir.length < root.length)
+                break;
+            chosen = configIn(dir);
+            if (chosen || dir === root)
+                break;
+        }
+    }
+    if (!chosen)
+        return { configs: [], read: [] };
+    const top = loadTsConfig(chosen, cache);
+    if (!top)
+        return { configs: [], read: [] };
+    const nested = reachable(top, cache);
+    const read = [top, ...nested];
+    if (ancestor && ![top, ...nested].some((c) => covers(c, files)))
+        return { configs: [], read: [] };
+    if (!top.solution)
+        return { configs: [top], read };
+    const covering = nested.filter((c) => !c.solution && covers(c, files));
+    return { configs: covering.length > 0 ? covering : [top], read };
+}
+/** The nearest `tsconfig.json`, else `jsconfig.json`, from `dir` up to the repository root. Absolute path. */
+export function nearestTsConfig(repoPath, dir) {
+    const root = path.resolve(repoPath);
+    for (let current = path.resolve(root, dir); current.length >= root.length; current = path.dirname(current)) {
+        const found = configIn(current);
+        if (found)
+            return found;
+        if (current === root)
+            break;
+    }
+    return undefined;
+}
+const optionsCache = new Map();
+/**
+ * The compiler options of the nearest `tsconfig.json`, else `jsconfig.json`, with `extends` chains resolved through a host that only
+ * sees tracked files (so `node_modules` is never read). Without a config: `Bundler` resolution, ESNext modules, `allowJs`, JSON modules.
+ */
+export function compilerOptionsFor(repoPath, dir) {
+    const fallback = {
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        module: ts.ModuleKind.ESNext,
+        allowJs: true,
+        resolveJsonModule: true,
+    };
+    const configFile = nearestTsConfig(repoPath, dir);
+    if (!configFile)
+        return fallback;
+    const cached = optionsCache.get(configFile);
+    if (cached)
+        return cached;
+    const root = path.resolve(repoPath);
+    const tracked = new Set(trackedPaths(repoPath));
+    const rel = (abs) => path.posix.relative(posix(root), posix(abs));
+    const visible = (abs) => tracked.has(rel(abs));
+    const configHost = {
+        useCaseSensitiveFileNames: true,
+        readDirectory: () => [],
+        fileExists: visible,
+        readFile: (abs) => (visible(abs) ? ts.sys.readFile(abs) : undefined),
+    };
+    const read = ts.readConfigFile(configFile, (abs) => configHost.readFile(abs));
+    const parsed = read.error ? undefined : ts.parseJsonConfigFileContent(read.config, configHost, path.dirname(configFile));
+    const options = { ...fallback, ...(parsed?.options ?? {}), allowJs: true };
+    optionsCache.set(configFile, options);
+    return options;
+}

package/dist/measure/types.js

@@ -0,0 +1 @@
+export {};

package/dist/measure/units.js

@@ -0,0 +1,41 @@
+export function logicFiles(scope, group) {
+    return scope.files.filter((f) => f.role === 'logic' && f.group === group);
+}
+export function unitId(file) {
+    return `${file.package}\0${file.group}`;
+}
+/** One tally per (package, group) that has logic files, weight = logic lines of the unit. */
+export function emptyTallies(files) {
+    const tallies = new Map();
+    for (const file of files) {
+        const key = unitId(file);
+        const tally = tallies.get(key) ?? { package: file.package, group: file.group, weight: 0, numerator: 0, denominator: 0 };
+        tally.weight += file.logicLines;
+        tallies.set(key, tally);
+    }
+    return tallies;
+}
+export function tallyUnits(tallies) {
+    return [...tallies.values()]
+        .sort((a, b) => a.package.localeCompare(b.package) || a.group.localeCompare(b.group))
+        .map((t) => ({
+        package: t.package,
+        group: t.group,
+        weight: t.weight,
+        raw: { kind: 'ratio', numerator: t.numerator, denominator: t.denominator, scale: 100 },
+    }));
+}
+/** One unit per (workspace package, language group) that has at least one logic-role file, sorted by package then group. */
+export function logicUnits(scope) {
+    const units = new Map();
+    for (const file of scope.files) {
+        if (file.role !== 'logic')
+            continue;
+        const key = unitId(file);
+        const unit = units.get(key) ?? { package: file.package, group: file.group, dir: file.package, weight: 0, files: [] };
+        unit.weight += file.logicLines;
+        unit.files.push(file);
+        units.set(key, unit);
+    }
+    return [...units.values()].sort((a, b) => a.package.localeCompare(b.package) || a.group.localeCompare(b.group));
+}

package/dist/methodology/load.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { dimensionFileSchema, methodologyFileSchema, presetFileSchema, scopeFileSchema, } from './schema.js';
+export class MethodologyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MethodologyError';
+    }
+}
+/** Package root: the directory holding `methodology/`, both from `src/` and from `dist/`. */
+/** The methodology version a scan uses when `--methodology` is not given. */
+export const CURRENT_METHODOLOGY_VERSION = '1.0';
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+function readYaml(file, schema) {
+    let doc;
+    try {
+        doc = parse(readFileSync(file, 'utf8'));
+    }
+    catch (err) {
+        throw new MethodologyError(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = schema.safeParse(doc);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const where = issue && issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        throw new MethodologyError(`${file}: ${where}: ${issue?.message ?? 'invalid'}`);
+    }
+    return result.data;
+}
+function commaList(text) {
+    return text
+        .split(',')
+        .map((entry) => entry.trim().replace(/^node:/, ''))
+        .filter((entry) => entry !== '');
+}
+function parseD3Lists(def, file = 'dimension 3') {
+    const lists = { forbiddenImports: { typescript_javascript: [], python: [] }, infrastructureDirectories: [] };
+    if (!def)
+        return lists;
+    const measure = def.measure ?? {};
+    for (const group of ['typescript_javascript', 'python']) {
+        const match = /Forbidden imports:\s*(.+?)\.(?:\s|$)/s.exec(measure[group] ?? '');
+        if (!match?.[1])
+            throw new MethodologyError(`${file}: parameter ${def.id} measure.${group} has no "Forbidden imports:" list`);
+        lists.forbiddenImports[group] = [...new Set(commaList(match[1]))];
+    }
+    const infra = (measure.infrastructure_directories ?? '').replace(/\.\s*$/, '');
+    lists.infrastructureDirectories = commaList(infra);
+    if (lists.infrastructureDirectories.length === 0) {
+        throw new MethodologyError(`${file}: parameter ${def.id} measure.infrastructure_directories is empty`);
+    }
+    return lists;
+}
+function words(text) {
+    return text
+        .replace(/\s+/g, ' ')
+        .replace(/,?\s+(?:and|or)\s+/g, ', ')
+        .split(/[,;]/)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== '');
+}
+function parseD6Lists(scriptResolution, defs, defs6x, file = 'dimension 6') {
+    const text = (scriptResolution ?? '').replace(/\s+/g, ' ');
+    const pick = (re, what) => {
+        const match = re.exec(text);
+        if (!match?.[1])
+            throw new MethodologyError(`${file}: script_resolution has no ${what} list`);
+        return words(match[1]);
+    };
+    const typecheckers = pick(/typecheckers (.+?);/, 'typecheckers');
+    const linters = pick(/linters (.+?);/, 'linters');
+    const testRunners = pick(/test runners (.+?)\. The prefixes/, 'test runners');
+    const prefixes = pick(/The prefixes (.+?) are removed/, 'prefixes');
+    const env = defs?.scoring.method === 'mean_of_components' ? defs.scoring.components.find((c) => c.key === 'env_documented') : undefined;
+    const runtime = defs?.scoring.method === 'mean_of_components' ? defs.scoring.components.find((c) => c.key === 'runtime_pinned') : undefined;
+    const envMeasure = (env?.measure ?? '').replace(/\s+/g, ' ');
+    const examples = /Example files: (.+?)\. Reads:/.exec(envMeasure)?.[1];
+    const excluded = /Excluded names: (.+?), and names starting with (.+?)\.?$/.exec(envMeasure);
+    if (!examples || !excluded?.[1] || !excluded[2])
+        throw new MethodologyError(`${file}: parameter 6.5 env_documented measure has no example files or excluded names`);
+    const pins = /^Any of (.+?)\.?$/.exec((runtime?.measure ?? '').replace(/\s+/g, ' '))?.[1];
+    if (!pins)
+        throw new MethodologyError(`${file}: parameter 6.5 runtime_pinned measure has no file list`);
+    const docMeasure = (defs6x?.measure?.all_languages ?? '').replace(/\s+/g, ' ');
+    const managers = /starts with a package manager \((.+?)\)/.exec(docMeasure)?.[1];
+    if (!managers)
+        throw new MethodologyError(`${file}: parameter 6.6 measure has no package manager list`);
+    return {
+        typecheckers,
+        linters,
+        testRunners,
+        prefixes,
+        envExcludedNames: words(excluded[1]),
+        envExcludedPrefixes: words(excluded[2]),
+        envExampleFiles: words(examples),
+        runtimePinFiles: words(pins),
+        docPackageManagers: words(managers),
+    };
+}
+export function loadMethodology(version, rootDir = packageRoot) {
+    if (!/^\d+\.\d+$/.test(version)) {
+        throw new MethodologyError(`Unknown methodology version "${version}"`);
+    }
+    const dir = path.join(rootDir, 'methodology', `v${version}`);
+    if (!existsSync(dir)) {
+        throw new MethodologyError(`Unknown methodology version "${version}" (no ${dir})`);
+    }
+    const main = readYaml(path.join(dir, 'methodology.yaml'), methodologyFileSchema);
+    if (main.version !== version) {
+        throw new MethodologyError(`${path.join(dir, 'methodology.yaml')}: version "${main.version}" does not match directory v${version}`);
+    }
+    const scope = readYaml(path.join(dir, 'scope.yaml'), scopeFileSchema);
+    const presets = {};
+    const dimensions = main.dimensions.map((entry) => {
+        const file = path.join(dir, entry.file);
+        const parsed = readYaml(file, dimensionFileSchema);
+        if (parsed.dimension.id !== entry.id || parsed.dimension.key !== entry.key) {
+            throw new MethodologyError(`${file}: dimension id/key do not match methodology.yaml`);
+        }
+        const total = parsed.parameters.reduce((sum, p) => sum + p.weight, 0);
+        if (Math.abs(total - 100) > 1e-9) {
+            throw new MethodologyError(`${file}: parameter weights sum to ${total}, expected 100`);
+        }
+        for (const presetFile of parsed.presets?.files ?? []) {
+            const loaded = readYaml(path.join(dir, presetFile), presetFileSchema);
+            presets[loaded.preset.key] = {
+                preset: loaded.preset.key,
+                name: loaded.preset.name,
+                ...(loaded.conventions === undefined ? {} : { conventions: loaded.conventions }),
+                languages: loaded.preset.languages,
+                layers: loaded.layers,
+                modules: loaded.modules,
+                rules: loaded.rules,
+            };
+        }
+        return {
+            id: parsed.dimension.id,
+            key: parsed.dimension.key,
+            name: parsed.dimension.name,
+            ...(parsed.script_resolution === undefined ? {} : { scriptResolution: parsed.script_resolution }),
+            parameters: parsed.parameters,
+        };
+    });
+    const d3Def = dimensions.find((d) => d.id === 3)?.parameters.find((p) => p.id === '3.5');
+    const d6Dim = dimensions.find((d) => d.id === 6);
+    return {
+        version,
+        presets,
+        d3: parseD3Lists(d3Def, path.join(dir, 'dimensions')),
+        d6: parseD6Lists(d6Dim?.scriptResolution, d6Dim?.parameters.find((p) => p.id === '6.5'), d6Dim?.parameters.find((p) => p.id === '6.6'), path.join(dir, 'dimensions')),
+        dimensions,
+        capMargin: main.aggregation.dimension_to_health.cap_margin,
+        bands: main.bands,
+        scope,
+        execution: main.execution,
+    };
+}

package/dist/methodology/schema.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+const anchor = z.object({ raw: z.number(), score: z.number(), descriptor: z.string().optional() });
+const levelEntry = z.object({ level: z.string(), score: z.number(), descriptor: z.string().optional() });
+const component = z.object({
+    key: z.string(),
+    method: z.enum(['levels', 'ratio']),
+    levels: z.array(levelEntry).optional(),
+    definition: z.string().optional(),
+    measure: z.string().optional(),
+});
+const scoring = z.discriminatedUnion('method', [
+    z.object({ method: z.literal('piecewise_linear'), anchors: z.array(anchor).min(2) }),
+    z.object({
+        method: z.literal('levels'),
+        levels: z.union([z.array(levelEntry), z.record(z.string(), z.array(levelEntry))]),
+    }),
+    z.object({ method: z.literal('mean_of_components'), components: z.array(component).min(1) }),
+]);
+const parameterSchema = z.object({
+    id: z.string(),
+    key: z.string(),
+    name: z.string(),
+    layer: z.enum(['static', 'execution']),
+    weight: z.number(),
+    pooling: z.enum(['ratio', 'unit_weighted']),
+    raw: z.object({ unit: z.string(), when_empty: z.number() }),
+    scoring,
+    /** Prose per language or topic, for example the 3.5 forbidden-import lists. */
+    measure: z.record(z.string(), z.string()).optional(),
+    not_applicable_when: z.string().nullable().optional(),
+});
+export const dimensionFileSchema = z.object({
+    dimension: z.object({ id: z.number(), key: z.string(), name: z.string() }),
+    /** Dimension 6 prose naming the recognised tools and the removed prefixes. */
+    script_resolution: z.string().optional(),
+    parameters: z.array(parameterSchema).min(1),
+    presets: z.object({ files: z.array(z.string()) }).optional(),
+});
+const stringList = z.array(z.string());
+const presetRule = z.object({
+    name: z.string(),
+    description: z.string(),
+    from: z.object({ in: stringList.optional(), not_in: stringList.optional() }),
+    to: z.object({ in: stringList.optional(), packages: stringList.optional() }),
+    severity: z.enum(['error', 'warn', 'info']),
+    type_only_imports: z.enum(['included', 'excluded']),
+});
+export const presetFileSchema = z.object({
+    preset: z.object({
+        key: z.enum(['nextjs', 'express', 'django', 'fastapi', 'generic']),
+        name: z.string(),
+        languages: stringList,
+    }),
+    conventions: z.string().optional(),
+    /** Glob lists, or prose for content layers (nextjs `server_only` and `client`). */
+    layers: z.record(z.string(), z.union([stringList, z.string()])),
+    modules: z.object({
+        roots: z.union([stringList, z.string()]),
+        public_entry: z.union([z.string(), stringList, z.record(z.string(), z.string())]),
+    }),
+    rules: z.array(presetRule),
+});
+export const methodologyFileSchema = z.object({
+    version: z.string(),
+    dimensions: z.array(z.object({ id: z.number(), key: z.string(), file: z.string() })).min(1),
+    aggregation: z.object({
+        dimension_to_health: z.object({ cap_margin: z.number() }),
+    }),
+    bands: z
+        .array(z.object({ key: z.string(), name: z.string(), min: z.number(), max: z.number(), meaning: z.string().optional() }))
+        .min(1),
+    execution: z.object({
+        runner: z.object({ image: z.string(), cpus: z.number(), memory_gb: z.number() }),
+        timeouts_seconds: z.object({
+            install: z.number(),
+            build: z.number(),
+            typecheck: z.number(),
+            lint: z.number(),
+            tests: z.number(),
+        }),
+    }),
+});
+const globList = z.array(z.string());
+export const scopeFileSchema = z.object({
+    source_files: z.object({
+        extensions: z.object({
+            typescript: globList,
+            javascript: globList,
+            python: globList,
+        }),
+    }),
+    exclusions: z.object({
+        vendored: globList,
+        build_output: globList,
+        generated: globList,
+        minified: globList,
+        migrations: globList,
+        declarations: globList,
+        test_data: globList,
+    }),
+    file_roles: z.object({
+        test: z.object({ typescript_javascript: globList, python: globList }),
+        config: globList,
+    }),
+});

package/dist/python/deadcode.js

@@ -0,0 +1,27 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolError } from '../scope/types.js';
+const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'python', 'dead_code_helper.py');
+/** Symbols, `__all__`, imports and class bases of every file, with one helper process. */
+export function analyzePythonDeadCode(repoPath, files) {
+    if (files.length === 0)
+        return {};
+    const result = spawnSync('python3', [helperPath], {
+        cwd: repoPath,
+        input: JSON.stringify({ files }),
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error)
+        throw new ToolError(`Could not run python3: ${result.error.message}`);
+    if (result.status !== 0) {
+        throw new ToolError(`dead_code_helper.py failed: ${result.stderr.trim() || `exit ${String(result.status)}`}`);
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError('dead_code_helper.py printed invalid JSON');
+    }
+}

package/dist/python/env.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { runPythonHelper } from './helper.js';
+const cache = new Map();
+/** Environment variable names read by each given Python file: one helper spawn per scan, memoized per repository. */
+export function pythonEnvReads(repoPath, files) {
+    const key = path.resolve(repoPath);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const reads = files.length === 0 ? {} : runPythonHelper('env_helper.py', repoPath, { files });
+    cache.set(key, reads);
+    return reads;
+}

package/dist/python/helper.js

@@ -0,0 +1,24 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolError } from '../scope/types.js';
+const pythonDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'python');
+/** Run one stdlib-only helper from `python/` with JSON in and JSON out. A missing interpreter or a crashed helper is a ToolError. */
+export function runPythonHelper(helper, repoPath, input) {
+    const result = spawnSync('python3', [path.join(pythonDir, helper)], {
+        cwd: repoPath,
+        input: JSON.stringify(input),
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error)
+        throw new ToolError(`Could not run python3: ${result.error.message}`);
+    if (result.status !== 0)
+        throw new ToolError(`${helper} failed: ${result.stderr.trim() || `exit ${String(result.status)}`}`);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError(`${helper} printed invalid JSON`);
+    }
+}

package/dist/python/imports.js

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolError } from '../scope/types.js';
+const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'python', 'imports_helper.py');
+function runHelper(repoPath, files) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('python3', [helperPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (err) => reject(new ToolError(`Could not run python3: ${err.message}`)));
+        child.on('close', (code) => {
+            if (code !== 0) {
+                reject(new ToolError(`imports_helper.py failed: ${stderr.trim() || `exit ${String(code)}`}`));
+                return;
+            }
+            try {
+                resolve(JSON.parse(stdout).files);
+            }
+            catch {
+                reject(new ToolError('imports_helper.py printed invalid JSON'));
+            }
+        });
+        child.stdin.on('error', () => undefined);
+        child.stdin.end(JSON.stringify({ root: path.resolve(repoPath), files }));
+    });
+}
+/** Import statements and builtin `open` calls of every in-scope Python file, one helper process per scan. */
+export function readPythonImports(ctx) {
+    return ctx.tools.memo(`d3-py-imports:${ctx.repoPath}`, () => {
+        const files = ctx.scope.files.filter((f) => f.group === 'python').map((f) => f.path);
+        return files.length === 0 ? Promise.resolve({}) : runHelper(ctx.repoPath, files);
+    });
+}

package/dist/python/nox.js

@@ -0,0 +1,16 @@
+import path from 'node:path';
+import { trackedPaths } from '../scope/tracked.js';
+import { runPythonHelper } from './helper.js';
+const cache = new Map();
+/** The sessions of the tracked `noxfile.py` in `file`'s directory (one helper spawn per scan, memoized per repository). Undefined when it does not parse. */
+export function noxSessions(repoPath, file) {
+    const key = path.resolve(repoPath);
+    let all = cache.get(key);
+    if (!all) {
+        const files = trackedPaths(repoPath).filter((f) => path.posix.basename(f) === 'noxfile.py');
+        all = files.length === 0 ? {} : runPythonHelper('nox_helper.py', repoPath, { files });
+        cache.set(key, all);
+    }
+    const found = all[file];
+    return found?.ok ? found.sessions : undefined;
+}

package/dist/python/scope.js

@@ -0,0 +1,35 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ToolError } from '../scope/types.js';
+const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'python', 'scope_helper.py');
+export function pythonVersion() {
+    const result = spawnSync('python3', ['--version'], { encoding: 'utf8' });
+    if (result.error || result.status !== 0) {
+        throw new ToolError('python3 is not available on PATH, but the repository has Python files');
+    }
+    return `${result.stdout}${result.stderr}`.trim().replace(/^Python\s+/, '');
+}
+/** Classify all Python files with one helper process. */
+export function analyzePythonFiles(repoPath, files) {
+    if (files.length === 0)
+        return {};
+    const result = spawnSync('python3', [helperPath], {
+        cwd: repoPath,
+        input: JSON.stringify({ files }),
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (result.error) {
+        throw new ToolError(`Could not run python3: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new ToolError(`scope_helper.py failed: ${result.stderr.trim() || `exit ${result.status}`}`);
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        throw new ToolError('scope_helper.py printed invalid JSON');
+    }
+}

package/dist/python/tests.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+import { trackedPaths } from '../scope/tracked.js';
+import { runPythonHelper } from './helper.js';
+const cache = new Map();
+const NOT_FIRST_PARTY = /(?:^|\/)(?:node_modules|\.venv|venv|site-packages|__pycache__)\//;
+/**
+ * Import and test-case facts of every tracked Python file, packages that only re-export included (they are not scoped files but
+ * 1.4 follows imports through them). One helper spawn per scan, memoized per repository.
+ */
+export function pythonTestFacts(repoPath) {
+    const key = path.resolve(repoPath);
+    const cached = cache.get(key);
+    if (cached)
+        return cached;
+    const files = trackedPaths(repoPath).filter((f) => f.endsWith('.py') && !NOT_FIRST_PARTY.test(f));
+    const facts = files.length === 0 ? {} : runPythonHelper('tests_helper.py', repoPath, { files });
+    cache.set(key, facts);
+    return facts;
+}