vouchington-tooling 0.37.1 → 0.37.2

package/README.md

@@ -89,6 +89,22 @@ vouchington post-review
 vouchington stage-review-payload optional|required <source> <destination>
 ```
 
+### Running `allocate-browser-safe-ports` without an install
+
+The allocator is a standalone Python script that needs only the Python 3 standard library: no
+Node, no `pnpm install`. Run it from the extracted published tarball:
+
+```bash
+npm pack vouchington-tooling@<version>   # or download the registry .tgz
+mkdir extracted && tar -xzf vouchington-tooling-<version>.tgz -C extracted
+python3 extracted/package/scripts/allocate-browser-safe-ports.py <count> [--policy ...] [--forbidden-ports ...]
+```
+
+`pnpm dlx` and `npx` resolve the package's whole dependency tree, which can fail under
+`minimumReleaseAge` (`ERR_PNPM_NO_MATURE_MATCHING_VERSION`) when a lockstep-published dependency
+straddles the cutoff. CI jobs without an install should fetch the tarball instead. Tests enforce
+that the script stays stdlib-only and reads only its two sibling JSON files.
+
 For persistent `pnpm-install`, v5 metadata tracks structural inputs separately from the
 `--install-scripts` policy. A warm scripts-enabled tree can therefore toggle
 `true → false → true` without forced reconciliation; a tree first installed with scripts disabled
@@ -216,6 +232,7 @@ import {
   installFakeGit,
   runNamedChecks,
 } from 'vouchington-tooling/shared-context'
+import { createSourceModuleGraph } from 'vouchington-tooling/source-module-graph'
 import {
   decodeSelectedFiles,
   writeSelectedFilesOutput,
@@ -657,6 +674,18 @@ TypeScript and route rows from Markdown. Callers configure declaration names and
 runbook headings, then compare the returned data using their own route policy.
 See the [API contract](docs/basic-auth-doc-sync.md).
 
+## TypeScript source graph
+
+`vouchington-tooling/source-module-graph` exports `createSourceModuleGraph`. It accepts the
+`modules` report from released no-mistakes
+`analyzeTypeScriptModules({ root, files })`, plus the caller's root, ordered source extensions,
+aliases, and file inventory. It resolves local imports and reexport owners without reading or
+parsing source again. `runtimeImports(file)` uses binding references rather than declaration
+presence, and `reachableFrom(entrypoints, { runtimeOnly: true })` follows used runtime imports,
+reexports, and literal dynamic/require loads. Missing or incomplete facts for a reached file
+throw; external specifiers resolve to `null`. The default file inventory limit is 10,000
+files and can be reduced with `maxFiles`.
+
 ## SQL view declarations
 
 `vouchington-tooling/sql-ast` exports `extractViewDeclarations(sql)` and the

package/dist/shared-context/source-graph-owner.d.mts

@@ -0,0 +1,4 @@
+import type { TypeScriptModuleFacts } from 'no-mistakes';
+import { type SourceGraphPaths } from './source-graph-resolve.mts';
+import type { SourceExportOwner } from './source-graph.mts';
+export declare function createExportOwnerResolver(paths: SourceGraphPaths, factsFor: (file: string) => TypeScriptModuleFacts, maxFiles: number): (file: string, exportName: string) => SourceExportOwner | null;

package/dist/shared-context/source-graph-owner.mjs

@@ -0,0 +1,67 @@
+import { relativeFile, resolveSourcePath } from "./source-graph-resolve.mjs";
+export function createExportOwnerResolver(paths, factsFor, maxFiles) {
+    return (file, exportName) => {
+        const start = relativeFile(paths.root, file);
+        if (!start || !paths.files.has(start))
+            return null;
+        const queue = [{ file: start, exportName }];
+        const seen = new Set();
+        const owners = new Map();
+        let unresolved = false;
+        for (let index = 0; index < queue.length; index++) {
+            const current = queue[index];
+            const key = `${current.file}\0${current.exportName}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (seen.size > maxFiles)
+                throw new Error('Source graph file limit exceeded');
+            const facts = factsFor(current.file);
+            const direct = facts.exports.filter((item) => !item.typeOnly && item.exported === current.exportName);
+            const matches = direct.length > 0
+                ? direct
+                : current.exportName === 'default'
+                    ? [] // ESM export-star never reexports default.
+                    : facts.exports.filter((item) => !item.typeOnly && item.local === '*' && item.exported === '*');
+            for (const item of matches) {
+                if (item.specifier) {
+                    const target = resolveSourcePath(paths, current.file, item.specifier);
+                    if (!target) {
+                        unresolved = true;
+                    }
+                    else if (item.local === '*' && item.exported !== '*') {
+                        factsFor(target);
+                        owners.set(`${target}\0*`, { file: target, exportName: '*' });
+                    }
+                    else {
+                        queue.push({
+                            file: target,
+                            exportName: item.local === '*' ? current.exportName : item.local,
+                        });
+                    }
+                    continue;
+                }
+                const imported = facts.imports.flatMap((entry) => entry.bindings
+                    .filter((binding) => !binding.typeOnly && binding.local === item.local)
+                    .map((binding) => ({ entry, binding })))[0];
+                if (imported) {
+                    const target = resolveSourcePath(paths, current.file, imported.entry.specifier);
+                    if (!target) {
+                        unresolved = true;
+                    }
+                    else if (imported.binding.kind === 'namespace') {
+                        factsFor(target);
+                        owners.set(`${target}\0*`, { file: target, exportName: '*' });
+                    }
+                    else {
+                        queue.push({ file: target, exportName: imported.binding.imported });
+                    }
+                    continue;
+                }
+                const owner = { file: current.file, exportName: item.exported };
+                owners.set(`${owner.file}\0${owner.exportName}`, owner);
+            }
+        }
+        return !unresolved && owners.size === 1 ? [...owners.values()][0] : null;
+    };
+}

