ushman-equiv 0.4.0

package/dist/tier-r-replay.js

@@ -0,0 +1,382 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readdir } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { canonicalize, hydrateCanonicalized } from "./canonicalize.js";
+import { createEquivExecutionContext } from "./equiv-execution-context.js";
+import { compareStrings } from "./shared.js";
+import { assertV4Workspace, chunk, createFilterMatcher, DEFAULT_EQUIV_MODE, DEFAULT_MAX_CONCURRENCY, MAX_MAX_CONCURRENCY, defaultFixturesDir, defaultModulesDir, directoryExists, displayPath, fileExists, readJsonFile, resolveWithinWorkspace, sanitizeSymbolName, sha256Text, toFileImportUrl, } from "./workspace.js";
+const createFallbackModulePath = (modulesDir, fn) => join(modulesDir, `${sanitizeSymbolName(fn)}.mjs`);
+const isReplayFixtureDocument = (value) => Boolean(value) &&
+    typeof value === 'object' &&
+    typeof value.fn === 'string' &&
+    Array.isArray(value.calls);
+const resolveReplayMaxConcurrency = (value) => {
+    if (value === undefined) {
+        return DEFAULT_MAX_CONCURRENCY;
+    }
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error('maxConcurrency must be a positive integer.');
+    }
+    if (value > MAX_MAX_CONCURRENCY) {
+        throw new Error(`maxConcurrency must be less than or equal to ${MAX_MAX_CONCURRENCY}.`);
+    }
+    return value;
+};
+const standardizeFixture = ({ fixturePath, modulesDir, value, workspaceRoot, }) => {
+    if (Array.isArray(value)) {
+        const fn = basename(fixturePath, extname(fixturePath));
+        return {
+            calls: value.map((entry) => ({
+                args: Array.isArray(entry.args) ? entry.args : [],
+                expected: 'expected' in entry ? entry.expected : undefined,
+                thisArg: 'thisArg' in entry ? entry.thisArg : undefined,
+                threw: 'threw' in entry ? entry.threw : undefined,
+            })),
+            fallbackModulePath: createFallbackModulePath(modulesDir, fn),
+            fixturePath,
+            fn,
+        };
+    }
+    if (!isReplayFixtureDocument(value)) {
+        throw new Error(`Invalid replay fixture: ${fixturePath}`);
+    }
+    return {
+        calls: value.calls.map((entry) => ({
+            args: Array.isArray(entry.args) ? entry.args : [],
+            expected: Object.hasOwn(entry, 'return') ? entry.return : entry.expected,
+            thisArg: entry.thisArg,
+            threw: entry.threw,
+        })),
+        fallbackModulePath: typeof value.module === 'string'
+            ? resolveWithinWorkspace(workspaceRoot, value.module)
+            : createFallbackModulePath(modulesDir, value.fn),
+        fixturePath,
+        fn: value.fn,
+    };
+};
+const loadFixture = async ({ fixturePath, modulesDir, workspaceRoot, }) => {
+    const result = await readJsonFile(fixturePath);
+    if (result.status !== 'ok') {
+        throw new Error(result.status === 'missing' ? `Missing fixture ${fixturePath}` : result.message);
+    }
+    return standardizeFixture({
+        fixturePath,
+        modulesDir,
+        value: result.value,
+        workspaceRoot,
+    });
+};
+const loadExportedFunction = async ({ exportName, modulePath, salt, }) => {
+    if (!(await fileExists(modulePath))) {
+        throw new Error(`Missing module file: ${modulePath}`);
+    }
+    let importedModule;
+    try {
+        importedModule = (await import(__rewriteRelativeImportExtension(toFileImportUrl(modulePath, salt))));
+    }
+    catch (error) {
+        throw new Error(`Unable to import ${modulePath} for ${exportName} (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const exportedValue = importedModule[exportName];
+    if (typeof exportedValue !== 'function') {
+        throw new Error(`Module does not export a callable ${exportName}.`);
+    }
+    return exportedValue;
+};
+const resolveReplayTarget = async ({ exportFiles, fixture, workspaceRoot, }) => {
+    const failedAttempts = [];
+    const attemptedModules = [];
+    const seenModules = new Set();
+    const candidateModulePath = exportFiles.get(fixture.fn);
+    for (const modulePath of [candidateModulePath, fixture.fallbackModulePath].filter((value) => typeof value === 'string' && value.length > 0)) {
+        if (seenModules.has(modulePath)) {
+            continue;
+        }
+        seenModules.add(modulePath);
+        attemptedModules.push(modulePath);
+        try {
+            return {
+                findings: [],
+                targetFunction: await loadExportedFunction({
+                    exportName: fixture.fn,
+                    modulePath,
+                    salt: `${fixture.fn}-${attemptedModules.length}`,
+                }),
+            };
+        }
+        catch (error) {
+            failedAttempts.push({
+                evidence: error instanceof Error ? error.message : String(error),
+                message: `Failed to load ${fixture.fn} from ${displayPath(workspaceRoot, modulePath)}.`,
+                path: displayPath(workspaceRoot, modulePath),
+                symbol: fixture.fn,
+            });
+        }
+    }
+    failedAttempts.push({
+        evidence: attemptedModules.map((modulePath) => displayPath(workspaceRoot, modulePath)),
+        message: `Unable to resolve a callable export for ${fixture.fn}.`,
+        path: attemptedModules[0]
+            ? displayPath(workspaceRoot, attemptedModules[0])
+            : displayPath(workspaceRoot, fixture.fixturePath),
+        symbol: fixture.fn,
+    });
+    return {
+        findings: failedAttempts,
+        targetFunction: null,
+    };
+};
+const stableEvidenceString = (value) => {
+    try {
+        const serialized = JSON.stringify(canonicalize(value));
+        return serialized === undefined ? 'undefined' : serialized;
+    }
+    catch {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? String(value) : serialized;
+    }
+};
+const createReplayDriftFinding = ({ actual, expected, fixture, message, workspaceRoot, }) => ({
+    evidence: {
+        actual,
+        actualHash: sha256Text(stableEvidenceString(actual)),
+        expected,
+        expectedHash: sha256Text(stableEvidenceString(expected)),
+    },
+    message,
+    path: displayPath(workspaceRoot, fixture.fixturePath),
+    symbol: fixture.fn,
+});
+const runReplayCall = async ({ fixture, index, targetFunction, workspaceRoot, }) => {
+    const call = fixture.calls[index];
+    const args = call.args.map((entry) => hydrateCanonicalized(entry));
+    const thisArg = hydrateCanonicalized(call.thisArg);
+    try {
+        const value = await Promise.resolve(targetFunction.apply(thisArg, args));
+        if (call.threw !== undefined && call.threw !== null) {
+            return {
+                finding: createReplayDriftFinding({
+                    actual: canonicalize(value),
+                    expected: call.threw,
+                    fixture,
+                    message: `Replay expected ${fixture.fn} call #${index + 1} to throw, but it returned.`,
+                    workspaceRoot,
+                }),
+                kind: 'drift',
+            };
+        }
+        const actual = canonicalize(value);
+        if (isDeepStrictEqual(actual, call.expected)) {
+            return { finding: null, kind: 'matched' };
+        }
+        return {
+            finding: createReplayDriftFinding({
+                actual,
+                expected: call.expected,
+                fixture,
+                message: `Replay drift for ${fixture.fn} call #${index + 1}.`,
+                workspaceRoot,
+            }),
+            kind: 'drift',
+        };
+    }
+    catch (error) {
+        if (call.threw !== undefined && call.threw !== null) {
+            const actual = canonicalize(error);
+            if (isDeepStrictEqual(actual, call.threw)) {
+                return { finding: null, kind: 'matched' };
+            }
+            return {
+                finding: createReplayDriftFinding({
+                    actual,
+                    expected: call.threw,
+                    fixture,
+                    message: `Replay threw a different value for ${fixture.fn} call #${index + 1}.`,
+                    workspaceRoot,
+                }),
+                kind: 'drift',
+            };
+        }
+        return {
+            finding: {
+                evidence: error instanceof Error ? (error.stack ?? error.message) : String(error),
+                message: `Replay threw for ${fixture.fn} call #${index + 1}.`,
+                path: displayPath(workspaceRoot, fixture.fixturePath),
+                symbol: fixture.fn,
+            },
+            kind: 'error',
+        };
+    }
+};
+const processFixture = async ({ exportFiles, fixture, workspaceRoot, }) => {
+    const { findings, targetFunction } = await resolveReplayTarget({
+        exportFiles,
+        fixture,
+        workspaceRoot,
+    });
+    if (!targetFunction) {
+        return { driftCount: 0, errorCount: findings.length, findings, matched: 0 };
+    }
+    let driftCount = 0;
+    let errorCount = findings.length;
+    let matched = 0;
+    for (const [index] of fixture.calls.entries()) {
+        const result = await runReplayCall({
+            fixture,
+            index,
+            targetFunction,
+            workspaceRoot,
+        });
+        if (result.kind === 'matched') {
+            matched += 1;
+        }
+        if (result.kind === 'drift') {
+            driftCount += 1;
+        }
+        if (result.kind === 'error') {
+            errorCount += 1;
+        }
+        if (result.finding) {
+            findings.push(result.finding);
+        }
+    }
+    return { driftCount, errorCount, findings, matched };
+};
+const loadSelectedFixtures = async ({ fixturesDir, matcher, modulesDir, workspaceRoot, }) => {
+    const fixtureFiles = (await readdir(fixturesDir))
+        .filter((entry) => entry.endsWith('.json'))
+        .map((entry) => join(fixturesDir, entry))
+        .sort(compareStrings);
+    const results = await Promise.all(fixtureFiles.map(async (fixturePath) => {
+        try {
+            const fixture = await loadFixture({
+                fixturePath,
+                modulesDir,
+                workspaceRoot,
+            });
+            return matcher(fixture.fn) ? { fixture } : {};
+        }
+        catch (error) {
+            return {
+                detail: {
+                    evidence: error instanceof Error ? error.message : String(error),
+                    message: `Unable to load replay fixture ${displayPath(workspaceRoot, fixturePath)}.`,
+                    path: displayPath(workspaceRoot, fixturePath),
+                },
+            };
+        }
+    }));
+    return {
+        details: results.flatMap((result) => (result.detail ? [result.detail] : [])),
+        fixtures: results.flatMap((result) => (result.fixture ? [result.fixture] : [])),
+    };
+};
+const createReplayBootFailure = ({ diagnostics, elapsedMs, mode, }) => ({
+    details: [
+        {
+            evidence: diagnostics,
+            message: `Candidate ${mode} boot failed before tier R replay started.`,
+        },
+    ],
+    elapsedMs,
+    severity: 'red',
+    summary: `mode=${mode}, booted=false, fixtures=0, matched=0, drift=0, errors=1`,
+    tier: 'R',
+});
+const resolveReplayDirectories = (options) => ({
+    fixturesDir: options.fixturesDir
+        ? resolveWithinWorkspace(options.workspaceRoot, options.fixturesDir)
+        : defaultFixturesDir(options.workspaceRoot),
+    modulesDir: options.modulesDir
+        ? resolveWithinWorkspace(options.workspaceRoot, options.modulesDir)
+        : defaultModulesDir(options.workspaceRoot),
+});
+const checkReplayWithContext = async (options, context) => {
+    const start = Date.now();
+    await assertV4Workspace(options.workspaceRoot);
+    const mode = options.mode ?? DEFAULT_EQUIV_MODE;
+    const bootResult = await context.getCandidateBoot({
+        mode,
+        workspaceRoot: options.workspaceRoot,
+    });
+    if (!bootResult.ok) {
+        return createReplayBootFailure({
+            diagnostics: bootResult.diagnostics,
+            elapsedMs: Date.now() - start,
+            mode,
+        });
+    }
+    const { fixturesDir, modulesDir } = resolveReplayDirectories(options);
+    const details = [];
+    if (!(await directoryExists(fixturesDir))) {
+        details.push({
+            message: `Replay fixtures directory is missing: ${displayPath(options.workspaceRoot, fixturesDir)}. Generate fixtures under .lab/characterize/replay before relying on tier R.`,
+            path: displayPath(options.workspaceRoot, fixturesDir),
+        });
+        return {
+            details,
+            elapsedMs: Date.now() - start,
+            severity: 'yellow',
+            summary: `mode=${mode}, booted=true, fixtures=0, matched=0, drift=0, errors=1`,
+            tier: 'R',
+        };
+    }
+    const matcher = createFilterMatcher(options.filter);
+    const loadedFixtures = await loadSelectedFixtures({
+        fixturesDir,
+        matcher,
+        modulesDir,
+        workspaceRoot: options.workspaceRoot,
+    });
+    const fixtures = loadedFixtures.fixtures;
+    details.push(...loadedFixtures.details);
+    if (fixtures.length === 0) {
+        details.push({
+            message: `Replay fixtures directory is present but empty after filtering: ${displayPath(options.workspaceRoot, fixturesDir)}`,
+            path: displayPath(options.workspaceRoot, fixturesDir),
+        });
+    }
+    const candidateSymbols = await context.getCandidateSymbols({
+        entrypoint: options.entrypoint,
+        filter: options.filter,
+        srcRoots: options.srcRoots,
+        workspaceRoot: options.workspaceRoot,
+    });
+    details.push(...candidateSymbols.errors);
+    details.push(...candidateSymbols.warnings);
+    let driftCount = 0;
+    let errorCount = loadedFixtures.details.length + candidateSymbols.errors.length;
+    let matched = 0;
+    const maxConcurrency = resolveReplayMaxConcurrency(options.maxConcurrency);
+    for (const fixtureChunk of chunk(fixtures, maxConcurrency)) {
+        const results = await Promise.all(fixtureChunk.map((fixture) => processFixture({
+            exportFiles: candidateSymbols.exportFiles,
+            fixture,
+            workspaceRoot: options.workspaceRoot,
+        })));
+        for (const result of results) {
+            driftCount += result.driftCount;
+            errorCount += result.errorCount;
+            matched += result.matched;
+            details.push(...result.findings);
+        }
+    }
+    const severity = driftCount > 0 || errorCount > 0 ? 'red' : fixtures.length === 0 ? 'yellow' : 'green';
+    return {
+        details: details.length > 0 ? details : undefined,
+        elapsedMs: Date.now() - start,
+        severity,
+        summary: `mode=${mode}, booted=true, fixtures=${fixtures.length}, matched=${matched}, drift=${driftCount}, errors=${errorCount}`,
+        tier: 'R',
+    };
+};
+export const checkReplay = async (options) => checkReplayWithContext(options, createEquivExecutionContext());
+export { checkReplayWithContext };

