@telorun/analyzer 0.72.0 → 0.74.0

package/src/release/workspace-config.ts

@@ -1,85 +1,521 @@
 /**
- * `telo-workspace.yaml` — the release anchor.
+ * `telo-workspace.yaml` — the anchor.
  *
- * Every path the release system names — a module key, a ledger entry, a
- * fragment's `modules:` — is relative to this file's directory. That is the
- * whole of its job: **its location is the anchor**, and its one field names the
- * subtrees that may hold modules, which is not derivable (a whole-tree scan
- * would read every example and every cached `.telo/manifests` copy as a released
- * module).
+ * **Its location is the anchor, and every field lives in a block scoped to what
+ * it governs.** Every path the release system names — a module key, a ledger
+ * entry, a fragment's `modules:` — is relative to this file's directory, and so
+ * is the `.telo` cache. `release:` is what `telo release` reads; `env:` is what
+ * `telo run` reads when it resolves a manifest's environment.
  *
- * The file is **optional**, and everything reading it is harmless without one.
- * `telo release` requires one. `telo run` uses its LOCATION — never `modules:`,
- * which is release scope — as the bound on the walk-up that collects `.env` /
- * `.env.local`, and with no marker reads the manifest's own directory alone, as
- * it did before this file existed; a bound is what keeps that walk out of a
- * user's home directory. Nothing else — not `check`, `publish`, `install`,
- * `upgrade`, `migrate`, `module`, and not the kernel — looks for it, so a
- * single-manifest repo, a bare `examples/` directory and a third-party module
- * checkout keep working with nothing added. Any field added later must be true
- * of the whole tree, not derivable from it, and harmless by its absence.
+ * That rule is why `modules:` sits under `release:` rather than at the top
+ * level. It is a release inventory, not an inventory of manifests: it exists so
+ * a whole-tree scan does not read every example and every cached
+ * `.telo/manifests` copy as something to version and publish, and nothing else
+ * consults it — the env walk refuses to, which is why a manifest under
+ * `examples/`, in no release subtree, still gets the full walk.
  *
- * Parsing lives here, in the browser-safe half, because the editor answers
- * "what does changing this library bump?" from the same model. Finding the file
- * on disk is the CLI's half — this side takes text.
+ * The file is **optional and every block in it is optional**. A marker whose
+ * whole content is comments is valid: it anchors the cache and bounds the env
+ * walk, which is exactly what a runner seeds one for.
+ *
+ * **The reader is lenient; the diagnostics are the strict half.** It returns
+ * everything it could read plus everything it found wrong, each anchored at a
+ * key path, because an editor wants all of them and a command wants to exit on
+ * the first. Which of them are fatal is the CALLER's policy, not the file's:
+ * `telo release` refuses on any error, while `telo run` consumes `env:` alone
+ * and prints the rest — aborting every app in a workspace over a release typo is
+ * not a trade to make silently.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers "what
+ * does changing this library bump?" from the same model. Finding the file on
+ * disk is the CLI's half — this side takes text. Gitignore matching is INJECTED
+ * (`PatternMatch`) for the same reason: the grammar belongs to the glob package,
+ * which this half does not depend on.
  */
 
 import { parseDocument } from "yaml";
+import {
+  DEFAULT_ENV_FILES,
+  DEFAULT_RELEASE_IGNORE,
+  MODULE_ENTRY_KEYS,
+  WORKSPACE_BLOCKS,
+  WORKSPACE_SCHEMA,
+  type WorkspaceKeySchema,
+} from "./workspace-schema.js";
 
 export const WORKSPACE_FILENAME = "telo-workspace.yaml";
 
