ushman-equiv 0.4.0

package/dist/workspace.d.ts

@@ -0,0 +1,63 @@
+import type { File } from '@babel/types';
+import type { WorkspacePaths } from 'ushman-lab-types';
+import { assertV4Workspace, buildV3MigrationMessage, createWorkspaceLayoutError, detectWorkspaceLayout, resolveWorkspacePaths, V4_MIGRATION_EXIT_CODE, WorkspaceLayoutError } from 'ushman-lab-types';
+export declare const DEFAULT_MAX_CONCURRENCY = 4;
+export declare const DEFAULT_EQUIV_MODE: "preview";
+export declare const DEFAULT_SRC_ROOTS: readonly ["src"];
+export declare const MAX_MAX_CONCURRENCY = 64;
+type JsonLoadResult<T> = {
+    readonly status: 'ok';
+    readonly value: T;
+} | {
+    readonly status: 'missing';
+} | {
+    readonly message: string;
+    readonly status: 'invalid';
+};
+export type { WorkspaceLayout, WorkspacePaths } from 'ushman-lab-types';
+export { assertV4Workspace, buildV3MigrationMessage, createWorkspaceLayoutError, detectWorkspaceLayout, resolveWorkspacePaths, V4_MIGRATION_EXIT_CODE, WorkspaceLayoutError, };
+export declare const defaultBaselineSymbolsPath: (workspaceRoot: string, resolvedPaths?: WorkspacePaths) => string;
+export declare const defaultFixturesDir: (workspaceRoot: string, resolvedPaths?: WorkspacePaths) => string;
+export declare const defaultModulesDir: (workspaceRoot: string, resolvedPaths?: WorkspacePaths) => string;
+export declare const defaultResultPath: (workspaceRoot: string, resolvedPaths?: WorkspacePaths) => string;
+export declare const isBareSpecifier: (specifier: string) => boolean;
+export declare const normalizeImportSpecifier: (specifier: string) => string;
+export declare const resolveWithinWorkspace: (workspaceRoot: string, candidatePath: string) => string;
+export declare const displayPath: (workspaceRoot: string, targetPath: string) => string;
+export declare const fileExists: (filePath: string) => Promise<boolean>;
+export declare const directoryExists: (filePath: string) => Promise<boolean>;
+export declare const readJsonFile: <T>(filePath: string) => Promise<JsonLoadResult<T>>;
+export declare const resolveWorkspaceInputPath: (workspaceRoot: string, candidatePath: string) => string;
+export declare const parseSourceText: (filePath: string, source: string) => File;
+export declare const parseSourceFile: (filePath: string) => Promise<{
+    readonly ast: File;
+    readonly source: string;
+}>;
+export type SourceFileCollection = {
+    readonly files: readonly string[];
+    readonly missingRoots: readonly string[];
+};
+export declare const collectSourceFiles: ({ includeEntrypoint, srcRoots, workspaceRoot, }: {
+    readonly includeEntrypoint?: string;
+    readonly srcRoots?: readonly string[];
+    readonly workspaceRoot: string;
+}) => Promise<SourceFileCollection>;
+export declare const discoverEntrypoint: ({ entrypoint, workspaceRoot, }: {
+    readonly entrypoint?: string;
+    readonly workspaceRoot: string;
+}) => Promise<string>;
+export declare const loadImportMap: (workspaceRoot: string) => Promise<Readonly<Record<string, string>>>;
+export declare const importMapMatchesSpecifier: (importMap: Readonly<Record<string, string>>, specifier: string) => string | null;
+export declare const resolveRelativeSpecifier: ({ importerPath, specifier, workspaceRoot, }: {
+    readonly importerPath: string;
+    readonly specifier: string;
+    readonly workspaceRoot: string;
+}) => Promise<string | null>;
+export declare const writeTextFileAtomically: (filePath: string, content: string) => Promise<void>;
+export declare const sha256Text: (value: string) => string;
+export declare const sha256File: (filePath: string) => Promise<string>;
+export declare const createFilterMatcher: (filter: string | undefined) => ((value: string) => boolean);
+export declare const chunk: <T>(values: readonly T[], size: number) => readonly (readonly T[])[];
+export declare const toFileImportUrl: (filePath: string, salt?: string) => string;
+export declare const sanitizeSymbolName: (value: string) => string;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

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

