@sleepy_panda_srl/portulan 0.1.1 → 0.1.3

package/cli/doctor.mjs

@@ -43,7 +43,16 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 // it looks like enforcement that quietly stopped covering something. Same reasoning that has
 // ./gate.mjs import the matcher instead of writing a second one. Zero
 // dependencies on both sides, so nothing is added to what this tool needs to run.
-import { parse, backends, resolvePack, rootPlan, packContributions, composeFragments } from "./compile.mjs";
+import {
+    parse,
+    backends,
+    resolvePack,
+    rootPlan,
+    packContributions,
+    composeFragments,
+    packDifferences,
+    shadowedCopy,
+} from "./compile.mjs";
 // The containment test the memory-index siting rule turns on, imported for the reason directly
 // above: the copy that used to live here drifted into the identical fail-open as the original.
 import { isInside, recordType } from "./index.mjs";
@@ -385,7 +394,11 @@ export function parseProvenance(source) {
 // the line a demotion pass retires by. Anchored to the bolded field at line start, so prose that
 // merely discusses retiring never matches — the same false-red caution parseProvenance takes with
 // backticked tokens, for the same reason: a false red is what gets a whole check switched off.
-const RETIRE_WHEN = /^\s*\*\*retire when:\*\*/im;
+// **Exported for `./skill-goldens.mjs`**, which binds `core/skills/consolidate/SKILL.md` step 1 —
+// *"Every record carries a `Retire when:` line"* — to the live store. Exported rather than re-spelled:
+// a second regex there would be a second carrier of this field's spelling, and the anchoring caution
+// above is the part a re-speller gets wrong first.
+export const RETIRE_WHEN = /^\s*\*\*retire when:\*\*/im;
 
 // ===========================================================================================
 // 3. Claims against the tree
@@ -1815,6 +1828,50 @@ export async function inspect(workspaceDir, options = {}) {
                 "packs",
                 `\`${name}\` resolves${from} to ${path.relative(dir, found.dir)} and validates against Pack Definition ${manifest.portulan.pack} — contributes ${parts.length ? parts.join(", ") : "nothing"}`,
             );
+
+            // **A SHADOWED pack is reported, and the report says WHAT DIFFERS** (#264). Resolution is
+            // first-match-wins and discovered roots come first, so where the host carries a copy of a
+            // pack the tree also carries, the installed one answers and nothing said so. Silence about
+            // the shadowed copy is the part that makes the failure unreproducible: the compiled artifact
+            // moves, the rail reds, and the deciding input is a directory outside the repository.
+            //
+            // A REPORT, never a verdict — an installed pack shadowing a tree copy is a fact about the
+            // machine, and this tool must not turn a fact about the machine into a verdict about the
+            // repository (the boundary this file already states for discovered roots).
+            {
+                const shadowed = shadowedCopy(name, origin, roots, (r) => originOf.get(r)) ?? { dir: null };
+                if (shadowed.dir) {
+                    let other = null;
+                    try {
+                        other = JSON.parse(fs.readFileSync(shadowed.manifest, "utf8"));
+                    } catch (cause) {
+                        // Could-not-compare, in so many words. A shadow we cannot read is not a shadow
+                        // we can call harmless, and saying nothing here would be the silence this whole
+                        // report exists to end.
+                        report(
+                            "packs",
+                            `\`${name}\` is SHADOWED — the tree-derived root also carries it at ${path.relative(dir, shadowed.dir)}, and that copy could not be read (${cause.message}), so what differs could not be compared`,
+                        );
+                    }
+                    if (other) {
+                        // **The comparison lives in `compile.mjs`, and this calls it.** It grew here,
+                        // and its two earlier spellings each claimed more than they compared — a
+                        // projection over `[id, tier, action]` that read a copy differing in `reason`
+                        // as agreeing, and a *byte-identical* claim `JSON.stringify` of a parsed value
+                        // cannot make. `compile` now has to answer the same question in order to refuse
+                        // a shadow it cannot honestly pick between (#316), and a second copy of a
+                        // comparison already corrected twice is exactly proposal `0020`'s defect. The
+                        // rationale for parsed-and-key-sorted moved with the code.
+                        const differs = packDifferences(manifest, other);
+                        report(
+                            "packs",
+                            `\`${name}\` is SHADOWED — the installed copy answered and the tree-derived root also carries it at ` +
+                                `${path.relative(dir, shadowed.dir)}; ${differs.length ? `they differ by ${differs.join(" and ")}` : "the two agree today"}. ` +
+                                "An unpinned `compile` or `recipe-set` REFUSES this rather than picking, and so does `index` for a workspace declaring a scope index — name the root: `--pack-root packs` for the tree, which is what the recipes check",
+                        );
+                    }
+                }
+            }
         }
     }