@sleepy_panda_srl/portulan 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -75,6 +75,33 @@
75
75
  * every manifest in this repository already has. A manifest formatted otherwise is reformatted, and
76
76
  * that is a real cost rather than a hidden one.
77
77
  *
78
+ * ## A pack two roots answer for is refused, not picked
79
+ *
80
+ * On a host carrying an installed copy of a composed pack **and** the tree's own, resolution is
81
+ * discovered-first and first-match-wins, so the installed copy answers. That copy lives outside the
82
+ * plugin root, containment fails, and this tool concluded the tree's declared skills path belonged to
83
+ * no composed pack — printing `--write` as the remedy, where `--write` is the mutation that strips a
84
+ * correct declaration out of a tracked manifest
85
+ * ([#317](https://github.com/sleepy-panda-srl/portulan/issues/317)).
86
+ *
87
+ * So this refuses at RESOLUTION — exit 2 — where `compile` refuses for the same family
88
+ * ([#316](https://github.com/sleepy-panda-srl/portulan/issues/316)), and for the same reason: the
89
+ * printer, `--check` and `--write` inherit ONE rule rather than three. Refusing on `--write` alone
90
+ * would leave `--check` exiting **1**, asserting the *repository* had drifted when it had not — and an
91
+ * exit code is the machine-read API, so a false 1 is a false verdict about the tree.
92
+ *
93
+ * **The predicate is imported, not re-spelled.** `shadowedCopy` and `packDifferences` live in
94
+ * `./compile.mjs`. That comparison had already been wrong twice in `doctor` before it became one
95
+ * carrier, and a third copy written inside a fix for its own family is precisely the defect
96
+ * `../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md` names.
97
+ *
98
+ * **Where this tool's reason is SHARPER than `compile`'s, and the message says so.** `compile` refuses
99
+ * a shadow whose manifests agree because `recordedOrigin` writes the answering root into the artifact,
100
+ * so agreement in the manifests is not agreement in the bytes. Here agreement is beside the point in a
101
+ * more direct way: the two copies sit on opposite sides of the plugin root, so which one answers
102
+ * decides whether this pack contributes a `skills` path **at all**. Version parity does not save it,
103
+ * which is why this fires on hosts where `compile`'s difference-driven half would have nothing to say.
104
+ *
78
105
  * Zero dependencies, no network, no install step — the same constraints as every tool here.
79
106
  */
80
107
 
@@ -93,7 +120,7 @@ import { pathToFileURL } from "node:url";
93
120
  // root wins outright; otherwise discovery is unioned with the derived root, discovered first** — asking
94
121
  // only selects the strict degrade. This tool exited **2** on the ordinary drafted workspace until then,
95
122
  // which is what the row's "optional where discovery finds a root" was not.)_
96
- import { resolvePack, rootPlan } from "./compile.mjs";
123
+ import { packDifferences, recordedOrigin, resolvePack, rootPlan, shadowedCopy } from "./compile.mjs";
97
124
  import { AUTO, discoverPackRoots, namedWithAuto } from "./discover.mjs";
98
125
 
99
126
  /**
@@ -425,6 +452,114 @@ export function declaredFor(set, pluginManifest, pluginRoot) {
425
452
  return [...portion.outside, ...set.paths.map((p) => p.path)];
426
453
  }
427
454
 
455
+ /**
456
+ * The refusal a shadowed pack earns, or `null` when no declared pack is shadowed.
457
+ *
458
+ * Separated from `run` so the sentence a reader gets is testable without a command line, and kept in
459
+ * this file rather than pushed into `compile.mjs` because the CONSEQUENCE clause is this tool's own:
460
+ * `compile` talks about emitted policy, and this one talks about whether a `skills` path is derived.
461
+ * What is shared — *is there a second copy behind the one that answered, and do the two differ* — is
462
+ * imported, and that split is the point.
463
+ *
464
+ * Only the **unasked** path reaches here. `--pack-root <dir>` names a root, which replaces the derived
465
+ * one and leaves nothing behind it to shadow; `--pack-root auto` is discovery ELECTED, and refusing
466
+ * somebody for answering the question the refusal asks would be incoherent. Both spellings are offered
467
+ * in the message for that reason — naming only the tree would make the refusal decide the question it
468
+ * claims to hand back.
469
+ */
470
+ export function shadowRefusal({ packs, roots, plan, repoRoot, pluginRoot }) {
471
+ const originOf = (r) => (plan?.origins ?? []).find((o) => path.resolve(o.root) === path.resolve(r))?.origin;
472
+ for (const ref of Array.isArray(packs) ? packs : []) {
473
+ const found = resolvePack(ref, roots);
474
+ if (!found?.dir || !found.manifest) continue;
475
+ const behind = shadowedCopy(found.name, recordedOrigin(found.root, plan, repoRoot), roots, originOf);
476
+ if (!behind) continue;
477
+
478
+ const there = path.relative(repoRoot, behind.root) || behind.root;
479
+ // **The tree spelling is the root we just named, not the conventional guess.** Both arms below
480
+ // hard-coded `--pack-root packs`, and the derived root is `path.resolve(workspaceDir, tree,
481
+ // "packs")` — so a workspace whose `tree` is `../nested/` derives `nested/packs` and was being
482
+ // told to pass a directory that does not carry the pack. That is this branch's own defect class
483
+ // one more time: a message prescribing a remedy it had not checked, in the sentence whose whole
484
+ // job is to hand back an accurate choice. `there` is already the relative spelling of that root,
485
+ // and for the conventional layout it is exactly `packs`, so the common output is unchanged.
486
+ //
487
+ // The `verify/plugin.sh` clause is gated with it, because that rail pins the literal
488
+ // `--pack-root packs`: claiming the equivalence for `nested/packs` would replace one false
489
+ // sentence with another. Raised through the promoted suppressed-note channel, which carries
490
+ // findings the inline round does not.
491
+ const rail = there === "packs" ? ", which is what `verify/plugin.sh` checks" : "";
492
+
493
+ // **Read and parse are two failures with two repairs**, and one sentence for both misdiagnoses
494
+ // the commoner one — the defect Copilot raised against `run`'s workspace arm on #229, whose
495
+ // comment sits one screen below this and which the first cut of this block reintroduced
496
+ // anyway. A `SyntaxError` from `JSON.parse` carries no `.code`, so a collapsed arm reporting
497
+ // `error.code ?? error.message` under *could not be read* sends somebody with a malformed
498
+ // manifest to look at permissions. `readManifest` and `resolverFor` both keep the two apart;
499
+ // so does this. It also names WHICH of the two copies is the broken one, which the collapsed
500
+ // form could not — with two manifests in play, "one of the two" is half a diagnosis.
501
+ const load = (file) => {
502
+ let text;
503
+ try {
504
+ text = fs.readFileSync(file, "utf8");
505
+ } catch (error) {
506
+ return { why: `could not be read — ${error.code ?? error.message}` };
507
+ }
508
+ try {
509
+ return { value: JSON.parse(text) };
510
+ } catch (error) {
511
+ return { why: `does not parse as JSON — ${error.message}` };
512
+ }
513
+ };
514
+ const here = load(found.manifest);
515
+ const beneath = load(behind.manifest);
516
+ const broken = here.why ? { at: found.root, why: here.why } : beneath.why ? { at: there, why: beneath.why } : null;
517
+ if (broken) {
518
+ // Could-not-run wearing its own sentence rather than the SHADOWED one: with a manifest
519
+ // unreadable, *what differs* is unanswerable, and a refusal that guessed would be claiming
520
+ // to have compared two things it could not read. The remedy is the same either way.
521
+ return (
522
+ `the pack \`${found.name}\` resolved under the root ${found.root} while the root ${there} also ` +
523
+ `carries it, and the copy under ${broken.at} ${broken.why} — so which one this would derive ` +
524
+ `from could not be established. Name the root: \`--pack-root ${there}\` derives from the tree${rail}, ` +
525
+ "`--pack-root auto` from the installed copy"
526
+ );
527
+ }
528
+ const mine = here.value;
529
+ const other = beneath.value;
530
+
531
+ // **Containment, computed rather than assumed.** The sharp case — one copy inside the plugin
532
+ // root and one outside — is what makes `--write` destructive, but it is not a law: a
533
+ // `--plugin-root` pointing elsewhere puts both outside, and the refusal still stands because
534
+ // the derived path is relative to whichever root answered. Asserting the sharp case
535
+ // unconditionally would be this message's first lie, in the sentence that exists to be exact.
536
+ //
537
+ // Tested against the ROOTS, which is also what `packPortion` partitions on — `resolvePack`
538
+ // builds `dir` as `<root>/<category>/<pack>`, so the two can never disagree here, and using the
539
+ // root keeps this predicate spelled the same way as the derivation it is predicting.
540
+ const differs = packDifferences(mine, other);
541
+ const split = escapes(pluginRoot, path.resolve(found.root)) !== escapes(pluginRoot, path.resolve(behind.root));
542
+ // **Both ROOTS by path — the roots, not the pack directories.** The sibling refusal in
543
+ // `compile` shipped `dir` while calling it a root, which mislabels the thing it names in a
544
+ // message whose own claim is to name both; the root is also the half a reader types back into
545
+ // `--pack-root`. Corrected here in the same stroke rather than left to be found twice.
546
+ return (
547
+ `the pack \`${found.name}\` is SHADOWED — it resolved under ${found.root}, a root discovered on this ` +
548
+ `host, while the root ${there} also carries it. ` +
549
+ (differs.length
550
+ ? `They differ by ${differs.join(" and ")}, and which root answers decides the derived set anyway: `
551
+ : "Their manifests agree, and here that changes nothing: ") +
552
+ (split
553
+ ? "the two sit on opposite sides of this plugin root, so one of them derives a `skills` path for " +
554
+ "this pack and the other derives none — `--write` would act on whichever answered. "
555
+ : "the two roots derive different `skills` paths, and `--write` would act on whichever answered. ") +
556
+ `Refusing to pick: name the root instead — \`--pack-root ${there}\` derives from the tree${rail}, ` +
557
+ "and `--pack-root auto` from the installed copy"
558
+ );
559
+ }
560
+ return null;
561
+ }
562
+
428
563
  /**
429
564
  * A resolver over a workspace's declared pack roots.
430
565
  *
@@ -545,8 +680,11 @@ function readManifest(file, pluginRoot) {
545
680
  * The runnable surface: the printer CI and an adopter's own pipeline call, plus `--check` and
546
681
  * `--write`.
547
682
  *
548
- * `options.manifest` and `options.resolve` are injection points for the suite, the way `init` injects
549
- * its reader. No production caller passes either; every flag below is the real surface.
683
+ * `options.manifest`, `options.resolve` and `options.discovery` are injection points for the suite, the
684
+ * way `init` injects its reader. No production caller passes any of them; every flag below is the real
685
+ * surface. `discovery` is injected as a THUNK like the production one, because the guarantee that a
686
+ * branch which cannot use the answer never touches the host is a property of the ARGUMENT — a suite
687
+ * handed a pre-computed value would be testing a shape production never takes.
550
688
  */
551
689
  export function run(argv = [], options = {}) {
552
690
  const { stdout = process.stdout, stderr = process.stderr } = options;
@@ -623,7 +761,7 @@ export function run(argv = [], options = {}) {
623
761
  // caller wiring no thunk stays hermetic on every arm.)_
624
762
  const plan = rootPlan(workspaceDir, manifest, {
625
763
  named: namedRoots,
626
- discovery: () => discoverPackRoots(),
764
+ discovery: options.discovery ?? (() => discoverPackRoots()),
627
765
  forced: wantsDiscovery,
628
766
  });
629
767
  if (plan.refusal || plan.couldNotRun) {
@@ -631,6 +769,30 @@ export function run(argv = [], options = {}) {
631
769
  return 2;
632
770
  }
633
771
  const roots = plan.roots ?? [];
772
+ // **Refused here, above the mode branches, so the printer, `--check` and `--write` inherit one
773
+ // rule** (#317). The damage this prevents is specific to the write path — the tool printed
774
+ // `run with --write` while `--write` would have stripped a correct, tracked `skills` entry on
775
+ // the strength of what happens to be installed on the machine — but guarding only `--write`
776
+ // would leave `--check` exiting 1 about a repository that had not drifted, which is a false
777
+ // verdict handed to a machine. `compile` settled the same question the same way for #316.
778
+ //
779
+ // A caller that injected its own `resolve` never reaches this, and that is deliberate rather
780
+ // than a hole: it chose its own roots, which is the same election `--pack-root` makes.
781
+ //
782
+ // **The `named` half of this condition is defence in depth, and it was measured HERE rather
783
+ // than inherited from `compile`'s note.** Forcing the whole condition to `true` reds exactly
784
+ // one case — the `--pack-root auto` exemption — while the named-root case goes on passing: a
785
+ // named root REPLACES the derived one, so the plan carries no discovered root, `shadowedCopy`
786
+ // finds nothing behind it, and there is no shadow to refuse. The protection is structural, and
787
+ // no test in this suite binds the clause. It stays because it states the intent at the site
788
+ // where a future change to `resolutionRoots` could quietly make it load-bearing.
789
+ if (!wantsDiscovery && plan.source !== "named") {
790
+ const shadowed = shadowRefusal({ packs: manifest?.packs, roots, plan, repoRoot, pluginRoot });
791
+ if (shadowed) {
792
+ stderr.write(`skills-set: ${shadowed}\n`);
793
+ return 2;
794
+ }
795
+ }
634
796
  resolve = resolverFor({ workspaceDir, manifest, roots });
635
797
  // The same roots stand in as the owned set when nothing resolves — so a workspace that has
636
798
  // stopped composing gets its stale entries cleaned wherever its packs WOULD have been, not