package/dist/shared-context/source-graph-resolve.d.mts

@@ -0,0 +1,8 @@
+export type SourceGraphPaths = {
+    root: string;
+    extensions: readonly string[];
+    aliases: Readonly<Record<string, string>>;
+    files: ReadonlySet<string>;
+};
+export declare function relativeFile(root: string, file: string): string | null;
+export declare function resolveSourcePath(paths: SourceGraphPaths, fromFile: string, specifier: string): string | null;

package/dist/shared-context/source-graph-resolve.mjs

@@ -0,0 +1,60 @@
+import { isAbsolute, posix, relative, win32 } from 'node:path';
+export function relativeFile(root, file) {
+    const value = isAbsolute(file) ? relative(root, file) : file;
+    if (win32.isAbsolute(value) || /^[A-Za-z]:/u.test(value))
+        return null;
+    const normalized = posix.normalize(value.replaceAll('\\', '/'));
+    return normalized === '..' || normalized.startsWith('../') || posix.isAbsolute(normalized)
+        ? null
+        : normalized;
+}
+export function resolveSourcePath(paths, fromFile, specifier) {
+    const normalizedFrom = relativeFile(paths.root, fromFile);
+    if (!normalizedFrom || !paths.files.has(normalizedFrom))
+        return null;
+    let target = null;
+    if (specifier.startsWith('.')) {
+        target = posix.join(posix.dirname(normalizedFrom), specifier);
+    }
+    else {
+        const alias = Object.keys(paths.aliases)
+            .filter((prefix) => specifier.startsWith(prefix))
+            .sort((a, b) => b.length - a.length)[0];
+        if (alias)
+            target = posix.join(paths.aliases[alias], specifier.slice(alias.length));
+    }
+    if (!target)
+        return null;
+    const base = relativeFile(paths.root, target);
+    if (!base)
+        return null;
+    const runtimeExtension = posix.extname(base);
+    const mappedExtensions = {
+        '.js': ['.ts', '.tsx'],
+        '.jsx': ['.tsx'],
+        '.mjs': ['.mts'],
+        '.cjs': ['.cts'],
+    };
+    const mapped = mappedExtensions[runtimeExtension];
+    if (mapped) {
+        const stem = base.slice(0, -runtimeExtension.length);
+        for (const suffix of paths.extensions) {
+            if (!mapped.includes(suffix))
+                continue;
+            const candidate = `${stem}${suffix}`;
+            if (paths.files.has(candidate))
+                return candidate;
+        }
+    }
+    for (const suffix of paths.extensions) {
+        const candidate = `${base}${suffix}`;
+        if (paths.files.has(candidate))
+            return candidate;
+    }
+    for (const suffix of paths.extensions) {
+        const candidate = posix.join(base, `index${suffix}`);
+        if (paths.files.has(candidate))
+            return candidate;
+    }
+    return paths.files.has(base) ? base : null;
+}

