@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/kernel/config/paths.ts

@@ -1,39 +1,39 @@
 /**
- * XDG base-directory resolution for config, cache, and state.
+ * XDG base-directory resolution for config and state.
  *
- * Config (the global JSON) lives under `$XDG_CONFIG_HOME/pragma`; the evaluated
- * project-config cache lives under `$XDG_STATE_HOME/pragma/config-cache`. Tests
- * point these env vars at per-run temp directories (see setupXdgIsolation) so
- * they never touch the developer's real state.
+ * Every directory is namespaced by the distribution's own {@link BIN_NAME}, so a
+ * fork stores its state beside this one instead of colliding in it — the
+ * greeting that quotes the resolved path then names one program, not two. Config
+ * (the global JSON) lives under `$XDG_CONFIG_HOME/<bin>`; the evaluated
+ * project-config cache lives under `$XDG_STATE_HOME/<bin>/config-cache`. The
+ * store layer's cache root (`$XDG_CACHE_HOME/<bin>`) is resolved by
+ * `kernel/runtime/paths.ts` instead — it must stay leaf-clean for the storeless
+ * fast path. Tests point these env vars at per-run temp directories (see
+ * setupXdgIsolation) so they never touch the developer's real state.
  */
 
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { BIN_NAME } from "../../constants.js";
 
-/** `$XDG_CONFIG_HOME/pragma` (default `~/.config/pragma`). */
+/** `$XDG_CONFIG_HOME/<bin>` (default `~/.config/<bin>`). */
 export function configDir(): string {
   const base = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
-  return join(base, "pragma");
+  return join(base, BIN_NAME);
 }
 
-/** `$XDG_CACHE_HOME/pragma` (default `~/.cache/pragma`). */
-export function cacheDir(): string {
-  const base = process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
-  return join(base, "pragma");
-}
-
-/** `$XDG_STATE_HOME/pragma` (default `~/.local/state/pragma`). */
+/** `$XDG_STATE_HOME/<bin>` (default `~/.local/state/<bin>`). */
 export function stateDir(): string {
   const base = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
-  return join(base, "pragma");
+  return join(base, BIN_NAME);
 }
 
-/** The global config file: `$XDG_CONFIG_HOME/pragma/config.json`. */
+/** The global config file: `$XDG_CONFIG_HOME/<bin>/config.json`. */
 export function globalConfigPath(): string {
   return join(configDir(), "config.json");
 }
 
-/** The evaluated-project-config cache dir: `$XDG_STATE_HOME/pragma/config-cache`. */
+/** The evaluated-project-config cache dir: `$XDG_STATE_HOME/<bin>/config-cache`. */
 export function configCacheDir(): string {
   return join(stateDir(), "config-cache");
 }

package/src/kernel/config/readConfig.test.ts

@@ -10,6 +10,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { runTask } from "@canonical/task/node";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { BIN_NAME, PROGRAM_DESCRIPTION } from "../../constants.js";
 import { evaluateProjectConfig } from "./evaluateProjectConfig.js";
 import { findProjectConfig } from "./findProjectConfig.js";
 import { readGlobalConfig } from "./globalConfig.js";
