@canonical/pragma-cli 0.36.0 → 0.38.0

package/src/capabilities/setup/setup.verb.ts

@@ -209,6 +209,31 @@ async function runSetup(
   // to know which of the two it is.
   const previewing = interactionMode === "batch-dry-run";
 
+  // The undo truth channel. A real `--undo` interprets this verb's task ONLY
+  // as the undo interpreter's mocked collection walk — every exec exits 0,
+  // every prompt answers its default, and the OutcomeSink is never written —
+  // so nothing the task body could report describes what the collected
+  // reversals later did. The body therefore says NOTHING on the undo path
+  // (see the guard in the gen body below); the kernel calls this seam after
+  // the reversals actually ran, handing over the interpreter's per-undo
+  // outcomes, and `appliedUndo` projects them onto the rows through the SAME
+  // sink + `applied` path the forward run reports through. One outcome
+  // model, both directions.
+  if (!previewing && input.undo) {
+    rt.undoReport = (outcomes) => {
+      const applied = run.appliedUndo(outcomes);
+      const width = Math.max(...applied.rows.map((row) => row.target.length));
+      for (const row of applied.rows) {
+        if (row.outcome === undefined) continue;
+        rt.report?.(renderProgressLine(row, width));
+      }
+      if (planExitFailed(applied)) {
+        rt.report?.(renderRecap(applied, "Removed"));
+        raiseFailedRows(applied, true);
+      }
+    };
+  }
+
   // A CONVERGED machine has no question to ask. Every row is `none` or `skip`,
   // so nothing composes an effect — and the wizard's confirm gate then mounted
   // Ink to render summon-core's "No operations planned." above a "Proceed?"
@@ -313,6 +338,16 @@ async function runSetup(
     const result = yield* $(task);
     const applied = run.applied(result.answers);
 
+    // A real `--undo` only ever drives this body under the undo
+    // interpreter's COLLECTION walk, with every effect mocked. `applied` is
+    // then a projection of the mocked walk (`removed` rows for reversals
+    // that have not run yet), so reporting it here printed green checks
+    // before anything happened. Say nothing; the kernel hands the executed
+    // reversals' outcomes to `rt.undoReport` afterwards, and `appliedUndo`
+    // grades the rows from those. (`--undo --dry-run` stays on the shared
+    // preview path below, where the same suppressions already apply.)
+    if (input.undo && !previewing) return applied;
+
     // Progress: one line per row on stderr for an unattended run (the Ink
     // session already draws them for the wizard). stdout stays the data stream.
     //
@@ -333,45 +368,58 @@ async function runSetup(
     // stdout on a failing run.
     if (planExitFailed(applied)) {
       rt.report?.(renderRecap(applied));
-      const failed = applied.rows.filter(
-        (row) => row.outcome?.status === "failed",
-      );
-
-      // ONE failure reports itself. The row already carries the cause it was
-      // given ("`bun` is not found on your PATH") and a remedy that runs on
-      // this machine; replacing them with a count would throw away the only
-      // two sentences that say what is wrong and what to do about it.
-      const only = failed.length === 1 ? failed[0] : undefined;
-      if (only?.outcome !== undefined) {
-        throw new PragmaError({
-          code: "UNSUPPORTED",
-          message: `${only.target}: ${only.outcome.note ?? "the step did not complete"}`,
-          ...(only.outcome.remedy === undefined
-            ? {}
-            : { recovery: { message: only.outcome.remedy } }),
-        });
-      }
+      raiseFailedRows(applied);
+    }
+    return applied;
+  });
+}
 