package/dist/tier-s-symbol-diff.d.ts

@@ -0,0 +1,19 @@
+import { type EquivExecutionContext } from './equiv-execution-context.ts';
+import type { EquivCheckResult, SymbolDiffOptions } from './types.ts';
+export declare const emitSymbolBaseline: (options: {
+    readonly bundlePath: string;
+    readonly outputPath: string;
+} | {
+    readonly entrypoint?: string;
+    readonly filter?: string;
+    readonly outputPath?: string;
+    readonly srcRoots?: readonly string[];
+    readonly workspaceRoot: string;
+}) => Promise<{
+    readonly outputPath: string;
+    readonly symbolCount: number;
+}>;
+declare const checkSymbolDiffWithContext: (options: SymbolDiffOptions, context: EquivExecutionContext) => Promise<EquivCheckResult>;
+export declare const checkSymbolDiff: (options: SymbolDiffOptions) => Promise<EquivCheckResult>;
+export { checkSymbolDiffWithContext };
+//# sourceMappingURL=tier-s-symbol-diff.d.ts.map

package/dist/tier-s-symbol-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tier-s-symbol-diff.d.ts","sourceRoot":"","sources":["../src/tier-s-symbol-diff.ts"],"names":[],"mappings":"AACA,OAAO,EAA+B,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAEvG,OAAO,KAAK,EACR,gBAAgB,EAIhB,iBAAiB,EACpB,MAAM,YAAY,CAAC;AAoHpB,eAAO,MAAM,kBAAkB,GAC3B,SACM;IACI,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B,GACD;IACI,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,KACR,OAAO,CAAC;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAKvE,CAAC;AAwBF,QAAA,MAAM,0BAA0B,GAC5B,SAAS,iBAAiB,EAC1B,SAAS,qBAAqB,KAC/B,OAAO,CAAC,gBAAgB,CAoE1B,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,SAAS,iBAAiB,KAAG,OAAO,CAAC,gBAAgB,CACrB,CAAC;AAEvE,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/tier-s-symbol-diff.js

