@vincentt-xr/cli 0.15.1 → 0.16.0

package/dist/platform/templateUpgrade.js

@@ -0,0 +1,476 @@
+/**
+ * The template half of an upgrade: fetch two tags, classify, replace the
+ * plumbing, and report.
+ *
+ * THE ORDERING IS THE MOST LIKELY SILENT DEFECT IN THIS FEATURE, so it is stated
+ * here rather than left to a caller:
+ *
+ *  1. The template half runs ONLY AFTER the dependency half has reported
+ *     completion for every platform package. Replacing plumbing that expects a
+ *     new SDK, over a project still on the old one, produces a project that
+ *     compiles against NEITHER — worse than either half alone, and the plumbing
+ *     is precisely the code that breaks when the SDK contract moves. (The
+ *     fail-forward rule governs WITHIN the dependency half, package to package.
+ *     The template half is not a fourth package and does not inherit it.)
+ *  2. THE BASELINE IS WRITTEN LAST — after the file operations AND after the
+ *     report is rendered. If the template half succeeded and a dependency bump
+ *     then failed, a baseline written early means the NEXT upgrade compares
+ *     against the new baseline and reports every file the creator had customized
+ *     as "unchanged by you". The destructive half loses its only trace, it is
+ *     invisible in a diff, and the symptom appears one upgrade later.
+ *  3. Because 1 and 2 are unverifiable at run time — the procedure may not read
+ *     exit codes — the precondition is ORDERING PLUS AN HONEST REPORT LINE, never
+ *     a detected gate. The procedure reads its own report.
+ *
+ * THE FROM REF IS UNTRUSTED INPUT. `.vincentt/project.json` travels with a
+ * repository and anyone who can land a commit can set it. Four controls, all
+ * here: semver-shaped validation before it reaches git; the remote is a module
+ * constant; a fully-qualified tag ref rather than a bare branch argument; and a
+ * ref that resolves but whose tree lacks the manifest is NO BASELINE.
+ *
+ * NO BACKUP COPY, NO PRE-FLIGHT CHECK, NO PLATFORM-SIDE REVERT. All three were
+ * ruled out deliberately: the creator's version control is the recovery
+ * mechanism and it is better than ours, and a `.bak` is the platform inventing a
+ * recovery mechanism in a repository it does not own. Do not add a safety
+ * measure the design refused.
+ */
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { PLATFORM_PACKAGES } from "./allowlist.js";
+import { isDeniedByName, validateZonePath } from "./zonePath.js";
+import { parseZoneManifest } from "./zones.js";
+import { renderBlockedReport, renderDegradedReport, renderDependencyIncompleteReport, renderUpgradeReport, } from "./upgradeReport.js";
+import { loadProjectBinding, writeProjectBinding } from "../shared/config.js";
+const execFileAsync = promisify(execFile);
+/** THE REMOTE IS A MODULE CONSTANT. Never read from the binding — see the header. */
+const TEMPLATE_REMOTE = "https://github.com/vincentt-xr/v2-template.git";
+/** The manifest file, read-only: it arrives with the TO tree and is never in its own overwrite set. */
+export const MANIFEST_FILE = ".vincentt-template.json";
+/** Anchored at both ends. A branch named `1.4.3` does not satisfy `refs/tags/1.4.3`. */
+const CONCRETE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+/** The first template version carrying a manifest, for the blocked report's copy. */
+export const FIRST_MANIFEST_VERSION = "1.5.0";
+const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+const realGit = async (args) => {
+    const { stdout } = await execFileAsync("git", args);
+    return stdout;
+};
+/**
+ * Validate a recorded FROM ref BEFORE it reaches git.
+ *
+ * Anything not exactly `MAJOR.MINOR.PATCH` is NO BASELINE — not an error, and
+ * not a bare attempt. `../../etc`, `refs/heads/1.4.3`, `1.4.3; rm -rf` and
+ * `latest` all resolve to "no baseline" without git being invoked at all.
+ */
+export function validateFromRef(raw) {
+    if (raw === undefined)
+        return undefined;
+    return CONCRETE_VERSION.test(raw) ? raw : undefined;
+}
+/**
+ * Run the template half.
+ *
+ * Every early return renders a report and writes nothing. There is no path
+ * through this function that overwrites a file without the report naming it.
+ */
+export async function upgradeTemplate(deps) {
+    // ORDERING, PART 1. Before any tag is fetched and before any file is read.
+    if (deps.dependencyOutcome.outstanding.length > 0) {
+        return {
+            report: renderDependencyIncompleteReport({
+                completed: deps.dependencyOutcome.completed,
+                outstanding: deps.dependencyOutcome.outstanding,
+            }),
+            templateAttempted: false,
+        };
+    }
+    const binding = await loadProjectBinding(deps.projectDir).catch(() => undefined);
+    const from = validateFromRef(binding?.template?.version);
+    const fetchTag = deps.fetchTag ?? ((ref) => cloneTag(ref, deps.runGit ?? realGit));
+    const toDir = await fetchTag(deps.to);
+    if (toDir === undefined) {
+        return {
+            report: renderBlockedReport({
+                dependencies: deps.dependencyOutcome.completed,
+                from,
+                firstManifestVersion: FIRST_MANIFEST_VERSION,
+            }),
+            templateAttempted: false,
+        };
+    }
+    // THE FLOOR RUNS BEFORE ANY FILE IS READ. One failure refuses the whole
+    // manifest and the template half reports not attempted.
+    const toZones = await readManifest(toDir);
+    if (!toZones.ok) {
+        return {
+            report: blockedFor(toZones.refusal, deps.dependencyOutcome.completed, from, deps.to),
+            templateAttempted: false,
+        };
+    }
+    // A ref that resolves but whose tree lacks the manifest is NO BASELINE — this
+    // closes the fallback-to-empty-manifest hole, where an attacker-chosen FROM
+    // with no manifest would otherwise degrade to "compare against nothing".
+    //
+    // The three values are one object rather than three variables, so "we have a
+    // baseline" is a single check the type system enforces. Held separately, a
+    // later edit can test one and read another, which is precisely how a
+    // no-baseline run would slip into the destructive path.
+    const baseline = await resolveBaseline(from, fetchTag);
+    const trackedStateOf = deps.trackedStateOf ?? gitTrackedState;
+    // Every manifest entry is permitted BY CONSTRUCTION: the whole manifest was
+    // floor-validated above, and one failure refuses all of it. So splitting the
+    // manifest by the floor cannot populate the not-permitted set, and an earlier
+    // version of this loop left that report section permanently empty — which is
+    // the opposite of what it exists for.
+    //
+    // The not-permitted set is the template's own plumbing that the manifest CANNOT
+    // name because the floor would refuse it: `scripts/*.mjs` execute on the
+    // creator's machine, and the template's lint config is a dot-leading root file.
+    // Both are therefore never upgraded, and the report NAMES them rather than
+    // letting them go silently stale.
+    const permitted = [...toZones.zones.platform];
+    const notPermitted = await unpermittedTemplatePaths(toDir, toZones.zones);
+    if (baseline === undefined) {
+        // THE DEGRADED PATH: reports, does not overwrite. Files already matching TO
+        // are verified or restored; anything differing is NAMED AND LEFT ALONE.
+        // Overwriting while unable to say what was overwritten is the destructive
+        // act with its only compensating control removed — and this path is
+        // reachable by deleting one gitignored file, which is invisible in a diff.
+        const matching = [];
+        const differing = [];
+        const restored = [];
+        for (const rel of permitted) {
+            const want = await readTemplateFile(toDir, rel);
+            if (want === undefined)
+                continue;
+            const have = await readProjectFile(deps.projectDir, rel);
+            if (have === undefined) {
+                await writeProjectFile(deps.projectDir, rel, want);
+                restored.push(rel);
+            }
+            else if (have.equals(want)) {
+                matching.push(rel);
+            }
+            else {
+                differing.push(rel);
+            }
+        }
+        const verified = [...matching, ...restored];
+        const report = renderDegradedReport({
+            dependencies: deps.dependencyOutcome.completed,
+            to: deps.to,
+            matching: verified.filter((p) => !TEST_FILE.test(p)),
+            matchingTestCount: verified.filter((p) => TEST_FILE.test(p)).length,
+            differing,
+            deletions: [],
+            baselineRecorded: true,
+        });
+        // BASELINE LAST — after the file operations and after the report renders.
+        await recordBaseline(deps.projectDir, deps.to);
+        return { report, templateAttempted: true, baselineWritten: deps.to };
+    }
+    // THE DESTRUCTIVE PATH. Classify against FROM's original, then replace.
+    const changed = [];
+    const unchanged = [];
+    let unchangedTestCount = 0;
+    for (const rel of permitted) {
+        const want = await readTemplateFile(toDir, rel);
+        if (want === undefined)
+            continue;
+        const original = await readTemplateFile(baseline.dir, rel);
+        const have = await readProjectFile(deps.projectDir, rel);
+        // Tracked-ness is read BEFORE the write, because after it the file is
+        // modified and `diff-index` would answer about the new contents.
+        const isChanged = have !== undefined && original !== undefined && !have.equals(original);
+        const tracked = isChanged ? await trackedStateOf(deps.projectDir, rel) : "tracked";
+        await writeProjectFile(deps.projectDir, rel, want);
+        if (isChanged) {
+            changed.push({ path: rel, tracked });
+        }
+        else if (TEST_FILE.test(rel)) {
+            unchangedTestCount++;
+        }
+        else {
+            unchanged.push(rel);
+        }
+    }
+    // Deletions are REPORTED, NEVER REMOVED. Removal is a step past overwriting,
+    // and the ruling that permits overwriting does not reach it.
+    const toSet = new Set(toZones.zones.platform);
+    const deletions = baseline.zones.platform.filter((p) => !toSet.has(p));
+    const report = renderUpgradeReport({
+        dependencies: deps.dependencyOutcome.completed,
+        comparedAgainst: baseline.ref,
+        to: deps.to,
+        changed,
+        unchanged,
+        unchangedTestCount,
+        deletions,
+        notPermitted,
+    });
+    // BASELINE LAST. See the header — this ordering is the whole defence against
+    // the next upgrade laundering the creator's work.
+    await recordBaseline(deps.projectDir, deps.to);
+    return { report, templateAttempted: true, baselineWritten: deps.to };
+}
+/**
+ * Resolve the baseline, or `undefined` for NO BASELINE.
+ *
+ * Every failure reduces rather than widens: an unvalidatable ref, an
+ * unreachable tag, a tree with no manifest and a manifest the floor refuses all
+ * return `undefined`, which routes to the reporting path where nothing is
+ * replaced. No fingerprinting and no guessed FROM — inference on a destructive
+ * path means confidently reporting "you had not changed this" about a file just
+ * destroyed.
+ */
+async function resolveBaseline(from, fetchTag) {
+    if (from === undefined)
+        return undefined;
+    const dir = await fetchTag(from);
+    if (dir === undefined)
+        return undefined;
+    const parsed = await readManifest(dir);
+    if (!parsed.ok)
+        return undefined;
+    return { ref: from, dir, zones: parsed.zones };
+}
+/**
+ * Every refusal produces the same OUTCOME — nothing read, nothing written — but
+ * not the same EXPLANATION.
+ *
+ * `unparseable` here means the manifest file was absent or unreadable, which is
+ * the day-one case: the tag predates the manifest. Every other refusal means a
+ * manifest was present and the floor rejected it, which is a fault in the
+ * template version rather than in the project's age. The report must not tell
+ * someone their old template lacks a file when the real cause is a refused one.
+ */
+function blockedFor(refusal, dependencies, from, to) {
+    return renderBlockedReport({
+        dependencies,
+        from,
+        to,
+        firstManifestVersion: FIRST_MANIFEST_VERSION,
+        reason: refusal.kind === "unparseable" ? "missing" : "refused",
+    });
+}
+/**
+ * `git clone --depth 1` at a fully-qualified TAG ref, read-only, no credential,
+ * remote from the module constant. Tags are immutable, so FROM is reproducible
+ * forever.
+ */
+async function cloneTag(ref, runGit) {
+    if (validateFromRef(ref) === undefined)
+        return undefined;
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "vincentt-tmpl-up-"));
+    try {
+        await runGit([
+            "clone",
+            "--depth",
+            "1",
+            // `refs/tags/<v>`, never a bare branch argument: a branch named `1.4.3`
+            // does not satisfy this and resolves to nothing rather than to a tree
+            // someone else controls.
+            "--branch",
+            `refs/tags/${ref}`,
+            TEMPLATE_REMOTE,
+            tmp,
+        ]);
+        return tmp;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The template's own plumbing that the manifest CANNOT name, because the floor
+ * would refuse the path.
+ *
+ * This is NOT "entries the floor rejected" — every manifest entry is permitted by
+ * construction, since one refusal rejects the whole manifest. It is the opposite
+ * direction: files the template genuinely ships, in neither zone array, whose
+ * paths the floor does not admit. `scripts/*.mjs` execute on the creator's
+ * machine and a dot-leading root file is refused by the segment rule, so neither
+ * can ever be in an overwrite set.
+ *
+ * They are NAMED IN THE REPORT rather than left silently stale, which is the
+ * whole point of the not-permitted section. Derived from the tree so a template
+ * that adds another such file is reported without a code change here.
+ */
+async function unpermittedTemplatePaths(toDir, zones) {
+    const listed = new Set([...zones.platform, ...zones.creator]);
+    const out = [];
+    const walk = async (rel) => {
+        const entries = await fs.readdir(path.join(toDir, rel || "."), {
+            withFileTypes: true,
+        });
+        for (const e of entries) {
+            const child = rel ? `${rel}/${e.name}` : e.name;
+            // `.git` is the clone's own plumbing, not the template's content.
+            if (e.name === ".git")
+                continue;
+            if (e.isDirectory()) {
+                if (e.name === "node_modules")
+                    continue;
+                await walk(child);
+                continue;
+            }
+            if (listed.has(child))
+                continue;
+            if (child === MANIFEST_FILE)
+                continue;
+            // Denied-by-name files are refused, but they are the CREATOR's or the
+            // grounding contract — never "plumbing we could not upgrade".
+            if (isDeniedByName(child))
+                continue;
+            if (!validateZonePath(child).ok)
+                out.push(child);
+        }
+    };
+    try {
+        await walk("");
+    }
+    catch {
+        // The tree is a temp clone we just read a manifest out of; if it became
+        // unreadable the report simply omits this section rather than failing an
+        // upgrade that already succeeded.
+        return [];
+    }
+    return out.sort();
+}
+async function readManifest(dir) {
+    try {
+        return parseZoneManifest(await fs.readFile(path.join(dir, MANIFEST_FILE), "utf8"));
+    }
+    catch {
+        return { ok: false, refusal: { kind: "unparseable" } };
+    }
+}
+/**
+ * Read one file from a fetched template tree.
+ *
+ * The path has already passed the floor, and it is re-checked here anyway: this
+ * is the last point before a read, and a caller assembling a path from a
+ * different source must not be able to reach the filesystem through this
+ * function.
+ */
+async function readTemplateFile(dir, rel) {
+    if (!validateZonePath(rel).ok)
+        return undefined;
+    try {
+        return await fs.readFile(path.join(dir, rel));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readProjectFile(projectDir, rel) {
+    if (!validateZonePath(rel).ok)
+        return undefined;
+    const target = await safeTarget(projectDir, rel);
+    if (target === undefined)
+        return undefined;
+    try {
+        return await fs.readFile(target);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeProjectFile(projectDir, rel, contents) {
+    if (!validateZonePath(rel).ok)
+        return;
+    if (isDeniedByName(rel))
+        return;
+    const target = await safeTarget(projectDir, rel);
+    if (target === undefined)
+        return;
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, contents);
+}
+/**
+ * Resolve a write destination inside the project root, refusing a symlink.
+ *
+ * Belt-and-braces against a symlink planted in the creator's tree, which the
+ * source-side floor structurally cannot see: the manifest names an innocuous
+ * relative path and the creator's own tree redirects it. `realpath` on the
+ * PARENT (the file itself may legitimately not exist yet, on the restore path),
+ * plus an lstat refusing a symlink at the leaf.
+ */
+async function safeTarget(projectDir, rel) {
+    const root = await fs.realpath(projectDir).catch(() => undefined);
+    if (root === undefined)
+        return undefined;
+    const target = path.resolve(root, rel);
+    const parent = path.dirname(target);
+    const realParent = await fs.realpath(parent).catch(() => parent);
+    if (realParent !== root && !realParent.startsWith(root + path.sep))
+        return undefined;
+    const stat = await fs.lstat(target).catch(() => undefined);
+    if (stat?.isSymbolicLink())
+        return undefined;
+    return path.join(realParent, path.basename(target));
+}
+/**
+ * How version control saw this file. A statement, NEVER a gate — nothing is
+ * refused, delayed, or required on the strength of it, so this does not
+ * reintroduce the refused pre-flight check as a courtesy.
+ */
+async function gitTrackedState(projectDir, rel) {
+    try {
+        await execFileAsync("git", ["-C", projectDir, "rev-parse", "--git-dir"]);
+    }
+    catch {
+        return "no_repository";
+    }
+    try {
+        await execFileAsync("git", ["-C", projectDir, "ls-files", "--error-unmatch", rel]);
+        return "tracked";
+    }
+    catch {
+        // Untracked: ignored is the narrower cause and a creator can act on the
+        // difference, so it is distinguished rather than folded in.
+        try {
+            const { stdout } = await execFileAsync("git", [
+                "-C",
+                projectDir,
+                "check-ignore",
+                rel,
+            ]);
+            return stdout.trim() === "" ? "untracked" : "ignored";
+        }
+        catch {
+            return "untracked";
+        }
+    }
+}
+/**
+ * THE ONE PLACE the platform writes `.vincentt/project.json` after create.
+ *
+ * Surfaced rather than absorbed: it is the CLI's own binding record and not the
+ * creator's source, it happens only on an explicitly-invoked act, it records a
+ * fact the creator's act just made true, and without it the no-baseline case
+ * never heals.
+ */
+async function recordBaseline(projectDir, version) {
+    const binding = await loadProjectBinding(projectDir).catch(() => undefined);
+    if (binding === undefined)
+        return;
+    await writeProjectBinding(projectDir, { ...binding, template: { version } }).catch(() => { });
+}
+/** Which platform packages this project has installed, for the ordering precondition. */
+export async function installedPlatformPackages(projectDir) {
+    const found = [];
+    for (const pkg of PLATFORM_PACKAGES) {
+        try {
+            await fs.access(path.join(projectDir, "node_modules", ...pkg.name.split("/"), "package.json"));
+            found.push(pkg.name);
+        }
+        catch {
+            // Not installed contributes nothing.
+        }
+    }
+    return found;
+}

package/dist/platform/upgradeReport.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The template upgrade report — the ONLY trace of an operation that replaced
+ * files in a repository the platform does not own, with no pre-flight check, no
+ * backup, and no platform-side revert.
+ *
+ * READ THIS MODULE AS A SECURITY CONTROL, because that is what it is. Every
+ * ordering decision serves one goal: a reader who takes only the first block
+ * takes the bad news.
+ *
+ * Four rules govern every string here, and each exists because a draft broke it:
+ *
+ *  1. The destructive section is FIRST, above every reassurance and every
+ *     success framing, and it is NEVER COMPRESSED at any length. Other sections
+ *     may collapse to middot lists and counts to keep this one above the fold.
+ *  2. The unrecoverable caveat PRECEDES the reassurance, with its files named. A
+ *     reader who takes one sentence of a pair takes the first.
+ *  3. `unchanged` is NEVER a bare claim. It always carries the ref it was
+ *     compared against, in the heading, because the heading is what a skimming
+ *     reader reads — and the procedure cannot verify that ref, so it must not
+ *     print a sentence implying it did.
+ *  4. NO state-restoring transformation is named anywhere. "Names no command"
+ *     was proven insufficient: a sentence naming no command can fully specify a
+ *     hard reset, which is instruction with the imperative removed. On this tree
+ *     a hard reset or force-clean destroys the project binding, the env file,
+ *     and every asset the creator dropped in — all gitignored, and a dirty tree
+ *     is the modal case here.
+ *
+ * There is no success glyph in this file. A `✓` above a list of destroyed work
+ * is the report arguing with itself. And no command appears anywhere — not a
+ * build command, not a test command, not a version-control command.
+ */
+/** How version control saw a replaced file. The two causes differ and a creator can act on the difference. */
+export type TrackedState = "tracked" | "untracked" | "ignored" | "no_repository";
+export interface ReplacedFile {
+    path: string;
+    tracked: TrackedState;
+}
+export interface DependencyChange {
+    name: string;
+    from: string;
+    to: string;
+}
+export interface UpgradeReport {
+    /** Present when the dependency half reported completion. Stated FIRST when the template half did not run. */
+    dependencies: DependencyChange[];
+    /** The FROM ref the classification rests on. Printed as a premise, never as a verified fact. */
+    comparedAgainst?: string;
+    to: string;
+    /** Replaced AND differing from FROM — the destructive list. */
+    changed: ReplacedFile[];
+    /** Replaced and byte-identical to FROM. */
+    unchanged: string[];
+    /** How many of `unchanged` are shipped test files, folded into a count. */
+    unchangedTestCount: number;
+    /** In FROM's platform set, absent from TO's. Reported, never removed. */
+    deletions: string[];
+    /** Named by the manifest but refused by the floor's allowlist. */
+    notPermitted: string[];
+}
+/**
+ * The full report for a completed upgrade.
+ *
+ * The header states the transition and nothing else — no duration, no file
+ * count, no "upgraded successfully".
+ */
+export declare function renderUpgradeReport(r: UpgradeReport): string[];
+/**
+ * The template half BLOCKED — a tag at either end carries no manifest, or its
+ * schema is unrecognized. THE MODAL OUTCOME for the first weeks, because every
+ * existing template tag predates the manifest.
+ *
+ * The dependency half's success is stated FIRST, because it did work. The reason
+ * is two sentences of plain language, it states what was NOT READ as well as not
+ * written, and it says what changes the situation without promising a date or
+ * naming a command. The word `zone` appears nowhere: it is internal vocabulary
+ * and a creator has never heard it.
+ */
+export declare function renderBlockedReport(r: {
+    dependencies: DependencyChange[];
+    from?: string;
+    firstManifestVersion: string;
+    /**
+     * `missing` — the tag predates the manifest (the day-one case).
+     * `refused` — a manifest IS present and did not pass the floor.
+     *
+     * The two must not share copy. Telling a creator their old template "does not
+     * carry the file" when a manifest was actually present and REFUSED is a
+     * misleading explanation on the one path where the explanation is the whole
+     * compensating control — and it would send someone upgrading the template to
+     * fix the wrong thing.
+     */
+    reason?: "missing" | "refused";
+    /** The version being upgraded TO, named in the refused-manifest copy. */
+    to?: string;
+}): string[];
+/**
+ * The DEGRADED report — no recorded baseline, so nothing was replaced.
+ *
+ * Two lists, and the distinction between them is the entire deliverable: "already
+ * matching, byte for byte" is a VERIFIED fact; "differs — left alone" is a fact
+ * with an UNKNOWN CAUSE. One combined list of "template files" would collapse
+ * them and make the report worthless.
+ *
+ * No `!` and no `✗`: nothing failed. This is the designed behavior of a project
+ * in a known state, and dressing it as a warning teaches creators to fear a safe
+ * outcome. The word "revert" does not appear and neither does any restoring
+ * phrase — nothing was destroyed here, so there is nothing to say about
+ * recovery, and saying it anyway would put the phrase into a transcript an agent
+ * may carry into the destructive path's context.
+ */
+export declare function renderDegradedReport(r: {
+    dependencies: DependencyChange[];
+    to: string;
+    matching: string[];
+    matchingTestCount: number;
+    differing: string[];
+    deletions: string[];
+    baselineRecorded: boolean;
+}): string[];
+/**
+ * The report for the case the ORDERING creates: the dependency half did not
+ * report completion, so the template half was not attempted.
+ *
+ * The precondition cannot be verified at run time — the procedure may not read
+ * exit codes — so it is expressed as ordering plus an honest line, never as a
+ * detected gate. The capability is DEFERRED, not withdrawn, and saying so is
+ * what stops a creator reading it as broken.
+ */
+export declare function renderDependencyIncompleteReport(r: {
+    completed: DependencyChange[];
+    outstanding: string[];
+}): string[];