+export { DEFAULT_ENV_FILES, DEFAULT_RELEASE_IGNORE };
+
+/** One `release.modules` entry. A bare string in the file normalizes to this
+ *  with no overrides. */
+export interface ModuleEntry {
+  readonly path: string;
+  readonly registry?: string;
+  readonly ignore?: readonly string[];
+}
+
+export interface ReleaseSettings {
+  readonly registry?: string;
+  readonly ignore?: readonly string[];
+  readonly modules: readonly ModuleEntry[];
+}
+
+export interface EnvSettings {
+  readonly roots?: readonly string[];
+  readonly files?: readonly string[];
+}
+
 export interface WorkspaceConfig {
-  /**
-   * Gitignore-style patterns, workspace-relative, naming the subtrees that may
-   * hold modules (`modules/*`, `apps/*`). A pattern names a place to look, never
-   * a module: what makes a directory a module is its `telo.yaml`.
-   */
-  readonly modules: readonly string[];
+  readonly release?: ReleaseSettings;
+  readonly env?: EnvSettings;
+}
+
+export type WorkspaceDiagnosticCode =
+  | "WORKSPACE_UNKNOWN_KEY"
+  | "WORKSPACE_MODULES_MOVED"
+  | "WORKSPACE_INVALID_VALUE"
+  | "WORKSPACE_ENTRY_MATCHES_NOTHING"
+  | "WORKSPACE_ENTRY_SHADOWED"
+  | "WORKSPACE_MARKER_SHADOWED";
+
+export interface WorkspaceDiagnostic {
+  readonly code: WorkspaceDiagnosticCode;
+  readonly severity: "error" | "warning";
+  readonly message: string;
+  /** Key path from the document root (`["release", "modules", 2, "registry"]`),
+   *  so a host can anchor a squiggle without re-deriving where it came from. */
+  readonly path: readonly (string | number)[];
+}
+
+export interface WorkspaceRead {
+  readonly config: WorkspaceConfig;
+  readonly diagnostics: readonly WorkspaceDiagnostic[];
 }
 
 export class WorkspaceConfigError extends Error {}
 
+const EMPTY: WorkspaceConfig = {};
+
 /**
- * Parse the marker file's text.
+ * Read the marker's text.
  *
- * Strict about its one field, because there is nothing here to be lenient with:
- * an empty or absent `modules:` names no subtree, so discovery would find no
- * module and every gate would silently pass over a whole repo.
+ * Never throws: unreadable YAML is itself a diagnostic, because the one caller
+ * that must not abort on it is the run path.
  */
