@krapwoo/ds-viewer 0.8.0 → 0.9.0

package/dist/cli/dependencyBumpProof.js

@@ -0,0 +1,216 @@
+// cli/dependencyBumpProof.ts
+/** Conservative proof that a dirty `package.json` or npm `package-lock.json` is *solely* a
+ *  viewer-only dependency bump to the version already installed — i.e. a previously-started
+ *  update that the running process itself already finished. Every check here fails closed:
+ *  malformed JSON, an unsupported lockfile shape, a missing side, or any other difference at all
+ *  leaves the file classified unsafe (still dirty). Pure functions only — `updatePlan.ts` owns
+ *  reading `HEAD` and the working tree. Every comparison here is against *parsed* JSON, not raw
+ *  text: formatting-only and key-ordering differences are never treated as a difference, and
+ *  duplicate keys in either side collapse to their last occurrence, exactly as `JSON.parse` does. */
+import { compareVersions, parseVersion } from "./semver.js";
+const PACKAGE_NAME = '@krapwoo/ds-viewer';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const aKeys = Object.keys(a);
+        return aKeys.length === Object.keys(b).length && aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key]));
+    }
+    return false;
+}
+/** Every leaf (or missing-key) difference between two parsed JSON values, each named by its full
+ *  key path. An empty result means the two values are deeply equal. */
+function diffJson(head, working, path = []) {
+    if (deepEqual(head, working))
+        return [];
+    if (isPlainObject(head) && isPlainObject(working)) {
+        const diffs = [];
+        for (const key of new Set([...Object.keys(head), ...Object.keys(working)])) {
+            const inHead = Object.prototype.hasOwnProperty.call(head, key);
+            const inWorking = Object.prototype.hasOwnProperty.call(working, key);
+            if (inHead && !inWorking)
+                diffs.push({ path: [...path, key], type: 'removed' });
+            else if (!inHead && inWorking)
+                diffs.push({ path: [...path, key], type: 'added', workingValue: working[key] });
+            else
+                diffs.push(...diffJson(head[key], working[key], [...path, key]));
+        }
+        return diffs;
+    }
+    return [{ path, type: 'changed', workingValue: working }];
+}
+/** The three registry forms `update` (and a prior run of it) ever writes for an exact target
+ *  version — never a local/path/workspace spec, which `isLocalSpec` elsewhere already refuses to
+ *  update over in the first place. */
+function isAcceptedRegistryForm(spec, currentVersion) {
+    return spec === currentVersion || spec === `^${currentVersion}` || spec === `~${currentVersion}`;
+}
+/** Whether a HEAD spec names a version strictly older than `currentVersion` — the proof that the
+ *  working spec is a genuine forward bump, not a same-version range edit (e.g. HEAD `"^0.4.0"` →
+ *  working `"0.4.0"` at `currentVersion` `"0.4.0"`, which names the same version both sides).
+ *  Fails closed on anything other than a parseable exact/caret/tilde registry form. */
+function isOlderRegistryForm(spec, currentVersion) {
+    if (typeof spec !== 'string')
+        return false;
+    const exact = spec.replace(/^[\^~]/, '');
+    try {
+        return compareVersions(parseVersion(exact), parseVersion(currentVersion)) === -1;
+    }
+    catch {
+        return false;
+    }
+}
+function headValueAtPath(head, path) {
+    let cursor = head;
+    for (const key of path) {
+        if (!isPlainObject(cursor))
+            return undefined;
+        cursor = cursor[key];
+    }
+    return cursor;
+}
+/** Safe only when `workingRaw` differs from `headRaw` solely at one existing `dependencies` or
+ *  `devDependencies` entry for `@krapwoo/ds-viewer`, and that entry's working value names
+ *  `currentVersion` in an accepted registry form. */
+export function isSafePackageJsonBump(headRaw, workingRaw, currentVersion) {
+    let head;
+    let working;
+    try {
+        head = JSON.parse(headRaw);
+        working = JSON.parse(workingRaw);
+    }
+    catch {
+        return false;
+    }
+    if (!isPlainObject(head) || !isPlainObject(working))
+        return false;
+    const diffs = diffJson(head, working);
+    if (diffs.length !== 1)
+        return false;
+    const [diff] = diffs;
+    if (diff.type !== 'changed' || diff.path.length !== 2)
+        return false;
+    const [section, name] = diff.path;
+    if (name !== PACKAGE_NAME)
+        return false;
+    if (section !== 'dependencies' && section !== 'devDependencies')
+        return false;
+    if (!isOlderRegistryForm(headValueAtPath(head, diff.path), currentVersion))
+        return false;
+    return isAcceptedRegistryForm(diff.workingValue, currentVersion);
+}
+function redactKey(value, keyPath) {
+    const clone = JSON.parse(JSON.stringify(value));
+    let cursor = clone;
+    for (let i = 0; i < keyPath.length - 1; i += 1) {
+        const next = cursor[keyPath[i]];
+        if (!isPlainObject(next))
+            return clone;
+        cursor = next;
+    }
+    delete cursor[keyPath[keyPath.length - 1]];
+    return clone;
+}
+/** Which section (`dependencies`/`devDependencies`) the lockfile root (`packages[""]`, design's
+ *  own npm v7+ shape) declares `@krapwoo/ds-viewer` in, and that its working value is an accepted
+ *  registry form of `currentVersion` — `undefined` for any ambiguity (declared in neither or both
+ *  sides, mismatched sections, or anything other than a plain string on either side). */
+function safeRootDeclarationSection(headRoot, workingRoot, currentVersion) {
+    for (const section of ['dependencies', 'devDependencies']) {
+        const other = section === 'dependencies' ? 'devDependencies' : 'dependencies';
+        const headValue = isPlainObject(headRoot[section]) ? headRoot[section][PACKAGE_NAME] : undefined;
+        const workingValue = isPlainObject(workingRoot[section]) ? workingRoot[section][PACKAGE_NAME] : undefined;
+        if (headValue === undefined && workingValue === undefined)
+            continue;
+        if (typeof headValue !== 'string' || typeof workingValue !== 'string')
+            return undefined;
+        const headOther = isPlainObject(headRoot[other]) ? headRoot[other][PACKAGE_NAME] : undefined;
+        const workingOther = isPlainObject(workingRoot[other]) ? workingRoot[other][PACKAGE_NAME] : undefined;
+        if (headOther !== undefined || workingOther !== undefined)
+            return undefined; // declared in both sections somewhere — ambiguous.
+        return isAcceptedRegistryForm(workingValue, currentVersion) && isOlderRegistryForm(headValue, currentVersion) ? section : undefined;
+    }
+    return undefined;
+}
+function isSafeLockfileV1Bump(head, working, currentVersion) {
+    const headDeps = head.dependencies;
+    const workingDeps = working.dependencies;
+    if (!isPlainObject(headDeps) || !isPlainObject(workingDeps))
+        return false;
+    const headEntry = headDeps[PACKAGE_NAME];
+    const workingEntry = workingDeps[PACKAGE_NAME];
+    if (!isPlainObject(headEntry) || !isPlainObject(workingEntry))
+        return false;
+    if (workingEntry.version !== currentVersion)
+        return false;
+    const redactedHead = redactKey(head, ['dependencies', PACKAGE_NAME]);
+    const redactedWorking = redactKey(working, ['dependencies', PACKAGE_NAME]);
+    return deepEqual(redactedHead, redactedWorking);
+}
+function isSafeLockfileV2Or3Bump(head, working, currentVersion) {
+    const nodeModulesKey = `node_modules/${PACKAGE_NAME}`;
+    const headPackages = head.packages;
+    const workingPackages = working.packages;
+    if (!isPlainObject(headPackages) || !isPlainObject(workingPackages))
+        return false;
+    const headEntry = headPackages[nodeModulesKey];
+    const workingEntry = workingPackages[nodeModulesKey];
+    if (!isPlainObject(headEntry) || !isPlainObject(workingEntry))
+        return false;
+    if (workingEntry.version !== currentVersion)
+        return false;
+    const headRoot = headPackages[''];
+    const workingRoot = workingPackages[''];
+    if (!isPlainObject(headRoot) || !isPlainObject(workingRoot))
+        return false;
+    const section = safeRootDeclarationSection(headRoot, workingRoot, currentVersion);
+    if (!section)
+        return false;
+    // npm v7/v8's legacy mirror tree, kept alongside `packages` for backward-compat tooling — absent
+    // in v9+'s v3 lockfiles. Unlike the two checks above, redacting this unconditionally (without
+    // first proving its own working value) would let an untracked edit to this entry hide behind an
+    // otherwise-safe bump.
+    const workingLegacy = isPlainObject(working.dependencies) ? working.dependencies[PACKAGE_NAME] : undefined;
+    if (workingLegacy !== undefined && (!isPlainObject(workingLegacy) || workingLegacy.version !== currentVersion))
+        return false;
+    let redactedHead = redactKey(head, ['packages', nodeModulesKey]);
+    let redactedWorking = redactKey(working, ['packages', nodeModulesKey]);
+    redactedHead = redactKey(redactedHead, ['packages', '', section, PACKAGE_NAME]);
+    redactedWorking = redactKey(redactedWorking, ['packages', '', section, PACKAGE_NAME]);
+    redactedHead = redactKey(redactedHead, ['dependencies', PACKAGE_NAME]);
+    redactedWorking = redactKey(redactedWorking, ['dependencies', PACKAGE_NAME]);
+    return deepEqual(redactedHead, redactedWorking);
+}
+/** Safe only when valid JSON differs from `HEAD` solely in the root declaration for
+ *  `@krapwoo/ds-viewer` and the package's own lock entry, both resolving `currentVersion`.
+ *  Supports lockfileVersion 1 (the single `dependencies` entry doubles as both) and 2/3 (the
+ *  `packages[""]` root declaration plus the `packages["node_modules/..."]` entry). Any other
+ *  `lockfileVersion`, or a mismatch between `HEAD` and the working tree, is an unsupported shape —
+ *  fails closed. */
+export function isSafeNpmLockfileBump(headRaw, workingRaw, currentVersion) {
+    let head;
+    let working;
+    try {
+        head = JSON.parse(headRaw);
+        working = JSON.parse(workingRaw);
+    }
+    catch {
+        return false;
+    }
+    if (!isPlainObject(head) || !isPlainObject(working))
+        return false;
+    const lockfileVersion = working.lockfileVersion;
+    if (head.lockfileVersion !== lockfileVersion)
+        return false;
+    if (lockfileVersion === 1)
+        return isSafeLockfileV1Bump(head, working, currentVersion);
+    if (lockfileVersion === 2 || lockfileVersion === 3)
+        return isSafeLockfileV2Or3Bump(head, working, currentVersion);
+    return false;
+}