@@ -58,13 +59,13 @@ describe("readConfig — layering + provenance", () => {
     expect(config.tier).toBe("core");
     expect(config.channel).toBe("experimental");
     expect(config.detail).toBe("detailed");
-    expect(config.packages).toHaveLength(3); // from defaults
+    expect(config.packs).toHaveLength(4); // from defaults
 
     expect(origins).toMatchObject({
       tier: "project",
       channel: "global",
       detail: "project", // project wins over global
-      packages: "default",
+      packs: "default",
     });
     expect(project.exists).toBe(true);
     expect(global.exists).toBe(true);
@@ -81,14 +82,46 @@ describe("readConfig — layering + provenance", () => {
     expect(project.exists).toBe(false);
   });
 
-  it("replaces packages wholesale from the project layer", async () => {
+  it("replaces packs wholesale from the project layer", async () => {
     freshXdg();
-    const dir = projectWith('export default { packages: ["@acme/only"] };');
+    const dir = projectWith('export default { packs: ["@acme/only"] };');
+
+    const { config, origins } = await readConfig(dir);
+
+    expect(config.packs).toEqual(["@acme/only"]);
+    expect(origins.packs).toBe("project");
+  });
+
+  it("accepts a layer's identity fields and gives them NO effect", async () => {
+    // Identity is read from `pragma.conf.ts` by `src/constants.ts` at module
+    // load, so a layer declaring it can only ever be silent. The validator
+    // still accepts the keys (the distribution config shares the schema), and
+    // the merged config now carries neither the value nor a provenance for it
+    // — which is what `config show` used to report and did not honour.
+    freshXdg();
+    writeGlobal('{"help":"Global help"}');
+    const dir = projectWith(
+      'export default { name: "acme", logo: ["ACME"], colophon: { markdown: "By Acme." }, issuesUrl: "https://acme.test/issues", tier: "core" };',
+    );
 
     const { config, origins } = await readConfig(dir);
 
-    expect(config.packages).toEqual(["@acme/only"]);
-    expect(origins.packages).toBe("project");
+    expect(config).not.toHaveProperty("name");
+    // `logo` is identity too: accepted by the shared schema, silent in a layer.
+    expect(config).not.toHaveProperty("logo");
+    expect(origins).not.toHaveProperty("logo");
+    expect(config).not.toHaveProperty("help");
+    expect(config).not.toHaveProperty("colophon");
+    expect(config).not.toHaveProperty("issuesUrl");
+    expect(origins).not.toHaveProperty("name");
+    // The positive control, from the SAME project file: a layerable field
+    // declared beside them IS merged and reported, so the assertions above
+    // cannot pass by the project layer having failed to load at all.
+    expect(config.tier).toBe("core");
+    expect(origins.tier).toBe("project");
+    // And the projected identity is unmoved by any of it.
+    expect(BIN_NAME).toBe("pragma");
+    expect(PROGRAM_DESCRIPTION).not.toBe("Global help");
   });
 
   it("merges the completion policy into the effective config", async () => {
@@ -106,6 +139,212 @@ describe("readConfig — layering + provenance", () => {
   });
 });
 
+describe("`detail` — a closed enum at load", () => {
+  it("a project config declaring an unknown level throws CONFIG_ERROR naming the file and the three levels", async () => {
+    freshXdg();
+    // Before the enum, `detail: "banana"` passed validation, was reported as
+    // `[project]` by `config show`, and silently rendered at `standard`.
+    const dir = projectWith('export default { detail: "banana" };');
+    const path = join(dir, "pragma.config.ts");
+
+    let caught: unknown;
+    try {
+      await evaluateProjectConfig(path);
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const message = (caught as { message: string }).message;
+    expect(message).toContain(path);
+    expect(message).toContain("detail");
+    for (const level of ["summary", "standard", "detailed"]) {
+      expect(message).toContain(level);
+    }
+  });
+
+  it("a global JSON declaring an unknown level throws the same loud error", () => {
+    freshXdg();
+    writeGlobal('{"detail": "digest"}');
+
+    let caught: unknown;
+    try {
+      readGlobalConfig();
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const message = (caught as { message: string }).message;
+    expect(message).toContain(globalConfigPath());
+    for (const level of ["summary", "standard", "detailed"]) {
+      expect(message).toContain(level);
+    }
+  });
+});
+
+describe("legacy config shapes — loud rename/removal errors", () => {
+  it("a project config declaring `packages` throws CONFIG_ERROR naming the rename", async () => {
+    freshXdg();
+    // Unknown keys are stripped by the schema, so the legacy key must be
+    // DETECTED — a silent ignore would boot the default packs while the user
+    // believes their own list is in force.
+    const dir = projectWith('export default { packages: ["@acme/only"] };');
+    const path = join(dir, "pragma.config.ts");
+
+    let caught: unknown;
+    try {
+      await evaluateProjectConfig(path);
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    expect((caught as { message: string }).message).toContain(
+      `Invalid config in ${path}: the "packages" field was renamed to "packs". The entry shape is unchanged.`,
+    );
+    // The recovery carries the path; the message drops the instruction.
+    expect(
+      (caught as { recovery?: { message: string } }).recovery?.message,
+    ).toBe(`In ${path}, rename "packages:" to "packs".`);
+  });
+
+  it("a legacy global JSON declaring `packages` throws the same rename error", () => {
+    freshXdg();
+    writeGlobal('{"packages": []}');
+
+    let caught: unknown;
+    try {
+      readGlobalConfig();
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    expect((caught as { message: string }).message).toContain(
+      'the "packages" field was renamed to "packs". The entry shape is unchanged.',
+    );
+  });
+
+  it("a removed `generators` field throws CONFIG_ERROR naming the field", async () => {
+    freshXdg();
+    // Ruled dead (L-OPEN-1): `resolveSources` never read it, `create` resolves
+    // its generators statically, and its only consumers were the merge and
+    // `config show`'s name display. A config still declaring it must fail
+    // naming the file — the schema's unknown-key stripping would otherwise
+    // swallow the deletion in silence.
+    const dir = projectWith(
+      'export default { generators: [{ name: "@acme/gen", source: "npm:@acme/gen@^1.0.0" }] };',
+    );
+    const path = join(dir, "pragma.config.ts");
+
+    let caught: unknown;
+    try {
+      await evaluateProjectConfig(path);
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const message = (caught as { message: string }).message;
+    expect(message).toContain(path);
+    expect(message).toContain('"generators"');
+    expect(message).toContain("removed");
+    expect(
+      (caught as { recovery?: { message: string } }).recovery?.message,
+    ).toBe(`In ${path}, delete the "generators" field.`);
+  });
+
+  it("a global JSON still declaring generators throws the same removal error", () => {
+    freshXdg();
+    writeGlobal('{"generators": []}');
+
+    let caught: unknown;
+    try {
+      readGlobalConfig();
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    expect((caught as { message: string }).message).toContain('"generators"');
+  });
+
+  it("a removed `completion.caseSensitive` throws CONFIG_ERROR naming the field", async () => {
+    freshXdg();
+    // The field was validated and read by NOTHING. Removing it silently would
+    // leave a config author believing case-sensitivity is in force; the schema
+    // strips unknown keys, so the removal must be DETECTED before validation.
+    const dir = projectWith(
+      "export default { completion: { minChars: 3, caseSensitive: true } };",
+    );
+    const path = join(dir, "pragma.config.ts");
+
+    let caught: unknown;
+    try {
+      await evaluateProjectConfig(path);
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    const message = (caught as { message: string }).message;
+    expect(message).toContain(path);
+    expect(message).toContain('"completion.caseSensitive"');
+    expect(message).toContain("removed");
+    expect(
+      (caught as { recovery?: { message: string } }).recovery?.message,
+    ).toBe(`In ${path}, delete "caseSensitive" from "completion".`);
+  });
+
+  it("a global JSON still setting completion.caseSensitive throws the same removal error", () => {
+    freshXdg();
+    writeGlobal('{"completion": {"caseSensitive": false}}');
+
+    let caught: unknown;
+    try {
+      readGlobalConfig();
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toMatchObject({ code: "CONFIG_ERROR" });
+    expect((caught as { message: string }).message).toContain(
+      '"completion.caseSensitive"',
+    );
+  });
+
+  it("a TOP-LEVEL `caseSensitive` key is an ordinary unknown key, not the removed field", async () => {
+    freshXdg();
+    // The detection reads exactly `completion.caseSensitive` — a stray
+    // top-level key keeps the forward-compatible unknown-key stripping.
+    const dir = projectWith(
+      "export default { caseSensitive: true, tier: 'core' };",
+    );
+    const path = join(dir, "pragma.config.ts");
+
+    await expect(evaluateProjectConfig(path)).resolves.toEqual({
+      tier: "core",
+    });
+  });
+
+  it("a `packages` key NESTED under another field does NOT trip the detection", async () => {
+    freshXdg();
+    // The rename detection is deliberately SHALLOW (top-level keys only): a
+    // `packages` key inside `prefixes` is a namespace prefix named `packages`,
+    // not the legacy field. Pin that against a future "helpful" deep check,
+    // which would false-positive here.
+    const dir = projectWith(
+      'export default { prefixes: { packages: "https://example.com/packages/" } };',
+    );
+    const path = join(dir, "pragma.config.ts");
+
+    await expect(evaluateProjectConfig(path)).resolves.toEqual({
+      prefixes: { packages: "https://example.com/packages/" },
+    });
+  });
+});
+
 describe("global config — corrupt-file recovery", () => {
   /** Backup siblings the recovery created next to the config file. */
   function corruptBackups(): string[] {
@@ -225,7 +464,7 @@ describe("evaluateProjectConfig — mtime+VERSION cache", () => {
     freshXdg();
     // A malformed project config: references an undefined symbol → the module
     // throws at evaluation. Left unwrapped this collapsed to INTERNAL_ERROR
-    // ("please report this issue") on EVERY command that reads config.
+    // ("report this issue") on EVERY command that reads config.
     const dir = projectWith("export default { tier: definitelyNotDefined };");
     const path = join(dir, "pragma.config.ts");
 

package/src/kernel/config/readConfig.ts

@@ -3,7 +3,7 @@
  *
  * Layer order, least to most specific: the built-in {@link defaults}, the
  * global XDG JSON, and the nearest evaluated `pragma.config.ts`. Merging is
- * per field — a more specific layer wins wholesale (so `packages` *replaces*,
+ * per field — a more specific layer wins wholesale (so `packs` *replaces*,
  * preserving the "project pins exactly" semantics) — and each field records
  * the layer that supplied it. Async because the project layer is evaluated
  * (and content-hash cached).
@@ -37,7 +37,7 @@ export async function readConfig(
   const project: RawConfig = projectPath
     ? await evaluateProjectConfig(projectPath)
     : {};
-  const defaultValues = defaults as RawConfig;
+  const defaultValues = defaults;
 
   const pick = <K extends keyof RawConfig>(
     field: K,
@@ -51,13 +51,15 @@ export async function readConfig(
     return { value: defaultValues[field], origin: "default" };
   };
 
+  // `name`/`help`/`logo`/`colophon`/`issuesUrl` are DELIBERATELY not picked: identity
+  // is read from `pragma.conf.ts` statically (`src/constants.ts`), so merging a
+  // layer's value here would report a provenance nothing honours.
   const tier = pick("tier");
   const channel = pick("channel");
   const detail = pick("detail");
-  const packages = pick("packages");
+  const packs = pick("packs");
   const stories = pick("stories");
   const prefixes = pick("prefixes");
-  const prompts = pick("prompts");
   // `completion` is read at `setup completions` emit time (not on any fast
   // path) and carries no `config show` provenance, so it merges into the
   // effective config but is deliberately absent from ConfigOrigins.
@@ -67,10 +69,9 @@ export async function readConfig(
     channel: (channel.value ?? defaults.channel) as Channel,
     ...(tier.value !== undefined ? { tier: tier.value } : {}),
     ...(detail.value !== undefined ? { detail: detail.value } : {}),
-    ...(packages.value !== undefined ? { packages: packages.value } : {}),
+    ...(packs.value !== undefined ? { packs: packs.value } : {}),
     ...(stories.value !== undefined ? { stories: stories.value } : {}),
     ...(prefixes.value !== undefined ? { prefixes: prefixes.value } : {}),
-    ...(prompts.value !== undefined ? { prompts: prompts.value } : {}),
     ...(completion.value !== undefined ? { completion: completion.value } : {}),
   };
 
@@ -80,10 +81,9 @@ export async function readConfig(
       tier: tier.origin,
       channel: channel.origin,
       detail: detail.origin,
-      packages: packages.origin,
+      packs: packs.origin,
       stories: stories.origin,
       prefixes: prefixes.origin,
-      prompts: prompts.origin,
     },
     global: { path: global.path, exists: global.exists },
     project: {

package/src/kernel/config/schema.test.ts

@@ -0,0 +1,50 @@
+/**
+ * The published configuration reference agrees with the validator a config
+ * actually hits.
+ *
+ * Two independently produced artifacts: `docs/reference/config.md` is rendered
+ * from an exhaustive `Record<keyof RawConfig, …>` (so `tsc` pins its row set to
+ * the TYPE), while `rawConfigSchema` is hand-written zod. `parseRawConfig`
+ * casts its result `as RawConfig`, so nothing else compares the two — a field
+ * the type declares and zod strips, or one zod accepts and the page never
+ * mentions, would be invisible.
+ *
+ * The page is parsed exactly as a reader would read it: the `Field` column of
+ * its `## Fields` table. Zod lives here already, so no new import crosses a
+ * boundary.
+ */
+
+import { describe, expect, it } from "vitest";
+import { emitReference } from "../spec/emitReference.js";
+import { rawConfigSchema } from "./schema.js";
+
+/** The `field` cells of the generated page's Fields table, in page order. */
+function readDocumentedFields(): string[] {
+  const page = emitReference([]).get("config.md") ?? "";
+  return [...page.matchAll(/^\| `([a-zA-Z]+)` \| /gm)].map((row) => row.at(1));
+}
+
+describe("the configuration reference agrees with the validator", () => {
+  it("documents exactly the fields the validator accepts", () => {
+    expect(readDocumentedFields().sort()).toEqual(
+      Object.keys(rawConfigSchema.shape).sort(),
+    );
+  });
+
+  it("marks a field optional iff the validator lets a layer omit it", () => {
+    // Every layer field is optional — a layer declares only what it overrides,
+    // which is what makes per-field provenance possible. Stated as a derived
+    // correspondence rather than a constant so a required field added later
+    // fails here instead of quietly contradicting the page.
+    const page = emitReference([]).get("config.md") ?? "";
+    for (const [field, schema] of Object.entries(rawConfigSchema.shape)) {
+      const row = page
+        .split("\n")
+        .find((line) => line.startsWith(`| \`${field}\` |`));
+      expect(row, `no row for \`${field}\``).toBeDefined();
+      expect(row?.includes("(optional)"), `\`${field}\` optionality`).toBe(
+        schema.safeParse(undefined).success,
+      );
+    }
+  });
+});

package/src/kernel/config/schema.ts

@@ -6,32 +6,81 @@
  * path, which are storeless and config-free. Validates the raw shape a global
  * JSON file or an evaluated `pragma.config.ts` declares; unknown keys are
  * stripped for forward compatibility, and only present keys survive so layer
- * merging keeps honest per-field provenance.
+ * merging keeps honest per-field provenance. Legacy shapes are NOT left to the
+ * unknown-key stripping: each is detected before validation and rejected with
+ * a loud CONFIG_ERROR naming the file and the fix, so an old config fails
+ * telling the user exactly what to change instead of silently ignoring the
+ * field. Three today: the `packages` key (renamed to `packs`), and the removed
+ * `completion.caseSensitive` and `generators` fields (each validated and read
+ * by nothing).
  */
 
 import { z } from "zod";
-import { PragmaError } from "../error/PragmaError.js";
-import { CHANNELS, type RawConfig } from "./types.js";
+import { PragmaError } from "../error/index.js";
+import { CHANNELS, DETAIL_LEVELS, type RawConfig } from "./types.js";
 
-const packageEntrySchema = z.union([
+const packDeclarationSchema = z.union([
   z.string().min(1),
-  z.object({ name: z.string().min(1), source: z.string().optional() }),
+  z.object({
+    name: z.string().min(1),
+    source: z.string().optional(),
+    // Opaque here: the pack grammar is validated by `parsePackDefinition` at
+    // dispatch, not by the config layer. Without this key the object arm would
+    // STRIP declared stories silently (unknown keys are dropped for forward
+    // compatibility), so a pack's stories would vanish with no error.
+    stories: z.array(z.unknown()).optional(),
+  }),
 ]);
 
 const completionSchema = z.object({
   minChars: z.number().int().min(0).optional(),
-  caseSensitive: z.boolean().optional(),
   families: z.record(z.string(), z.boolean()).optional(),
 });
 
-const rawConfigSchema = z.object({
+/**
+ * The `completion` object a raw layer declares, when it declares one — read
+ * WITHOUT validation, for the removed-field detection that must run before
+ * the schema's unknown-key stripping could hide the key.
+ */
+function declaredCompletion(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { completion } = value as { completion?: unknown };
+  return typeof completion === "object" && completion !== null
+    ? (completion as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * The validator every config layer passes through. EXPORTED for
+ * `schema.test.ts`, which compares its field set and each field's optionality
+ * against the generated `docs/reference/config.md` — the two are produced
+ * independently (the page from `keyof RawConfig`, this from hand-written zod)
+ * and `parseRawConfig`'s `as RawConfig` cast means `tsc` cannot catch them
+ * drifting apart.
+ */
+export const rawConfigSchema = z.object({
+  name: z.string().min(1).optional(),
+  help: z.string().min(1).optional(),
+  // Identity, like `name`/`help`: the wordmark root `--help` opens with.
+  logo: z.array(z.string()).optional(),
+  // Declared toolchain content: the `colophon` verb renders whatever the
+  // distribution declares here (markdown body + optional condensed summary).
+  colophon: z
+    .object({
+      markdown: z.string().min(1),
+      summary: z.string().min(1).optional(),
+    })
+    .optional(),
+  issuesUrl: z.string().url().optional(),
   tier: z.string().optional(),
   channel: z.enum(CHANNELS).optional(),
-  detail: z.string().optional(),
-  packages: z.array(packageEntrySchema).optional(),
+  // Closed over the documented ladder, like `channel`: a level the renderer
+  // would silently degrade to `standard` is a config error naming the file and
+  // the three valid values, not a value `config show` reports as honoured.
+  detail: z.enum(DETAIL_LEVELS).optional(),
+  packs: z.array(packDeclarationSchema).optional(),
   stories: z.array(z.unknown()).optional(),
   prefixes: z.record(z.string(), z.string()).optional(),
-  prompts: z.record(z.string(), z.unknown()).optional(),
   completion: completionSchema.optional(),
 });
 
@@ -41,9 +90,49 @@ const rawConfigSchema = z.object({
  * @param value - The parsed JSON or evaluated module default.
  * @param source - The file path, used in error messages.
  * @returns The validated layer values (only the keys actually present).
- * @throws PragmaError with code `CONFIG_ERROR` on an invalid shape.
+ * @throws PragmaError with code `CONFIG_ERROR` on an invalid shape, when the
+ *   value declares the legacy `packages` key (renamed to `packs`), or when it
+ *   still sets the removed `generators` or `completion.caseSensitive` fields.
  */
 export function parseRawConfig(value: unknown, source: string): RawConfig {
+  // Rename detection must precede validation: unknown keys are stripped, so a
+  // legacy `packages` field would otherwise vanish silently.
+  if (typeof value === "object" && value !== null && "packages" in value) {
+    throw PragmaError.configError(
+      `Invalid config in ${source}: the "packages" field was renamed to "packs". The entry shape is unchanged.`,
+      {
+        recovery: {
+          message: `In ${source}, rename "packages:" to "packs".`,
+        },
+      },
+    );
+  }
+  // Removed-field detection, before validation for the same reason: each field
+  // was accepted and read by NOTHING, so a config still setting one gets a
+  // loud error naming the removed field, not silence. `generators` was ruled
+  // dead (L-OPEN-1): `resolveSources` never read it and the `create` verbs
+  // resolve their generators statically — declaring it only changed what
+  // `config show` printed.
+  if (typeof value === "object" && value !== null && "generators" in value) {
+    throw PragmaError.configError(
+      `Invalid config in ${source}: the "generators" field was removed — it was read by nothing. The create verbs resolve their generators statically.`,
+      {
+        recovery: {
+          message: `In ${source}, delete the "generators" field.`,
+        },
+      },
+    );
+  }
+  if ("caseSensitive" in (declaredCompletion(value) ?? {})) {
+    throw PragmaError.configError(
+      `Invalid config in ${source}: the "completion.caseSensitive" field was removed — it was read by nothing. Completion matching is declared by the grammar, not configured.`,
+      {
+        recovery: {
+          message: `In ${source}, delete "caseSensitive" from "completion".`,
+        },
+      },
+    );
+  }
   const result = rawConfigSchema.safeParse(value ?? {});
   if (!result.success) {
     const issue = result.error.issues[0];