ushman-equiv 0.4.0

package/dist/cli.js

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { renderEquivReport, runEquiv, writeEquivResult } from "./run.js";
+import { resolvePackageVersion } from "./shared.js";
+import { emitSymbolBaseline } from "./tier-s-symbol-diff.js";
+import { MAX_MAX_CONCURRENCY, WorkspaceLayoutError } from "./workspace.js";
+const DEFAULT_MAX_OLD_SPACE_SIZE_MB = 8192;
+const MAX_OLD_SPACE_SIZE_PATTERN = /(?:^|\s)--max-old-space-size(?:=|\s)\d+(?:\s|$)/u;
+/**
+ * The in-zip CLI runs directly inside the LLM sandbox. Multi-MB bundles can
+ * exhaust Node's default heap during AST traversal (Tier I), module-load
+ * (Tier L), and per-fixture replay (Tier R) — so direct execution respawns
+ * once with an 8 GB old-space default unless the operator has already set
+ * one. Mirrors @ushman/verify's runWithHeapGuard.
+ */
+const hasMaxOldSpaceSize = (nodeOptions) => typeof nodeOptions === 'string' && MAX_OLD_SPACE_SIZE_PATTERN.test(nodeOptions);
+const withDefaultMaxOldSpaceSize = (nodeOptions) => [`--max-old-space-size=${DEFAULT_MAX_OLD_SPACE_SIZE_MB}`, nodeOptions?.trim()]
+    .filter((value) => Boolean(value))
+    .join(' ');
+export const runWithHeapGuard = async (runner) => {
+    if (hasMaxOldSpaceSize(process.env.NODE_OPTIONS)) {
+        return runner();
+    }
+    const child = spawn(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
+        env: {
+            ...process.env,
+            NODE_OPTIONS: withDefaultMaxOldSpaceSize(process.env.NODE_OPTIONS),
+        },
+        stdio: 'inherit',
+    });
+    return await new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (code, signal) => {
+            if (signal) {
+                resolve(2);
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+};
+const renderHelpText = (mode = 'main') => mode === 'emit-baseline'
+    ? [
+        'Usage:',
+        '  ushman-equiv emit-baseline [<workspace> | --workspace=<path>] [--out=<path>]',
+        '                             [--entrypoint=<path>] [--filter=<glob-or-/regex/>]',
+        '                             [--src-roots=<comma-list>]',
+        '',
+        'Options:',
+        '  --workspace  Workspace root to baseline. Defaults to the current directory.',
+        '  --out        Output file for ushman-equiv-baseline/v1 JSON.',
+        '  --entrypoint Override the default root index.html entrypoint discovery.',
+        '  --filter     Match symbol names with a glob or /regex/.',
+        '  --src-roots  Comma-separated source roots. Defaults to src.',
+    ].join('\n')
+    : [
+        'Usage:',
+        '  ushman-equiv [<workspace> | --workspace=<path>] [--tiers=I,L,S,R | --tier=I]',
+        '               [--filter=<glob-or-/regex/>]',
+        '               [--entrypoint=<path>] [--baseline=<path>]',
+        '               [--fixtures=<dir>] [--modules=<dir>]',
+        '               [--src-roots=<comma-list>] [--mode=preview|dev] [--max-concurrency=<n>]',
+        '               [--write-result] [--json]',
+        '  ushman-equiv emit-baseline [<workspace> | --workspace=<path>] [--out=<path>]',
+        '',
+        'Paths are resolved relative to the current working directory unless documented otherwise.',
+        '--baseline may be workspace-relative or absolute.',
+        '--filter matches source-file paths for tier I, symbol names for tier S, and fixture names for tier R.',
+        'Glob syntax supports *, ?, and **. Use /pattern/ for regex.',
+        '',
+        'Flags:',
+        '  --workspace      Workspace root. Defaults to the current directory.',
+        '  --mode           Boot mode for tiers L and R. Defaults to preview.',
+        `  --max-concurrency Limit replay concurrency. Max ${MAX_MAX_CONCURRENCY}.`,
+        '  --json           Print the full report as JSON.',
+        '  --write-result   Write .lab/equiv/result.json inside the workspace.',
+        '  -h, --help       Show this help text.',
+        '  -v, --version    Show the installed ushman-equiv version.',
+    ].join('\n');
+const parseTierValues = (tier, tiersValue) => {
+    const values = [...(tier ?? []), ...(tiersValue ? tiersValue.split(',') : [])].filter(Boolean);
+    if (values.length === 0) {
+        return undefined;
+    }
+    const unique = new Set();
+    for (const value of values) {
+        if (value === 'I' || value === 'L' || value === 'R' || value === 'S') {
+            unique.add(value);
+            continue;
+        }
+        throw new Error(`Unsupported tier value: ${value}`);
+    }
+    return [...unique];
+};
+const parsePositiveIntegerOption = (value, flagName) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(value)) {
+        throw new Error(`${flagName} must be a positive integer.`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (parsed <= 0) {
+        throw new Error(`${flagName} must be greater than zero.`);
+    }
+    if (parsed > MAX_MAX_CONCURRENCY) {
+        throw new Error(`${flagName} must be less than or equal to ${MAX_MAX_CONCURRENCY}.`);
+    }
+    return parsed;
+};
+const parseMode = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === 'preview' || value === 'dev') {
+        return value;
+    }
+    throw new Error(`Unsupported mode value: ${value}`);
+};
+const isHelpSignal = (error) => error instanceof Error && error.message === '__USHMAN_EQUIV_HELP__';
+const resolveWorkspaceFlag = ({ positionals, workspaceFlag, }) => {
+    if (positionals.length > 1) {
+        throw new Error(`Expected at most one workspace path, received ${positionals.length}: ${positionals.join(', ')}`);
+    }
+    const positionalWorkspace = positionals[0];
+    if (workspaceFlag && positionalWorkspace && path.resolve(workspaceFlag) !== path.resolve(positionalWorkspace)) {
+        throw new Error('Cannot provide conflicting workspace values via both --workspace and a positional path.');
+    }
+    return path.resolve(workspaceFlag ?? positionalWorkspace ?? '.');
+};
+const parseCommonRunOptions = (argv) => {
+    const parsed = parseArgs({
+        allowPositionals: true,
+        args: argv,
+        options: {
+            baseline: { type: 'string' },
+            entrypoint: { type: 'string' },
+            filter: { type: 'string' },
+            fixtures: { type: 'string' },
+            help: { short: 'h', type: 'boolean' },
+            json: { type: 'boolean' },
+            'max-concurrency': { type: 'string' },
+            mode: { type: 'string' },
+            modules: { type: 'string' },
+            'src-roots': { type: 'string' },
+            tier: { multiple: true, type: 'string' },
+            tiers: { type: 'string' },
+            version: { short: 'v', type: 'boolean' },
+            workspace: { type: 'string' },
+            'write-result': { type: 'boolean' },
+        },
+        strict: true,
+    });
+    if (parsed.values.help) {
+        process.stdout.write(`${renderHelpText()}\n`);
+        throw new Error('__USHMAN_EQUIV_HELP__');
+    }
+    if (parsed.values.version) {
+        throw new Error('__USHMAN_EQUIV_VERSION__');
+    }
+    return {
+        baselineSymbolsPath: parsed.values.baseline,
+        entrypoint: parsed.values.entrypoint,
+        filter: parsed.values.filter,
+        fixturesDir: parsed.values.fixtures,
+        json: parsed.values.json ?? false,
+        maxConcurrency: parsePositiveIntegerOption(parsed.values['max-concurrency'], '--max-concurrency'),
+        mode: parseMode(parsed.values.mode),
+        modulesDir: parsed.values.modules,
+        srcRoots: parsed.values['src-roots']
+            ?.split(',')
+            .map((value) => value.trim())
+            .filter(Boolean),
+        tiers: parseTierValues(parsed.values.tier, parsed.values.tiers),
+        workspaceRoot: resolveWorkspaceFlag({
+            positionals: parsed.positionals,
+            workspaceFlag: parsed.values.workspace,
+        }),
+        writeResult: parsed.values['write-result'] ?? false,
+    };
+};
+const parseEmitBaselineOptions = (argv) => {
+    const parsed = parseArgs({
+        allowPositionals: true,
+        args: argv,
+        options: {
+            entrypoint: { type: 'string' },
+            filter: { type: 'string' },
+            help: { short: 'h', type: 'boolean' },
+            out: { type: 'string' },
+            'src-roots': { type: 'string' },
+            version: { short: 'v', type: 'boolean' },
+            workspace: { type: 'string' },
+        },
+        strict: true,
+    });
+    if (parsed.values.help) {
+        process.stdout.write(`${renderHelpText('emit-baseline')}\n`);
+        throw new Error('__USHMAN_EQUIV_HELP__');
+    }
+    if (parsed.values.version) {
+        throw new Error('__USHMAN_EQUIV_VERSION__');
+    }
+    return {
+        entrypoint: parsed.values.entrypoint,
+        filter: parsed.values.filter,
+        outputPath: parsed.values.out ? path.resolve(parsed.values.out) : undefined,
+        srcRoots: parsed.values['src-roots']
+            ?.split(',')
+            .map((value) => value.trim())
+            .filter(Boolean),
+        workspaceRoot: resolveWorkspaceFlag({
+            positionals: parsed.positionals,
+            workspaceFlag: parsed.values.workspace,
+        }),
+    };
+};
+const runEmitBaselineCommand = async (argv) => {
+    let options;
+    try {
+        options = parseEmitBaselineOptions(argv.slice(1));
+    }
+    catch (error) {
+        if (isHelpSignal(error)) {
+            return 0;
+        }
+        if (error instanceof Error && error.message === '__USHMAN_EQUIV_VERSION__') {
+            process.stdout.write(`${await resolvePackageVersion()}\n`);
+            return 0;
+        }
+        throw error;
+    }
+    try {
+        const result = await emitSymbolBaseline(options);
+        process.stdout.write(`schema=ushman-equiv-baseline/v1 symbols=${result.symbolCount} out=${result.outputPath}\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceLayoutError) {
+            process.stderr.write(`${error.message}\n`);
+            return error.exitCode;
+        }
+        throw error;
+    }
+};
+const parseRunOptions = (argv) => {
+    try {
+        return parseCommonRunOptions(argv);
+    }
+    catch (error) {
+        if (isHelpSignal(error)) {
+            return null;
+        }
+        if (error instanceof Error && error.message === '__USHMAN_EQUIV_VERSION__') {
+            return '__USHMAN_EQUIV_VERSION__';
+        }
+        throw error;
+    }
+};
+const runEquivCommand = async (options) => {
+    try {
+        const report = await runEquiv(options);
+        process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : `${renderEquivReport(report)}\n`);
+        if (options.writeResult) {
+            await writeEquivResult({
+                report,
+                workspaceRoot: options.workspaceRoot,
+            });
+        }
+        return report.verdict === 'red' ? 1 : 0;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceLayoutError) {
+            process.stderr.write(`${error.message}\n`);
+            return error.exitCode;
+        }
+        throw error;
+    }
+};
+export const main = async (argv = process.argv.slice(2)) => {
+    if (argv[0] === 'emit-baseline') {
+        return runEmitBaselineCommand(argv);
+    }
+    const options = parseRunOptions(argv);
+    if (!options) {
+        return 0;
+    }
+    if (options === '__USHMAN_EQUIV_VERSION__') {
+        process.stdout.write(`${await resolvePackageVersion()}\n`);
+        return 0;
+    }
+    return runEquivCommand(options);
+};
+const directExecutionHref = process.argv[1] ? pathToFileURL(process.argv[1]).href : null;
+if (directExecutionHref === import.meta.url) {
+    runWithHeapGuard(() => main()).then((code) => {
+        process.exit(code);
+    }, (error) => {
+        if (isHelpSignal(error)) {
+            process.exit(0);
+        }
+        if (error instanceof WorkspaceLayoutError) {
+            process.stderr.write(`${error.message}\n`);
+            process.exit(error.exitCode);
+        }
+        process.stderr.write(`${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+        process.exit(2);
+    });
+}

package/dist/equiv-execution-context.d.ts

@@ -0,0 +1,25 @@
+import type { CandidateBootSmokeResult } from './candidate-boot.ts';
+import { type AnalysisContextSeed, type CandidateSymbolAnalysisOptions, type CandidateSymbolCollection, type ImportGraphAnalysis, type SharedAnalysisContext } from './analysis-context.ts';
+import type { EquivMode, ImportGraphOptions } from './types.ts';
+type CandidateBootOptions = {
+    readonly mode?: EquivMode;
+    readonly workspaceRoot: string;
+};
+type EquivExecutionContextDependencies = {
+    readonly createAnalysisContext?: (options: AnalysisContextSeed) => Promise<SharedAnalysisContext>;
+    readonly smokeCandidateBoot?: (options: CandidateBootOptions) => Promise<CandidateBootSmokeResult>;
+};
+export type EquivExecutionContext = {
+    readonly getAnalysisContext: (options: AnalysisContextSeed) => Promise<SharedAnalysisContext>;
+    readonly getCandidateBoot: (options: CandidateBootOptions) => Promise<CandidateBootSmokeResult>;
+    readonly getCandidateSymbols: (options: CandidateSymbolAnalysisOptions) => Promise<CandidateSymbolCollection>;
+    readonly getImportGraph: (options: ImportGraphOptions) => Promise<ImportGraphAnalysis>;
+};
+/**
+ * Creates the internal execution context shared by `runEquiv()` and tier-local
+ * helpers so boot smoke, import-graph analysis, and symbol analysis are reused
+ * across tiers instead of recomputed or tunneled through private option fields.
+ */
+export declare const createEquivExecutionContext: (dependencies?: EquivExecutionContextDependencies) => EquivExecutionContext;
+export {};
+//# sourceMappingURL=equiv-execution-context.d.ts.map

package/dist/equiv-execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"equiv-execution-context.d.ts","sourceRoot":"","sources":["../src/equiv-execution-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,EAGH,KAAK,mBAAmB,EACxB,KAAK,8BAA8B,EACnC,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC7B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAQhE,KAAK,oBAAoB,GAAG;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,KAAK,iCAAiC,GAAG;IACrC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAClG,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtG,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAChC,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC9F,QAAQ,CAAC,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAChG,QAAQ,CAAC,mBAAmB,EAAE,CAC1B,OAAO,EAAE,8BAA8B,KACtC,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACxC,QAAQ,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC1F,CAAC;AAkEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GACpC,eAAc,iCAAsC,KACrD,qBAqCF,CAAC"}

package/dist/equiv-execution-context.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { smokeCandidateBoot } from "./candidate-boot.js";
+import { createAnalysisContext, selectCandidateSymbols, } from "./analysis-context.js";
+import { DEFAULT_EQUIV_MODE } from "./workspace.js";
+const normalizeWorkspaceInputPath = (workspaceRoot, candidatePath) => path.isAbsolute(candidatePath) ? path.resolve(candidatePath) : path.resolve(workspaceRoot, candidatePath);
+const normalizeWorkspaceRoot = (workspaceRoot) => path.resolve(workspaceRoot);
+const normalizeStringArray = (values) => values ? [...new Set(values)].sort() : [];
+const memoizePromise = (cache, key, loader) => {
+    const cached = cache.get(key);
+    if (cached) {
+        return cached;
+    }
+    const pending = loader().catch((error) => {
+        cache.delete(key);
+        throw error;
+    });
+    cache.set(key, pending);
+    return pending;
+};
+const createAnalysisKey = (options) => JSON.stringify({
+    entrypoint: options.entrypoint === undefined
+        ? null
+        : normalizeWorkspaceInputPath(options.workspaceRoot, options.entrypoint),
+    srcRoots: normalizeStringArray(options.srcRoots).map((srcRoot) => normalizeWorkspaceInputPath(options.workspaceRoot, srcRoot)),
+    workspaceRoot: normalizeWorkspaceRoot(options.workspaceRoot),
+});
+const createCandidateSymbolsKey = (options) => JSON.stringify({
+    entrypoint: options.entrypoint === undefined
+        ? null
+        : normalizeWorkspaceInputPath(options.workspaceRoot, options.entrypoint),
+    filter: options.filter ?? null,
+    srcRoots: normalizeStringArray(options.srcRoots).map((srcRoot) => normalizeWorkspaceInputPath(options.workspaceRoot, srcRoot)),
+    workspaceRoot: normalizeWorkspaceRoot(options.workspaceRoot),
+});
+const createImportGraphKey = (options) => JSON.stringify({
+    entrypoint: options.entrypoint === undefined
+        ? null
+        : normalizeWorkspaceInputPath(options.workspaceRoot, options.entrypoint),
+    filter: options.filter ?? null,
+    srcRoots: normalizeStringArray(options.srcRoots).map((srcRoot) => normalizeWorkspaceInputPath(options.workspaceRoot, srcRoot)),
+    workspaceRoot: normalizeWorkspaceRoot(options.workspaceRoot),
+});
+const createCandidateBootKey = (options) => JSON.stringify({
+    mode: options.mode ?? DEFAULT_EQUIV_MODE,
+    workspaceRoot: normalizeWorkspaceRoot(options.workspaceRoot),
+});
+/**
+ * Creates the internal execution context shared by `runEquiv()` and tier-local
+ * helpers so boot smoke, import-graph analysis, and symbol analysis are reused
+ * across tiers instead of recomputed or tunneled through private option fields.
+ */
+export const createEquivExecutionContext = (dependencies = {}) => {
+    const analysisContextCache = new Map();
+    const importGraphCache = new Map();
+    const candidateSymbolsCache = new Map();
+    const candidateBootCache = new Map();
+    const loadAnalysisContext = (options) => memoizePromise(analysisContextCache, createAnalysisKey(options), async () => (dependencies.createAnalysisContext ?? createAnalysisContext)(options));
+    return {
+        getAnalysisContext(options) {
+            return loadAnalysisContext(options);
+        },
+        getCandidateBoot(options) {
+            return memoizePromise(candidateBootCache, createCandidateBootKey(options), async () => (dependencies.smokeCandidateBoot ?? smokeCandidateBoot)(options));
+        },
+        getCandidateSymbols(options) {
+            return memoizePromise(candidateSymbolsCache, createCandidateSymbolsKey(options), async () => {
+                const analysisContext = await loadAnalysisContext(options);
+                const index = await analysisContext.getSymbolIndex();
+                return selectCandidateSymbols({
+                    filter: options.filter,
+                    index,
+                });
+            });
+        },
+        getImportGraph(options) {
+            return memoizePromise(importGraphCache, createImportGraphKey(options), async () => {
+                const analysisContext = await loadAnalysisContext(options);
+                return analysisContext.getImportGraphAnalysis(options.filter);
+            });
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { canonicalize } from './canonicalize.ts';
+export { main as cliMain } from './cli.ts';
+export { createEquivExecutionContext } from './equiv-execution-context.ts';
+export { renderEquivReport, runEquiv, writeEquivResult } from './run.ts';
+export { checkImportGraph, checkImportGraphWithContext } from './tier-i-import-graph.ts';
+export { checkModuleLoad, checkModuleLoadWithContext } from './tier-l-module-load.ts';
+export { checkReplay, checkReplayWithContext } from './tier-r-replay.ts';
+export { checkSymbolDiff, checkSymbolDiffWithContext, emitSymbolBaseline } from './tier-s-symbol-diff.ts';
+export type { BareImportUsage, CandidateSymbolCollection, ImportGraphAnalysis, SharedAnalysisContext, WorkspaceSymbolIndex, } from './analysis-context.ts';
+export type { EquivExecutionContext } from './equiv-execution-context.ts';
+export type { EquivCheckResult, EquivFinding, EquivMode, EquivOptions, EquivReport, EquivSeverity, EquivTier, ImportGraphOptions, ModuleLoadOptions, ReplayFixtureDocument, ReplayOptions, SymbolBaselineDeclaration, SymbolBaselineDeclKind, SymbolBaselineDocument, SymbolDiffOptions, } from './types.ts';
+export { ALL_EQUIV_MODES, ALL_TIERS, EQUIV_BASELINE_SCHEMA_NAME, EQUIV_BASELINE_SCHEMA_VERSION, EQUIV_REPORT_VERSION, EQUIV_RESULT_SCHEMA_NAME, EQUIV_RESULT_SCHEMA_VERSION, verdictForChecks, } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1G,YAAY,EACR,eAAe,EACf,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAC1E,YAAY,EACR,gBAAgB,EAChB,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,yBAAyB,EACzB,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACH,eAAe,EACf,SAAS,EACT,0BAA0B,EAC1B,6BAA6B,EAC7B,oBAAoB,EACpB,wBAAwB,EACxB,2BAA2B,EAC3B,gBAAgB,GACnB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// Public surface of ushman-equiv.
+// Pure-Node Tier I/L/S/R equivalence checks for ushman cleanup workspaces.
+export { canonicalize } from "./canonicalize.js";
+export { main as cliMain } from "./cli.js";
+export { createEquivExecutionContext } from "./equiv-execution-context.js";
+export { renderEquivReport, runEquiv, writeEquivResult } from "./run.js";
+export { checkImportGraph, checkImportGraphWithContext } from "./tier-i-import-graph.js";
+export { checkModuleLoad, checkModuleLoadWithContext } from "./tier-l-module-load.js";
+export { checkReplay, checkReplayWithContext } from "./tier-r-replay.js";
+export { checkSymbolDiff, checkSymbolDiffWithContext, emitSymbolBaseline } from "./tier-s-symbol-diff.js";
+export { ALL_EQUIV_MODES, ALL_TIERS, EQUIV_BASELINE_SCHEMA_NAME, EQUIV_BASELINE_SCHEMA_VERSION, EQUIV_REPORT_VERSION, EQUIV_RESULT_SCHEMA_NAME, EQUIV_RESULT_SCHEMA_VERSION, verdictForChecks, } from "./types.js";

package/dist/run.d.ts

@@ -0,0 +1,8 @@
+import type { EquivOptions, EquivReport } from './types.ts';
+export declare const runEquiv: (options: EquivOptions) => Promise<EquivReport>;
+export declare const renderEquivReport: (report: EquivReport) => string;
+export declare const writeEquivResult: ({ report, workspaceRoot, }: {
+    readonly report: EquivReport;
+    readonly workspaceRoot: string;
+}) => Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAoB,YAAY,EAAE,WAAW,EAAa,MAAM,YAAY,CAAC;AAiFzF,eAAO,MAAM,QAAQ,GAAU,SAAS,YAAY,KAAG,OAAO,CAAC,WAAW,CA+BzE,CAAC;AAcF,eAAO,MAAM,iBAAiB,GAAI,QAAQ,WAAW,KAAG,MAkBvD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,4BAGpC;IACC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,KAAG,OAAO,CAAC,IAAI,CAEf,CAAC"}

package/dist/run.js

@@ -0,0 +1,129 @@
+import { buildValidatorResultRecord, openLedger } from 'ushman-ledger';
+import { createEquivExecutionContext } from "./equiv-execution-context.js";
+import { indentMultiline, resolvePackageVersion } from "./shared.js";
+import { checkImportGraphWithContext } from "./tier-i-import-graph.js";
+import { checkModuleLoadWithContext } from "./tier-l-module-load.js";
+import { checkReplayWithContext } from "./tier-r-replay.js";
+import { checkSymbolDiffWithContext } from "./tier-s-symbol-diff.js";
+import { ALL_TIERS, EQUIV_REPORT_VERSION, EQUIV_RESULT_SCHEMA_NAME, EQUIV_RESULT_SCHEMA_VERSION, verdictForChecks, } from "./types.js";
+import { assertV4Workspace, DEFAULT_EQUIV_MODE, defaultResultPath, writeTextFileAtomically } from "./workspace.js";
+const timestamp = () => new Date().toISOString().replace(/\.\d+Z$/u, 'Z');
+const normalizeTiers = (tiers) => {
+    if (!tiers || tiers.length === 0) {
+        return ALL_TIERS;
+    }
+    const unique = new Set(tiers);
+    return ALL_TIERS.filter((tier) => unique.has(tier));
+};
+const wrapUnexpectedTierError = (tier, error) => ({
+    details: [
+        {
+            evidence: error instanceof Error ? (error.stack ?? error.message) : String(error),
+            message: `Equiv crashed while running tier ${tier}.`,
+        },
+    ],
+    elapsedMs: 0,
+    severity: 'red',
+    summary: `tier=${tier} crashed`,
+    tier,
+});
+const TIER_HANDLERS = {
+    I: checkImportGraphWithContext,
+    L: checkModuleLoadWithContext,
+    R: checkReplayWithContext,
+    S: checkSymbolDiffWithContext,
+};
+const recordValidatorResult = async ({ report, version, workspaceRoot, }) => {
+    try {
+        const ledger = await openLedger(workspaceRoot);
+        await ledger.record(buildValidatorResultRecord({
+            details: {
+                checks: report.checks,
+                schemaVersion: report.schemaVersion,
+                tiers: report.tiers,
+            },
+            emitter: {
+                tool: 'ushman-equiv',
+                version,
+            },
+            kind: 'validator-result',
+            metrics: {
+                checkCount: report.checks.length,
+                mode: report.mode,
+                verdict: report.verdict,
+            },
+            phase: 'equiv',
+            summary: `equiv ${report.verdict}`,
+            validator: 'equiv',
+            verdict: report.verdict,
+        }));
+    }
+    catch (error) {
+        process.emitWarning(`ushman-equiv could not record the validator result in the ledger: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+export const runEquiv = async (options) => {
+    await assertV4Workspace(options.workspaceRoot);
+    const tiers = normalizeTiers(options.tiers);
+    const version = await resolvePackageVersion();
+    const executionContext = createEquivExecutionContext();
+    const checks = [];
+    for (const tier of tiers) {
+        try {
+            checks.push(await TIER_HANDLERS[tier](options, executionContext));
+        }
+        catch (error) {
+            checks.push(wrapUnexpectedTierError(tier, error));
+        }
+    }
+    const report = {
+        checks,
+        createdAt: timestamp(),
+        mode: options.mode ?? DEFAULT_EQUIV_MODE,
+        reportVersion: EQUIV_REPORT_VERSION,
+        schemaName: EQUIV_RESULT_SCHEMA_NAME,
+        schemaVersion: EQUIV_RESULT_SCHEMA_VERSION,
+        tiers,
+        ushmanEquivVersion: version,
+        verdict: verdictForChecks(checks),
+        workspace: options.workspaceRoot,
+    };
+    await recordValidatorResult({
+        report,
+        version,
+        workspaceRoot: options.workspaceRoot,
+    });
+    return report;
+};
+const renderDetail = (detail) => {
+    const prefix = [detail.path, detail.symbol].filter(Boolean).join(' ');
+    const evidence = detail.evidence === undefined ? null : indentMultiline(JSON.stringify(detail.evidence, null, 2), '          ');
+    return [
+        prefix ? `        - ${prefix}: ${detail.message}` : `        - ${detail.message}`,
+        evidence ? `          ${evidence}` : null,
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n');
+};
+export const renderEquivReport = (report) => {
+    const lines = [
+        `ushman equiv @ ${report.createdAt}`,
+        `workspace: ${report.workspace}`,
+        `mode:      ${report.mode}`,
+        `report:    v${report.reportVersion}`,
+        `schema:    ${report.schemaName}@${report.schemaVersion}`,
+        `package:   ${report.ushmanEquivVersion}`,
+        `verdict:   ${report.verdict.toUpperCase()}`,
+        '',
+    ];
+    for (const check of report.checks) {
+        lines.push(`[${check.severity.toUpperCase()}] ${check.tier}: ${check.summary} (${check.elapsedMs}ms)`);
+        for (const detail of check.details ?? []) {
+            lines.push(renderDetail(detail));
+        }
+    }
+    return lines.join('\n');
+};
+export const writeEquivResult = async ({ report, workspaceRoot, }) => {
+    await writeTextFileAtomically(defaultResultPath(workspaceRoot), `${JSON.stringify(report, null, 2)}\n`);
+};

package/dist/shared.d.ts

@@ -0,0 +1,9 @@
+export declare const compareStrings: (left: string, right: string) => number;
+export declare const indentMultiline: (value: string, indent: string) => string;
+export declare const readPositiveIntegerEnv: (name: string, fallback: number) => number;
+export declare const captureChildText: ({ maxBytes, stream, }: {
+    readonly maxBytes: number;
+    readonly stream: NodeJS.ReadableStream | null | undefined;
+}) => (() => string);
+export declare const resolvePackageVersion: () => Promise<string>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG,MAQ5D,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAG,MAI7C,CAAC;AAEpB,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,EAAE,UAAU,MAAM,KAAG,MAOvE,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,uBAG9B;IACC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7D,KAAG,CAAC,MAAM,MAAM,CAahB,CAAC;AAIF,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,CAU5D,CAAC"}

package/dist/shared.js

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises';
+export const compareStrings = (left, right) => {
+    if (left < right) {
+        return -1;
+    }
+    if (left > right) {
+        return 1;
+    }
+    return 0;
+};
+export const indentMultiline = (value, indent) => value
+    .split('\n')
+    .map((line) => `${indent}${line}`)
+    .join('\n');
+export const readPositiveIntegerEnv = (name, fallback) => {
+    const rawValue = process.env[name];
+    if (!rawValue) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(rawValue, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+export const captureChildText = ({ maxBytes, stream, }) => {
+    let text = '';
+    if (!stream) {
+        return () => text.trim();
+    }
+    stream.setEncoding('utf8');
+    stream.on('data', (chunk) => {
+        text += chunk;
+        if (text.length > maxBytes) {
+            text = `...<truncated>\n${text.slice(-maxBytes)}`;
+        }
+    });
+    return () => text.trim();
+};
+const FALLBACK_PACKAGE_VERSION = '0.1.0';
+export const resolvePackageVersion = async () => {
+    try {
+        const packageJson = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        return packageJson.version ?? FALLBACK_PACKAGE_VERSION;
+    }
+    catch {
+        // Bundled single-file harnesses do not always carry a sibling package.json.
+        return FALLBACK_PACKAGE_VERSION;
+    }
+};

package/dist/tier-i-import-graph.d.ts

@@ -0,0 +1,7 @@
+import { type EquivExecutionContext } from './equiv-execution-context.ts';
+import type { EquivCheckResult, ImportGraphOptions } from './types.ts';
+declare const checkImportGraphWithContext: (options: ImportGraphOptions, context: EquivExecutionContext) => Promise<EquivCheckResult>;
+export declare const checkImportGraph: (options: ImportGraphOptions) => Promise<EquivCheckResult>;
+export { checkImportGraphWithContext };
+export type { BareImportUsage, ImportGraphAnalysis } from './analysis-context.ts';
+//# sourceMappingURL=tier-i-import-graph.d.ts.map