-      // Several failures: name every one with its own cause, then point at the
-      // recap above. A bare list of target names would make the reader re-run
-      // each one to find out why it failed.
-      const named = failed
+/**
+ * Raise the run's failure from its rows — shared by the forward run's recap
+ * and the post-undo truth report, so the two paths name a shortfall in the
+ * same words. `undo` only re-words the multi-failure recovery line: the
+ * command that retries a removal is `setup <target> --undo`, not the
+ * installer.
+ *
+ * @param applied - The plan with outcomes filled in (at least one `failed`).
+ * @param undo - Whether the failed run was a removal.
+ * @throws PragmaError naming the failed row(s), always.
+ */
+function raiseFailedRows(applied: SetupPlan, undo = false): never {
+  const failed = applied.rows.filter((row) => row.outcome?.status === "failed");
+
+  // ONE failure reports itself. The row already carries the cause it was
+  // given ("`bun` is not found on your PATH") and a remedy that runs on
+  // this machine; replacing them with a count would throw away the only
+  // two sentences that say what is wrong and what to do about it.
+  const only = failed.length === 1 ? failed[0] : undefined;
+  if (only?.outcome !== undefined) {
+    throw new PragmaError({
+      code: "UNSUPPORTED",
+      message: `${only.target}: ${only.outcome.note ?? "the step did not complete"}`,
+      ...(only.outcome.remedy === undefined
+        ? {}
+        : { recovery: { message: only.outcome.remedy } }),
+    });
+  }
+
+  // Several failures: name every one with its own cause, then point at the
+  // recap above. A bare list of target names would make the reader re-run
+  // each one to find out why it failed.
+  const named = failed
+    .map((row) => `${row.target} (${row.outcome?.note ?? "no cause recorded"})`)
+    .join("; ");
+  throw new PragmaError({
+    code: "UNSUPPORTED",
+    message: `${failed.length} of ${planTally(applied).accountable} targets did not complete: ${named}.`,
+    recovery: {
+      message: `The other targets are ${undo ? "removed" : "configured"}. Re-run the ones that did not complete: ${failed
         .map(
           (row) =>
-            `${row.target} (${row.outcome?.note ?? "no cause recorded"})`,
+            `\`${BIN_NAME} setup ${row.target}${undo ? " --undo" : ""}\``,
         )
-        .join("; ");
-      throw new PragmaError({
-        code: "UNSUPPORTED",
-        message: `${failed.length} of ${planTally(applied).accountable} targets did not complete: ${named}.`,
-        recovery: {
-          message: `The other targets are configured. Re-run the ones that did not complete: ${failed
-            .map((row) => `\`${BIN_NAME} setup ${row.target}\``)
-            .join(", ")}.`,
-        },
-      });
-    }
-    return applied;
+        .join(", ")}.`,
+    },
   });
 }
 