package/dist/cli/update.js

@@ -51,7 +51,8 @@ export function localInstallRefusal(spec, latest) {
 /** Design §5 "`npx ds-viewer update`", steps 1-6. */
 export async function runUpdate(config, options = {}) {
     const currentVersion = options.currentVersion ?? readOwnVersion(path.dirname(fileURLToPath(import.meta.url)));
-    const plan = await (options.buildPlan ?? buildUpdatePlan)(config, currentVersion);
+    const buildPlan = options.buildPlan ?? buildUpdatePlan;
+    let plan = await buildPlan(config, currentVersion);
     if ('error' in plan)
         return { output: plan.error, exitCode: isAlreadyUpToDate(plan.error) ? 0 : 1 };
     const planText = formatPlanHuman(plan);
@@ -78,6 +79,24 @@ export async function runUpdate(config, options = {}) {
         const proceed = await (options.confirm ?? defaultConfirm)(`${planText}\n\nUpdate to ${plan.latest}? [y/N] `);
         if (!proceed)
             return { output: 'Aborted: nothing was changed.', exitCode: 0 };
+        // The prompt can sit open for a while — a file could have changed, or a newer version could
+        // have appeared, in the meantime. Revalidate immediately before the one side effect (install)
+        // this function ever runs, rather than trusting the plan the user approved. `--yes` has no
+        // prompt to sit open behind, so it deliberately skips this and uses the plan already built
+        // above (frozen scope: "may use the initial immediately preceding plan").
+        const revalidated = await buildPlan(config, currentVersion);
+        if ('error' in revalidated) {
+            if (isAlreadyUpToDate(revalidated.error))
+                return { output: revalidated.error, exitCode: 0 };
+            return { output: "Couldn't re-check the plan before installing. Nothing was changed.", exitCode: 1 };
+        }
+        if (revalidated.latest !== plan.latest || (!options.force && revalidated.dirtyFiles.length > 0)) {
+            return {
+                output: 'The plan changed while confirming — a file changed, or a newer version appeared. Nothing was changed. Run update again to see the new plan.',
+                exitCode: 1,
+            };
+        }
+        plan = revalidated;
     }
     const execImpl = options.execImpl ?? ((cmd, args, opts) => {
         const run = platformCommand(cmd, args);

package/dist/cli/updatePlan.js

@@ -1,10 +1,11 @@
 // cli/updatePlan.ts
 import { execFile, execFileSync } from 'node:child_process';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { detectPackageManager, platformCommand } from "./packageManager.js";
+import { isSafeNpmLockfileBump, isSafePackageJsonBump } from "./dependencyBumpProof.js";
 import { listKitFileDiffs } from "./kitDiff.js";
 import { extractSummaryBullets, fetchWithTimeout } from "./updateCheck.js";
 import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
@@ -20,20 +21,56 @@ function lockfileName(pm) {
         return 'yarn.lock';
     return 'package-lock.json';
 }
-/** `git status --porcelain`'s format is `XY path` (plain) or `XY old -> new` (a rename) — the
- *  path starts at column 3 either way; a rename's own "dirty" identity is its *new* path (the one
- *  this plan's own `files` list names), never the old one (Important finding, Fable correction
- *  pass: `R  old -> new` was previously read as the single literal path `"old -> new"`, which
- *  could never match a planned file). */
-function parseDirtyPaths(porcelain) {
-    return new Set(porcelain
+function parseDirtyEntries(porcelain) {
+    return porcelain
         .split('\n')
         .filter((line) => line.length > 3)
         .map((line) => {
+        const code = line.slice(0, 2);
         const raw = line.slice(3).trim();
         const arrow = raw.indexOf(' -> ');
-        return arrow === -1 ? raw : raw.slice(arrow + 4);
-    }));
+        return { path: arrow === -1 ? raw : raw.slice(arrow + 4), code };
+    });
+}
+/** Only a plain modification, staged or not (`" M"`, `"M "`, `"MM"`) — never an add, delete,
+ *  rename, or untracked file (`"A "`, `"D "`, `"R "`, `"??"`, …), which the content-only proof
+ *  below can't always distinguish from a genuine edit on its own. */
+function isPlainModification(code) {
+    return code !== '  ' && /^[ M]{2}$/.test(code);
+}
+// Exported for the integration test only (verifies the real git/filesystem behavior for a
+// subdirectory project); every other caller goes through `BuildPlanOptions`.
+export function defaultGitShow(projectRoot, filePath) {
+    try {
+        // `<rev>:<path>` is resolved relative to the *repository root* — only a `./`-prefixed path is
+        // resolved relative to `cwd` (`projectRoot`), which is what `filePath` (already stripped to be
+        // project-relative) needs for any project in a subdirectory.
+        return execFileSync('git', ['show', `HEAD:./${filePath}`], { cwd: projectRoot, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function defaultReadWorkingFile(projectRoot, filePath) {
+    try {
+        return readFileSync(path.join(projectRoot, filePath), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Frozen scope's one safe case: a dirty `package.json`/npm `package-lock.json` that provably
+ *  differs from `HEAD` solely by a prior, already-finished bump to `currentVersion` (the viewer
+ *  version this very process is running). Every other package manager's lockfile stays
+ *  conservative — unproven, and so left dirty. */
+function isSafeSupersededDependencyFile(filePath, pm, currentVersion, headRaw, workingRaw) {
+    if (headRaw === undefined || workingRaw === undefined)
+        return false;
+    if (filePath === 'package.json')
+        return isSafePackageJsonBump(headRaw, workingRaw, currentVersion);
+    if (pm === 'npm' && filePath === lockfileName(pm))
+        return isSafeNpmLockfileBump(headRaw, workingRaw, currentVersion);
+    return false;
 }
 /** Strips the repository-root prefix `git rev-parse --show-prefix` reports from every path in a
  *  `git status --porcelain` listing (both sides of a rename), so the result reads relative to
@@ -106,6 +143,8 @@ export async function buildUpdatePlan(config, currentVersion, options = {}) {
     const fetchImpl = options.fetchImpl ?? fetch;
     const tmpDirImpl = options.tmpDirImpl ?? (() => mkdtempSync(path.join(tmpdir(), 'ds-viewer-update-')));
     const gitStatusImpl = options.gitStatusImpl ?? defaultGitStatus;
+    const gitShowImpl = options.gitShowImpl ?? defaultGitShow;
+    const readWorkingFileImpl = options.readWorkingFileImpl ?? defaultReadWorkingFile;
     // Important finding, Fable correction pass: a real, unreachable registry otherwise hangs `npm
     // view`/`npm pack` for minutes (observed: "Checking…" sat for 140s, with `/update/status` not
     // answering at all in that time — this whole function runs inside the endpoint's own request
@@ -180,9 +219,26 @@ export async function buildUpdatePlan(config, currentVersion, options = {}) {
         return { error: `Couldn't check for uncommitted changes (git): ${error.message}` };
     }
     const outsideGitRepo = porcelain === undefined;
-    const dirtyPaths = porcelain === undefined ? new Set() : parseDirtyPaths(porcelain);
+    const dirtyEntries = porcelain === undefined ? [] : parseDirtyEntries(porcelain);
+    const dirtyPaths = new Set(dirtyEntries.map((entry) => entry.path));
     for (const file of files)
         file.dirty = dirtyPaths.has(file.path);
+    // Frozen scope: a dirty `package.json`/npm lockfile is resolved back to clean only when it
+    // provably differs from `HEAD` solely by a prior, already-finished bump to `currentVersion` —
+    // never for an add, delete, rename, or untracked file, which `isPlainModification` rules out
+    // before the content proof is even attempted.
+    const codeByPath = new Map(dirtyEntries.map((entry) => [entry.path, entry.code]));
+    for (const file of files) {
+        if (!file.dirty || (file.path !== 'package.json' && file.path !== lockfileName(pm)))
+            continue;
+        const code = codeByPath.get(file.path);
+        if (!code || !isPlainModification(code))
+            continue;
+        const headRaw = gitShowImpl(config.projectRoot, file.path);
+        const workingRaw = readWorkingFileImpl(config.projectRoot, file.path);
+        if (isSafeSupersededDependencyFile(file.path, pm, currentVersion, headRaw, workingRaw))
+            file.dirty = false;
+    }
     let summary = [];
     let releasedAt;
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",