@software-dlc/cli 0.157.2

package/dist/packages-uses.js

@@ -0,0 +1,737 @@
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { checkFloors, compareSemver, diffPackageContent, graphPackageContentTypes, latestVersion, markChange, packageDiffView, rebaseOverrides, renderTextView, resolvePackageUse, resolveRebase } from '@software-dlc/graph/packages';
+import { portable_graph_package_use_schema } from '@software-dlc/graph/schema';
+import { z } from 'zod';
+import { GraphPackagesLockError, defaultGraphPackagesCacheDir } from './graph-packages-lock.js';
+import { stringifyCanonicalJson } from './local/canonical.js';
+import { PACKAGE_USES_FILE } from './local/projection.js';
+import { contentTypeFor, defaultGraphPackagesSnapshotDir, defaultHeldVersion, findLocalPackage, heldVersion, localPackageSource, parsePackageSpec, readLocalPackages, withdrawnOf } from './packages-browse.js';
+/**
+ * A local graph's package uses (graph-packages.md, Local resolution): `sdlc packages use` adds,
+ * changes or removes one in the workspace's sdlc/package-uses.json, `preview` shows what a use
+ * would change, and `resolve` prints each use's resolved content. All read only the bundled
+ * snapshot and the download cache, so they work offline. A local workspace graph is a project
+ * graph; governance graphs come with the local governance graph.
+ */
+export const USE_ACTIONS = ['use', 'preview', 'resolve', 'upgrade'];
+export const PACKAGES_USES_USAGE = 'Usage: sdlc packages use <coordinate>[@<version>] [--mode reference|extend|import] [--drop-overrides]\n' +
+    '       sdlc packages use <coordinate> --remove\n' +
+    '       sdlc packages preview <coordinate>[@<version>] [--mode reference|extend|import] [--json]\n' +
+    '       sdlc packages resolve [<coordinate>] [--out <file>]\n' +
+    '       sdlc packages upgrade [<coordinate>] [--to <version>] [--json]\n' +
+    '       sdlc packages upgrade <coordinate> [--to <version>] --accept [--resolve <override>=keep_local|take_upstream|drop_override]...\n' +
+    "Use graph packages in this workspace's local graph, offline: run them in a workspace, where they read and write sdlc/package-uses.json; sdlc workspace commit records the change. " +
+    'use adds a use of a package held here (default: its newest held version that is not withdrawn, in reference mode), or changes the version or mode of the use the graph has; a withdrawn version is refused. ' +
+    'A use with overrides moves to another version only through an upgrade proposal, so use refuses that; a change to reference mode drops overrides only with --drop-overrides. ' +
+    'Overrides are edited by hand in sdlc/package-uses.json for now, and checked whenever the use resolves. --remove drops the use. ' +
+    "preview shows what using that version would change against the graph's current use (or against nothing), the overrides a version change would put in conflict, the content type's marks, and the floor findings. " +
+    'resolve prints the resolved content of each use, or the named one, as JSON with its use key, pinned content_hash and resolved hash; --out writes it to a file instead, outside sdlc/ (a path inside it is refused). ' +
+    'upgrade shows the upgrade proposal of each use, or the named one: its newest held version that is not withdrawn (or --to), with the upstream diff, the resolved diff, the overrides in conflict, the floor findings and the gates the marked changes need. ' +
+    '--accept moves the use to that version, resolving each conflicting override as --resolve says (every one needs a resolution); a floor finding refuses it. sdlc packages fetch downloads newer versions. ' +
+    'Exit 0: done; 1: refused, with the reason on stderr.';
+/**
+ * The floor check on a use's resolved content. An authoring use's findings report and do not
+ * block: they block when the version is adopted (graph-packages.md, Use).
+ */
+export function useFloors(resolved, policyFor = () => null) {
+    if (!resolved.content || !resolved.content_type)
+        return { findings: [], blocking: false };
+    const checked = checkFloors({
+        content_type: resolved.content_type,
+        resolved: resolved.content,
+        policy: policyFor(resolved.content_type) ?? null
+    });
+    return {
+        findings: checked.findings,
+        blocking: checked.blocking && !resolved.authoring
+    };
+}
+export function describeFloor(finding) {
+    return `${finding.severity} ${finding.rule}: ${finding.message}`;
+}
+function refuseFloors(resolved, local, policyFor) {
+    const floors = useFloors(resolved, policyFor);
+    if (!floors.blocking)
+        return;
+    throw new GraphPackagesLockError(`${labelOf(local, resolved.use)} (${resolved.use.mode}) breaks the org's floors: ${floors.findings
+        .filter((finding) => finding.severity === 'floor')
+        .map(describeFloor)
+        .join('; ')}`);
+}
+const package_uses_schema = z.array(portable_graph_package_use_schema);
+const MODES = ['reference', 'extend', 'import'];
+/** The projection directory of the workspace the command runs in. */
+function projectionDirOf(cwd) {
+    const dir = path.join(cwd, 'sdlc');
+    if (!existsSync(path.join(dir, 'tags.json')))
+        throw new GraphPackagesLockError(`no local graph projection at ${dir}; run this in a workspace (sdlc workspace status)`);
+    return dir;
+}
+export function readPackageUses(projection_dir) {
+    const file = path.join(projection_dir, PACKAGE_USES_FILE);
+    if (!existsSync(file))
+        return [];
+    const parsed = package_uses_schema.safeParse(JSON.parse(readFileSync(file, 'utf8')));
+    if (!parsed.success)
+        throw new GraphPackagesLockError(`${file} is not a valid list of package uses: ${parsed.error.issues
+            .map((issue) => `${issue.path.join('.') || '(uses)'}: ${issue.message}`)
+            .join('; ')}`);
+    const keys = new Set();
+    for (const use of parsed.data) {
+        const key = `${use.package_id}@${use.project_id ?? ''}`;
+        if (keys.has(key))
+            throw new GraphPackagesLockError(`${file} uses ${use.package_id}${use.project_id ? ` for project ${use.project_id}` : ''} more than once; a graph uses a package once`);
+        keys.add(key);
+    }
+    return parsed.data;
+}
+/** Written as the projection writes it; the file exists only while the graph uses a package. */
+function writePackageUses(projection_dir, uses) {
+    const file = path.join(projection_dir, PACKAGE_USES_FILE);
+    if (uses.length === 0)
+        rmSync(file, { force: true });
+    else
+        writeFileSync(file, `${stringifyCanonicalJson(uses, 2)}\n`);
+}
+/**
+ * A finding as a line, with what to do about it here. fetch finds a package by its id only while
+ * some version of it is held, so the remedy names its coordinate when that is known.
+ */
+export function describeUseFinding(finding, use, coordinate = null) {
+    if (finding.code === 'document_unavailable')
+        return coordinate
+            ? `${finding.message} Download it with sdlc packages fetch ${coordinate}@${use.version}.`
+            : `${finding.message} No version of package ${use.package_id} is held here; download it with sdlc packages fetch <its coordinate>@${use.version}.`;
+    return finding.message;
+}
+/** Resolves a use of a project graph against what is held here. */
+export function resolveLocalUse(use, source, registry) {
+    return resolvePackageUse({ use, graph: 'project', source, registry });
+}
+/** `sdlc packages use|preview|resolve`: the exit code. */
+export async function runPackagesUsesCommand(args, context = {}) {
+    const stdout = context.stdout ?? process.stdout;
+    const stderr = context.stderr ?? process.stderr;
+    try {
+        const [action, ...rest] = args;
+        const options = parseUsesOptions(action, rest);
+        const env = context.env ?? process.env;
+        const cwd = context.cwd ?? process.cwd();
+        const projection_dir = projectionDirOf(cwd);
+        const local = readLocalPackages({
+            snapshotDir: context.snapshotDir ?? defaultGraphPackagesSnapshotDir(),
+            cacheDir: defaultGraphPackagesCacheDir(env)
+        });
+        for (const warning of local.warnings)
+            stderr.write(`warning: ${warning}\n`);
+        const registry = context.registry ?? graphPackageContentTypes;
+        let output;
+        if (action === 'use')
+            output = useCommand(projection_dir, local, registry, options, context);
+        else if (action === 'preview')
+            output = previewCommand(projection_dir, local, registry, options, context);
+        else if (action === 'upgrade')
+            output = upgradeCommand(projection_dir, local, registry, options, context);
+        else
+            output = resolveCommand(projection_dir, local, registry, {
+                ...options,
+                out: options.out && path.resolve(cwd, options.out)
+            });
+        stdout.write(`${output}\n`);
+        return 0;
+    }
+    catch (error) {
+        stderr.write(`sdlc packages: ${error.message}\n`);
+        return 1;
+    }
+}
+const FLAGS = {
+    use: ['--mode', '--remove', '--drop-overrides'],
+    preview: ['--mode', '--json'],
+    resolve: ['--out'],
+    upgrade: ['--to', '--json', '--accept', '--resolve']
+};
+const RESOLUTIONS = [
+    'keep_local',
+    'take_upstream',
+    'drop_override'
+];
+function parseResolution(value, into) {
+    const match = /^(\d+)=(.+)$/.exec(value);
+    if (!match || !RESOLUTIONS.includes(match[2]))
+        throw new GraphPackagesLockError(`--resolve takes <override>=${RESOLUTIONS.join('|')}, not ${value}`);
+    const index = Number(match[1]);
+    if (into.has(index))
+        throw new GraphPackagesLockError(`--resolve names override ${index} more than once`);
+    into.set(index, match[2]);
+}
+function parseUsesOptions(action, args) {
+    const options = {
+        spec: null,
+        mode: null,
+        remove: false,
+        drop_overrides: false,
+        json: false,
+        out: null,
+        to: null,
+        accept: false,
+        resolutions: new Map()
+    };
+    const allowed = FLAGS[action];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            if (!allowed.includes(arg))
+                throw new GraphPackagesLockError(`unexpected option ${arg} for ${action}\n${PACKAGES_USES_USAGE}`);
+            if (arg === '--mode' ||
+                arg === '--out' ||
+                arg === '--to' ||
+                arg === '--resolve') {
+                const value = args[i + 1];
+                if (!value || value.startsWith('--'))
+                    throw new GraphPackagesLockError(`${arg} needs a value`);
+                i += 1;
+                if (arg === '--out')
+                    options.out = value;
+                else if (arg === '--to')
+                    options.to = value;
+                else if (arg === '--resolve')
+                    parseResolution(value, options.resolutions);
+                else if (MODES.includes(value))
+                    options.mode = value;
+                else
+                    throw new GraphPackagesLockError(`--mode is one of ${MODES.join(', ')}, not ${value}`);
+            }
+            else if (arg === '--remove')
+                options.remove = true;
+            else if (arg === '--drop-overrides')
+                options.drop_overrides = true;
+            else if (arg === '--accept')
+                options.accept = true;
+            else
+                options.json = true;
+        }
+        else if (options.spec !== null) {
+            throw new GraphPackagesLockError(`unexpected argument ${arg}\n${PACKAGES_USES_USAGE}`);
+        }
+        else
+            options.spec = arg;
+    }
+    if (action === 'upgrade') {
+        if (options.spec === null && (options.to || options.accept))
+            throw new GraphPackagesLockError(`--to and --accept need a package: sdlc packages upgrade <coordinate>\n${PACKAGES_USES_USAGE}`);
+        if (options.resolutions.size > 0 && !options.accept)
+            throw new GraphPackagesLockError('--resolve goes with --accept');
+        if (options.accept && options.json)
+            throw new GraphPackagesLockError('--accept takes no --json');
+        if (options.spec !== null && parsePackageSpec(options.spec).version)
+            throw new GraphPackagesLockError(`name the version with --to: sdlc packages upgrade ${parsePackageSpec(options.spec).coordinate} --to ${parsePackageSpec(options.spec).version}`);
+    }
+    else if (action !== 'resolve' && options.spec === null)
+        throw new GraphPackagesLockError(`name a package: <coordinate>[@<version>]\n${PACKAGES_USES_USAGE}`);
+    if (options.remove && (options.mode || options.drop_overrides))
+        throw new GraphPackagesLockError('--remove takes no --mode or --drop-overrides');
+    return options;
+}
+/**
+ * The use of the package a name gives, by coordinate or id, among the graph's uses. A project
+ * graph's uses carry no project id (one that does is a finding), so only those are matched.
+ */
+function findUse(uses, local, name) {
+    const held = local.packages.find((entry) => entry.coordinate === name || entry.id === name);
+    return (uses.find((use) => use.project_id === undefined &&
+        (use.package_id === name || use.package_id === held?.id)) ?? null);
+}
+function coordinateOf(local, use) {
+    return (local.packages.find((entry) => entry.id === use.package_id)?.coordinate ??
+        null);
+}
+function labelOf(local, use) {
+    return `${coordinateOf(local, use) ?? use.package_id}@${use.version}`;
+}
+function refuseFindings(resolved, local) {
+    if (resolved.findings.length === 0)
+        return;
+    throw new GraphPackagesLockError(`${labelOf(local, resolved.use)} (${resolved.use.mode}) cannot be used: ${resolved.findings
+        .map((finding) => describeUseFinding(finding, resolved.use, coordinateOf(local, resolved.use)))
+        .join(' ')}`);
+}
+/** The use a `use` or `preview` would leave, before it is resolved. */
+function proposedUse(uses, local, options) {
+    const { coordinate, version } = parsePackageSpec(options.spec);
+    const entry = findLocalPackage(local, coordinate);
+    const current = findUse(uses, local, entry.id);
+    const held = version
+        ? heldVersion(entry, version)
+        : current
+            ? heldVersion(entry, current.version)
+            : defaultHeldVersion(entry);
+    // The pin wins: a held document of the same version with another hash is not what the
+    // graph uses (graph-packages.md, Local resolution), so it is never re-pinned in passing.
+    const withdrawn = withdrawnOf(entry, held.version);
+    if (current &&
+        held.version === current.version &&
+        held.content_hash !== current.content_hash)
+        throw new GraphPackagesLockError(`${entry.coordinate}@${held.version} is pinned to ${current.content_hash}, but the copy held here hashes to ${held.content_hash}, so the graph's use does not resolve here. To keep the pin, this machine needs the pinned copy in place of the one it holds; ${withdrawn
+            ? `the version is withdrawn, so it cannot be added again once removed: move the use to another version instead (sdlc packages use ${entry.coordinate}@<version>)`
+            : `to pin the held copy instead, remove the use and add it again (sdlc packages use ${entry.coordinate} --remove, then sdlc packages use ${entry.coordinate}@${held.version} --mode ${options.mode ?? current.mode})`}`);
+    if (withdrawn && held.version !== current?.version)
+        throw new GraphPackagesLockError(`${entry.coordinate}@${held.version} is withdrawn${withdrawn.withdrawn_reason ? `: ${withdrawn.withdrawn_reason}` : ''}`);
+    return {
+        current,
+        next: {
+            package_id: entry.id,
+            version: held.version,
+            content_hash: held.content_hash,
+            mode: options.mode ?? current?.mode ?? 'reference',
+            overrides: current?.overrides ?? []
+        }
+    };
+}
+function useCommand(projection_dir, local, registry, options, context) {
+    const uses = readPackageUses(projection_dir);
+    if (options.remove) {
+        const { coordinate, version } = parsePackageSpec(options.spec);
+        if (version)
+            throw new GraphPackagesLockError(`--remove takes a package without a version: sdlc packages use ${coordinate} --remove`);
+        const current = findUse(uses, local, coordinate);
+        if (!current)
+            throw new GraphPackagesLockError(`this graph does not use ${coordinate}`);
+        writePackageUses(projection_dir, uses.filter((use) => use !== current));
+        return `removed the use of ${labelOf(local, current)}; record it with sdlc workspace commit`;
+    }
+    const { current, next } = proposedUse(uses, local, options);
+    if (current &&
+        current.overrides.length > 0 &&
+        (current.version !== next.version ||
+            current.content_hash !== next.content_hash)) {
+        const coordinate = coordinateOf(local, current) ?? current.package_id;
+        throw new GraphPackagesLockError(compareSemver(next.version, current.version) > 0
+            ? `${labelOf(local, current)} has ${current.overrides.length} override(s); only an upgrade proposal moves a use with overrides to another version, rebasing them: sdlc packages upgrade ${coordinate} --to ${next.version}`
+            : `${labelOf(local, current)} has ${current.overrides.length} override(s), and an upgrade proposal only moves forward; to move it to ${next.version}, remove the use and add it again, which drops its overrides (sdlc packages use ${coordinate} --remove, then sdlc packages use ${coordinate}@${next.version} --mode ${next.mode})`);
+    }
+    if (next.mode === 'reference' && next.overrides.length > 0) {
+        if (!options.drop_overrides)
+            throw new GraphPackagesLockError(`${labelOf(local, next)} has ${next.overrides.length} override(s), which a reference use cannot carry; add --drop-overrides to drop them`);
+        next.overrides = [];
+    }
+    if (current &&
+        current.version === next.version &&
+        current.content_hash === next.content_hash &&
+        current.mode === next.mode &&
+        current.overrides.length === next.overrides.length) {
+        return `this graph already uses ${labelOf(local, next)} (${next.mode})`;
+    }
+    const resolved = resolveLocalUse(next, localPackageSource(local), registry);
+    refuseFindings(resolved, local);
+    refuseFloors(resolved, local, context.floorPolicy);
+    writePackageUses(projection_dir, current
+        ? uses.map((use) => (use === current ? next : use))
+        : [...uses, next]);
+    const verb = current ? 'now uses' : 'uses';
+    const authoring = resolved.authoring
+        ? '; authoring only: this graph never reads it as active'
+        : '';
+    return `this graph ${verb} ${labelOf(local, next)} (${next.mode}), resolved hash ${resolved.resolved_hash}${authoring}; record it with sdlc workspace commit`;
+}
+const EMPTY_CONTENT = {
+    root_manifest_node_ids: [],
+    nodes: [],
+    included_edges: [],
+    included_paths: [],
+    included_path_relations: []
+};
+/** A diff view's changed items only, as text. */
+function changedText(view) {
+    const changed = view.sections
+        .map((section) => ({
+        ...section,
+        items: section.items.filter((item) => item.change)
+    }))
+        .filter((section) => section.items.length);
+    return changed.length ? renderTextView({ sections: changed }) : 'No changes.';
+}
+function floorLines(floors, authoring) {
+    return floors.findings.map((finding) => `${describeFloor(finding)}${finding.severity !== 'floor'
+        ? ''
+        : authoring
+            ? ' (reported: authoring only)'
+            : ' (blocks it)'}`);
+}
+function previewCommand(projection_dir, local, registry, options, context) {
+    const uses = readPackageUses(projection_dir);
+    const { current, next } = proposedUse(uses, local, options);
+    const source = localPackageSource(local);
+    const before = current ? resolveLocalUse(current, source, registry) : null;
+    const pinned = source.document(next.package_id, next.version);
+    const { type, known } = contentTypeFor(registry, pinned.document.package.content_type);
+    // A version change rebases the overrides: those that carry over apply, the rest conflict.
+    const moving = current !== null &&
+        next.overrides.length > 0 &&
+        current.content_hash !== next.content_hash &&
+        before?.document !== null &&
+        before?.document !== undefined;
+    const rebase = moving
+        ? rebaseOverrides({
+            from: before.document.content,
+            to: pinned.document.content,
+            overrides: next.overrides,
+            content_type: type,
+            registry
+        })
+        : null;
+    const candidate = rebase
+        ? { ...next, overrides: rebase.carried.map((entry) => entry.override) }
+        : next;
+    const after = resolveLocalUse(candidate, source, registry);
+    const before_content = before?.content ?? EMPTY_CONTENT;
+    const after_content = after.content ?? EMPTY_CONTENT;
+    const change = markChange({
+        content_type: type,
+        before: before_content,
+        after: after_content
+    });
+    const view = packageDiffView({
+        content_type: type,
+        before: before_content,
+        after: after_content
+    });
+    const conflicts = (rebase?.conflicts ?? []).map((conflict) => ({
+        index: conflict.index,
+        id: conflict.id,
+        reason: conflict.reason
+    }));
+    const floors = useFloors(after, context.floorPolicy);
+    if (options.json) {
+        return JSON.stringify({
+            package: {
+                id: next.package_id,
+                coordinate: pinned.document.package.coordinate,
+                content_type: pinned.document.package.content_type,
+                content_type_known: known
+            },
+            current: current
+                ? {
+                    version: current.version,
+                    mode: current.mode,
+                    resolved_hash: before?.resolved_hash ?? null
+                }
+                : null,
+            proposed: {
+                version: next.version,
+                mode: next.mode,
+                content_hash: next.content_hash,
+                resolved_hash: after.resolved_hash,
+                authoring: after.authoring
+            },
+            findings: after.findings.map((finding) => ({
+                code: finding.code,
+                message: describeUseFinding(finding, candidate, coordinateOf(local, candidate))
+            })),
+            conflicts,
+            floors,
+            diff: change.diff,
+            marks: change.marks,
+            required_gates: change.required_gates,
+            view
+        }, null, 2);
+    }
+    const counts = `${change.diff.added.length} added, ${change.diff.modified.length} changed, ${change.diff.deleted.length} removed`;
+    const from = current
+        ? `${labelOf(local, current)} (${current.mode})`
+        : 'no use';
+    const lines = [`${from} → ${labelOf(local, next)} (${next.mode}): ${counts}`];
+    if (after.authoring)
+        lines.push('authoring only: a use of this content type in a project graph is never read as active');
+    if (!known)
+        lines.push(`${pinned.document.package.content_type} is not known to this sdlc: drawn with the default view, with no marks`);
+    for (const finding of after.findings)
+        lines.push(`cannot be used: ${describeUseFinding(finding, candidate, coordinateOf(local, candidate))}`);
+    for (const conflict of conflicts)
+        lines.push(`override ${conflict.index} on ${conflict.id} conflicts: ${conflict.reason.replace('_', ' ')}`);
+    lines.push(...floorLines(floors, after.authoring));
+    if (change.required_gates.length)
+        lines.push(`gates the marked changes need: ${change.required_gates.join(', ')}`);
+    lines.push('', changedText(view));
+    return lines.join('\n');
+}
+/**
+ * The version a use's upgrade proposal offers: --to, or the newest held version newer than the
+ * pin that is not withdrawn. Withdrawn versions are never proposed (graph-packages.md, Withdrawal).
+ */
+function upgradeTarget(entry, current, to) {
+    if (to !== null) {
+        const held = heldVersion(entry, to);
+        const withdrawn = withdrawnOf(entry, to);
+        if (withdrawn)
+            throw new GraphPackagesLockError(`${entry.coordinate}@${to} is withdrawn${withdrawn.withdrawn_reason ? `: ${withdrawn.withdrawn_reason}` : ''}; it is never proposed`);
+        if (compareSemver(to, current.version) <= 0)
+            throw new GraphPackagesLockError(`${entry.coordinate}@${to} is not newer than the pinned ${current.version}; an upgrade moves forward (sdlc packages use moves a use without overrides to any version)`);
+        return held;
+    }
+    // The index's rule over the newer held versions: a release before any pre-release.
+    const newest = latestVersion(entry.held
+        .filter((held) => compareSemver(held.version, current.version) > 0)
+        .map((held) => ({
+        version: held.version,
+        withdrawn: Boolean(withdrawnOf(entry, held.version))
+    })));
+    return newest === null ? null : heldVersion(entry, newest);
+}
+function upgradeProposal(current, local, registry, to, policyFor) {
+    const entry = local.packages.find((held) => held.id === current.package_id);
+    if (!entry)
+        throw new GraphPackagesLockError(`no version of package ${current.package_id} is held here, so it has no upgrade proposal; download one with sdlc packages fetch <its coordinate>`);
+    const target = upgradeTarget(entry, current, to);
+    if (!target)
+        return null;
+    const source = localPackageSource(local);
+    const before = resolveLocalUse(current, source, registry);
+    // The rebase and the upstream diff start from the pinned version, so it must be held as pinned.
+    const pinned_issue = before.findings.find((finding) => finding.code === 'document_unavailable' ||
+        finding.code === 'hash_mismatch');
+    if (pinned_issue || !before.document)
+        throw new GraphPackagesLockError(`${entry.coordinate}@${current.version} (the pinned version) does not resolve here, so its upgrade cannot be worked out: ${describeUseFinding(pinned_issue, current, entry.coordinate)}`);
+    const { type } = contentTypeFor(registry, target.document.package.content_type);
+    const from_content = before.document.content;
+    const to_content = target.document.content;
+    const rebase = current.overrides.length > 0
+        ? rebaseOverrides({
+            from: from_content,
+            to: to_content,
+            overrides: current.overrides,
+            content_type: type,
+            registry
+        })
+        : null;
+    const next = {
+        ...current,
+        version: target.version,
+        content_hash: target.content_hash,
+        overrides: rebase
+            ? rebase.carried.map((entry) => entry.override)
+            : current.overrides
+    };
+    const resolved = resolveLocalUse(next, source, registry);
+    const before_content = before.content ?? EMPTY_CONTENT;
+    const after_content = resolved.content ?? EMPTY_CONTENT;
+    return {
+        coordinate: entry.coordinate,
+        current,
+        next,
+        upstream: diffPackageContent(from_content, to_content),
+        change: markChange({
+            content_type: type,
+            before: before_content,
+            after: after_content
+        }),
+        view: packageDiffView({
+            content_type: type,
+            before: before_content,
+            after: after_content
+        }),
+        conflicts: rebase?.conflicts ?? [],
+        rebase,
+        resolved,
+        floors: useFloors(resolved, policyFor)
+    };
+}
+function diffCounts(diff) {
+    return `${diff.added.length} added, ${diff.modified.length} changed, ${diff.deleted.length} removed`;
+}
+function proposalJson(proposal, local) {
+    return {
+        package: {
+            id: proposal.current.package_id,
+            coordinate: proposal.coordinate
+        },
+        from: proposal.current.version,
+        to: proposal.next.version,
+        mode: proposal.current.mode,
+        authoring: proposal.resolved.authoring,
+        upstream_diff: proposal.upstream,
+        resolved_diff: proposal.change.diff,
+        conflicts: proposal.conflicts.map((conflict) => ({
+            index: conflict.index,
+            id: conflict.id,
+            reason: conflict.reason
+        })),
+        findings: proposal.resolved.findings.map((finding) => ({
+            code: finding.code,
+            message: describeUseFinding(finding, proposal.next, coordinateOf(local, proposal.next))
+        })),
+        floors: proposal.floors,
+        marks: proposal.change.marks,
+        required_gates: proposal.change.required_gates,
+        view: proposal.view
+    };
+}
+function proposalText(proposal) {
+    const { coordinate, current, next } = proposal;
+    const lines = [
+        `${coordinate}@${current.version} → ${next.version} (${current.mode})`,
+        `upstream: ${diffCounts(proposal.upstream)}`,
+        `resolved: ${diffCounts(proposal.change.diff)}`
+    ];
+    if (proposal.resolved.authoring)
+        lines.push('authoring only: a use of this content type in a project graph is never read as active');
+    for (const conflict of proposal.conflicts)
+        lines.push(`override ${conflict.index} on ${conflict.id} conflicts: ${conflict.reason.replace('_', ' ')}${conflict.reason === 'id_taken'
+            ? ' (take_upstream or drop_override)'
+            : ''}`);
+    // Conflicting overrides are left out until resolved, so a finding here can come from that.
+    for (const finding of proposal.resolved.findings)
+        lines.push(`does not resolve as proposed: ${finding.message}`);
+    lines.push(...floorLines(proposal.floors, proposal.resolved.authoring));
+    if (proposal.change.required_gates.length)
+        lines.push(`gates the marked changes need: ${proposal.change.required_gates.join(', ')}`);
+    const resolve = proposal.conflicts
+        .map((conflict) => ` --resolve ${conflict.index}=<resolution>`)
+        .join('');
+    lines.push(`accept with: sdlc packages upgrade ${coordinate} --to ${next.version} --accept${resolve}`, '', changedText(proposal.view));
+    return lines.join('\n');
+}
+/**
+ * `sdlc packages upgrade` (graph-packages.md, Upgrade proposals): a proposal for each use with a
+ * newer held version, which nothing applies until the user accepts it. Accepting is an ordinary
+ * workspace change: it moves the pin and rebases the overrides as each conflict's resolution says.
+ */
+function upgradeCommand(projection_dir, local, registry, options, context) {
+    const uses = readPackageUses(projection_dir);
+    let selected = uses.filter((use) => use.project_id === undefined);
+    if (options.spec !== null) {
+        const use = findUse(uses, local, options.spec);
+        if (!use)
+            throw new GraphPackagesLockError(`this graph does not use ${options.spec}`);
+        selected = [use];
+    }
+    // Listing every use, one whose proposal cannot be worked out is noted, not fatal.
+    const notes = [];
+    const proposals = selected.flatMap((use) => {
+        try {
+            const proposal = upgradeProposal(use, local, registry, options.to, context.floorPolicy);
+            return proposal ? [proposal] : [];
+        }
+        catch (error) {
+            if (options.spec !== null)
+                throw error;
+            notes.push(`${labelOf(local, use)}: ${error.message}`);
+            return [];
+        }
+    });
+    for (const note of notes)
+        (context.stderr ?? process.stderr).write(`note: ${note}\n`);
+    if (options.accept) {
+        const proposal = proposals[0];
+        if (!proposal)
+            throw new GraphPackagesLockError(`${labelOf(local, selected[0])} has no newer held version that is not withdrawn; sdlc packages fetch downloads newer ones`);
+        return acceptUpgrade(projection_dir, uses, proposal, local, registry, options, context);
+    }
+    if (options.json)
+        return JSON.stringify({ proposals: proposals.map((proposal) => proposalJson(proposal, local)) }, null, 2);
+    if (proposals.length === 0)
+        return selected.length === 0
+            ? 'this graph uses no packages'
+            : 'no upgrade proposals: each use is on its newest held version that is not withdrawn; sdlc packages fetch downloads newer ones';
+    return proposals.map(proposalText).join('\n\n');
+}
+function acceptUpgrade(projection_dir, uses, proposal, local, registry, options, context) {
+    const conflicting = new Set(proposal.conflicts.map((conflict) => conflict.index));
+    const unknown = [...options.resolutions.keys()].filter((index) => !conflicting.has(index));
+    if (unknown.length)
+        throw new GraphPackagesLockError(`--resolve names override(s) ${unknown.join(', ')}, which do not conflict; the conflicting ones are ${[...conflicting].join(', ') || 'none'}`);
+    const missing = proposal.conflicts.filter((conflict) => !options.resolutions.has(conflict.index));
+    if (missing.length)
+        throw new GraphPackagesLockError(`resolve each conflicting override: ${missing
+            .map((conflict) => `--resolve ${conflict.index}=keep_local|take_upstream|drop_override (${conflict.id}: ${conflict.reason.replace('_', ' ')})`)
+            .join(', ')}`);
+    let overrides;
+    try {
+        overrides = proposal.rebase
+            ? resolveRebase(proposal.rebase, options.resolutions)
+            : proposal.current.overrides;
+    }
+    catch (error) {
+        throw new GraphPackagesLockError(error.message);
+    }
+    const next = { ...proposal.next, overrides };
+    const resolved = resolveLocalUse(next, localPackageSource(local), registry);
+    refuseFindings(resolved, local);
+    refuseFloors(resolved, local, context.floorPolicy);
+    writePackageUses(projection_dir, uses.map((use) => (use === proposal.current ? next : use)));
+    const kept = [...options.resolutions.values()].filter((resolution) => resolution === 'keep_local').length;
+    return `this graph now uses ${proposal.coordinate}@${next.version} (${next.mode}), upgraded from ${proposal.current.version}${proposal.conflicts.length
+        ? `; ${proposal.conflicts.length} conflict(s) resolved, ${kept} kept local`
+        : ''}, resolved hash ${resolved.resolved_hash}; record it with sdlc workspace commit`;
+}
+/** A path as the filesystem names it: the nearest existing ancestor's real path, plus the rest. */
+function realPathOf(file) {
+    const rest = [];
+    let at = path.resolve(file);
+    while (!existsSync(at)) {
+        const parent = path.dirname(at);
+        if (parent === at)
+            break;
+        rest.unshift(path.basename(at));
+        at = parent;
+    }
+    return path.join(realpathSync.native(at), ...rest);
+}
+/**
+ * Whether a path is the directory or inside it. macOS and Windows filesystems ignore case by
+ * default, so there the comparison does too: SDLC/x is sdlc/x.
+ */
+export function isWithin(directory, file) {
+    const fold = (value) => process.platform === 'darwin' || process.platform === 'win32'
+        ? value.toLowerCase()
+        : value;
+    const relative = path.relative(fold(realPathOf(directory)), fold(realPathOf(file)));
+    return (relative !== '..' &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative));
+}
+function resolveCommand(projection_dir, local, registry, options) {
+    // The resolved content is never part of the graph: --out stays outside the projection.
+    if (options.out) {
+        if (isWithin(projection_dir, options.out))
+            throw new GraphPackagesLockError(`--out ${options.out} is inside the graph's projection ${projection_dir}; write the resolved content outside it`);
+    }
+    const uses = readPackageUses(projection_dir);
+    let selected = uses;
+    if (options.spec !== null) {
+        const use = findUse(uses, local, options.spec);
+        if (!use)
+            throw new GraphPackagesLockError(`this graph does not use ${options.spec}`);
+        selected = [use];
+    }
+    const source = localPackageSource(local);
+    const resolved = selected.map((use) => {
+        const result = resolveLocalUse(use, source, registry);
+        return {
+            key: use.project_id === undefined
+                ? use.package_id
+                : `${use.package_id}@${use.project_id}`,
+            package_id: use.package_id,
+            coordinate: result.document?.package.coordinate ?? null,
+            version: use.version,
+            mode: use.mode,
+            content_hash: use.content_hash,
+            resolved_hash: result.resolved_hash,
+            authoring: result.authoring,
+            findings: result.findings.map((finding) => ({
+                code: finding.code,
+                message: describeUseFinding(finding, use, coordinateOf(local, use))
+            })),
+            content: result.content
+        };
+    });
+    const text = JSON.stringify({ uses: resolved }, null, 2);
+    const unresolved = resolved.filter((entry) => entry.findings.length > 0);
+    if (options.out) {
+        writeFileSync(options.out, `${text}\n`);
+        return `wrote ${resolved.length} use(s) to ${options.out}${unresolved.length ? `; ${unresolved.length} unresolved` : ''}`;
+    }
+    return text;
+}
+//# sourceMappingURL=packages-uses.js.map