vouchington-tooling 0.37.0 → 0.37.2

package/dist/session-friction/ci-failures.mjs

@@ -13,8 +13,22 @@ const FIELD_PREFIXES = [
     '  - Root diagnostic: ',
     '  - Disposition: ',
 ];
-function matchBlock(markdown) {
-    return matchAuditBlock(markdown, [GROUP_HEADER, EVIDENCE, ROOT_DIAGNOSTIC, DISPOSITION], FIELD_PREFIXES);
+const CI_SECTION_MAX_BYTES = 4_000;
+// Field order: header, Evidence, Root diagnostic, Disposition. Cut Root diagnostic first and
+// Evidence last, so the run URL and commit SHA survive longest.
+const SHRINK_ORDER = [2, 3, 0, 1];
+const SESSION_ID_MAX_BYTES = 120;
+function matchBlock(markdown, render = {}) {
+    return matchAuditBlock(markdown, [GROUP_HEADER, EVIDENCE, ROOT_DIAGNOSTIC, DISPOSITION], FIELD_PREFIXES, { ...render, shrinkOrder: SHRINK_ORDER });
+}
+/** A conforming group that reports dropped groups, so omission is never silent. */
+function omissionGroup(count) {
+    return [
+        `- \`one-off\` — \`GitHub Actions\` — ${count} further failure groups omitted to fit the size limit; see journal`,
+        '  - Evidence: omitted groups remain in the session journal',
+        '  - Root diagnostic: omitted to fit the retrospective size limit',
+        '  - Disposition: see journal for the omitted failure groups',
+    ].join('\n');
 }
 export function isConformingCiFailureBlock(markdown) {
     if (markdown.length > CI_FAILURE_BLOCK_MAX_BYTES ||
@@ -22,8 +36,8 @@ export function isConformingCiFailureBlock(markdown) {
         return false;
     return matchBlock(markdown) !== null;
 }
-export function getConformingGroups(entries) {
-    return conformingBlocks(entries, matchBlock);
+export function getConformingGroups(entries, redact, maxBytes = CI_SECTION_MAX_BYTES) {
+    return conformingBlocks(entries, matchBlock, Math.min(maxBytes, CI_SECTION_MAX_BYTES), redact, omissionGroup);
 }
 export function incompleteCiSection(markdownBlocks) {
     return [
@@ -35,7 +49,7 @@ export function buildCiFailuresSection(sessionId, journal, frictionStatus) {
     if (journal.status === 'unreachable')
         return `${CI_FAILURES_HEADER}\nStatus: unavailable (blackboard unreachable)`;
     if (journal.markdownBlocks.length === 0 && frictionStatus === 'absent')
-        return `${CI_FAILURES_HEADER}\nStatus: unavailable (no friction log for session ${markdownAuditText(sessionId)})`;
+        return `${CI_FAILURES_HEADER}\nStatus: unavailable (no friction log for session ${markdownAuditText(sessionId, undefined, SESSION_ID_MAX_BYTES)})`;
     if (journal.markdownBlocks.length === 0)
         return `${CI_FAILURES_HEADER}\nStatus: none observed`;
     return `${CI_FAILURES_HEADER}\nStatus: failures observed\n\n${journal.markdownBlocks.join('\n\n')}`;

package/dist/session-friction/index.d.mts

@@ -1,6 +1,6 @@
 export { classifyFrictionObservation } from './classify.mts';
 export { normalizeCommandPrefix } from './normalize.mts';
 export { FRICTION_LOG_MAX_EVENTS, readFrictionLog, recordFriction } from './log.mts';
-export { buildSessionFrictionReport } from './report.mts';
+export { buildSessionFrictionReport, loadFrictionReportInputs, renderFrictionReport, type FrictionReportInputs, } from './report.mts';
 export { isConformingCiFailureBlock } from './ci-failures.mts';
 export type { FrictionEvent, FrictionEventKind, FrictionLogOptions, FrictionLogReadResult, FrictionObservation, JournalEntry, JournalLoadResult, JournalLoader, PermissionRequestObservation, SessionFrictionReport, SessionFrictionCoverage, SessionFrictionReportOptions, ToolResultObservation, } from './types.mts';

package/dist/session-friction/index.mjs

@@ -1,5 +1,5 @@
 export { classifyFrictionObservation } from "./classify.mjs";
 export { normalizeCommandPrefix } from "./normalize.mjs";
 export { FRICTION_LOG_MAX_EVENTS, readFrictionLog, recordFriction } from "./log.mjs";
-export { buildSessionFrictionReport } from "./report.mjs";
+export { buildSessionFrictionReport, loadFrictionReportInputs, renderFrictionReport, } from "./report.mjs";
 export { isConformingCiFailureBlock } from "./ci-failures.mjs";

package/dist/session-friction/report.d.mts

@@ -1,2 +1,16 @@
-import type { SessionFrictionReport, SessionFrictionReportOptions } from './types.mts';
+import { type JournalScan } from './journal.mts';
+import type { FrictionLogReadResult, SessionFrictionReport, SessionFrictionReportOptions } from './types.mts';
+type FrictionRead = {
+    result: FrictionLogReadResult;
+} | {
+    error: unknown;
+};
+/** Everything a report reads from outside, loaded once so rendering can be repeated for free. */
+export type FrictionReportInputs = {
+    scanned: JournalScan;
+    read: FrictionRead;
+};
+export declare function loadFrictionReportInputs(sessionId: string, options: SessionFrictionReportOptions): Promise<FrictionReportInputs>;
+export declare function renderFrictionReport(sessionId: string, options: SessionFrictionReportOptions, { scanned, read }: FrictionReportInputs): SessionFrictionReport;
 export declare function buildSessionFrictionReport(sessionId: string, options: SessionFrictionReportOptions): Promise<SessionFrictionReport>;
+export {};

package/dist/session-friction/report.mjs

@@ -3,17 +3,17 @@ import { buildCiFailuresSection, getConformingGroups, incompleteCiSection } from
 import { errorMessage, scanJournal } from "./journal.mjs";
 import { buildSandboxSection } from "./sandbox.mjs";
 import { validateSessionId } from "./session-id.mjs";
-function sandboxMarkdown(friction) {
+function sandboxMarkdown(friction, options) {
     if (friction.status === 'events')
-        return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events)}`;
+        return `${friction.truncated ? `## Capture Coverage\nStatus: partial\nDropped records: ${friction.droppedCount}\n\n` : ''}${buildSandboxSection(friction.events, options.redact, options.budgets?.sandboxBytes)}`;
     if (friction.status === 'empty' && friction.truncated)
         return `## Sandbox & Permission Audit\nStatus: unavailable (partial capture; dropped ${friction.droppedCount} records)`;
     const status = friction.status === 'empty' ? 'none observed' : 'unavailable (no friction log)';
     return `## Sandbox & Permission Audit\nStatus: ${status}`;
 }
-function reportFromLog(sessionId, logOptions, journal) {
-    try {
-        const friction = readFrictionLog(sessionId, logOptions);
+function reportFromLog(sessionId, logOptions, journal, read) {
+    if ('result' in read) {
+        const friction = read.result;
         const coverage = {
             journalStatus: journal.status === 'unreachable'
                 ? 'unavailable'
@@ -27,12 +27,14 @@ function reportFromLog(sessionId, logOptions, journal) {
         if (journal.status === 'ok' && journal.truncated)
             return {
                 coverage,
-                markdown: incompleteCiSection(journal.markdownBlocks) + '\n\n' + sandboxMarkdown(friction),
+                markdown: incompleteCiSection(journal.markdownBlocks) +
+                    '\n\n' +
+                    sandboxMarkdown(friction, logOptions),
             };
         const markdown = buildCiFailuresSection(sessionId, journal, friction.status);
-        return { coverage, markdown: `${markdown}\n\n${sandboxMarkdown(friction)}` };
+        return { coverage, markdown: `${markdown}\n\n${sandboxMarkdown(friction, logOptions)}` };
     }
-    catch (error) {
+    else {
         const ciMarkdown = journal.status === 'ok' && journal.truncated
             ? incompleteCiSection(journal.markdownBlocks)
             : journal.status === 'ok' && journal.markdownBlocks.length === 0
@@ -49,25 +51,33 @@ function reportFromLog(sessionId, logOptions, journal) {
                 truncated: true,
             },
             markdown: `${ciMarkdown}\n\n## Sandbox & Permission Audit\nStatus: unavailable (friction log unreadable)`,
-            diagnostic: errorMessage(error),
+            diagnostic: errorMessage(read.error),
         };
     }
 }
-export async function buildSessionFrictionReport(sessionId, options) {
+export async function loadFrictionReportInputs(sessionId, options) {
     validateSessionId(sessionId);
     requireDirectory(options.directory);
     eventLimit(options.maxEvents);
     const scanned = await scanJournal(sessionId, options.journalLoader);
+    try {
+        return { scanned, read: { result: readFrictionLog(sessionId, options) } };
+    }
+    catch (error) {
+        return { scanned, read: { error } };
+    }
+}
+export function renderFrictionReport(sessionId, options, { scanned, read }) {
     const journal = scanned.status === 'unreachable'
         ? scanned
         : scanned.status === 'not-found'
             ? { status: 'ok', markdownBlocks: [], truncated: false }
             : {
                 status: 'ok',
-                markdownBlocks: getConformingGroups(scanned.entries),
+                markdownBlocks: getConformingGroups(scanned.entries, options.redact, options.budgets?.ciBytes),
                 truncated: scanned.truncated,
             };
-    const report = reportFromLog(sessionId, options, journal);
+    const report = reportFromLog(sessionId, options, journal, read);
     if (journal.status === 'unreachable') {
         const diagnostic = report.diagnostic
             ? `${journal.diagnostic}; ${report.diagnostic}`
@@ -76,3 +86,6 @@ export async function buildSessionFrictionReport(sessionId, options) {
     }
     return report;
 }
+export async function buildSessionFrictionReport(sessionId, options) {
+    return renderFrictionReport(sessionId, options, await loadFrictionReportInputs(sessionId, options));
+}

package/dist/session-friction/sandbox.d.mts

@@ -1,2 +1,3 @@
 import type { FrictionEvent } from './types.mts';
-export declare function buildSandboxSection(events: FrictionEvent[]): string;
+import { type AuditRedactor } from './text.mts';
+export declare function buildSandboxSection(events: FrictionEvent[], redact?: AuditRedactor, maxBytes?: number): string;

package/dist/session-friction/sandbox.mjs

@@ -1,22 +1,43 @@
-import { markdownAuditText } from "./text.mjs";
+import { byteLength, fitFields, selectWithin } from "./audit-fit.mjs";
+import { markdownAuditUnits } from "./text.mjs";
 const SANDBOX_SECTION_HEADER = '## Sandbox & Permission Audit';
+const SANDBOX_SECTION_MAX_BYTES = 3_000;
+// Room for the `- kind (n)` group lines, which are rendered outside the per-event budget.
+const GROUP_LINES_BYTES = 120;
+// Below this an event line would keep little beyond its timestamp, so it is omitted and counted.
+const MIN_EVENT_SHARE_BYTES = 120;
+// Event line fields: command prefix, detail, timestamp. Cut detail first, the timestamp never.
+const SHRINK_ORDER = [1, 0];
 const KIND_ORDER = [
     'sandbox-escalation',
     'sandbox-failure',
     'ambiguous-failure',
 ];
-export function buildSandboxSection(events) {
+/** Reports dropped events as a group in the same shape as the rest, so omission is never silent. */
+function omissionGroup(count) {
+    return `- omitted (${count})\n  - see journal — ${count} events omitted to fit the size limit — n/a`;
+}
+export function buildSandboxSection(events, redact, maxBytes = SANDBOX_SECTION_MAX_BYTES) {
     const observations = events.flatMap((event) => event.failure
         ? [event, { ...event, kind: event.failure.kind, detail: event.failure.detail }]
         : [event]);
+    const render = (event, budgetBytes) => {
+        const outcome = event.kind === 'sandbox-escalation' ? ` — outcome: ${event.outcome ?? 'unknown'}` : '';
+        const [prefix, detail, timestamp] = fitFields([event.commandPrefix, event.detail, event.timestamp].map((field) => markdownAuditUnits(field, redact)), byteLength(`  -  —  — ${outcome}`), budgetBytes, SHRINK_ORDER);
+        return `  - ${prefix} — ${detail} — ${timestamp}${outcome}`;
+    };
+    const total = Math.max(0, Math.min(maxBytes, SANDBOX_SECTION_MAX_BYTES) - GROUP_LINES_BYTES);
+    const { rendered, omitted } = selectWithin(observations, total, byteLength(omissionGroup(observations.length)) + 1, 1, MIN_EVENT_SHARE_BYTES, render);
+    const kept = observations
+        .slice(0, rendered.length)
+        .map((event, i) => ({ event, line: rendered[i] }));
     const groups = KIND_ORDER.map((kind) => {
-        const selected = observations.filter((event) => event.kind === kind);
+        const selected = kept.filter(({ event }) => event.kind === kind);
         return selected.length
-            ? [
-                `- ${kind} (${selected.length})`,
-                ...selected.map((event) => `  - ${markdownAuditText(event.commandPrefix)} — ${markdownAuditText(event.detail)} — ${markdownAuditText(event.timestamp)}${event.kind === 'sandbox-escalation' ? ` — outcome: ${event.outcome ?? 'unknown'}` : ''}`),
-            ].join('\n')
+            ? [`- ${kind} (${selected.length})`, ...selected.map(({ line }) => line)].join('\n')
             : undefined;
     }).filter((group) => group !== undefined);
+    if (omitted)
+        groups.push(omissionGroup(omitted));
     return `${SANDBOX_SECTION_HEADER}\nEvents observed: ${observations.length}\n\n${groups.join('\n')}`;
 }

package/dist/session-friction/text.d.mts

@@ -2,4 +2,17 @@ export declare function normalizeAuditText(value: string): string;
 export declare function boundedText(value: string, maximum: number): string;
 export declare function isWellFormedUnicode(value: string): boolean;
 export declare function isSafeAuditText(value: unknown): value is string;
-export declare function markdownAuditText(value: string): string;
+export type AuditRedactor = (value: string) => string;
+/**
+ * Splits a field into atomic Markdown-escaped units (one code point, plus its backslash when
+ * escaped), so a later cut can never land inside an escape sequence. Redaction runs on the raw
+ * text first: escaping inserts backslashes that would otherwise break secret and token matching.
+ * normalizeAuditText trims and escaping adds no whitespace, so the result has none at its edges.
+ */
+export declare function markdownAuditUnits(value: string, redact?: AuditRedactor): string[];
+/**
+ * Joins escaped units whole, or, when over `maxBytes`, keeps only complete whitespace-separated
+ * tokens (so URLs and SHAs are never split) and marks the cut. Never ends in whitespace.
+ */
+export declare function fitUnits(units: string[], maxBytes: number, atTokens?: boolean): string;
+export declare function markdownAuditText(value: string, redact?: AuditRedactor, maxBytes?: number): string;

package/dist/session-friction/text.mjs

@@ -1,6 +1,5 @@
 const CONTROL_CHARACTERS = /[\p{Cc}\p{Cf}]+/gu;
 const MARKDOWN_CHARACTER = /\\|`|\*|_|~|\[|\]|<|>|#|-|\+|!|\||&/;
-const MARKDOWN_AUDIT_MAX_LENGTH = 120;
 export function normalizeAuditText(value) {
     return value.replace(CONTROL_CHARACTERS, ' ').trim();
 }
@@ -32,14 +31,40 @@ export function isSafeAuditText(value) {
         isWellFormedUnicode(value) &&
         value === normalizeAuditText(value));
 }
-export function markdownAuditText(value) {
-    // Escaping is atomic, so the result may be shorter than the maximum.
-    let result = '';
-    for (const character of normalizeAuditText(value)) {
-        const escaped = MARKDOWN_CHARACTER.test(character) ? `\\${character}` : character;
-        if (result.length + escaped.length > MARKDOWN_AUDIT_MAX_LENGTH)
+/**
+ * Splits a field into atomic Markdown-escaped units (one code point, plus its backslash when
+ * escaped), so a later cut can never land inside an escape sequence. Redaction runs on the raw
+ * text first: escaping inserts backslashes that would otherwise break secret and token matching.
+ * normalizeAuditText trims and escaping adds no whitespace, so the result has none at its edges.
+ */
+export function markdownAuditUnits(value, redact) {
+    const raw = normalizeAuditText(value);
+    return Array.from(redact ? normalizeAuditText(redact(raw)) : raw).map((character) => MARKDOWN_CHARACTER.test(character) ? `\\${character}` : character);
+}
+const CUT_MARKER = '…';
+const WHITESPACE = /^\s$/u;
+/**
+ * Joins escaped units whole, or, when over `maxBytes`, keeps only complete whitespace-separated
+ * tokens (so URLs and SHAs are never split) and marks the cut. Never ends in whitespace.
+ */
+export function fitUnits(units, maxBytes, atTokens = true) {
+    const whole = units.join('');
+    if (Buffer.byteLength(whole) <= maxBytes)
+        return whole;
+    const room = maxBytes - Buffer.byteLength(` ${CUT_MARKER}`);
+    let used = 0;
+    let boundary = 0;
+    for (const [index, unit] of units.entries()) {
+        used += Buffer.byteLength(unit);
+        if (used > room)
             break;
-        result += escaped;
+        if (!atTokens || WHITESPACE.test(unit))
+            boundary = atTokens ? index : index + 1;
     }
-    return result;
+    const kept = units.slice(0, boundary).join('').trimEnd();
+    return kept ? `${kept}${atTokens ? ' ' : ''}${CUT_MARKER}` : CUT_MARKER;
+}
+export function markdownAuditText(value, redact, maxBytes = Infinity) {
+    // Used for identifiers, which have no token boundaries to cut at.
+    return fitUnits(markdownAuditUnits(value, redact), maxBytes, false);
 }

package/dist/session-friction/types.d.mts

@@ -69,5 +69,12 @@ export type SessionFrictionReport = {
 };
 export type SessionFrictionReportOptions = FrictionLogOptions & {
     journalLoader: JournalLoader;
+    /** Redacts raw field text before Markdown escaping, which would otherwise break matching. */
+    redact?: (value: string) => string;
+    /** Byte allowances for the CI and sandbox sections, as maximums over the built-in budgets. */
+    budgets?: {
+        ciBytes: number;
+        sandboxBytes: number;
+    };
 };
 export {};

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.0",
+  "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