@loomhelix/deptrail 0.1.0

package/dist/actions/dry-run.js

@@ -0,0 +1,287 @@
+import { posix } from 'node:path';
+import { SEVERITY_ORDER } from "../enrich/types.js";
+import { PLACEHOLDER_PREFIX } from "../model.js";
+import { compareVersions, graphDiff, packageVersions } from "../query/graph-diff.js";
+import { messageOf, parseRootLockfile } from "../scan/build-root.js";
+import { edgeMoveWarnings } from "./edge-moves.js";
+import { ROOT_MANIFEST, WORKSPACE_FILE, applySteps, manifestPathOf, relockPins, stepPaths } from "./edit-plan.js";
+import { checkGoals } from "./goal-check.js";
+import { parseManagerVersion } from "./overrides-location.js";
+import { LOCKFILE_ONLY_ARGS, PROBE_TIMEOUT_MS, SANDBOX_TIMEOUT_MS, commandText } from "./recipes.js";
+import { sharedRootWarnings } from "./shared-packages.js";
+import { createSandbox } from "./sandbox.js";
+import { truncateUtf8, unifiedDiff } from "./text-diff.js";
+export { checkGoals };
+export const LOCKFILE_DIFF_MAX_BYTES = 2_097_152;
+export const STDERR_TAIL_CHARS = 400;
+const OUTPUT_WARNING_LIMIT = 20;
+const CANCELED_MESSAGE = 'canceled';
+const SANDBOX_TIMEOUT_TEXT = `${SANDBOX_TIMEOUT_MS / 60_000} minutes`;
+const PROBE_TIMEOUT_TEXT = `${PROBE_TIMEOUT_MS / 1000} seconds`;
+const VERSION_ARGS = ['--version'];
+const EOVERRIDE_CODE = 'EOVERRIDE';
+const EOVERRIDE_HINT = ' npm refused an override of a direct dependency; update the direct dependency instead.';
+const PNPM_WARNING_PREFIX = 'WARN';
+const NPM_WARNING_PREFIX = 'npm warn';
+const LOCKFILE_VERSION_PATTERN = /^\s*"?lockfileVersion"?\s*:\s*['"]?([0-9][\w.]*)/m;
+export class DryRunError extends Error {
+    cancelled;
+    constructor(message, cancelled = false) {
+        super(message);
+        this.cancelled = cancelled;
+    }
+}
+function throwIfCancelled(signal) {
+    if (signal.aborted)
+        throw new DryRunError(CANCELED_MESSAGE, true);
+}
+function manifestPaths(root) {
+    return [...new Set([ROOT_MANIFEST, ...root.importers.map((importer) => manifestPathOf(importer.id))])].sort();
+}
+async function readTexts(sandbox, paths) {
+    const texts = new Map();
+    for (const path of paths)
+        texts.set(path, await sandbox.readText(path));
+    return texts;
+}
+function editedTexts(texts, steps) {
+    const changed = new Map();
+    for (const path of stepPaths(steps)) {
+        const stepsOfPath = steps.filter((step) => stepPaths([step])[0] === path);
+        try {
+            for (const [changedPath, text] of applySteps(texts, stepsOfPath))
+                changed.set(changedPath, text);
+        }
+        catch (failure) {
+            throw new DryRunError(`could not edit ${path}: ${messageOf(failure)}`);
+        }
+    }
+    return changed;
+}
+async function editSandbox(sandbox, texts, steps) {
+    const previous = new Map();
+    for (const [path, text] of editedTexts(texts, steps)) {
+        previous.set(path, texts.get(path) ?? null);
+        texts.set(path, text);
+        await sandbox.writeText(path, text);
+    }
+    return previous;
+}
+async function restoreSandbox(sandbox, previous) {
+    for (const [path, text] of previous) {
+        if (text === null)
+            await sandbox.deleteFile(path);
+        else
+            await sandbox.writeText(path, text);
+    }
+}
+function isWarningLine(line) {
+    return line.startsWith(PNPM_WARNING_PREFIX) || line.toLowerCase().startsWith(NPM_WARNING_PREFIX);
+}
+function createOutputLog(input) {
+    const warnings = new Set();
+    return {
+        warnings,
+        onLine(line) {
+            const redacted = input.secrets.redact(line);
+            const trimmed = redacted.trim();
+            if (warnings.size < OUTPUT_WARNING_LIMIT && isWarningLine(trimmed))
+                warnings.add(trimmed);
+            input.onLine(redacted);
+        },
+    };
+}
+function failureMessage(command, result, secrets) {
+    const output = secrets.redact([result.stdout.trim(), result.stderr.trim()].filter((text) => text !== '').join('\n'));
+    const hint = output.includes(EOVERRIDE_CODE) ? EOVERRIDE_HINT : '';
+    return `${command} failed: ${output.slice(-STDERR_TAIL_CHARS)}${hint}`;
+}
+function startFailureMessage(input, command, failure) {
+    if (failure.code === 'ENOENT')
+        return `${input.manager.name} was not found`;
+    return `${command} could not be started: ${input.secrets.redact(messageOf(failure))}`;
+}
+async function runManager(input, run) {
+    const command = commandText(input.manager.name, run.args);
+    let result;
+    try {
+        result = await input.runner.run({
+            command: input.manager.name,
+            args: run.args,
+            cwd: run.cwd,
+            env: input.env,
+            timeoutMs: run.timeoutMs,
+            signal: input.signal,
+            ...(run.onLine === undefined ? {} : { onLine: run.onLine }),
+        });
+    }
+    catch (failure) {
+        throw new DryRunError(startFailureMessage(input, command, failure));
+    }
+    if (result.cancelled)
+        throw new DryRunError(CANCELED_MESSAGE, true);
+    if (result.timedOut)
+        throw new DryRunError(`${command} did not finish within ${run.timeoutText}`);
+    if (result.code !== 0)
+        throw new DryRunError(failureMessage(command, result, input.secrets));
+    return result;
+}
+async function checkSandboxManager(input, cwd) {
+    const result = await runManager(input, { args: VERSION_ARGS, cwd, timeoutMs: PROBE_TIMEOUT_MS, timeoutText: PROBE_TIMEOUT_TEXT });
+    const found = parseManagerVersion(result.stdout);
+    if (found === undefined)
+        throw new DryRunError(`${commandText(input.manager.name, VERSION_ARGS)} printed no version in the temporary copy`);
+    if (found !== input.manager.version)
+        throw new DryRunError(`the temporary copy runs ${input.manager.name} ${found} instead of ${input.manager.version}`);
+}
+async function resolveLockfile(input, cwd, output) {
+    await runManager(input, { args: LOCKFILE_ONLY_ARGS[input.manager.name], cwd, timeoutMs: SANDBOX_TIMEOUT_MS, timeoutText: SANDBOX_TIMEOUT_TEXT, onLine: output.onLine });
+}
+function lockfileVersionOf(text) {
+    return text === null ? undefined : LOCKFILE_VERSION_PATTERN.exec(text)?.[1];
+}
+function lockfileVersionWarning(before, after) {
+    const from = lockfileVersionOf(before);
+    const to = lockfileVersionOf(after);
+    return from !== undefined && to !== undefined && from !== to ? [`Lockfile format version changes from ${from} to ${to}`] : [];
+}
+function writtenTexts(paths, originals, finals) {
+    const written = new Map();
+    for (const path of paths) {
+        const text = finals.get(path) ?? null;
+        if (text !== null && text !== originals.get(path))
+            written.set(path, text);
+    }
+    return written;
+}
+function previewFiles(written, originals, lockfile, shared) {
+    const files = [];
+    let lockfileDiff = { diff: '', truncated: false };
+    for (const [path, text] of written) {
+        const original = originals.get(path) ?? null;
+        const { diff, added, removed } = unifiedDiff(path, original, text);
+        const change = original === null ? 'created' : 'modified';
+        const sharedWith = (shared.get(path) ?? []).map((sharing) => sharing.id);
+        const sharedMark = sharedWith.length > 0 ? { sharedWith } : {};
+        if (path !== lockfile) {
+            files.push({ path, change, added, removed, diff, ...sharedMark });
+            continue;
+        }
+        const cut = truncateUtf8(diff, LOCKFILE_DIFF_MAX_BYTES);
+        lockfileDiff = { diff: cut.text, truncated: cut.truncated };
+        files.push({ path, change, added, removed, ...sharedMark, ...(cut.truncated ? { diffTruncated: true } : {}) });
+    }
+    return { files, lockfileDiff };
+}
+function isRegistryPackage(node) {
+    return node.nonRegistry !== true && !node.id.startsWith(PLACEHOLDER_PREFIX);
+}
+function newPackages(before, after) {
+    const known = packageVersions(before);
+    const fresh = new Map();
+    for (const node of after.packages.values()) {
+        if (!isRegistryPackage(node) || known.get(node.name)?.has(node.version))
+            continue;
+        fresh.set(`${node.name}@${node.version}`, { name: node.name, version: node.version });
+    }
+    return [...fresh.values()].sort((left, right) => (left.name === right.name ? compareVersions(left.version, right.version) : left.name < right.name ? -1 : 1));
+}
+function severityRank(issue) {
+    return issue.severity === undefined ? SEVERITY_ORDER.length : SEVERITY_ORDER.indexOf(issue.severity);
+}
+function compareIssues(left, right) {
+    const bySeverity = severityRank(left) - severityRank(right);
+    if (bySeverity !== 0)
+        return bySeverity;
+    if (left.name !== right.name)
+        return left.name < right.name ? -1 : 1;
+    return compareVersions(left.version, right.version);
+}
+function issueOf(assessed) {
+    if (assessed.severity === undefined && assessed.deprecated === undefined && assessed.notChecked === undefined)
+        return undefined;
+    return {
+        name: assessed.name,
+        version: assessed.version,
+        ...(assessed.severity === undefined ? {} : { severity: assessed.severity }),
+        vulnIds: assessed.vulnIds,
+        ...(assessed.deprecated === undefined ? {} : { deprecated: assessed.deprecated }),
+        ...(assessed.notChecked === undefined ? {} : { notChecked: assessed.notChecked }),
+    };
+}
+async function newIssues(input, after) {
+    const packages = newPackages(input.root, after);
+    if (packages.length === 0)
+        return [];
+    const assessed = await input.assess(packages);
+    return assessed.flatMap((entry) => issueOf(entry) ?? []).sort(compareIssues);
+}
+function parsedLockfile(input, text) {
+    if (text === null)
+        throw new DryRunError(`could not parse the new lockfile: ${input.lockfile} was not written`);
+    const parsed = parseRootLockfile(input.root, input.lockfile, text);
+    if ('error' in parsed)
+        throw new DryRunError(`could not parse the new lockfile: ${input.secrets.redact(parsed.error)}`);
+    return parsed.graph;
+}
+export async function runDryRun(input) {
+    input.onPhase('staging');
+    const manifests = manifestPaths(input.root);
+    const writeList = [...manifests, WORKSPACE_FILE, input.lockfile];
+    const sandbox = await createSandbox({
+        scope: input.scope,
+        manager: input.manager,
+        importerPaths: manifests.map((path) => posix.dirname(path)),
+        lockfile: input.lockfile,
+    });
+    try {
+        throwIfCancelled(input.signal);
+        const originals = await readTexts(sandbox, writeList);
+        const steps = input.items.flatMap((item) => item.steps);
+        const texts = new Map(originals);
+        await editSandbox(sandbox, texts, steps);
+        const relocks = steps.filter((step) => step.kind === 'relock');
+        const pins = relockPins(input.root, input.manager.name, relocks, input.overridesFile);
+        const beforePins = await editSandbox(sandbox, texts, pins);
+        throwIfCancelled(input.signal);
+        input.onPhase('resolving');
+        const output = createOutputLog(input);
+        await checkSandboxManager(input, sandbox.dir);
+        await resolveLockfile(input, sandbox.dir, output);
+        if (beforePins.size > 0) {
+            await restoreSandbox(sandbox, beforePins);
+            await resolveLockfile(input, sandbox.dir, output);
+        }
+        input.onPhase('checking');
+        const finals = await readTexts(sandbox, writeList);
+        const after = parsedLockfile(input, finals.get(input.lockfile) ?? null);
+        const issues = await newIssues(input, after);
+        throwIfCancelled(input.signal);
+        const written = writtenTexts(writeList, originals, finals);
+        const { files, lockfileDiff } = previewFiles(written, originals, input.lockfile, input.sharedManifests);
+        const warnings = [
+            ...input.items.flatMap((item) => item.warnings),
+            ...lockfileVersionWarning(originals.get(input.lockfile) ?? null, finals.get(input.lockfile) ?? null),
+            ...edgeMoveWarnings(steps, input.root, after),
+            ...sharedRootWarnings([...written.keys()], input.sharedManifests),
+            ...output.warnings,
+        ];
+        const preview = {
+            id: input.previewId,
+            rootId: input.root.id,
+            createdAt: input.now().toISOString(),
+            stale: false,
+            manager: { name: input.manager.name, version: input.manager.version },
+            goals: checkGoals(input.items, input.root, after, input.view),
+            newIssues: issues,
+            warnings: [...new Set(warnings)],
+            files,
+            packageChanges: graphDiff(input.root, after),
+            ...(input.scope.outsideManifests.length > 0 ? { outsidePackages: input.scope.outsideManifests.length } : {}),
+        };
+        return { preview, written, originals, sources: new Map(sandbox.sources), lockfileDiff };
+    }
+    finally {
+        await sandbox.remove();
+    }
+}

package/dist/actions/edge-moves.js

@@ -0,0 +1,108 @@
+import semver from 'semver';
+import { PLACEHOLDER_PREFIX } from "../model.js";
+import { selectorParts } from "./edit-plan.js";
+import { importerLabel } from "./labels.js";
+import { catalogNameOf } from "./range-style.js";
+const DEFAULT_CATALOG = 'default';
+function targetedName(step) {
+    if (step.kind === 'relock')
+        return step.name;
+    if (step.kind === 'override')
+        return selectorParts(step.selector).name;
+    return undefined;
+}
+function isImporter(parent) {
+    return 'path' in parent;
+}
+function edgeKey(parent, edge) {
+    return isImporter(parent) ? `${parent.id}\0${edge.kind}\0${edge.range}` : `${parent.name}@${parent.version}\0${edge.kind}`;
+}
+function parentLabel(parent) {
+    return isImporter(parent) ? importerLabel(parent.id) : `${parent.name} ${parent.version}`;
+}
+function editedCatalogs(steps, name) {
+    const edits = steps.filter((step) => step.kind === 'set-range' && step.place === 'catalog' && step.dependency === name);
+    return new Set(edits.map((step) => step.catalog ?? DEFAULT_CATALOG));
+}
+function isSetByUpdate(parent, edge, catalogs) {
+    if (!isImporter(parent))
+        return false;
+    const catalog = catalogNameOf(edge.range);
+    return catalog !== undefined && catalogs.has(catalog);
+}
+function resolutionsOf(graph, name, catalogs) {
+    const resolutions = new Map();
+    const parents = [...graph.importers, ...[...graph.packages.values()].filter((node) => !node.id.startsWith(PLACEHOLDER_PREFIX))];
+    for (const parent of parents) {
+        for (const edge of parent.deps) {
+            const child = graph.packages.get(edge.to);
+            if (child === undefined || child.name !== name || child.id.startsWith(PLACEHOLDER_PREFIX))
+                continue;
+            if (isSetByUpdate(parent, edge, catalogs))
+                continue;
+            const key = edgeKey(parent, edge);
+            const known = resolutions.get(key);
+            if (known === undefined)
+                resolutions.set(key, { label: parentLabel(parent), versions: new Set([child.version]) });
+            else
+                known.versions.add(child.version);
+        }
+    }
+    return resolutions;
+}
+function onlyIn(source, other) {
+    return [...source].filter((version) => !other.has(version));
+}
+function satisfiesValue(version, value) {
+    if (version === value)
+        return true;
+    return semver.valid(version) !== null && semver.validRange(value) !== null && semver.satisfies(version, value);
+}
+function selectorMatches(range, version) {
+    if (range === undefined)
+        return true;
+    return semver.valid(version) !== null && semver.validRange(range) !== null && semver.satisfies(version, range);
+}
+function isIntended(intended, name, from, to) {
+    if (intended.relocks.some((step) => step.name === name && step.from === from && step.to === to))
+        return true;
+    return intended.overrides.some((step) => {
+        const selector = selectorParts(step.selector);
+        return selector.name === name && satisfiesValue(to, step.value) && selectorMatches(selector.range, from);
+    });
+}
+function isDowngrade(from, to) {
+    return semver.valid(from) !== null && semver.valid(to) !== null && semver.lt(to, from);
+}
+function moveText(label, name, from, to) {
+    return `${label} moves ${name} ${from} → ${to}${isDowngrade(from, to) ? ' (downgrade)' : ''}`;
+}
+function sameVersions(left, right) {
+    return left.size === right.size && [...left].every((version) => right.has(version));
+}
+export function edgeMoveWarnings(steps, before, after) {
+    const intended = {
+        relocks: steps.filter((step) => step.kind === 'relock'),
+        overrides: steps.filter((step) => step.kind === 'override'),
+    };
+    const names = new Set(steps.flatMap((step) => targetedName(step) ?? []));
+    const warnings = new Set();
+    for (const name of names) {
+        const catalogs = editedCatalogs(steps, name);
+        const afterResolutions = resolutionsOf(after, name, catalogs);
+        for (const [key, previous] of resolutionsOf(before, name, catalogs)) {
+            const current = afterResolutions.get(key);
+            if (current === undefined || sameVersions(previous.versions, current.versions))
+                continue;
+            const removed = onlyIn(previous.versions, current.versions);
+            const added = onlyIn(current.versions, previous.versions);
+            for (const from of removed.length > 0 ? removed : [...previous.versions]) {
+                for (const to of added.length > 0 ? added : [...current.versions]) {
+                    if (from !== to && !isIntended(intended, name, from, to))
+                        warnings.add(moveText(previous.label, name, from, to));
+                }
+            }
+        }
+    }
+    return [...warnings];
+}

package/dist/actions/edit-plan.js

@@ -0,0 +1,179 @@
+import { parse } from 'yaml';
+import semver from 'semver';
+import { setJsonString } from "./json-edit.js";
+import { fieldOf, importerLabel } from "./labels.js";
+import { findNode } from "../query/lookup.js";
+import { setWorkspaceString } from "./workspace-edit.js";
+export const ROOT_MANIFEST = 'package.json';
+export const WORKSPACE_FILE = 'pnpm-workspace.yaml';
+const IMPORTER_ID_PREFIX = 'importer:';
+const ROOT_IMPORTER_PATH = '.';
+const DEFAULT_CATALOG = 'default';
+export class EditError extends Error {
+}
+export function manifestPathOf(importer) {
+    const path = importer.startsWith(IMPORTER_ID_PREFIX) ? importer.slice(IMPORTER_ID_PREFIX.length) : importer;
+    return path === ROOT_IMPORTER_PATH ? ROOT_MANIFEST : `${path}/package.json`;
+}
+export function overridesFilePath(file) {
+    return file === 'pnpm-workspace.yaml' ? WORKSPACE_FILE : ROOT_MANIFEST;
+}
+function pathOfStep(step) {
+    if (step.kind === 'relock')
+        return undefined;
+    if (step.kind === 'override')
+        return overridesFilePath(step.file);
+    return step.place === 'catalog' ? WORKSPACE_FILE : manifestPathOf(step.importer);
+}
+export function stepPaths(steps) {
+    const paths = new Set();
+    for (const step of steps) {
+        const path = pathOfStep(step);
+        if (path !== undefined)
+            paths.add(path);
+    }
+    return [...paths];
+}
+function stepKey(step) {
+    const { reason: _reason, ...rest } = step;
+    return JSON.stringify(rest);
+}
+function hasDefaultCatalogEntry(text, dependency) {
+    if (text === null)
+        return false;
+    const document = parse(text);
+    if (typeof document !== 'object' || document === null)
+        return false;
+    const catalogs = document.catalogs;
+    if (typeof catalogs !== 'object' || catalogs === null)
+        return false;
+    const entries = catalogs[DEFAULT_CATALOG];
+    return typeof entries === 'object' && entries !== null && dependency in entries;
+}
+function catalogPath(step, text) {
+    if (step.catalog !== undefined)
+        return ['catalogs', step.catalog, step.dependency];
+    if (hasDefaultCatalogEntry(text, step.dependency))
+        return ['catalogs', DEFAULT_CATALOG, step.dependency];
+    return ['catalog', step.dependency];
+}
+function overridePath(step) {
+    if (step.file === 'package.json#pnpm.overrides')
+        return ['pnpm', 'overrides', step.selector];
+    return ['overrides', step.selector];
+}
+function applyOne(path, text, step) {
+    if (path === WORKSPACE_FILE) {
+        const target = step.kind === 'override' ? ['overrides', step.selector] : catalogPath(step, text);
+        return setWorkspaceString(text, target, step.kind === 'override' ? step.value : step.to);
+    }
+    if (text === null)
+        throw new EditError(`${path} is missing`);
+    const target = step.kind === 'override' ? overridePath(step) : [step.field, step.dependency];
+    return setJsonString(text, target, step.kind === 'override' ? step.value : step.to);
+}
+export function applySteps(texts, steps) {
+    const current = new Map(texts);
+    const changed = new Map();
+    const applied = new Set();
+    for (const step of steps) {
+        if (step.kind === 'relock')
+            continue;
+        const key = stepKey(step);
+        if (applied.has(key))
+            continue;
+        applied.add(key);
+        const path = pathOfStep(step);
+        const next = applyOne(path, current.get(path) ?? null, step);
+        current.set(path, next);
+        changed.set(path, next);
+    }
+    return changed;
+}
+function pinnedImporterSteps(root, relock) {
+    const steps = [];
+    for (const importer of root.importers) {
+        for (const edge of importer.deps) {
+            const field = fieldOf(edge.kind);
+            const node = findNode(root, edge.to);
+            if (field === undefined || node === undefined || node.name !== relock.name)
+                continue;
+            if (!('version' in node) || node.version !== relock.from)
+                continue;
+            if (semver.validRange(edge.range) === null || !semver.satisfies(relock.from, edge.range))
+                continue;
+            steps.push({
+                kind: 'set-range',
+                importer: importer.id,
+                dependency: relock.name,
+                field,
+                place: 'manifest',
+                from: edge.range,
+                to: relock.to,
+                reason: `npm rejects an override that changes a direct dependency of ${importerLabel(importer.id)}`,
+            });
+        }
+    }
+    return steps;
+}
+export function relockPins(root, manager, relocks, file) {
+    const steps = [];
+    for (const relock of relocks) {
+        steps.push({ kind: 'override', selector: `${relock.name}@${relock.from}`, value: relock.to, file, reason: relock.reason });
+        if (manager === 'npm')
+            steps.push(...pinnedImporterSteps(root, relock));
+    }
+    return steps;
+}
+export function sameGoal(left, right) {
+    if (left.kind === 'fix' && right.kind === 'fix')
+        return left.name === right.name && left.version === right.version;
+    if (left.kind === 'update' && right.kind === 'update')
+        return left.name === right.name;
+    return false;
+}
+function setTarget(step) {
+    return step.place === 'catalog' ? `catalog:${step.catalog ?? DEFAULT_CATALOG}` : step.importer;
+}
+function setLocation(step) {
+    return step.place === 'catalog' ? `the ${step.catalog ?? DEFAULT_CATALOG} catalog` : importerLabel(step.importer);
+}
+export function selectorParts(selector) {
+    const separator = selector.lastIndexOf('@');
+    if (separator <= 0)
+        return { name: selector.split('>').pop() };
+    return { name: selector.slice(0, separator).split('>').pop(), range: selector.slice(separator + 1) };
+}
+function selectorMatchesRelock(step, relock) {
+    const { name, range } = selectorParts(step.selector);
+    return name === relock.name && range !== undefined && semver.validRange(range) !== null && semver.satisfies(relock.from, range);
+}
+function stepConflict(first, second) {
+    if (first.kind === 'set-range' && second.kind === 'set-range') {
+        const same = setTarget(first) === setTarget(second) && first.dependency === second.dependency;
+        return same && first.to !== second.to ? `both set ${first.dependency} in ${setLocation(first)}` : undefined;
+    }
+    if (first.kind === 'override' && second.kind === 'override') {
+        return first.selector === second.selector && first.value !== second.value ? `both override ${first.selector}` : undefined;
+    }
+    if (first.kind === 'relock' && second.kind === 'relock') {
+        return first.name === second.name && first.from === second.from && first.to !== second.to ? `both re-lock ${first.name} ${first.from}` : undefined;
+    }
+    const [overrideStep, relockStep] = first.kind === 'override' ? [first, second] : [second, first];
+    if (overrideStep.kind === 'override' && relockStep.kind === 'relock' && selectorMatchesRelock(overrideStep, relockStep)) {
+        return `the override ${overrideStep.selector} also matches the re-lock of ${relockStep.name} ${relockStep.from}`;
+    }
+    return undefined;
+}
+export function findConflict(items, candidate) {
+    for (const item of items) {
+        for (const existing of item.steps) {
+            for (const proposed of candidate.steps) {
+                const reason = stepConflict(existing, proposed);
+                if (reason !== undefined)
+                    return { item, reason };
+            }
+        }
+    }
+    return undefined;
+}

package/dist/actions/file-scope.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import path, { posix } from 'node:path';
+import { compileWorkspacePatterns } from "../config/glob.js";
+import { IMPORTER_PREFIX } from "../model.js";
+export class OutsideScopeError extends Error {
+}
+const PARENT_SEGMENT = '..';
+const PARENT_PREFIX = '../';
+const PACKAGE_MANIFEST = 'package.json';
+const UNREACHABLE_CODES = new Set(['ENOENT', 'ENOTDIR', 'ELOOP']);
+function isMissing(failure) {
+    return failure.code === 'ENOENT';
+}
+function isUnreachable(failure) {
+    return UNREACHABLE_CODES.has(failure.code ?? '');
+}
+function isInside(realBase, candidate) {
+    return candidate === realBase || candidate.startsWith(realBase + path.sep);
+}
+export function leavesRoot(relative) {
+    const normalized = posix.normalize(relative);
+    return normalized === PARENT_SEGMENT || normalized.startsWith(PARENT_PREFIX) || posix.isAbsolute(normalized);
+}
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function outsideScopeError(relative) {
+    return new OutsideScopeError(`${relative} is outside the root directory and its declared workspace packages`);
+}
+function unresolvedManifestError(relative) {
+    return new OutsideScopeError(`${relative} is missing or resolves outside its workspace package`);
+}
+export function outsideImporters(root) {
+    const isDeclared = compileWorkspacePatterns(root.config?.workspacePatterns ?? []);
+    const declared = [];
+    for (const importer of root.importers) {
+        const rootRelative = posix.normalize(importer.id.slice(IMPORTER_PREFIX.length));
+        if (!leavesRoot(rootRelative))
+            continue;
+        if (leavesRoot(importer.path)) {
+            return { declared, problem: { kind: 'outside-repository', path: rootRelative } };
+        }
+        if (root.manager === 'npm')
+            return { declared, problem: { kind: 'npm', path: rootRelative } };
+        if (!isDeclared(rootRelative))
+            return { declared, problem: { kind: 'undeclared', path: rootRelative } };
+        declared.push(rootRelative);
+    }
+    return { declared };
+}
+export function fileScopeOf(repoPath, root) {
+    const { declared } = outsideImporters(root);
+    return {
+        rootDir: path.join(repoPath, root.path),
+        repoDir: repoPath,
+        outsideManifests: declared.map((declaredPath) => `${declaredPath}/${PACKAGE_MANIFEST}`),
+    };
+}
+async function resolveInsideRoot(scope, relative, normalized) {
+    const realRoot = await realpath(scope.rootDir);
+    const requested = path.resolve(realRoot, ...normalized.split('/'));
+    if (!isInside(realRoot, requested))
+        throw outsideScopeError(relative);
+    let resolved;
+    try {
+        resolved = await realpath(requested);
+    }
+    catch (failure) {
+        if (!isMissing(failure))
+            throw failure;
+        resolved = path.join(await realpath(path.dirname(requested)), path.basename(requested));
+    }
+    if (!isInside(realRoot, resolved))
+        throw outsideScopeError(relative);
+    return resolved;
+}
+async function resolveDeclaredManifest(scope, relative, normalized) {
+    if (!scope.outsideManifests.includes(normalized))
+        throw outsideScopeError(relative);
+    const requested = path.resolve(scope.rootDir, ...normalized.split('/'));
+    let real;
+    try {
+        real = await Promise.all([realpath(scope.repoDir), realpath(path.dirname(requested)), realpath(requested)]);
+    }
+    catch (failure) {
+        if (isUnreachable(failure))
+            throw unresolvedManifestError(relative);
+        throw failure;
+    }
+    const [realRepo, realPackageDir, realFile] = real;
+    if (!isInside(realRepo, realPackageDir) || !realFile.startsWith(realPackageDir + path.sep))
+        throw unresolvedManifestError(relative);
+    return realFile;
+}
+export async function resolveInScope(scope, relative) {
+    if (posix.isAbsolute(relative) || path.isAbsolute(relative))
+        throw outsideScopeError(relative);
+    const normalized = posix.normalize(relative);
+    if (leavesRoot(normalized))
+        return resolveDeclaredManifest(scope, relative, normalized);
+    return resolveInsideRoot(scope, relative, normalized);
+}
+export async function readInScope(scope, relative) {
+    try {
+        return await readFile(await resolveInScope(scope, relative));
+    }
+    catch {
+        return null;
+    }
+}
+export async function hashSources(scope, paths) {
+    const entries = await Promise.all(paths.map(async (relative) => {
+        const content = await readInScope(scope, relative);
+        return [relative, content === null ? null : sha256Hex(content)];
+    }));
+    return new Map(entries);
+}