package/dist/shared-context/source-graph.d.mts

@@ -0,0 +1,24 @@
+import type { TypeScriptModuleImport, TypeScriptModulesReport } from 'no-mistakes';
+export type SourceModuleGraphOptions = {
+    root: string;
+    extensions: readonly string[];
+    aliases?: Readonly<Record<string, string>>;
+    files: readonly string[];
+    facts: TypeScriptModulesReport;
+    /** Caps the supplied file inventory and every traversal. */
+    maxFiles?: number;
+};
+export type SourceExportOwner = {
+    file: string;
+    exportName: string;
+};
+export type SourceModuleGraph = {
+    resolveSource(fromFile: string, specifier: string): string | null;
+    runtimeImports(file: string): TypeScriptModuleImport[];
+    reachableFrom(entrypoints: readonly string[], options?: {
+        runtimeOnly?: boolean;
+    }): string[];
+    resolveExportOwner(file: string, exportName: string): SourceExportOwner | null;
+};
+/** Resolve only caller-supplied files; syntax and binding facts come from no-mistakes. */
+export declare function createSourceModuleGraph(options: SourceModuleGraphOptions): SourceModuleGraph;

package/dist/shared-context/source-graph.mjs

@@ -0,0 +1,86 @@
+import { resolve } from 'node:path';
+import { createExportOwnerResolver } from "./source-graph-owner.mjs";
+import { relativeFile, resolveSourcePath } from "./source-graph-resolve.mjs";
+/** Resolve only caller-supplied files; syntax and binding facts come from no-mistakes. */
+export function createSourceModuleGraph(options) {
+    const root = resolve(options.root);
+    const maxFiles = options.maxFiles ?? 10_000;
+    if (!Number.isSafeInteger(maxFiles) || maxFiles < 1 || options.files.length > maxFiles) {
+        throw new Error('Source graph file limit exceeded');
+    }
+    const fileSet = new Set();
+    for (const file of options.files) {
+        const normalized = relativeFile(root, file);
+        if (!normalized)
+            throw new Error(`Source graph file escapes root: ${file}`);
+        fileSet.add(normalized);
+    }
+    const paths = {
+        root,
+        extensions: options.extensions,
+        aliases: options.aliases ?? {},
+        files: fileSet,
+    };
+    const modules = new Map();
+    for (const module of options.facts.modules) {
+        const file = relativeFile(root, module.fileName);
+        if (!file || !fileSet.has(file) || modules.has(file)) {
+            throw new Error(`Unexpected source module facts: ${module.fileName}`);
+        }
+        modules.set(file, module);
+    }
+    function factsFor(file) {
+        const normalized = relativeFile(root, file);
+        const facts = normalized && fileSet.has(normalized) ? modules.get(normalized) : undefined;
+        if (!facts || !facts.complete)
+            throw new Error(`Incomplete source module facts: ${file}`);
+        return facts;
+    }
+    function runtimeImports(file) {
+        const facts = factsFor(file);
+        return facts.imports.flatMap((entry) => {
+            if (entry.typeOnly)
+                return [];
+            if (entry.bindings.length === 0)
+                return [entry]; // Side-effect import.
+            const bindings = entry.bindings.filter((imported) => {
+                if (imported.typeOnly)
+                    return false;
+                const binding = facts.bindings.find((item) => item.id === imported.bindingId);
+                if (!binding)
+                    throw new Error(`Missing import binding facts: ${file}`);
+                return binding.references.some((reference) => reference.runtime && !reference.typeOnly);
+            });
+            return bindings.length > 0 ? [{ ...entry, bindings }] : [];
+        });
+    }
+    function reachableFrom(entrypoints, traversal = {}) {
+        const queue = entrypoints.map((file) => relativeFile(root, file));
+        const seen = new Set();
+        for (let index = 0; index < queue.length; index++) {
+            const file = queue[index];
+            if (!file || !fileSet.has(file) || seen.has(file))
+                continue;
+            seen.add(file);
+            const facts = factsFor(file);
+            const imports = traversal.runtimeOnly ? runtimeImports(file) : facts.imports;
+            const specifiers = [
+                ...imports.map((item) => item.specifier),
+                ...facts.exports.flatMap((item) => item.specifier && (!traversal.runtimeOnly || !item.typeOnly) ? [item.specifier] : []),
+                ...facts.loads.map((item) => item.specifier),
+            ];
+            for (const specifier of specifiers) {
+                const resolved = resolveSourcePath(paths, file, specifier);
+                if (resolved && !seen.has(resolved))
+                    queue.push(resolved);
+            }
+        }
+        return [...seen].sort();
+    }
+    return {
+        resolveSource: (fromFile, specifier) => resolveSourcePath(paths, fromFile, specifier),
+        runtimeImports,
+        reachableFrom,
+        resolveExportOwner: createExportOwnerResolver(paths, factsFor, maxFiles),
+    };
+}