@@ -456,7 +504,7 @@ const skillsVerb = setupVerb(
 
 const lspVerb = setupVerb(
   ["setup", "lsp"],
-  "Install the Terrazzo design-token extension into your VS Code-family editors.",
+  "Install the Terrazzo design-token extension into the VS Code-family editors on this machine (on PATH, under /Applications or ~/Applications, or by its user directory).",
   "lsp",
   SUB_CAPABILITY,
 );

package/src/capabilities/setup/targets.ts

@@ -24,6 +24,7 @@
  * doctor's), so nothing here lands on the `--help`/`__complete` fast path.
  */
 
+import { dirname } from "node:path";
 import type { Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/index.js";
@@ -42,9 +43,13 @@ import {
 import {
   composeLsp,
   composeLspRemoval,
+  describeEditorSource,
   detectLsp,
+  firstLspBlock,
+  installableEditors,
   LSP_SKIP_REMEDY,
   type LspDetection,
+  lspBlockReason,
   lspEditorNames,
   lspSkipReason,
   ownedLspEditors,
@@ -53,7 +58,10 @@ import {
   composeMcp,
   composeMcpRemoval,
   detectMcp,
+  firstMcpBlock,
   type McpDetection,
+  mcpBlockReason,
+  mcpGroupBlock,
   mcpGroupState,
   ownedMcpGroups,
   selectedGroups,
@@ -68,10 +76,11 @@ import {
   skillsSkipRemedy,
   staleSkillLinks,
 } from "./operations/setupSkills.js";
+import type { FsProbe } from "./operations/writability.js";
 import {
   type PlanAction,
   type PlanChildRow,
-  type SetupPlan,
+  type Roots,
   shortenPath,
   type TargetId,
 } from "./plan.js";
@@ -88,9 +97,6 @@ export interface TargetDraft {
   readonly remedy?: string;
 }
 
-/** The context a draft is rendered against — the plan's two named roots. */
-export type Roots = SetupPlan["roots"];
-
 /**
  * One row of the table, generic over its own detection type. Every consumer
  * treats the detection as opaque and hands it straight back to the same row,
@@ -101,8 +107,15 @@ export interface TargetDefinition<D> {
   /** Human title, used where a sentence needs one; the id is the row name. */
   readonly title: string;
   readonly scopes: readonly Scope[];
-  /** Real reads, up front, once per (target, scope) per invocation. */
-  detect(rt: PragmaRuntime, scope: Scope): Promise<D>;
+  /**
+   * Real reads, up front, once per (target, scope) per invocation.
+   *
+   * `probe` is the writability filesystem seam, threaded from `detectTargets`
+   * so a test can drive the two arms no CI host has — a `/nix/store` path, and
+   * (as root) a directory that refuses `W_OK` — through the SAME entry points
+   * production uses. Rows that write nothing ignore it.
+   */
+  detect(rt: PragmaRuntime, scope: Scope, probe?: FsProbe): Promise<D>;
   /** What a forward run would do. */
   plan(detection: D, scope: Scope, roots: Roots): TargetDraft;
   /** What a removal would do — composed from what detection says we own. */
@@ -112,8 +125,12 @@ export interface TargetDefinition<D> {
    * paths); a row without children ignores it.
    */
   compose(detection: D, chosen?: readonly string[]): Task<void>;
-  /** The removal effects: forward re-assertion carrying the reversal as `undo`. */
-  composeRemoval(detection: D): Task<void>;
+  /**
+   * The removal effects: forward re-assertion carrying the reversal as
+   * `undo`. `undoKey` (the row's identity) is stamped on every reversal so
+   * the undo interpreter's outcomes can be read back per row.
+   */
+  composeRemoval(detection: D, undoKey?: string): Task<void>;
 }
 
 /** A table row with its detection type erased — how every consumer holds one. */
@@ -150,7 +167,7 @@ const configTarget = defineTarget<ConfigDetection>({
     return { action: "remove", detail: path };
   },
   compose: (d) => composeConfigFile(d),
-  composeRemoval: (d) => composeConfigRemoval(d),
+  composeRemoval: (d, undoKey) => composeConfigRemoval(d, undoKey),
 });
 
 const completionsTarget = defineTarget<CompletionsDetection>({
@@ -207,66 +224,123 @@ const completionsTarget = defineTarget<CompletionsDetection>({
     return { action: "remove", detail: shortenPath(d.path, roots) };
   },
   compose: (d) => composeCompletions(d),
-  composeRemoval: (d) => composeCompletionsRemoval(d),
+  composeRemoval: (d, undoKey) => composeCompletionsRemoval(d, undoKey),
 });
 
+/**
+ * The named skip for a machine with no VS Code-family editor at all — the one
+ * finding the forward plan and the removal share verbatim.
+ */
+const draftLspNothingFound = (d: LspDetection): TargetDraft => ({
+  action: "skip",
+  detail: lspSkipReason(d),
+  reason: lspSkipReason(d),
+  remedy: LSP_SKIP_REMEDY,
+});
+
+/**
+ * One child per detected editor, exactly like the mcp row's files: a machine
+ * with several VS Code forks should not have the extension pushed into all of
+ * them because they happen to be installed.
+ *
+ * Each label carries HOW the editor was found, because that is the fact a user
+ * whose run did nothing needs — whether pragma missed their editor or found it
+ * and could not act.
+ *
+ * An INSTALLED editor is `unchanged` even when its folder is blocked: the copy
+ * really is there, and a child reading `skip — make the folder writable` told
+ * a user to chmod and reinstall an extension they already have. A block only
+ * decides the child when there is nothing installed for it to be about.
+ */
+const lspChildren = (d: LspDetection, roots: Roots): PlanChildRow[] =>
+  d.editors.map((e): PlanChildRow => {
+    const label = `${e.editor.cli} — ${e.editor.name} · ${describeEditorSource(e, roots)}`;
+    if (e.installed) {
+      return { key: e.editor.cli, label, action: "unchanged" };
+    }
+    const reason = lspBlockReason(e);
+    if (reason !== undefined) {
+      return { key: e.editor.cli, label, action: "skip", reason };
+    }
+    return { key: e.editor.cli, label, action: "add" };
+  });
+
+/**
+ * The row-level skip for a machine where nothing can be done at all —
+ * `undefined` when there is still something the row can say for itself.
+ *
+ * `actionable` is the row's own count of editors it could act on (pending
+ * installs going forward, owned copies on a removal) PLUS the ones already
+ * installed: a machine that is fully installed everywhere it can be is a `no
+ * change` row, not a permanent skip telling its owner to fix a folder whose
+ * extension is in place. Zero of those AND at least one block means the row's
+ * whole answer is the block, so it carries the FIRST one's reason and the
+ * remedy that matches it: a Nix declaration, a `chmod`, or the palette
+ * command, never one sentence standing for all three.
+ */
+const draftLspRowBlock = (
+  d: LspDetection,
+  actionable: number,
+): TargetDraft | undefined => {
+  if (actionable > 0) return undefined;
+  const block = firstLspBlock(d);
+  if (block === undefined) return undefined;
+  return {
+    action: "skip",
+    detail: block.headline,
+    reason: block.headline,
+    remedy: block.remedy,
+  };
+};
+
 const lspTarget = defineTarget<LspDetection>({
   id: "lsp",
   title: "Terrazzo LSP extension",
   scopes: ["global"],
-  detect: (rt) => detectLsp(rt.cwd),
-  plan: (d) => {
-    if (d.state === "unknown") {
-      return {
-        action: "skip",
-        detail: lspSkipReason(d),
-        reason: lspSkipReason(d),
-        remedy: LSP_SKIP_REMEDY,
-      };
-    }
-    // One child per detected editor, exactly like the mcp row's files: a
-    // machine with several VS Code forks on PATH should not have the extension
-    // pushed into all of them because they happen to be installed.
-    const children: PlanChildRow[] = d.editors.map((e) => ({
-      key: e.editor.cli,
-      label: `${e.editor.cli} — ${e.editor.name}`,
-      action: e.installed ? ("unchanged" as const) : ("add" as const),
-    }));
+  detect: (rt, _scope, probe) => detectLsp(rt.cwd, undefined, probe),
+  plan: (d, _scope, roots) => {
+    if (d.state === "unknown") return draftLspNothingFound(d);
+    const children = lspChildren(d, roots);
+    // The editors an install could actually act on: missing the extension AND
+    // not blocked. A blocked editor is not a candidate the user declined.
+    const installable = installableEditors(d);
+    const installed = d.editors.filter((e) => e.installed);
+    const blocked = draftLspRowBlock(d, installable.length + installed.length);
+    if (blocked !== undefined) return { ...blocked, children };
     // The detail names WHAT is being placed and WHERE — never the row's own
     // state, which the action column already carries. `installed (VSCodium)`
     // beside a child row reading `codium — VSCodium (unchanged)` said the
     // editor's name twice and "nothing happens here" twice.
-    if (d.state === "installed") {
+    if (installable.length === 0) {
       return {
         action: "none",
         detail: `Terrazzo extension in ${lspEditorNames(d).join(", ")}`,
         children,
       };
     }
-    const pending = d.editors.filter((e) => !e.installed);
     return {
       action: "install",
-      detail: `Terrazzo extension → ${pending
+      detail: `Terrazzo extension → ${installable
         .map((e) => e.editor.name)
         .join(", ")}`,
       children,
     };
   },
-  removalPlan: (d) => {
-    // No editor CLI on PATH is the SAME named skip the forward plan reports:
+  removalPlan: (d, _scope, roots) => {
+    // No editor found at all is the SAME named skip the forward plan reports:
     // there is nothing on this machine to run an uninstall with.
-    if (d.state === "unknown") {
-      return {
-        action: "skip",
-        detail: lspSkipReason(d),
-        reason: lspSkipReason(d),
-        remedy: LSP_SKIP_REMEDY,
-      };
-    }
+    if (d.state === "unknown") return draftLspNothingFound(d);
     // Removal is composed from what detection says we OWN — a copy that is
     // present, whatever its version. The forward plan's version gate would let
     // a dead pre-0.8.3 copy this command installed survive its own `--undo`.
     const owned = ownedLspEditors(d);
+    // Nothing owned AND something blocked is the same skip the forward row
+    // reports, for the same reason: the uninstall would need a CLI this
+    // machine has not got, or a write pragma must not make.
+    const blocked = draftLspRowBlock(d, owned.length);
+    if (blocked !== undefined) {
+      return { ...blocked, children: lspChildren(d, roots) };
+    }
     if (owned.length === 0) {
       return { action: "none", detail: "no editor carries the extension" };
     }
@@ -283,7 +357,7 @@ const lspTarget = defineTarget<LspDetection>({
     };
   },
   compose: (d, chosen) => composeLsp(d, chosen),
-  composeRemoval: (d) => composeLspRemoval(d),
+  composeRemoval: (d, undoKey) => composeLspRemoval(d, undoKey),
 });
 
 /**
@@ -303,10 +377,18 @@ const mcpChild = (
   group: McpDetection["groups"][number],
   roots: Roots,
 ): PlanChildRow => {
+  const label = shortenPath(group.path, roots);
+  // A file pragma cannot write is a child SKIP with its own reason, not an
+  // `add` that fails. The probe ran before anything was composed, so the row
+  // knows this without having tried.
+  const blocked = mcpBlockReason(d, group, roots);
+  if (blocked !== undefined) {
+    return { key: group.path, label, action: "skip", reason: blocked };
+  }
   const state = mcpGroupState(d, group.path);
   return {
     key: group.path,
-    label: shortenPath(group.path, roots),
+    label,
     action:
       state === "registered"
         ? "unchanged"
@@ -320,7 +402,7 @@ const mcpTarget = defineTarget<McpDetection>({
   id: "mcp",
   title: "MCP server registration",
   scopes: ["global", "project"],
-  detect: (rt, scope) => detectMcp(rt, scope),
+  detect: (rt, scope, probe) => detectMcp(rt, scope, probe),
   plan: (d, scope, roots) => {
     if (d.groups.length === 0) {
       return {
@@ -330,7 +412,24 @@ const mcpTarget = defineTarget<McpDetection>({
       };
     }
     const children = d.groups.map((group) => mcpChild(d, group, roots));
-    const pending = children.filter((c) => c.action !== "unchanged");
+    // Every file blocked means the row's whole answer is the block: it carries
+    // the first one's reason and the entry to declare by hand.
+    const writable = d.groups.filter(
+      (group) => mcpGroupBlock(d, group.path) === undefined,
+    );
+    const block = writable.length === 0 ? firstMcpBlock(d, roots) : undefined;
+    if (block !== undefined) {
+      return {
+        action: "skip",
+        detail: block.reason,
+        reason: block.reason,
+        remedy: block.remedy,
+        children,
+      };
+    }
+    const pending = children.filter(
+      (c) => c.action !== "unchanged" && c.action !== "skip",
+    );
     return {
       action: pending.length === 0 ? "none" : "update",
       detail: `${d.groups.length} ${
@@ -356,7 +455,7 @@ const mcpTarget = defineTarget<McpDetection>({
   },
   compose: (d, chosen) =>
     composeMcp(d, chosen ? selectedGroups(d, chosen) : d.groups),
-  composeRemoval: (d) => composeMcpRemoval(d),
+  composeRemoval: (d, undoKey) => composeMcpRemoval(d, undoKey),
 });
 
 const skillsTarget = defineTarget<SkillsDetection>({
@@ -402,7 +501,12 @@ const skillsTarget = defineTarget<SkillsDetection>({
     if (owned.length === 0) {
       return { action: "none", detail: "no link to remove" };
     }
-    const dirs = [...new Set(owned.map((a) => shortenPath(a.linkPath, roots)))];
+    // Dedupe to the FOLDERS the links live in — `linkPath` itself is one path
+    // per link, so a Set over it deduped nothing and the removal preview
+    // printed an 18-path wall where the forward plan says `… → 2 folders`.
+    const dirs = [
+      ...new Set(owned.map((a) => shortenPath(dirname(a.linkPath), roots))),
+    ];
     return {
       action: "remove",
       detail: `${owned.length} ${owned.length === 1 ? "link" : "links"}`,
@@ -414,7 +518,7 @@ const skillsTarget = defineTarget<SkillsDetection>({
     };
   },
   compose: (d) => composeSkills(d),
-  composeRemoval: (d) => composeSkillsRemoval(d),
+  composeRemoval: (d, undoKey) => composeSkillsRemoval(d, undoKey),
 });
 
 /** THE table, in display order. */

package/src/capabilities/setup/types.ts

@@ -43,10 +43,46 @@ export type CompletionsState = "absent" | "installed" | "stale";
 
 /**
  * The detected state of the Terrazzo LSP extension across the VS Code-family
- * editors on this machine, probed up front by `detectLsp`: `installed` (every
- * editor whose CLI is on PATH already has it — a re-run skips), `absent` (at
- * least one detected editor is missing it, so the sideload runs for those), or
- * `unknown` (NO editor CLI was found on PATH — the step is a named skip, since
- * there is nothing to install into).
+ * editors on this machine, probed up front by `detectLsp`.
+ *
+ * An editor is FOUND by any of three probes — its CLI on PATH, its CLI inside
+ * its macOS app bundle, or its per-user configuration directory — and the
+ * state is about every editor found, whichever probe found it:
+ *
+ * - `installed`: every found editor already carries a working copy, so a
+ *   re-run skips. A BLOCKED editor (no CLI to run, or an extensions folder
+ *   this command must not write to) counts here when it is installed: the
+ *   copy really is there, and the block is only about changing it.
+ * - `absent`: at least one found editor is missing it. The sideload runs for
+ *   the ones that are missing it AND can be written to — never for a blocked
+ *   editor, whose row carries its own remedy instead.
+ * - `unknown`: NO editor was found by any of the three probes, so the step is
+ *   a named skip: there is nothing on this machine to install into.
  */
 export type LspState = "installed" | "absent" | "unknown";
+
+/**
+ * Why a write cannot happen at a path — a fact with a remedy, never an error.
+ *
+ * The two kinds are kept apart because their remedies are unrelated: a store
+ * path needs a DECLARATION in the config that produced it, and a read-only
+ * path needs permissions changed. Collapsing them to one "not writable" would
+ * print the `chmod` advice at a Nix user, which cannot work — `chmod` on the
+ * store is not the fix, and the next `nixos-rebuild` would undo it.
+ *
+ * It lives here, beside {@link LspState} and {@link McpTargetState}, because
+ * it is the same kind of thing: a setup-domain state vocabulary that the lsp
+ * detection, the mcp detection, the target table and doctor all read.
+ * `probeWritable` (`operations/writability.ts`) is what produces one.
+ */
+export type WriteBlock =
+  | {
+      readonly kind: "nix-store";
+      /** The store path the target resolves to — the evidence, and the remedy's subject. */
+      readonly resolved: string;
+    }
+  | {
+      readonly kind: "read-only";
+      /** The existing node that refused `W_OK` — the path a remedy must name. */
+      readonly path: string;
+    };

package/src/capabilities/shared/index.ts

@@ -25,6 +25,7 @@
 export {
   assertExecOk,
   checkExecOk,
+  failPragma,
   guardMissingBinary,
 } from "./assertExecOk.js";
 export type {

package/src/capabilities/sources/sources.test.ts

@@ -33,6 +33,7 @@ import {
 } from "../../kernel/runtime/paths.js";
 import {
   detectPrefixClashes,
+  harvestPrefixes,
   resolvePackageJson,
 } from "../../kernel/runtime/refs/resolve.js";
 import { createLazyStore } from "../../kernel/runtime/store.js";
@@ -333,6 +334,60 @@ describe("sources update — conflicting @prefix detection (A5)", () => {
     ]);
   });
 
+  it("ignores a prefix declaration inside a string literal", () => {
+    // The code-standards pack ships guidance ABOUT Turtle: its `cs:code`
+    // examples contain declarations, including a deliberately discouraged one.
+    // Scanning raw text reported a clash on every single update for a file that
+    // asserts no triple in that namespace at all.
+    const clashes = detectPrefixClashes([
+      { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },
+      {
+        content: [
+          "@prefix cs: <https://cs.test/#> .",
+          'cs:rule cs:code """',
+          "# Bad: do not do this",
+          "@prefix ex: <https://wrong.test/data/> .",
+          '""" .',
+        ].join("\n"),
+      },
+    ]);
+
+    expect(clashes).toEqual([]);
+  });
+
+  it("does not let a literal rebind a real prefix in the harvested map", () => {
+    // Worse than a spurious warning: last-wins meant a code sample could
+    // overwrite a real namespace, so every entity of the losing package
+    // compacted to the wrong prefix.
+    const prefixes = harvestPrefixes([
+      { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },
+      {
+        content: [
+          'cs:rule cs:code """',
+          "@prefix ex: <https://wrong.test/data/> .",
+          '""" .',
+        ].join("\n"),
+      },
+    ]);
+
+    expect(prefixes.ex).toBe("https://a.test/#");
+  });
+
+  it("still reads declarations that follow a literal in the same file", () => {
+    // Masking must not swallow the rest of the file.
+    const prefixes = harvestPrefixes([
+      {
+        content: [
+          'cs:rule cs:code """@prefix ignored: <https://no.test/> .""" .',
+          "@prefix real: <https://yes.test/#> .",
+        ].join("\n"),
+      },
+    ]);
+
+    expect(prefixes.real).toBe("https://yes.test/#");
+    expect(prefixes.ignored).toBeUndefined();
+  });
+
   it("does NOT flag harmless same-label/same-IRI redeclarations", () => {
     const clashes = detectPrefixClashes([
       { content: "@prefix ex: <https://a.test/#> .\nex:One a ex:T ." },