@canonical/pragma-cli 0.33.0 → 0.34.0

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,79 @@
  * 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 { 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(),
+  // 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 +88,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];

package/src/kernel/config/types.ts

@@ -13,14 +13,47 @@ export const CHANNELS = ["normal", "experimental", "prerelease"] as const;
 /** A release channel name. */
 export type Channel = (typeof CHANNELS)[number];
 
-/** The object form of a package source declaration. */
-export interface PackageDeclaration {
+/**
+ * Progressive-disclosure levels, least to most detail. Declared HERE, beside
+ * {@link CHANNELS}, because the config validator closes `detail` over this set
+ * and this module is the one config module the storeless fast path may reach
+ * (`completion/safety.test.ts` positive-lists it; `capabilities/lazy.test.ts`
+ * pins it inert). `src/constants.ts` re-exports it for every other reader.
+ */
+export const DETAIL_LEVELS = ["summary", "standard", "detailed"] as const;
+
+/** A progressive-disclosure level. */
+export type DetailLevel = (typeof DETAIL_LEVELS)[number];
+
+/** The object form of a pack source declaration. */
+export interface PackSource {
   readonly name: string;
   readonly source?: string;
+  /**
+   * Declarative read stories this pack supplies, in the pack grammar
+   * (`kernel/packs/types.PackDefinition`). OPAQUE here on purpose — the config
+   * layer does not know that grammar; `parsePackDefinition` validates it at
+   * dispatch. Declared beside the pack so a story can move out to the package's
+   * own `stories/*.json` by deleting this field and nothing else.
+   */
+  readonly stories?: readonly unknown[];
 }
 
-/** A `packages` entry: a bare npm name or a `{ name, source }` declaration. */
-export type PackageEntry = string | PackageDeclaration;
+/** A `packs` entry: a bare npm name or a `{ name, source }` declaration. */
+export type PackDeclaration = string | PackSource;
+
+/**
+ * The toolchain colophon the distribution declares — CONTENT, not machinery.
+ * The `colophon` verb renders whatever is declared here as its first section,
+ * titled with the distribution's name; a fork tells its own story by editing
+ * its config. Both strings are Markdown BODIES with no leading H1 (the
+ * renderer supplies the heading). `summary` is the condensed `--format llm`
+ * form; omitted, the full `markdown` serves both.
+ */
+export interface ColophonDeclaration {
+  readonly markdown: string;
+  readonly summary?: string;
+}
 
 /**
  * Completion policy, read at `setup completions` emit time (never on the
@@ -31,28 +64,41 @@ export type PackageEntry = string | PackageDeclaration;
 export interface CompletionConfig {
   /** Minimum typed chars before the shell execs `__complete` (default 2). */
   readonly minChars?: number;
-  /** Match case-sensitively (default false — loose match, canonical emit). */
-  readonly caseSensitive?: boolean;
   /** Per-family opt-out: a noun mapped to `false` drops its name completion. */
   readonly families?: Readonly<Record<string, boolean>>;
 }
 
-/** The effective, resolved configuration. `channel` always has a value. */
+/**
+ * The effective, resolved configuration. `channel` always has a value.
+ *
+ * IDENTITY IS NOT HERE. `name`, `help` and `issuesUrl` are read from
+ * `pragma.conf.ts` by `src/constants.ts` at module load, because the surfaces
+ * that need them — `--help`, `__complete`, the MCP handshake, first-run
+ * onboarding — all run before or without the config layer; `colophon` is read
+ * from the same file at render time by the `colophon` verb. They stay in
+ * {@link RawConfig} (the distribution config is `satisfies RawConfig`), but
+ * merging them into the effective config only bought `config show` a
+ * `[project]` marker the kernel does not honour.
+ */
 export interface PragmaConfig {
   /** Active tier path, or absent when no tier is configured. */
   readonly tier?: string;
   /** Release channel controlling component visibility. */
   readonly channel: Channel;
   /** Default progressive-disclosure level. */
-  readonly detail?: string;
-  /** Semantic package sources; replaces (does not merge) across layers. */
-  readonly packages?: readonly PackageEntry[];
-  /** Declarative read stories compiled at boot (experimental; opaque here). */
+  readonly detail?: DetailLevel;
+  /** Semantic pack sources; replaces (does not merge) across layers. */
+  readonly packs?: readonly PackDeclaration[];
+  /** Declarative read stories, compiled at DISPATCH (opaque here). */
   readonly stories?: readonly unknown[];
-  /** Additional namespace prefixes merged over the built-in map. */
+  /**
+   * Namespace prefixes the pack is built with — they win every harvest, so a
+   * layer here decides what the store binds and what the index is keyed under.
+   * The DISTRIBUTION layer's entries additionally seed the compiled-in
+   * `DEFAULT_PREFIX_MAP`; a project layer's do not, because that map is read on
+   * the storeless fast path where no config layer exists.
+   */
   readonly prefixes?: Readonly<Record<string, string>>;
-  /** Named prompt overrides (global machine state). */
-  readonly prompts?: Readonly<Record<string, unknown>>;
   /** Completion policy (read at `setup completions` emit time). */
   readonly completion?: CompletionConfig;
 }
@@ -61,15 +107,24 @@ export interface PragmaConfig {
  * The fields a single config layer (global JSON or project TS) may declare. A
  * key is present only when that layer sets it — presence drives which layer
  * wins during the merge.
+ *
+ * WIDER than {@link PragmaConfig}: the DISTRIBUTION layer (`pragma.conf.ts`)
+ * is `satisfies RawConfig` and declares the four identity fields, which are
+ * read statically and never merged. A global or project layer declaring one is
+ * accepted by the validator and has no effect — `docs/reference/config.md`
+ * says so, and `readConfig.test.ts` pins it.
  */
 export interface RawConfig {
+  readonly name?: string;
+  readonly help?: string;
+  readonly colophon?: ColophonDeclaration;
+  readonly issuesUrl?: string;
   readonly tier?: string;
   readonly channel?: Channel;
-  readonly detail?: string;
-  readonly packages?: readonly PackageEntry[];
+  readonly detail?: DetailLevel;
+  readonly packs?: readonly PackDeclaration[];
   readonly stories?: readonly unknown[];
   readonly prefixes?: Readonly<Record<string, string>>;
-  readonly prompts?: Readonly<Record<string, unknown>>;
   readonly completion?: CompletionConfig;
 }
 
@@ -81,10 +136,9 @@ export interface ConfigOrigins {
   readonly tier: ConfigOrigin;
   readonly channel: ConfigOrigin;
   readonly detail: ConfigOrigin;
-  readonly packages: ConfigOrigin;
+  readonly packs: ConfigOrigin;
   readonly stories: ConfigOrigin;
   readonly prefixes: ConfigOrigin;
-  readonly prompts: ConfigOrigin;
 }
 
 /** A resolved config layer's file location and existence. */