-export function parseWorkspaceConfig(text: string, where: string): WorkspaceConfig {
+export function readWorkspaceConfig(text: string, where: string): WorkspaceRead {
+  const diagnostics: WorkspaceDiagnostic[] = [];
+  const report = (
+    code: WorkspaceDiagnosticCode,
+    message: string,
+    path: (string | number)[],
+    severity: "error" | "warning" = "error",
+  ): void => {
+    diagnostics.push({ code, severity, message, path });
+  };
+
   let value: unknown;
   try {
     value = parseDocument(text).toJSON();
   } catch (err) {
-    throw new WorkspaceConfigError(
+    report(
+      "WORKSPACE_INVALID_VALUE",
       `${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`,
+      [],
     );
+    return { config: EMPTY, diagnostics };
   }
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    throw new WorkspaceConfigError(`${where} must be a YAML mapping.`);
+  if (value === null || value === undefined) return { config: EMPTY, diagnostics };
+  if (typeof value !== "object" || Array.isArray(value)) {
+    report("WORKSPACE_INVALID_VALUE", `${where} must be a YAML mapping.`, []);
+    return { config: EMPTY, diagnostics };
   }
-  const record = value as Record<string, unknown>;
 
+  const record = value as Record<string, unknown>;
   for (const key of Object.keys(record)) {
-    if (key !== "modules") {
-      throw new WorkspaceConfigError(
-        `${where}: unknown field '${key}'. The workspace marker carries only 'modules:' — ` +
-          `the subtrees that may hold modules.`,
+    if (WORKSPACE_BLOCKS.includes(key)) continue;
+    if (key === "modules") {
+      report(
+        "WORKSPACE_MODULES_MOVED",
+        `${where}: 'modules' moved under 'release:'. It is release scope — where modules live, ` +
+          `for versioning and publishing — and every field of this file now sits in the block ` +
+          `that governs it. Indent this list under a 'release:' key.`,
+        ["modules"],
+      );
+      continue;
+    }
+    // A near-miss of a block name is the typo whose settings would otherwise go
+    // silently unapplied; an unrecognized block is a version skew, so the next
+    // one ships without breaking today's runs.
+    const near = nearMiss(key, WORKSPACE_BLOCKS);
+    if (near) {
+      report("WORKSPACE_UNKNOWN_KEY", `${where}: unknown block '${key}'. Did you mean '${near}'?`, [key]);
+    } else {
+      report(
+        "WORKSPACE_UNKNOWN_KEY",
+        `${where}: unknown block '${key}', which nothing reads. This telo knows ${WORKSPACE_BLOCKS.map((b) => `'${b}'`).join(" and ")}.`,
+        [key],
+        "warning",
       );
     }
   }
 
-  const modules = record.modules;
-  if (!Array.isArray(modules) || modules.some((entry) => typeof entry !== "string")) {
-    throw new WorkspaceConfigError(
-      `${where}: 'modules' must be a list of path patterns, e.g. [modules/*, apps/*].`,
+  const release = readRelease(record.release, where, report);
+  const env = readEnv(record.env, where, report);
+  return {
+    config: { ...(release ? { release } : {}), ...(env ? { env } : {}) },
+    diagnostics,
+  };
+}
+
+type Report = (
+  code: WorkspaceDiagnosticCode,
+  message: string,
+  path: (string | number)[],
+  severity?: "error" | "warning",
+) => void;
+
+function readRelease(raw: unknown, where: string, report: Report): ReleaseSettings | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    report("WORKSPACE_INVALID_VALUE", `${where}: 'release' must be a mapping.`, ["release"]);
+    return undefined;
+  }
+  const block = raw as Record<string, unknown>;
+  const read = readBlock(block, WORKSPACE_SCHEMA.release.properties, where, ["release"], report);
+  return {
+    ...(read.registry !== undefined ? { registry: read.registry as string } : {}),
+    ...(read.ignore !== undefined ? { ignore: read.ignore as readonly string[] } : {}),
+    modules: (read.modules as readonly ModuleEntry[]) ?? [],
+  };
+}
+
+/**
+ * Read one block against its declared shape.
+ *
+ * The declared `type` is what DISPATCHES, so a new key is one entry in the
+ * schema and no change here. Reading the key names from the data while
+ * hand-writing every type check beside it would leave the half nothing reads
+ * free to drift from the half that decides — with the data half being the one no
+ * test would catch.
+ */
+function readBlock(
+  block: Record<string, unknown>,
+  properties: Readonly<Record<string, WorkspaceKeySchema>>,
+  where: string,
+  at: (string | number)[],
+  report: Report,
+): Record<string, unknown> {
+  reportUnknownKeys(block, properties, where, at, report);
+  const out: Record<string, unknown> = {};
+  for (const [name, schema] of Object.entries(properties)) {
+    const value =
+      schema.type === "string"
+        ? readString(block[name], where, [...at, name], report)
+        : schema.type === "string[]"
+          ? readStringList(block[name], where, [...at, name], report)
+          : readModuleEntries(block[name], where, report);
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
+}
+
+function readModuleEntries(raw: unknown, where: string, report: Report): readonly ModuleEntry[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    report(
+      "WORKSPACE_INVALID_VALUE",
+      `${where}: 'release.modules' must be a list of path patterns, e.g. [modules/*, apps/*].`,
+      ["release", "modules"],
     );
+    return [];
   }
-  if (modules.length === 0) {
-    throw new WorkspaceConfigError(
-      `${where}: 'modules' is empty, so no directory can ever be discovered as a module. ` +
+  if (raw.length === 0) {
+    report(
+      "WORKSPACE_INVALID_VALUE",
+      `${where}: 'release.modules' is empty, so no directory can ever be discovered as a module. ` +
         `List the subtrees that hold them, e.g. [modules/*, apps/*].`,
+      ["release", "modules"],
+    );
+    return [];
+  }
+
+  const entries: ModuleEntry[] = [];
+  for (const [index, item] of raw.entries()) {
+    const at = ["release", "modules", index];
+    if (typeof item === "string") {
+      entries.push({ path: item });
+      continue;
+    }
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      report(
+        "WORKSPACE_INVALID_VALUE",
+        `${where}: 'release.modules' entry ${index} must be a pattern string, or a mapping ` +
+          `carrying 'path:' plus the keys it overrides.`,
+        at,
+      );
+      continue;
+    }
+    const entry = item as Record<string, unknown>;
+    const read = readBlock(entry, MODULE_ENTRY_KEYS, where, at, report);
+    const path = read.path as string | undefined;
+    if (path === undefined) {
+      report(
+        "WORKSPACE_INVALID_VALUE",
+        `${where}: 'release.modules' entry ${index} declares no 'path:', so it matches nothing.`,
+        at,
+      );
+      continue;
+    }
+    entries.push({
+      path,
+      ...(read.registry !== undefined ? { registry: read.registry as string } : {}),
+      ...(read.ignore !== undefined ? { ignore: read.ignore as readonly string[] } : {}),
+    });
+  }
+  return entries;
+}
+
+function readEnv(raw: unknown, where: string, report: Report): EnvSettings | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    report("WORKSPACE_INVALID_VALUE", `${where}: 'env' must be a mapping.`, ["env"]);
+    return undefined;
+  }
+  const block = raw as Record<string, unknown>;
+  const read = readBlock(block, WORKSPACE_SCHEMA.env.properties, where, ["env"], report);
+  const roots = read.roots as readonly string[] | undefined;
+  const files = read.files as readonly string[] | undefined;
+  if (files) {
+    for (const [index, name] of files.entries()) {
+      // A path would let one entry reach outside the bound `roots:` exists to
+      // state, so the list is filenames and the refusal is structural.
+      if (name.includes("/") || name.includes("\\") || name.includes("*")) {
+        report(
+          "WORKSPACE_INVALID_VALUE",
+          `${where}: 'env.files' entry '${name}' is a path or a glob. It names a file collected in ` +
+            `each directory the walk visits, so it must be a bare filename — the walk's reach is ` +
+            `'env.roots'.`,
+          ["env", "files", index],
+        );
+      }
+    }
+  }
+  return {
+    ...(roots !== undefined ? { roots } : {}),
+    ...(files !== undefined ? { files } : {}),
+  };
+}
+
+function reportUnknownKeys(
+  block: Record<string, unknown>,
+  known: Readonly<Record<string, unknown>>,
+  where: string,
+  at: (string | number)[],
+  report: Report,
+): void {
+  const names = Object.keys(known);
+  for (const key of Object.keys(block)) {
+    if (names.includes(key)) continue;
+    const near = nearMiss(key, names);
+    report(
+      "WORKSPACE_UNKNOWN_KEY",
+      `${where}: unknown key '${[...at, key].join(".")}'.` +
+        (near ? ` Did you mean '${near}'?` : ` Known keys: ${names.map((n) => `'${n}'`).join(", ")}.`),
+      [...at, key],
+    );
+  }
+}
+
+function readString(
+  raw: unknown,
+  where: string,
+  at: (string | number)[],
+  report: Report,
+): string | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (typeof raw !== "string") {
+    report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' must be a string.`, at);
+    return undefined;
+  }
+  if (raw === "") {
+    // Reported rather than read as an absence: an empty value would fall
+    // through to the next rung of the cascade and publish somewhere the author
+    // did not name, which is the one thing a declared destination must not do.
+    report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' is empty.`, at);
+    return undefined;
+  }
+  return raw;
+}
+
+function readStringList(
+  raw: unknown,
+  where: string,
+  at: (string | number)[],
+  report: Report,
+): readonly string[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (!Array.isArray(raw)) {
+    report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' must be a list of strings.`, at);
+    return undefined;
+  }
+  const out: string[] = [];
+  for (const [index, item] of raw.entries()) {
+    if (typeof item !== "string") {
+      report("WORKSPACE_INVALID_VALUE", `${where}: '${at.join(".")}' entry ${index} must be a string.`, [
+        ...at,
+        index,
+      ]);
+      continue;
+    }
+    out.push(item);
+  }
+  return out;
+}
+
+/** One edit apart, case-insensitively — enough to separate a typo from a key
+ *  this reader is simply too old to know. */
+function nearMiss(key: string, known: readonly string[]): string | undefined {
+  const lower = key.toLowerCase();
+  return known.find((name) => name !== key && editDistanceAtMostOne(lower, name.toLowerCase()));
+}
+
+function editDistanceAtMostOne(a: string, b: string): boolean {
+  if (a === b) return true;
+  if (Math.abs(a.length - b.length) > 1) return false;
+  let i = 0;
+  let j = 0;
+  let edits = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      i++;
+      j++;
+      continue;
+    }
+    if (++edits > 1) return false;
+    if (a.length > b.length) i++;
+    else if (a.length < b.length) j++;
+    else {
+      i++;
+      j++;
+    }
+  }
+  return edits + (a.length - i) + (b.length - j) <= 1;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostics as a caller's policy
+// ---------------------------------------------------------------------------
+
+/** The diagnostics anchored inside one top-level block, plus the ones anchored
+ *  at the document itself (unreadable YAML, a non-mapping root) — those are
+ *  every block's problem. */
+export function diagnosticsFor(
+  diagnostics: readonly WorkspaceDiagnostic[],
+  block: string,
+): readonly WorkspaceDiagnostic[] {
+  return diagnostics.filter((d) => d.path.length === 0 || d.path[0] === block);
+}
+
+export function hasError(diagnostics: readonly WorkspaceDiagnostic[]): boolean {
+  return diagnostics.some((d) => d.severity === "error");
+}
+
+/**
+ * The release settings, or a throw naming what is missing.
+ *
+ * `telo release` is the one caller for which any error is fatal, and for which
+ * an absent block is itself one: a marker with no `release:` anchors a cache and
+ * declares no release scope, which is exactly the state a runner's seeded marker
+ * is in.
+ */
+export function requireReleaseSettings(
+  read: WorkspaceRead,
+  where: string,
+): ReleaseSettings {
+  const first = read.diagnostics.find((d) => d.severity === "error");
+  if (first) throw new WorkspaceConfigError(first.message);
+  if (!read.config.release || read.config.release.modules.length === 0) {
+    throw new WorkspaceConfigError(
+      `${where} declares no 'release.modules', so no directory can be discovered as a module. ` +
+        `List the subtrees that hold them:\n\n  release:\n    modules:\n      - modules/*\n      - apps/*\n`,
     );
   }
-  return { modules: modules as string[] };
+  return read.config.release;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Gitignore-style matching over one authored list.
+ *
+ * Injected rather than imported: the grammar is the glob package's, and this
+ * half is browser-safe. Returns the index of the LAST pattern matching `path`,
+ * or `-1` — which is what makes a decision attributable to the entry that made
+ * it (the `buildImportUpgrades` environment precedent).
+ */
+export type PatternMatch = (path: string, patterns: readonly string[]) => number;
+
+export interface ModuleSettings {
+  /** Index into `release.modules` of the entry that decided this module. */
+  readonly entry: number;
+  readonly registry?: string;
+  readonly ignore: readonly string[];
+}
+
+/**
+ * Which entry claims `key`, and what it therefore settles.
+ *
+ * **The last matching entry supplies them** — the rule the list already has,
+ * since it is one gitignore-style list evaluated last-match-wins. A negation
+ * entry is an exclusion and therefore supplies nothing: a module the last match
+ * excludes is not a module of this workspace at all, which is why this returns
+ * `undefined` rather than a settings object for it.
+ *
+ * The cascade is key-wise and each key's value replaces whole, so an entry
+ * naming only `registry:` keeps the block's `ignore:`.
+ */
+export function settingsForModule(
+  release: ReleaseSettings,
+  key: string,
+  match: PatternMatch,
+): ModuleSettings | undefined {
+  const index = decidingIndex(key, release.modules.map((entry) => entry.path), match);
+  if (index < 0) return undefined;
+  const entry = release.modules[index]!;
+  return {
+    entry: index,
+    ...(entry.registry ?? release.registry
+      ? { registry: entry.registry ?? release.registry }
+      : {}),
+    ignore: entry.ignore ?? release.ignore ?? DEFAULT_RELEASE_IGNORE,
+  };
+}
+
+/** Whether `path` is matched by an authored pattern list, negations honoured.
+ *  `env.roots` and a resolved `ignore` list are both read through this. */
+export function matchesPatterns(
+  path: string,
+  patterns: readonly string[],
+  match: PatternMatch,
+): boolean {
+  return decidingIndex(path, patterns, match) >= 0;
+}
+
+/**
+ * The index of the entry that CLAIMS `path`, or `-1`.
+ *
+ * The one place last-match-wins and the negation reading live: every pattern
+ * list in this file rests on that rule, and two derivations of it would be two
+ * answers to what a marker means.
+ */
+function decidingIndex(
+  path: string,
+  patterns: readonly string[],
+  match: PatternMatch,
+): number {
+  const index = match(path, patterns);
+  return index >= 0 && patterns[index]!.startsWith("!") ? -1 : index;
 }

package/src/release/workspace-schema.ts

@@ -0,0 +1,99 @@
+/**
+ * The shape of `telo-workspace.yaml`, declared as data.
+ *
+ * One declaration read by two consumers — the strict half that reports what a
+ * marker got wrong, and the editor's completion list. Two hand-maintained key
+ * lists drift, and the drift is silent in the worst direction: an editor
+ * offering a key the checker rejects.
+ *
+ * Written as JSON Schema because that is what the shape *is*, and because the
+ * `description` a completion item shows and the type a diagnostic names are the
+ * same two facts a schema already carries. It is not compiled by AJV — the
+ * strict half walks it, which is what lets a wrong value say `'registry' must be
+ * the publish destination base, as a string` instead of a keyword trace.
+ */
+
+export interface WorkspaceKeySchema {
+  readonly type: "string" | "string[]" | "entry[]";
+  readonly description: string;
+  /** Values worth offering at this key when nothing better is known. */
+  readonly examples?: readonly string[];
+}
+
+export interface WorkspaceBlockSchema {
+  readonly description: string;
+  readonly properties: Readonly<Record<string, WorkspaceKeySchema>>;
+}
+
+/**
+ * Every block, and every key in it, is optional — a marker whose whole content
+ * is comments is valid, and is what a runner seeds for the cache anchor alone.
+ */
+export const WORKSPACE_SCHEMA: Readonly<Record<string, WorkspaceBlockSchema>> = {
+  release: {
+    description: "How `telo release` behaves: where modules are, where they publish, and which of their paths are not release-relevant.",
+    properties: {
+      registry: {
+        type: "string",
+        description:
+          "Publish destination base. A module's ref is `<registry>/<its own directory name>`. Omitted: --registry, then TELO_OCI_REGISTRY, then the base each module's own ledger entry recorded.",
+        examples: ["oci://ghcr.io/telorun"],
+      },
+      ignore: {
+        type: "string[]",
+        description:
+          "Paths under a module whose changes are not release-relevant, so no changelog fragment is asked for. Module-relative, gitignore-style. Declaring it replaces the built-in default; [] ignores nothing.",
+        examples: ["**/tests/**", "**/docs/**", "**/plans/**", "**/README.md", "**/CHANGELOG.md"],
+      },
+      modules: {
+        type: "entry[]",
+        description:
+          "The subtrees that may hold modules — a place to look, never a module: what makes a directory a module is its telo.yaml. Workspace-relative, gitignore-style, last match wins. A bare string is an entry with no overrides.",
+      },
+    },
+  },
+  env: {
+    description: "How `telo run` resolves a manifest's environment.",
+    properties: {
+      roots: {
+        type: "string[]",
+        description:
+          "How far up the .env walk may climb. Workspace-relative, gitignore-style, matched against each ancestor directory; the nearest match stops the walk. Omitted: the walk stops at this file.",
+      },
+      files: {
+        type: "string[]",
+        description:
+          "Which files are collected in each directory, later winning within one directory. Filenames only — a / or a glob is an error. Declaring it replaces the default; [] collects none.",
+        examples: [".env", ".env.local"],
+      },
+    },
+  },
+};
+
+/** Keys a `release.modules` entry may carry in its object form. `path` is the
+ *  pattern; the rest override the block's own keys, key-wise. */
+export const MODULE_ENTRY_KEYS: Readonly<Record<string, WorkspaceKeySchema>> = {
+  path: {
+    type: "string",
+    description: "The gitignore-style pattern this entry matches modules with.",
+  },
+  registry: WORKSPACE_SCHEMA.release.properties.registry,
+  ignore: WORKSPACE_SCHEMA.release.properties.ignore,
+};
+
+export const WORKSPACE_BLOCKS: readonly string[] = Object.keys(WORKSPACE_SCHEMA);
+
+/** Built-in when `release.ignore` is absent. Every pattern carries `**\/` — the
+ *  anchoring at a module root is the defect this replaced, so anchoring some and
+ *  not others would reproduce it partially. */
+export const DEFAULT_RELEASE_IGNORE: readonly string[] = [
+  "**/tests/**",
+  "**/docs/**",
+  "**/plans/**",
+  "**/README.md",
+  "**/CHANGELOG.md",
+];
+
+/** Built-in when `env.files` is absent — the pair the walk hardcoded before it
+ *  was authorable, in the order it applied them. */
+export const DEFAULT_ENV_FILES: readonly string[] = [".env", ".env.local"];