package/dist/workspace.js

@@ -0,0 +1,459 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse } from '@babel/parser';
+import { assertV4Workspace, buildV3MigrationMessage, createWorkspaceLayoutError, detectWorkspaceLayout, resolveWorkspacePaths, V4_MIGRATION_EXIT_CODE, WorkspaceLayoutError, } from 'ushman-lab-types';
+import { compareStrings } from "./shared.js";
+export const DEFAULT_MAX_CONCURRENCY = 4;
+export const DEFAULT_EQUIV_MODE = 'preview';
+export const DEFAULT_SRC_ROOTS = ['src'];
+export const MAX_MAX_CONCURRENCY = 64;
+const DEFAULT_FIXTURES_SUBDIR = 'replay';
+const DEFAULT_MODULES_SUBDIR = 'modules';
+const DEFAULT_RESULT_FILE = 'result.json';
+const DEFAULT_BASELINE_FILE = 'baseline.json';
+const FALLBACK_HTML_CANDIDATES = ['index.html', 'public/index.html'];
+const IGNORED_WALK_DIRECTORIES = new Set(['.git', '.lab', '.vite', 'asl', 'dist', 'node_modules']);
+const SOURCE_EXTENSIONS = ['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx'];
+const RELATIVE_RESOLUTION_EXTENSIONS = ['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx'];
+const COMMON_BABEL_PLUGINS = ['decorators-legacy', 'dynamicImport', 'importAttributes', 'topLevelAwait'];
+const REAL_WORKSPACE_ROOT_CACHE = new Map();
+const isStringRecord = (value) => value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.values(value).every((entry) => typeof entry === 'string');
+export { assertV4Workspace, buildV3MigrationMessage, createWorkspaceLayoutError, detectWorkspaceLayout, resolveWorkspacePaths, V4_MIGRATION_EXIT_CODE, WorkspaceLayoutError, };
+const isSourceExtension = (filePath) => SOURCE_EXTENSIONS.some((extension) => filePath.endsWith(extension));
+const resolveV4Paths = (workspaceRoot, resolvedPaths) => (resolvedPaths ?? resolveWorkspacePaths(workspaceRoot)).v4;
+export const defaultBaselineSymbolsPath = (workspaceRoot, resolvedPaths) => path.join(resolveV4Paths(workspaceRoot, resolvedPaths).equiv, DEFAULT_BASELINE_FILE);
+export const defaultFixturesDir = (workspaceRoot, resolvedPaths) => path.join(resolveV4Paths(workspaceRoot, resolvedPaths).characterize, DEFAULT_FIXTURES_SUBDIR);
+export const defaultModulesDir = (workspaceRoot, resolvedPaths) => path.join(resolveV4Paths(workspaceRoot, resolvedPaths).characterize, DEFAULT_MODULES_SUBDIR);
+export const defaultResultPath = (workspaceRoot, resolvedPaths) => path.join(resolveV4Paths(workspaceRoot, resolvedPaths).equiv, DEFAULT_RESULT_FILE);
+export const isBareSpecifier = (specifier) => !specifier.startsWith('.') &&
+    !specifier.startsWith('/') &&
+    !specifier.startsWith('file:') &&
+    !specifier.startsWith('node:');
+export const normalizeImportSpecifier = (specifier) => specifier.replace(/[?#].*$/u, '');
+const isWithinWorkspace = (workspaceRoot, targetPath) => {
+    const relativePath = path.relative(workspaceRoot, targetPath);
+    return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+};
+const resolveLexicalWorkspaceRoot = (workspaceRoot) => path.resolve(workspaceRoot);
+const resolveRealWorkspaceRoot = (workspaceRoot) => {
+    const lexicalRoot = resolveLexicalWorkspaceRoot(workspaceRoot);
+    const cached = REAL_WORKSPACE_ROOT_CACHE.get(lexicalRoot);
+    if (cached) {
+        return cached;
+    }
+    const realRoot = realpathSync(lexicalRoot);
+    REAL_WORKSPACE_ROOT_CACHE.set(lexicalRoot, realRoot);
+    return realRoot;
+};
+const resolveWorkspaceCandidatePath = (workspaceRoot, candidatePath) => {
+    const lexicalRoot = resolveLexicalWorkspaceRoot(workspaceRoot);
+    if (path.isAbsolute(candidatePath) && isWithinWorkspace(lexicalRoot, candidatePath)) {
+        return path.resolve(candidatePath);
+    }
+    return candidatePath.startsWith('/')
+        ? path.resolve(lexicalRoot, `.${candidatePath}`)
+        : path.resolve(lexicalRoot, candidatePath);
+};
+const resolveNearestExistingRealPath = (rootPath, candidatePath) => {
+    let currentPath = candidatePath;
+    while (true) {
+        try {
+            return realpathSync(currentPath);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT') {
+                throw error;
+            }
+            if (currentPath === rootPath) {
+                throw error;
+            }
+            const parentPath = path.dirname(currentPath);
+            if (!isWithinWorkspace(rootPath, parentPath)) {
+                return realpathSync(rootPath);
+            }
+            currentPath = parentPath;
+        }
+    }
+};
+const assertWithinWorkspacePath = (workspaceRoot, candidatePath) => {
+    const lexicalRoot = resolveLexicalWorkspaceRoot(workspaceRoot);
+    const resolvedPath = path.resolve(candidatePath);
+    if (!isWithinWorkspace(lexicalRoot, resolvedPath)) {
+        throw new Error(`Path escapes workspace root: ${candidatePath}`);
+    }
+    const realRoot = resolveRealWorkspaceRoot(workspaceRoot);
+    const nearestExistingRealPath = resolveNearestExistingRealPath(lexicalRoot, resolvedPath);
+    if (!isWithinWorkspace(realRoot, nearestExistingRealPath)) {
+        throw new Error(`Path escapes workspace root via symlink: ${candidatePath}`);
+    }
+    return resolvedPath;
+};
+export const resolveWithinWorkspace = (workspaceRoot, candidatePath) => assertWithinWorkspacePath(workspaceRoot, resolveWorkspaceCandidatePath(workspaceRoot, candidatePath));
+export const displayPath = (workspaceRoot, targetPath) => path.relative(workspaceRoot, targetPath) || '.';
+export const fileExists = async (filePath) => {
+    try {
+        return (await stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+const getPathKind = async (filePath) => {
+    try {
+        const targetStat = await stat(filePath);
+        if (targetStat.isFile()) {
+            return 'file';
+        }
+        if (targetStat.isDirectory()) {
+            return 'directory';
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+};
+export const directoryExists = async (filePath) => {
+    try {
+        return (await stat(filePath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+export const readJsonFile = async (filePath) => {
+    try {
+        return { status: 'ok', value: JSON.parse(await readFile(filePath, 'utf8')) };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { status: 'missing' };
+        }
+        return {
+            message: error instanceof Error ? error.message : String(error),
+            status: 'invalid',
+        };
+    }
+};
+export const resolveWorkspaceInputPath = (workspaceRoot, candidatePath) => path.isAbsolute(candidatePath) ? path.resolve(candidatePath) : path.resolve(workspaceRoot, candidatePath);
+const parserPluginsForPath = (filePath) => {
+    const plugins = [...COMMON_BABEL_PLUGINS];
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+        plugins.push('typescript');
+    }
+    if (filePath.endsWith('.jsx') || filePath.endsWith('.tsx')) {
+        plugins.push('jsx');
+    }
+    return plugins;
+};
+const parserSourceTypeForPath = (filePath) => {
+    if (filePath.endsWith('.cjs')) {
+        return 'script';
+    }
+    if (filePath.endsWith('.jsx') ||
+        filePath.endsWith('.mjs') ||
+        filePath.endsWith('.ts') ||
+        filePath.endsWith('.tsx')) {
+        return 'module';
+    }
+    return 'unambiguous';
+};
+export const parseSourceText = (filePath, source) => parse(source, {
+    plugins: parserPluginsForPath(filePath),
+    sourceFilename: filePath,
+    sourceType: parserSourceTypeForPath(filePath),
+});
+export const parseSourceFile = async (filePath) => {
+    const source = await readFile(filePath, 'utf8');
+    return {
+        ast: parseSourceText(filePath, source),
+        source,
+    };
+};
+const shouldIgnoreWalkDirectory = (entryName) => IGNORED_WALK_DIRECTORIES.has(entryName) || (entryName.startsWith('.') && entryName !== '.');
+const walkDirectory = async (directoryPath) => {
+    const files = [];
+    const pendingDirectories = [directoryPath];
+    while (pendingDirectories.length > 0) {
+        const currentDirectory = pendingDirectories.pop();
+        if (!currentDirectory) {
+            continue;
+        }
+        const entries = await readdir(currentDirectory, { withFileTypes: true });
+        for (const entry of entries) {
+            const targetPath = path.join(currentDirectory, entry.name);
+            if (entry.isDirectory()) {
+                if (shouldIgnoreWalkDirectory(entry.name)) {
+                    continue;
+                }
+                pendingDirectories.push(targetPath);
+                continue;
+            }
+            if (entry.isFile()) {
+                files.push(targetPath);
+            }
+        }
+    }
+    return files;
+};
+export const collectSourceFiles = async ({ includeEntrypoint, srcRoots, workspaceRoot, }) => {
+    const missingRoots = [];
+    const collectFromSourceRoot = async (files, srcRoot) => {
+        const absoluteRoot = resolveWithinWorkspace(workspaceRoot, srcRoot);
+        const pathKind = await getPathKind(absoluteRoot);
+        if (pathKind === 'file') {
+            if (isSourceExtension(absoluteRoot)) {
+                files.add(absoluteRoot);
+            }
+            return;
+        }
+        if (pathKind !== 'directory') {
+            missingRoots.push(srcRoot);
+            return;
+        }
+        for (const candidateFile of await walkDirectory(absoluteRoot)) {
+            if (isSourceExtension(candidateFile)) {
+                files.add(candidateFile);
+            }
+        }
+    };
+    const files = new Set();
+    for (const srcRoot of srcRoots ?? DEFAULT_SRC_ROOTS) {
+        await collectFromSourceRoot(files, srcRoot);
+    }
+    if (includeEntrypoint && (await fileExists(includeEntrypoint))) {
+        files.add(includeEntrypoint);
+    }
+    return {
+        files: [...files].sort(compareStrings),
+        missingRoots,
+    };
+};
+const readWorkspaceHtmlDocument = async (workspaceRoot) => {
+    for (const relativePath of FALLBACK_HTML_CANDIDATES) {
+        const absolutePath = resolveWithinWorkspace(workspaceRoot, relativePath);
+        if (!(await fileExists(absolutePath))) {
+            continue;
+        }
+        return {
+            htmlPath: absolutePath,
+            source: await readFile(absolutePath, 'utf8'),
+        };
+    }
+    return null;
+};
+const parseHtmlAttributes = (rawAttributes) => {
+    const attributes = {};
+    const attributePattern = /([^\s=/>]+)(?:\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/gu;
+    for (const match of rawAttributes.matchAll(attributePattern)) {
+        const [, attributeName, , doubleQuoted, singleQuoted, bareValue] = match;
+        attributes[attributeName.toLowerCase()] = doubleQuoted ?? singleQuoted ?? bareValue ?? '';
+    }
+    return attributes;
+};
+const parseScriptTags = (html) => [...html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/giu)].map((match) => ({
+    attributes: parseHtmlAttributes(match[1] ?? ''),
+    content: (match[2] ?? '').trim(),
+}));
+const scoreModuleScriptSource = (candidatePath) => {
+    if (/^https?:\/\//u.test(candidatePath)) {
+        return 0;
+    }
+    if (/^(?:\/|\.\/)?src\/(?:main|index|app)\.[cm]?[jt]sx?$/u.test(candidatePath)) {
+        return 100;
+    }
+    if (/^(?:\/|\.\/)?src\//u.test(candidatePath)) {
+        return 80;
+    }
+    if (/^(?:\/|\.\/)?(?:main|index|app)\.[cm]?[jt]sx?$/u.test(candidatePath)) {
+        return 60;
+    }
+    return 40;
+};
+const extractScriptSource = (html) => {
+    const moduleScripts = parseScriptTags(html)
+        .map((scriptTag, index) => ({
+        index,
+        scriptTag,
+    }))
+        .filter((entry) => entry.scriptTag.attributes.type === 'module' && typeof entry.scriptTag.attributes.src === 'string')
+        .sort((left, right) => scoreModuleScriptSource(right.scriptTag.attributes.src) -
+        scoreModuleScriptSource(left.scriptTag.attributes.src) || left.index - right.index);
+    return moduleScripts[0]?.scriptTag.attributes.src ?? null;
+};
+const extractImportMapJson = (html) => {
+    for (const scriptTag of parseScriptTags(html)) {
+        if (scriptTag.attributes.type === 'importmap') {
+            return scriptTag.content;
+        }
+    }
+    return null;
+};
+const buildRegexMatcher = (pattern) => {
+    try {
+        return new RegExp(pattern);
+    }
+    catch (error) {
+        throw new Error(`Invalid filter regex: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const resolveHtmlRelativePath = (workspaceRoot, htmlPath, candidatePath) => {
+    if (candidatePath.startsWith('/')) {
+        return resolveWithinWorkspace(workspaceRoot, candidatePath);
+    }
+    return assertWithinWorkspacePath(workspaceRoot, path.resolve(path.dirname(htmlPath), candidatePath));
+};
+export const discoverEntrypoint = async ({ entrypoint, workspaceRoot, }) => {
+    if (entrypoint) {
+        const resolvedEntrypoint = resolveWithinWorkspace(workspaceRoot, entrypoint);
+        if (!(await fileExists(resolvedEntrypoint))) {
+            throw new Error(`Entrypoint file does not exist: ${entrypoint}`);
+        }
+        return resolvedEntrypoint;
+    }
+    const htmlDocument = await readWorkspaceHtmlDocument(workspaceRoot);
+    if (!htmlDocument) {
+        throw new Error(`Unable to locate index.html under ${workspaceRoot}`);
+    }
+    const scriptSource = extractScriptSource(htmlDocument.source);
+    if (!scriptSource) {
+        throw new Error(`Unable to locate <script type="module" src="..."> in ${displayPath(workspaceRoot, htmlDocument.htmlPath)}`);
+    }
+    return resolveHtmlRelativePath(workspaceRoot, htmlDocument.htmlPath, scriptSource);
+};
+export const loadImportMap = async (workspaceRoot) => {
+    const htmlDocument = await readWorkspaceHtmlDocument(workspaceRoot);
+    if (!htmlDocument) {
+        return {};
+    }
+    const importMapScript = parseScriptTags(htmlDocument.source).find((scriptTag) => scriptTag.attributes.type === 'importmap');
+    if (!importMapScript) {
+        return {};
+    }
+    const importMapJson = typeof importMapScript.attributes.src === 'string' && importMapScript.attributes.src.length > 0
+        ? await readFile(resolveHtmlRelativePath(workspaceRoot, htmlDocument.htmlPath, importMapScript.attributes.src), 'utf8')
+        : extractImportMapJson(htmlDocument.source);
+    if (!importMapJson) {
+        return {};
+    }
+    const parsed = JSON.parse(importMapJson);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Invalid importmap JSON: expected a top-level object.');
+    }
+    if (parsed.imports === undefined) {
+        return {};
+    }
+    if (!isStringRecord(parsed.imports)) {
+        throw new Error('Invalid importmap JSON: imports must be an object with string values.');
+    }
+    return parsed.imports;
+};
+export const importMapMatchesSpecifier = (importMap, specifier) => {
+    if (specifier in importMap) {
+        return importMap[specifier] ?? null;
+    }
+    const prefixMatch = Object.keys(importMap)
+        .filter((key) => key.endsWith('/'))
+        .sort((left, right) => right.length - left.length || compareStrings(left, right))
+        .find((key) => specifier.startsWith(key));
+    return prefixMatch ? (importMap[prefixMatch] ?? null) : null;
+};
+export const resolveRelativeSpecifier = async ({ importerPath, specifier, workspaceRoot, }) => {
+    const normalizedSpecifier = normalizeImportSpecifier(specifier);
+    const basePath = normalizedSpecifier.startsWith('/')
+        ? resolveWithinWorkspace(workspaceRoot, normalizedSpecifier)
+        : path.resolve(path.dirname(importerPath), normalizedSpecifier);
+    const candidates = new Set([basePath]);
+    if (!path.extname(basePath)) {
+        for (const extension of RELATIVE_RESOLUTION_EXTENSIONS) {
+            candidates.add(`${basePath}${extension}`);
+        }
+        for (const extension of RELATIVE_RESOLUTION_EXTENSIONS) {
+            candidates.add(path.join(basePath, `index${extension}`));
+        }
+    }
+    const existenceResults = await Promise.all([...candidates].map(async (candidatePath) => ({
+        candidatePath,
+        exists: await fileExists(candidatePath),
+    })));
+    for (const result of existenceResults) {
+        if (result.exists) {
+            return result.candidatePath;
+        }
+    }
+    return null;
+};
+export const writeTextFileAtomically = async (filePath, content) => {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tempPath, content, 'utf8');
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+};
+export const sha256Text = (value) => createHash('sha256').update(value).digest('hex');
+export const sha256File = async (filePath) => sha256Text(await readFile(filePath, 'utf8'));
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+const buildGlobExpression = (filter) => {
+    const patternParts = ['^'];
+    for (let index = 0; index < filter.length; index += 1) {
+        const character = filter[index];
+        const nextCharacter = filter[index + 1];
+        if (character === '*' && nextCharacter === '*') {
+            patternParts.push('.*');
+            index += 1;
+            continue;
+        }
+        if (character === '*') {
+            patternParts.push('[^/]*');
+            continue;
+        }
+        if (character === '?') {
+            patternParts.push('[^/]');
+            continue;
+        }
+        patternParts.push(escapeRegExp(character));
+    }
+    patternParts.push('$');
+    return new RegExp(patternParts.join(''));
+};
+export const createFilterMatcher = (filter) => {
+    if (!filter) {
+        return () => true;
+    }
+    if (filter.startsWith('/') && filter.endsWith('/') && filter.length > 1) {
+        const expression = buildRegexMatcher(filter.slice(1, -1));
+        return (value) => expression.test(value);
+    }
+    const expression = buildGlobExpression(filter);
+    return (value) => expression.test(value);
+};
+export const chunk = (values, size) => {
+    if (!Number.isFinite(size) || size <= 0) {
+        return [values];
+    }
+    const chunks = [];
+    for (let index = 0; index < values.length; index += size) {
+        chunks.push(values.slice(index, index + size));
+    }
+    return chunks;
+};
+export const toFileImportUrl = (filePath, salt) => {
+    const fileUrl = pathToFileURL(filePath);
+    if (salt) {
+        fileUrl.searchParams.set('ushman-equiv', salt);
+    }
+    return fileUrl.href;
+};
+export const sanitizeSymbolName = (value) => value.replace(/[^\w.-]+/gu, '_');

package/package.json

@@ -0,0 +1,64 @@
+{
+    "author": {
+        "name": "Ragaeeb Haq",
+        "url": "https://github.com/ragaeeb"
+    },
+    "bin": {
+        "ushman-equiv": "dist/cli.js"
+    },
+    "bugs": {
+        "url": "https://github.com/ragaeeb/ushman-equiv/issues"
+    },
+    "dependencies": {
+        "@babel/parser": "^7.29.3",
+        "@babel/traverse": "^7.29.0",
+        "@babel/types": "^7.29.0",
+        "ushman-ledger": "^0.3.0"
+    },
+    "description": "Pure-Node equivalence checks for ushman refactors. Runs import-graph, module-load, symbol-diff, and replay tiers inside Node-only sandboxes.",
+    "devDependencies": {
+        "@biomejs/biome": "^2.4.15",
+        "@types/babel__traverse": "^7.28.0",
+        "@types/bun": "1.3.14",
+        "@types/node": "^25.8.0",
+        "typescript": "^6.0.3",
+        "ushman-lab-types": "^0.1.0"
+    },
+    "engines": {
+        "node": ">=24"
+    },
+    "files": [
+        "bin",
+        "dist",
+        "README.md",
+        "AGENTS.md",
+        "LICENSE.md"
+    ],
+    "homepage": "https://github.com/ragaeeb/ushman-equiv#readme",
+    "keywords": [
+        "ushman",
+        "equiv",
+        "equivalence",
+        "llm",
+        "reverse-engineering"
+    ],
+    "license": "MIT",
+    "main": "dist/index.js",
+    "name": "ushman-equiv",
+    "packageManager": "bun@1.3.14",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ragaeeb/ushman-equiv.git"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "check": "bun run lint && bun run typecheck && bun test && bun run build",
+        "format": "biome check . --write && biome lint . --write",
+        "lint": "biome lint .",
+        "prepack": "tsc -p tsconfig.build.json",
+        "typecheck": "tsc --noEmit -p tsconfig.json"
+    },
+    "type": "module",
+    "types": "dist/index.d.ts",
+    "version": "0.4.0"
+}