@@ -0,0 +1,156 @@
+import { scanTopLevelDeclarations } from "./analysis-context.js";
+import { createEquivExecutionContext } from "./equiv-execution-context.js";
+import { compareStrings } from "./shared.js";
+import { EQUIV_BASELINE_SCHEMA_NAME, EQUIV_BASELINE_SCHEMA_VERSION } from "./types.js";
+import { assertV4Workspace, createFilterMatcher, defaultBaselineSymbolsPath, displayPath, parseSourceFile, readJsonFile, resolveWorkspaceInputPath, sha256File, sha256Text, writeTextFileAtomically, } from "./workspace.js";
+const collectTopLevelDeclarations = async (filePath) => {
+    const { ast } = await parseSourceFile(filePath);
+    return new Map(scanTopLevelDeclarations(ast).declarations);
+};
+const createBaselineDocument = ({ sourceKind, sourcePath, sourceSha256, topLevelDecls, }) => ({
+    createdAt: new Date().toISOString().replace(/\.\d+Z$/u, 'Z'),
+    schemaName: EQUIV_BASELINE_SCHEMA_NAME,
+    schemaVersion: EQUIV_BASELINE_SCHEMA_VERSION,
+    source: {
+        kind: sourceKind,
+        path: sourcePath,
+        sha256: sourceSha256,
+    },
+    topLevelDecls,
+});
+const emitBundleSymbolBaseline = async ({ bundlePath, outputPath, }) => {
+    const declarations = await collectTopLevelDeclarations(bundlePath);
+    const document = createBaselineDocument({
+        sourceKind: 'bundle',
+        sourcePath: bundlePath,
+        sourceSha256: await sha256File(bundlePath),
+        topLevelDecls: [...declarations.entries()]
+            .sort(([left], [right]) => compareStrings(left, right))
+            .map(([name, kind]) => ({
+            kind,
+            name,
+        })),
+    });
+    await writeTextFileAtomically(outputPath, `${JSON.stringify(document, null, 2)}\n`);
+    return {
+        outputPath,
+        symbolCount: document.topLevelDecls.length,
+    };
+};
+const formatBaselineEmitFailure = (errors) => [
+    `Cannot emit a baseline because ${errors.length} source file${errors.length === 1 ? '' : 's'} failed to parse.`,
+    ...errors.slice(0, 5).map((error) => (error.path ? `${error.path}: ${error.message}` : error.message)),
+].join('\n');
+const emitWorkspaceSymbolBaseline = async ({ entrypoint, filter, outputPath, srcRoots, workspaceRoot, }) => {
+    await assertV4Workspace(workspaceRoot);
+    const candidateSymbols = await createEquivExecutionContext().getCandidateSymbols({
+        entrypoint,
+        filter,
+        srcRoots,
+        workspaceRoot,
+    });
+    if (candidateSymbols.errors.length > 0) {
+        throw new Error(formatBaselineEmitFailure(candidateSymbols.errors));
+    }
+    const resolvedOutputPath = outputPath ?? defaultBaselineSymbolsPath(workspaceRoot);
+    const sourceFingerprint = sha256Text(candidateSymbols.symbols.map((declaration) => `${declaration.kind}:${declaration.name}`).join('\n'));
+    const document = createBaselineDocument({
+        sourceKind: 'workspace',
+        sourcePath: workspaceRoot,
+        sourceSha256: sourceFingerprint,
+        topLevelDecls: candidateSymbols.symbols,
+    });
+    await writeTextFileAtomically(resolvedOutputPath, `${JSON.stringify(document, null, 2)}\n`);
+    return {
+        outputPath: resolvedOutputPath,
+        symbolCount: document.topLevelDecls.length,
+    };
+};
+export const emitSymbolBaseline = async (options) => {
+    if ('bundlePath' in options) {
+        return emitBundleSymbolBaseline(options);
+    }
+    return emitWorkspaceSymbolBaseline(options);
+};
+const isLegacySymbolBaselineDocument = (value) => Boolean(value) &&
+    typeof value === 'object' &&
+    value.schemaName === 'ushman.equiv-baseline';
+const isSymbolBaselineDocument = (value) => value.schemaName === EQUIV_BASELINE_SCHEMA_NAME &&
+    value.schemaVersion === EQUIV_BASELINE_SCHEMA_VERSION &&
+    value.source !== null &&
+    typeof value.source === 'object' &&
+    typeof value.source.kind === 'string' &&
+    typeof value.source.path === 'string' &&
+    typeof value.source.sha256 === 'string' &&
+    Array.isArray(value.topLevelDecls) &&
+    value.topLevelDecls.every((declaration) => Boolean(declaration) &&
+        typeof declaration === 'object' &&
+        typeof declaration.name === 'string' &&
+        typeof declaration.kind === 'string');
+const checkSymbolDiffWithContext = async (options, context) => {
+    const start = Date.now();
+    await assertV4Workspace(options.workspaceRoot);
+    const baselinePath = options.baselineSymbolsPath
+        ? resolveWorkspaceInputPath(options.workspaceRoot, options.baselineSymbolsPath)
+        : defaultBaselineSymbolsPath(options.workspaceRoot);
+    const baselineResult = await readJsonFile(baselinePath);
+    const details = [];
+    if (baselineResult.status !== 'ok') {
+        details.push({
+            message: baselineResult.status === 'missing'
+                ? `Baseline symbols file is missing: ${displayPath(options.workspaceRoot, baselinePath)}`
+                : `Invalid baseline symbols file: ${baselineResult.message}`,
+            path: displayPath(options.workspaceRoot, baselinePath),
+        });
+        return {
+            details,
+            elapsedMs: Date.now() - start,
+            severity: 'red',
+            summary: 'baseline=0, candidate=0, dropped=0, extras=0',
+            tier: 'S',
+        };
+    }
+    if (!isSymbolBaselineDocument(baselineResult.value)) {
+        const legacyHint = isLegacySymbolBaselineDocument(baselineResult.value)
+            ? ' Legacy v3 baseline files are not supported after the v4 hard cutover; regenerate the baseline from the v4 workspace.'
+            : '';
+        return {
+            details: [
+                {
+                    message: `Baseline symbols file has an invalid schema or declaration shape: ${displayPath(options.workspaceRoot, baselinePath)}.${legacyHint}`,
+                    path: displayPath(options.workspaceRoot, baselinePath),
+                },
+            ],
+            elapsedMs: Date.now() - start,
+            severity: 'red',
+            summary: 'baseline=0, candidate=0, dropped=0, extras=0',
+            tier: 'S',
+        };
+    }
+    const matcher = createFilterMatcher(options.filter);
+    const baselineNames = baselineResult.value.topLevelDecls
+        .map((declaration) => declaration.name)
+        .filter((name) => matcher(name));
+    const candidateSymbols = await context.getCandidateSymbols(options);
+    details.push(...candidateSymbols.errors);
+    details.push(...candidateSymbols.warnings);
+    const candidateSet = new Set(candidateSymbols.symbolNames);
+    const baselineSet = new Set(baselineNames);
+    const dropped = [...baselineSet].filter((name) => !candidateSet.has(name)).sort(compareStrings);
+    const extras = [...candidateSet].filter((name) => !baselineSet.has(name)).sort(compareStrings);
+    for (const name of dropped) {
+        details.push({
+            message: `Baseline symbol is missing from the candidate: ${name}`,
+            symbol: name,
+        });
+    }
+    return {
+        details: details.length > 0 ? details : undefined,
+        elapsedMs: Date.now() - start,
+        severity: dropped.length > 0 || candidateSymbols.errors.length > 0 ? 'red' : 'green',
+        summary: `baseline=${baselineNames.length}, candidate=${candidateSymbols.symbolNames.length}, dropped=${dropped.length}, extras=${extras.length}`,
+        tier: 'S',
+    };
+};
+export const checkSymbolDiff = async (options) => checkSymbolDiffWithContext(options, createEquivExecutionContext());
+export { checkSymbolDiffWithContext };

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+export declare const EQUIV_REPORT_VERSION = "1.0.0";
+export declare const EQUIV_RESULT_SCHEMA_NAME = "ushman-equiv-result";
+export declare const EQUIV_RESULT_SCHEMA_VERSION = "ushman-equiv-result/v1";
+export declare const EQUIV_BASELINE_SCHEMA_NAME = "ushman-equiv-baseline";
+export declare const EQUIV_BASELINE_SCHEMA_VERSION = "ushman-equiv-baseline/v1";
+export declare const ALL_TIERS: readonly ["I", "L", "S", "R"];
+export declare const ALL_EQUIV_MODES: readonly ["preview", "dev"];
+export type EquivTier = (typeof ALL_TIERS)[number];
+export type EquivMode = (typeof ALL_EQUIV_MODES)[number];
+export type EquivSeverity = 'green' | 'yellow' | 'red';
+export type EquivFinding = {
+    readonly evidence?: unknown;
+    readonly message: string;
+    readonly path?: string;
+    readonly symbol?: string;
+};
+export type EquivCheckResult = {
+    readonly details?: readonly EquivFinding[];
+    readonly elapsedMs: number;
+    readonly severity: EquivSeverity;
+    readonly summary: string;
+    readonly tier: EquivTier;
+};
+export type EquivReport = {
+    readonly checks: readonly EquivCheckResult[];
+    readonly createdAt: string;
+    readonly mode: EquivMode;
+    readonly reportVersion: typeof EQUIV_REPORT_VERSION;
+    readonly schemaName: typeof EQUIV_RESULT_SCHEMA_NAME;
+    readonly schemaVersion: typeof EQUIV_RESULT_SCHEMA_VERSION;
+    readonly tiers: readonly EquivTier[];
+    readonly ushmanEquivVersion: string;
+    readonly verdict: EquivSeverity;
+    readonly workspace: string;
+};
+type CommonTierOptions = {
+    readonly entrypoint?: string;
+    readonly filter?: string;
+    readonly mode?: EquivMode;
+    readonly srcRoots?: readonly string[];
+    readonly workspaceRoot: string;
+};
+export type EquivOptions = CommonTierOptions & {
+    readonly baselineSymbolsPath?: string;
+    readonly fixturesDir?: string;
+    readonly maxConcurrency?: number;
+    readonly modulesDir?: string;
+    readonly tiers?: readonly EquivTier[];
+};
+export type ImportGraphOptions = CommonTierOptions;
+export type ModuleLoadOptions = CommonTierOptions;
+export type SymbolBaselineDeclKind = 'class' | 'const' | 'export' | 'function' | 'let' | 'var';
+export type SymbolBaselineDeclaration = {
+    readonly kind: SymbolBaselineDeclKind;
+    readonly name: string;
+};
+export type SymbolBaselineSource = {
+    readonly kind: 'bundle' | 'workspace';
+    readonly path: string;
+    readonly sha256: string;
+};
+export type SymbolBaselineDocument = {
+    readonly createdAt: string;
+    readonly schemaName: typeof EQUIV_BASELINE_SCHEMA_NAME;
+    readonly schemaVersion: typeof EQUIV_BASELINE_SCHEMA_VERSION;
+    readonly source: SymbolBaselineSource;
+    readonly topLevelDecls: readonly SymbolBaselineDeclaration[];
+};
+export type SymbolDiffOptions = CommonTierOptions & {
+    readonly baselineSymbolsPath?: string;
+};
+export type ReplayCallRecord = {
+    readonly args?: readonly unknown[];
+    readonly expected?: unknown;
+    readonly return?: unknown;
+    readonly thisArg?: unknown;
+    readonly threw?: unknown;
+};
+export type ReplayFixtureDocument = {
+    readonly calls: readonly ReplayCallRecord[];
+    readonly fn: string;
+    readonly module?: string;
+};
+export type ReplayOptions = CommonTierOptions & {
+    readonly fixturesDir?: string;
+    readonly maxConcurrency?: number;
+    readonly modulesDir?: string;
+};
+export declare const verdictForChecks: (checks: readonly EquivCheckResult[]) => EquivSeverity;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,19 @@
+export const EQUIV_REPORT_VERSION = '1.0.0';
+export const EQUIV_RESULT_SCHEMA_NAME = 'ushman-equiv-result';
+export const EQUIV_RESULT_SCHEMA_VERSION = 'ushman-equiv-result/v1';
+export const EQUIV_BASELINE_SCHEMA_NAME = 'ushman-equiv-baseline';
+export const EQUIV_BASELINE_SCHEMA_VERSION = 'ushman-equiv-baseline/v1';
+export const ALL_TIERS = ['I', 'L', 'S', 'R'];
+export const ALL_EQUIV_MODES = ['preview', 'dev'];
+export const verdictForChecks = (checks) => {
+    if (checks.length === 0) {
+        return 'yellow';
+    }
+    if (checks.some((check) => check.severity === 'red')) {
+        return 'red';
+    }
+    if (checks.some((check) => check.severity === 'yellow')) {
+        return 'yellow';
+    }
+    return 'green';
+};