package/dist/source-module-graph/index.d.mts

@@ -0,0 +1,2 @@
+export { createSourceModuleGraph } from '../shared-context/source-graph.mts';
+export type { SourceExportOwner, SourceModuleGraph, SourceModuleGraphOptions, } from '../shared-context/source-graph.mts';

package/dist/source-module-graph/index.mjs

@@ -0,0 +1 @@
+export { createSourceModuleGraph } from "../shared-context/source-graph.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.37.1",
+  "version": "0.37.2",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -136,6 +136,11 @@
       "import": "./dist/shared-context/index.mjs",
       "default": "./dist/shared-context/index.mjs"
     },
+    "./source-module-graph": {
+      "types": "./dist/source-module-graph/index.d.mts",
+      "import": "./dist/source-module-graph/index.mjs",
+      "default": "./dist/source-module-graph/index.mjs"
+    },
     "./gha-selected-files": {
       "types": "./dist/gha-selected-files/index.d.mts",
       "import": "./dist/gha-selected-files/index.mjs",
@@ -376,12 +381,14 @@
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.6.0",
+    "no-mistakes": "0.78.0",
     "smol-toml": "1.9.0",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
     "agent-blackboard": "^0.6.0",
+    "no-mistakes": "^0.78.0",
     "typescript": ">=5",
     "vitest": ">=5"
   },
@@ -392,6 +399,9 @@
     "@modelcontextprotocol/sdk": {
       "optional": true
     },
+    "no-mistakes": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     },

package/scripts/allocate-browser-safe-ports.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python3
+# Must stay stdlib-only and self-contained (reads only the sibling fetch-forbidden-ports.json
+# and runner-port-policy.json): CI runs it from the extracted published tarball with no install.
+# Enforced by allocate-browser-safe-ports-no-install.test.mts.
 from __future__ import annotations
 
 import argparse