@deftai/directive-core 0.97.0 → 0.98.0

package/dist/init-deposit/hygiene.js

@@ -8,7 +8,7 @@
  * and scope briefs are never installer-managed; if they reappear in
  * `installerManagedMatchers()`, unit tests and deposit-time assert fail closed.
  *
- * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117.
+ * Refs #1576, #1453, #1430, #3029, #3030, #3127, #3117, #3193.
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, rmSync } from "node:fs";
@@ -82,11 +82,12 @@ export function installerManagedMatchers() {
         { exact: CODEQL_CONFIG_REL },
         { exact: CORE_GUARD_WORKFLOW_REL },
         { exact: "Taskfile.yml" },
-        // Upgrade co-travel unit (#3127): npm pin + lock follow-through and the
-        // freshness live stamp (#3117) are part of a normal framework upgrade, not
-        // product feature work. Path-level allow for v1 (stricter “only
-        // @deftai/directive version changed” is a follow-on if needed).
-        // Mixing .deft/core/** with true app/product paths still fails (#1430).
+        // Upgrade co-travel unit (#3127 / #3193): path-allow package/lock + GENERATION
+        // so they are not auto-classified as "app". When mixed with .deft/core/**, the
+        // deposited guard + classifyMixedCoreAndAppContentAware additionally require
+        // package.json to be @deftai/directive* dependency-key pin-only and lockfiles
+        // to be pin follow-through (not unrelated direct product deps). GENERATION
+        // stays path-only (#3117). True app/product paths still fail (#1430).
         { exact: "package.json" },
         { exact: "package-lock.json" },
         { exact: "pnpm-lock.yaml" },
@@ -183,10 +184,541 @@ export function installerManagedGuardEre() {
 export function isInstallerManagedPath(path) {
     return matchesInstallerManaged(path, installerManagedMatchers());
 }
+/** Paths that path-allowlist for upgrade co-travel but need content checks with core (#3193). */
+export const UPGRADE_PIN_CONTENT_PATHS = [
+    "package.json",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+];
+/** package.json dependency map fields that may hold @deftai/directive* pins. */
+export const PACKAGE_JSON_DEP_FIELDS = [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+];
+/**
+ * True when `name` is an `@deftai/directive*` dependency **key** (#3193).
+ * Substring hits in scripts/settings values do not qualify.
+ */
+export function isDirectiveDependencyKey(name) {
+    return name.startsWith("@deftai/directive");
+}
+function deepEqualJson(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqualJson(v, b[i]));
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao).sort();
+    const bk = Object.keys(bo).sort();
+    if (ak.length !== bk.length)
+        return false;
+    for (let i = 0; i < ak.length; i++) {
+        if (ak[i] !== bk[i])
+            return false;
+    }
+    return ak.every((k) => deepEqualJson(ao[k], bo[k]));
+}
+function stripDirectivePinsFromPackageJson(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return value;
+    }
+    const obj = value;
+    const out = {};
+    for (const [key, raw] of Object.entries(obj)) {
+        if (PACKAGE_JSON_DEP_FIELDS.includes(key) &&
+            raw !== null &&
+            typeof raw === "object" &&
+            !Array.isArray(raw)) {
+            const kept = {};
+            for (const [depKey, depVal] of Object.entries(raw)) {
+                if (!isDirectiveDependencyKey(depKey))
+                    kept[depKey] = depVal;
+            }
+            out[key] = kept;
+        }
+        else {
+            out[key] = raw;
+        }
+    }
+    return out;
+}
+/**
+ * package.json co-travel is allowed only when the sole differences are
+ * `@deftai/directive*` dependency-key pins under the standard dep maps (#3193).
+ * Scripts/settings/metadata that merely contain the substring still fail.
+ */
+export function isPackageJsonDirectivePinOnlyDiff(baseRaw, headRaw) {
+    let base;
+    let head;
+    try {
+        base = JSON.parse(baseRaw);
+        head = JSON.parse(headRaw);
+    }
+    catch {
+        return false;
+    }
+    return deepEqualJson(stripDirectivePinsFromPackageJson(base), stripDirectivePinsFromPackageJson(head));
+}
+function collectDepIdentities(pkg) {
+    const out = {};
+    for (const field of PACKAGE_JSON_DEP_FIELDS) {
+        const block = pkg[field];
+        if (block !== null && typeof block === "object" && !Array.isArray(block)) {
+            for (const [k, v] of Object.entries(block)) {
+                if (typeof v === "string")
+                    out[k] = v;
+                else if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+                    const version = v.version;
+                    if (typeof version === "string")
+                        out[k] = version;
+                    else
+                        out[k] = JSON.stringify(v);
+                }
+                else if (v !== undefined && v !== null) {
+                    out[k] = String(v);
+                }
+            }
+        }
+    }
+    return out;
+}
+function onlyDirectiveDirectDepsDiffer(baseDeps, headDeps) {
+    const keys = new Set([...Object.keys(baseDeps), ...Object.keys(headDeps)]);
+    for (const key of keys) {
+        if (isDirectiveDependencyKey(key))
+            continue;
+        if ((baseDeps[key] ?? null) !== (headDeps[key] ?? null))
+            return false;
+    }
+    return true;
+}
+function npmLockRootDirectDeps(lock) {
+    const packages = lock.packages;
+    if (packages !== null && typeof packages === "object" && !Array.isArray(packages)) {
+        const root = packages[""];
+        if (root !== null && typeof root === "object" && !Array.isArray(root)) {
+            return collectDepIdentities(root);
+        }
+    }
+    if (lock.dependencies !== null &&
+        typeof lock.dependencies === "object" &&
+        !Array.isArray(lock.dependencies)) {
+        const out = {};
+        for (const [k, v] of Object.entries(lock.dependencies)) {
+            if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+                const version = v.version;
+                out[k] = typeof version === "string" ? version : JSON.stringify(v);
+            }
+            else if (typeof v === "string") {
+                out[k] = v;
+            }
+        }
+        return out;
+    }
+    return {};
+}
+/** Strip @deftai/directive* keys recursively from an npm v1 dependencies tree. */
+function stripDirectiveFromNpmV1Deps(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const obj = value;
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (isDirectiveDependencyKey(k))
+            continue;
+        if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            const entry = v;
+            const next = { ...entry };
+            if (entry.dependencies !== undefined) {
+                next.dependencies = stripDirectiveFromNpmV1Deps(entry.dependencies);
+            }
+            out[k] = next;
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    return out;
+}
+/**
+ * package-lock.json follow-through: non-@deftai/directive* root direct dependency
+ * identities (and their `node_modules/<name>` package entries when present) must
+ * be unchanged. Directive pin identity + transitive/resolution churn may change.
+ */
+export function isPackageLockDirectivePinFollowThrough(baseRaw, headRaw) {
+    let base;
+    let head;
+    try {
+        base = JSON.parse(baseRaw);
+        head = JSON.parse(headRaw);
+    }
+    catch {
+        return false;
+    }
+    if (base === null ||
+        head === null ||
+        typeof base !== "object" ||
+        typeof head !== "object" ||
+        Array.isArray(base) ||
+        Array.isArray(head)) {
+        return false;
+    }
+    const baseObj = base;
+    const headObj = head;
+    const baseRoot = npmLockRootDirectDeps(baseObj);
+    const headRoot = npmLockRootDirectDeps(headObj);
+    if (!onlyDirectiveDirectDepsDiffer(baseRoot, headRoot))
+        return false;
+    const basePkgs = baseObj.packages !== null &&
+        typeof baseObj.packages === "object" &&
+        !Array.isArray(baseObj.packages)
+        ? baseObj.packages
+        : {};
+    const headPkgs = headObj.packages !== null &&
+        typeof headObj.packages === "object" &&
+        !Array.isArray(headObj.packages)
+        ? headObj.packages
+        : {};
+    // Freeze every non-@deftai/directive package record (including hoisted
+    // transitives and nested product trees). Only packages[""] root dep maps
+    // (directive keys only) and node_modules/@deftai/directive* trees may change.
+    const allPkgKeys = new Set([...Object.keys(basePkgs), ...Object.keys(headPkgs)]);
+    for (const key of allPkgKeys) {
+        if (key === "")
+            continue;
+        if (key.includes("node_modules/@deftai/directive") || key.includes("/@deftai/directive/")) {
+            continue;
+        }
+        if (!deepEqualJson(basePkgs[key], headPkgs[key]))
+            return false;
+    }
+    // Legacy npm lockfileVersion 1: no packages map — freeze the full nested
+    // dependencies tree after stripping @deftai/directive* keys (#3193 Greptile).
+    if (Object.keys(basePkgs).length === 0 && Object.keys(headPkgs).length === 0) {
+        if (!deepEqualJson(stripDirectiveFromNpmV1Deps(baseObj.dependencies), stripDirectiveFromNpmV1Deps(headObj.dependencies))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Minimal pnpm-lock.yaml (v6/v9) root importer (`.`) direct-dep extractor.
+ * Avoids a YAML dependency; sufficient for pin follow-through identity checks.
+ */
+export function pnpmLockRootDirectDeps(raw) {
+    const lines = raw.split(/\r?\n/);
+    const out = {};
+    let inImporters = false;
+    let inRoot = false;
+    let inDepBlock = false;
+    let currentPkg = null;
+    const unquote = (s) => {
+        const t = s.trim();
+        if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) {
+            return t.slice(1, -1);
+        }
+        return t;
+    };
+    for (const line of lines) {
+        if (/^importers:\s*$/.test(line)) {
+            inImporters = true;
+            inRoot = false;
+            inDepBlock = false;
+            currentPkg = null;
+            continue;
+        }
+        if (!inImporters)
+            continue;
+        // Left the importers section (top-level key at column 0).
+        if (/^[^\s#]/.test(line) && !line.startsWith("importers")) {
+            break;
+        }
+        // Root importer `.` (quoted or bare).
+        if (/^ {2}(?:\.|'\.'|"\."):\s*$/.test(line)) {
+            inRoot = true;
+            inDepBlock = false;
+            currentPkg = null;
+            continue;
+        }
+        // Sibling importer under importers (2-space indent, not a dep field).
+        if (inRoot && /^ {2}\S/.test(line) && !/^ {2}\./.test(line)) {
+            inRoot = false;
+            inDepBlock = false;
+            currentPkg = null;
+            continue;
+        }
+        if (!inRoot)
+            continue;
+        if (/^ {4}(?:dependencies|devDependencies|optionalDependencies|peerDependencies):\s*$/.test(line)) {
+            inDepBlock = true;
+            currentPkg = null;
+            continue;
+        }
+        // Non-dep field under root importer ends a dep block.
+        if (inDepBlock && /^ {4}\S/.test(line)) {
+            inDepBlock = false;
+            currentPkg = null;
+            continue;
+        }
+        if (!inDepBlock)
+            continue;
+        const pkgMatch = line.match(/^ {6}(.+?):\s*$/);
+        if (pkgMatch) {
+            currentPkg = unquote(pkgMatch[1] ?? "");
+            continue;
+        }
+        if (currentPkg) {
+            const verMatch = line.match(/^ {8}version:\s*(.+?)\s*$/);
+            if (verMatch) {
+                out[currentPkg] = unquote(verMatch[1] ?? "");
+                currentPkg = null;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Extract pnpm `packages:` section records keyed by the package name (not
+ * name@version). Used to freeze product package resolution blocks.
+ */
+export function pnpmPackagesByName(raw) {
+    const map = new Map();
+    const lines = raw.split(/\r?\n/);
+    let inPackages = false;
+    let currentName = null;
+    let buf = [];
+    const flush = () => {
+        if (currentName === null)
+            return;
+        const prev = map.get(currentName) ?? [];
+        prev.push(buf.join("\n"));
+        map.set(currentName, prev);
+        currentName = null;
+        buf = [];
+    };
+    const unquote = (s) => {
+        const t = s.trim();
+        if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) {
+            return t.slice(1, -1);
+        }
+        return t;
+    };
+    for (const line of lines) {
+        if (/^packages:\s*$/.test(line)) {
+            flush();
+            inPackages = true;
+            continue;
+        }
+        if (!inPackages)
+            continue;
+        if (/^[^\s#]/.test(line) && !line.startsWith("packages")) {
+            flush();
+            break;
+        }
+        // Package key at 2-space indent: `  lodash@4.17.21:` or `  '@scope/pkg@1.0.0':`
+        const keyMatch = line.match(/^ {2}(.+?):\s*$/);
+        if (keyMatch) {
+            flush();
+            const key = unquote(keyMatch[1] ?? "");
+            // name@version or @scope/name@version — strip version suffix after last @
+            // that is not the scope marker.
+            const at = key.startsWith("@") ? key.indexOf("@", 1) : key.indexOf("@");
+            currentName = at > 0 ? key.slice(0, at) : key;
+            buf = [line];
+            continue;
+        }
+        if (currentName !== null)
+            buf.push(line);
+    }
+    flush();
+    // Join multi-version records for stable compare.
+    const out = new Map();
+    for (const [name, blocks] of map) {
+        out.set(name, blocks.slice().sort().join("\n---\n"));
+    }
+    return out;
+}
+/**
+ * pnpm-lock.yaml follow-through: root importer (`.`) non-directive direct dep
+ * identities must be unchanged, and every non-@deftai/directive packages-section
+ * record (including transitive product packages) must be byte-stable (#3193).
+ */
+/**
+ * Extract a top-level pnpm section (`packages:` or `snapshots:`) keyed by package name.
+ */
+function pnpmNamedSectionByName(raw, section) {
+    const map = new Map();
+    const lines = raw.split(/\r?\n/);
+    let inSection = false;
+    let currentName = null;
+    let buf = [];
+    const sectionRe = new RegExp(`^${section}:\\s*$`);
+    const flush = () => {
+        if (currentName === null)
+            return;
+        const prev = map.get(currentName) ?? [];
+        prev.push(buf.join("\n"));
+        map.set(currentName, prev);
+        currentName = null;
+        buf = [];
+    };
+    const unquote = (s) => {
+        const t = s.trim();
+        if ((t.startsWith("'") && t.endsWith("'")) || (t.startsWith('"') && t.endsWith('"'))) {
+            return t.slice(1, -1);
+        }
+        return t;
+    };
+    for (const line of lines) {
+        if (sectionRe.test(line)) {
+            flush();
+            inSection = true;
+            continue;
+        }
+        if (!inSection)
+            continue;
+        if (/^[^\s#]/.test(line) && !line.startsWith(section)) {
+            flush();
+            break;
+        }
+        const keyMatch = line.match(/^ {2}(.+?):\s*$/);
+        if (keyMatch) {
+            flush();
+            const key = unquote(keyMatch[1] ?? "");
+            const at = key.startsWith("@") ? key.indexOf("@", 1) : key.indexOf("@");
+            currentName = at > 0 ? key.slice(0, at) : key;
+            buf = [line];
+            continue;
+        }
+        if (currentName !== null)
+            buf.push(line);
+    }
+    flush();
+    const out = new Map();
+    for (const [name, blocks] of map) {
+        out.set(name, blocks.slice().sort().join("\n---\n"));
+    }
+    return out;
+}
+export function isPnpmLockDirectivePinFollowThrough(baseRaw, headRaw) {
+    const baseRoot = pnpmLockRootDirectDeps(baseRaw);
+    const headRoot = pnpmLockRootDirectDeps(headRaw);
+    if (!onlyDirectiveDirectDepsDiffer(baseRoot, headRoot))
+        return false;
+    for (const section of ["packages", "snapshots"]) {
+        const baseSec = pnpmNamedSectionByName(baseRaw, section);
+        const headSec = pnpmNamedSectionByName(headRaw, section);
+        const names = new Set([...baseSec.keys(), ...headSec.keys()]);
+        for (const name of names) {
+            if (isDirectiveDependencyKey(name))
+                continue;
+            if ((baseSec.get(name) ?? null) !== (headSec.get(name) ?? null))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * yarn.lock (v1) package identity blocks: every non-@deftai/directive* package
+ * must keep identical block text (or fail if added/removed). Directive package
+ * blocks may change freely as pin follow-through (#3193).
+ */
+export function isYarnLockDirectivePinFollowThrough(baseRaw, headRaw) {
+    const baseBlocks = yarnLockPackageBlocks(baseRaw);
+    const headBlocks = yarnLockPackageBlocks(headRaw);
+    const names = new Set([...baseBlocks.keys(), ...headBlocks.keys()]);
+    for (const name of names) {
+        if (isDirectiveDependencyKey(name))
+            continue;
+        if ((baseBlocks.get(name) ?? null) !== (headBlocks.get(name) ?? null))
+            return false;
+    }
+    return true;
+}
+function yarnLockPackageBlocks(raw) {
+    const map = new Map();
+    const lines = raw.split(/\r?\n/);
+    let currentNames = [];
+    let buf = [];
+    const flush = () => {
+        if (currentNames.length === 0)
+            return;
+        const body = buf.join("\n");
+        for (const name of currentNames) {
+            map.set(name, body);
+        }
+        currentNames = [];
+        buf = [];
+    };
+    for (const line of lines) {
+        if (line === "" || line.startsWith("#")) {
+            if (currentNames.length > 0 && line === "") {
+                flush();
+            }
+            continue;
+        }
+        // Package header: `"lodash@^4.17.21":` or `lodash@^4.17.21:`
+        if (!/^\s/.test(line) && line.endsWith(":")) {
+            flush();
+            const header = line.slice(0, -1);
+            currentNames = header.split(",").map((part) => {
+                let p = part.trim();
+                if ((p.startsWith('"') && p.endsWith('"')) || (p.startsWith("'") && p.endsWith("'"))) {
+                    p = p.slice(1, -1);
+                }
+                // name@version or @scope/name@version
+                const at = p.startsWith("@") ? p.indexOf("@", 1) : p.indexOf("@");
+                return at > 0 ? p.slice(0, at) : p;
+            });
+            buf = [line];
+            continue;
+        }
+        if (currentNames.length > 0)
+            buf.push(line);
+    }
+    flush();
+    return map;
+}
+/**
+ * Content-aware check for a single upgrade pin path (#3193).
+ * Returns true when the path may co-travel with `.deft/core/**`.
+ */
+export function isUpgradePinPathContentAllowed(path, baseRaw, headRaw) {
+    const normalized = path.replace(/\\/g, "/");
+    switch (normalized) {
+        case "package.json":
+            return isPackageJsonDirectivePinOnlyDiff(baseRaw, headRaw);
+        case "package-lock.json":
+            return isPackageLockDirectivePinFollowThrough(baseRaw, headRaw);
+        case "pnpm-lock.yaml":
+            return isPnpmLockDirectivePinFollowThrough(baseRaw, headRaw);
+        case "yarn.lock":
+            return isYarnLockDirectivePinFollowThrough(baseRaw, headRaw);
+        default:
+            return false;
+    }
+}
 /**
  * TS twin of Go `classifyChangedPaths` / deposited shell guard (#1430).
  * Core = `.deft/core/**`; installer-managed = allowlist; app = everything else.
  * Guard fails iff both core and app are non-empty.
+ *
+ * Path-only: does not inspect package/lock contents. Prefer
+ * {@link classifyMixedCoreAndAppContentAware} when base/head blobs are available
+ * (deposited guard + unit tests for #3193).
  */
 export function classifyMixedCoreAndApp(changedPaths, matchers = installerManagedMatchers()) {
     const core = [];
@@ -213,6 +745,47 @@ export function classifyMixedCoreAndApp(changedPaths, matchers = installerManage
         wouldFail: core.length > 0 && app.length > 0,
     };
 }
+/**
+ * Content-aware upgrade co-travel classifier (#3193).
+ *
+ * Starts from path classification (#3127 allowlist), then when `.deft/core/**`
+ * is present reclassifies package.json / lockfile paths as **app** unless their
+ * base→head content is the Directive pin unit (or lock follow-through).
+ * `.deft/GENERATION.json` remains path-allowlisted with no content constraint.
+ *
+ * Missing content for a pin path co-travelling with core fails closed (treated
+ * as app) so partial fixtures cannot silently re-open the path-only hole.
+ */
+export function classifyMixedCoreAndAppContentAware(changedPaths, fileContents, matchers = installerManagedMatchers()) {
+    const base = classifyMixedCoreAndApp(changedPaths, matchers);
+    if (base.core.length === 0) {
+        return { ...base, pinContentRejected: [] };
+    }
+    const pinContentRejected = [];
+    const keptManaged = [];
+    const app = [...base.app];
+    for (const path of base.installerManaged) {
+        if (!UPGRADE_PIN_CONTENT_PATHS.includes(path)) {
+            keptManaged.push(path);
+            continue;
+        }
+        const pair = fileContents[path];
+        if (!pair || !isUpgradePinPathContentAllowed(path, pair.base, pair.head)) {
+            pinContentRejected.push(path);
+            app.push(path);
+        }
+        else {
+            keptManaged.push(path);
+        }
+    }
+    return {
+        core: base.core,
+        installerManaged: keptManaged,
+        app,
+        wouldFail: app.length > 0,
+        pinContentRejected,
+    };
+}
 export function frameworkStagePaths(projectDir, deftDir, options = {}) {
     const paths = [];
     const seen = new Set();
@@ -486,11 +1059,12 @@ export function printCommitGuidance(io, paths, staged) {
     if (paths.length === 0)
         return;
     const addCmd = `git add ${paths.join(" ")}`;
-    io.printf("\nCommit hygiene (#1453, #1671, #3127): keep the framework upgrade in its OWN branch/PR.\n");
+    io.printf("\nCommit hygiene (#1453, #1671, #3127, #3193): keep the framework upgrade in its OWN branch/PR.\n");
     io.printf("Do NOT use `git add -A` -- mixing the payload with product/app files trips the\n");
     io.printf("deft-core-guard CI check.\n");
     io.printf("One upgrade PR MAY co-travel: .deft/core/** + installer-managed deposits + package.json\n");
-    io.printf("pin/lock + .deft/GENERATION.json. True app/product paths still require a separate PR.\n");
+    io.printf("pin/lock (Directive pin-only + lock follow-through, #3193) + .deft/GENERATION.json.\n");
+    io.printf("True app/product paths still require a separate PR.\n");
     if (staged) {
         io.printf("The installer already staged ONLY these framework + installer-managed paths:\n");
         io.printf(`  ${addCmd}\n`);