@metaobjectsdev/codegen-ts 0.23.1 → 0.24.0

package/src/generators/trace-helper-file.ts

@@ -24,8 +24,10 @@ import {
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_RESPONSE_REF,
   TEMPLATE_ATTR_FORMAT,
+  RESPONSE_FORMAT_XML,
   TEMPLATE_ATTR_TEXT_REF,
 } from "@metaobjectsdev/metadata";
+import { responseFormatOf } from "../templates/find-inbound.js";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import {
   type EmittedFile,
@@ -113,13 +115,19 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
         ? `{ ...input, callType: ${JSON.stringify(callTypeValue)}, status, errorDetail }`
         : `{ ...input, status, errorDetail }`;
 
-      // Derive the parse format from the prompt's @format attr.
-      // "xml" → Format.XML; absent or any other value → Format.JSON.
-      // ADR-0039: resolving — a prompt may inherit @format via extends.
-      const promptFormat = prompt.attr(TEMPLATE_ATTR_FORMAT);
-      const formatLiteral = typeof promptFormat === "string" && promptFormat.toLowerCase() === "xml"
-        ? "Format.XML"
-        : "Format.JSON";
+      // ADR-0053: the REPLY's syntax is @responseFormat, not @format.
+      //
+      // This site used to read @format twice — once as the reply's syntax and once
+      // as the prompt body's — under a comment calling them "two intentionally
+      // different shapes". They are two different FACTS, not two shapes of one:
+      // a plain-text prompt can elicit an XML reply, and the shipped docs-site
+      // fixture is exactly that. Reading @format here mis-parsed every prompt whose
+      // body format differed from its reply's.
+      //
+      // The same rule the output-parser / extractor / response-format-fragment
+      // generators use — all four now go through responseFormatOf().
+      const formatLiteral =
+        responseFormatOf(prompt) === RESPONSE_FORMAT_XML ? "Format.XML" : "Format.JSON";
 
       // Collect VO names for interface emission (dedupe via batch emitter).
       // Both refs are guaranteed strings by the guards above. ADR-0042: a bare
@@ -137,9 +145,11 @@ export const traceHelperFile = function traceHelperFile(opts?: TraceHelperOpts):
       // ADR-0039: resolving — a prompt may inherit @textRef via extends.
       const textRef = prompt.attr(TEMPLATE_ATTR_TEXT_REF);
       const renderable = typeof textRef === "string";
-      // Same @format attr, two intentionally different shapes: extract() takes the
-      // Format enum (formatLiteral, above → Format.XML/Format.JSON), render() takes the
-      // raw format string (renderFormat, here → e.g. "json"/"xml", default "text").
+      // render() takes the raw format string of the prompt BODY — @format, which is
+      // genuinely this attribute's job. Distinct from formatLiteral above, which is
+      // the REPLY's syntax and comes from @responseFormat (ADR-0053).
+      // ADR-0039: resolving — a prompt may inherit @format via extends.
+      const promptFormat = prompt.attr(TEMPLATE_ATTR_FORMAT);
       const renderFormat = typeof promptFormat === "string" ? promptFormat : "text";
 
       // Build the import block — all imports MUST stay at the top of the emitted file.

package/src/index.ts

@@ -37,7 +37,7 @@ export {
 } from "./generator-registry.js";
 export type { GeneratorRegistryEntry, GeneratorTier } from "./generator-registry.js";
 
-export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface, VerifyConfig } from "./metaobjects-config.js";
+export type { MetaobjectsGenConfig, NormalizedMetaobjectsGenConfig, ResolvedGenConfig, Dialect, ExtStyle, ColumnNamingStrategy, MetaDataTypeProvider, GeneratorSpec, DocsConfig, ResolvedDocsConfig, DocsSurface, ApiSurface } from "./metaobjects-config.js";
 export { defineConfig, normalizeConfig, resolveGenerators, resolveDocsConfig } from "./metaobjects-config.js";
 export { apiLabel } from "./generators/api-label.js";
 
@@ -193,3 +193,49 @@ export type {
 export { buildEntityDocData } from "./generators/docs-data-builder.js";
 export type { TemplateDocData, TemplateOutputPart } from "./generators/template-doc-data.js";
 export { buildTemplateDocData } from "./generators/template-doc-builder.js";
+
+// FR-038 — requirement-derived test stubs.
+//
+// Both the factory AND its primitives are exported deliberately. Scaffold-and-own
+// means the application owns its generator file, but that is only a real escape
+// hatch if it can compose one from parts — otherwise an app needing one different
+// behaviour must reimplement the requirement walk, and reimplementing it badly is
+// worse than the bug report this is meant to avoid.
+export { requirementTests } from "./generators/requirement-tests.js";
+export { requirementsFile } from "./generators/requirements-file.js";
+export type { RequirementRow } from "./generators/requirements-view.js";
+export type {
+  RequirementTestsOpts,
+  RequirementTestRenderer,
+} from "./generators/requirement-tests.js";
+export {
+  walkRequirements,
+  groupByConcern,
+  concernOf,
+  NO_CONCERN,
+} from "./requirement-walk.js";
+export type {
+  RequirementView,
+  ResolvedClaim,
+  WalkedRequirement,
+} from "./requirement-walk.js";
+export { renderRequirementTest } from "./templates/requirement-test.js";
+export type { RequirementTestArgs } from "./templates/requirement-test.js";
+
+// FR-038 §8 — deletion integrity. Pure decision logic: which no-longer-generated
+// files may be removed, and which were hand-edited and must be refused instead.
+// `OrphanPolicy` is the Generator field an app sets to opt in; `sweepOrphans` is
+// the filesystem binding, exported so an app composing its own generator can
+// reconcile the same way the runner does instead of hand-rolling the walk.
+export { reconcileOrphans, refusedOrphanMessage } from "./reconcile-orphans.js";
+export type {
+  OrphanDecision,
+  ReconcileOrphansArgs,
+  OrphanPolicy,
+} from "./reconcile-orphans.js";
+export { sweepOrphans } from "./orphan-sweep.js";
+export type {
+  OrphanJob,
+  SweepOrphansArgs,
+  SweepOrphansResult,
+} from "./orphan-sweep.js";

package/src/metaobjects-config.ts

@@ -154,30 +154,21 @@ export interface MetaobjectsGenConfig extends Omit<ResolvedGenConfig, "dbImport"
    * loader. Composed AFTER the default core+forge bundle.
    */
   providers?: readonly MetaDataTypeProvider[];
-  /** `meta verify` settings. Nothing here affects codegen. */
-  verify?: VerifyConfig;
-}
-
-/** `meta verify` settings. */
-export interface VerifyConfig {
   /**
-   * Glob patterns naming this project's test files, for the `@verifiedBy` check.
-   *
-   * **What counts as a test file is the project's call.** The built-in patterns cover
-   * the conventions this repo ports to (jest/vitest/bun, JUnit, Maven Failsafe `*IT`,
-   * xUnit/NUnit, pytest, Kotlin) and are a CONVENIENCE, not an authority — a list of
-   * guesses about someone else's repository will always be incomplete, and when it is,
-   * a requirement naming a real test reads as a broken claim. Anything declared here is
-   * added to the built-ins.
+   * MetaObjects-shipped library packages this project loads alongside its own metadata —
+   * `["ai"]` makes `extends: "metaobjects::ai::LlmCallBase"` resolve.
    *
-   * Matched against forward-slash paths relative to the project root: `**` spans
-   * separators, `*` does not.
+   * Sits beside `providers` because it answers the same shape of question: what does this
+   * project's model need in scope beyond the files it declares. Opt-in, because a library
+   * registers real top-level nodes and a project that never references one should not find
+   * them in its model, its generated output or its docs.
    *
-   * ```ts
-   * verify: { testFiles: ["**\/*IT.kt", "**\/*.feature"] }
-   * ```
+   * Threaded to `loadMemory` by every CLI command that loads metadata. Before it existed,
+   * `librarySources` was reachable only from `MetaDataLoader.fromDirectory` — which the
+   * CLI does not use — so a generator that consumes a library was registered FOR the CLI
+   * while its input was unreachable THROUGH it (#333).
    */
-  testFiles?: string[];
+  libraries?: readonly string[];
 }
 
 /** MetaobjectsGenConfig after applying defaults. All fields required.
@@ -201,7 +192,7 @@ export interface NormalizedMetaobjectsGenConfig
   targets: Record<string, ResolvedTarget>;
 }
 
-export type DocsSurface = "model" | "api";
+export type DocsSurface = "model" | "api" | "requirements";
 
 export interface ApiSurface {
   lang: string;
@@ -240,7 +231,11 @@ export function resolveDocsConfig(
     outDir: cli.outDir ?? block?.outDir ?? "./docs",
     layout: cli.layout ?? block?.layout ?? fallbackLayout,
     baseUrl: cli.baseUrl ?? block?.baseUrl ?? "",
-    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api"],
+    // `requirements` defaults ON. Safe ONLY because requirementsFile() emits ZERO
+    // files for a project declaring no `requirement.*` node — not an empty page. A
+    // project without a ledger sees byte-identical output to before the surface
+    // existed; see requirements-file.ts.
+    surfaces: cli.surfaces ?? block?.surfaces ?? ["model", "api", "requirements"],
     apiSurfaces: cli.apiSurfaces ?? block?.apiSurfaces ?? [{ lang: "ts", subDir: "api" }],
   };
 }

package/src/orphan-sweep.ts

@@ -0,0 +1,178 @@
+// FR-038 §8 — bind the orphan decision to the filesystem.
+//
+// reconcile-orphans.ts is deliberately pure: it answers "remove, refuse, or
+// already gone?" from readers the caller supplies. This module supplies those
+// readers, applies the answer, and keeps `.gen-state` honest afterwards. Keeping
+// the two apart is what lets the RULE be tested without a filesystem and the
+// PLUMBING be tested against real files, rather than only through a full runGen.
+//
+// Three properties this file is responsible for, none of which the pure decision
+// can enforce on its own:
+//
+//   1. NAMESPACE SCOPE. A generator's `owns` predicate speaks in paths relative
+//      to its own output directory; gen-state speaks in project-relative paths.
+//      Translating between them is where a boundary is won or lost, so a path
+//      that resolves outside the generator's directory is never even offered to
+//      the predicate.
+//   2. RECORD HYGIENE. A removed or already-gone path must be forgotten, or the
+//      next run re-decides a settled orphan forever. A REFUSED path must be
+//      kept, or a refusal degrades into permanent silence on the run after.
+//   3. DRY-RUN HONESTY. `--dry-run` must report a pending deletion and perform
+//      none, because a preview that hides a deletion is worse than no preview.
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import {
+  listGeneratedPaths,
+  isPristineGenerated,
+  forgetGeneratedPaths,
+} from "./overwrite-policy.js";
+import { reconcileOrphans, type OrphanPolicy } from "./reconcile-orphans.js";
+
+/** One opt-in generator's stake in the sweep. */
+export interface OrphanJob {
+  /** For diagnostics — which generator's namespace this is. */
+  readonly generatorName: string;
+  /** Absolute directory this generator wrote to, i.e. the base its policy's
+   *  relative paths are measured from. */
+  readonly writeOutDir: string;
+  readonly policy: OrphanPolicy;
+}
+
+export interface SweepOrphansArgs {
+  readonly genStateDir: string;
+  /** Absolute project root — the base gen-state keys are relative to. */
+  readonly projectRoot: string;
+  /** Project-relative paths written on THIS run, by ANY generator. A path some
+   *  other generator now produces is not an orphan, so the whole run's output is
+   *  the right exclusion set, not just the opting-in generator's. */
+  readonly emittedRelPaths: readonly string[];
+  readonly jobs: readonly OrphanJob[];
+  /** Decide and report, touch nothing. */
+  readonly dryRun: boolean;
+}
+
+export interface SweepOrphansResult {
+  /** Untouched orphans deleted (or, under dryRun, that would be). */
+  readonly removed: string[];
+  /** Hand-edited orphans left alone and reported. */
+  readonly refused: string[];
+  /** Which generator's namespace each refusal came from, so the caller can name it
+   *  instead of assuming one. `orphanPolicy` is a generic `Generator` field and an app
+   *  is encouraged to compose its own generator, so a message hardcoding one
+   *  generator's name would be wrong for exactly the users the seam exists for. */
+  readonly refusedBy: ReadonlyMap<string, string>;
+  /** Hand-edited orphans deleted because their policy set `force`. Separate from
+   *  `removed` so the caller can say the louder thing about them. */
+  readonly forced: string[];
+}
+
+/** gen-state keys carry the platform separator; an `owns` predicate is written
+ *  against generated output, which is always `/`-separated. Normalize once so a
+ *  predicate authored the obvious way is not silently wrong off Linux. */
+function toPosix(p: string): string {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+
+export function sweepOrphans(args: SweepOrphansArgs): SweepOrphansResult {
+  if (args.jobs.length === 0) {
+    return { removed: [], refused: [], forced: [], refusedBy: new Map() };
+  }
+
+  const previouslyGenerated = listGeneratedPaths(args.genStateDir);
+  if (previouslyGenerated.length === 0) {
+    return { removed: [], refused: [], forced: [], refusedBy: new Map() };
+  }
+
+  // NOT normalized: both sides of this comparison are produced by
+  // `relative(projectRoot, …)` — gen-state's keys and the runner's emitted paths
+  // alike — so they already share whatever separator the platform uses.
+  // Normalizing one side is what would break them apart. `toPosix` is used only
+  // where a HUMAN-authored string is involved (the `owns` predicate below).
+  const emitted = args.emittedRelPaths;
+  // A path can fall inside two jobs' namespaces (an app may register several
+  // requirementTests() instances). Sets keep the second visit from re-reporting
+  // a file the first already dealt with.
+  const removed = new Set<string>();
+  const refused = new Set<string>();
+  const forced = new Set<string>();
+  const forget = new Set<string>();
+  const refusedBy = new Map<string, string>();
+
+  for (const job of args.jobs) {
+    const decision = reconcileOrphans({
+      previouslyGenerated,
+      emitted,
+      owns: (relPath) => {
+        const inTarget = relative(job.writeOutDir, resolve(args.projectRoot, relPath));
+        // "" is the directory itself; a `..` prefix or an absolute result means
+        // the path is outside this generator's output entirely. Neither is
+        // something the predicate should get a say in.
+        if (inTarget === "" || inTarget.startsWith("..") || isAbsolute(inTarget)) {
+          return false;
+        }
+        return job.policy.owns(toPosix(inTarget));
+      },
+      exists: (relPath) => existsSync(resolve(args.projectRoot, relPath)),
+      // The committed hash manifest, NOT the snapshot body — the bodies are
+      // gitignored, so on a fresh clone a body-based check could never prove a
+      // file untouched and orphan cleanup would refuse everything forever.
+      isUntouched: (relPath) => {
+        const full = resolve(args.projectRoot, relPath);
+        if (!existsSync(full)) return false;
+        return isPristineGenerated(
+          args.genStateDir,
+          relPath,
+          readFileSync(full, "utf-8"),
+        );
+      },
+    });
+
+    for (const relPath of decision.remove) {
+      if (refused.has(relPath) || forced.has(relPath)) continue;
+      removed.add(relPath);
+      forget.add(relPath);
+    }
+    for (const relPath of decision.refused) {
+      // `refused` belongs in this guard too. Without it, a path already refused by a
+      // non-forcing job could be picked up by a later FORCING job whose namespace
+      // overlaps (the file anticipates several requirementTests() instances), landing
+      // in `refused` and `forced` at once — deleted from disk, while
+      // `refusedOrphanMessage` tells the user it "was NOT deleted".
+      //
+      // First decision wins: a refusal is the conservative answer, and letting a
+      // later job escalate it to a deletion would make the outcome depend on job
+      // ORDER, which is exactly the ambiguity the runner's duplicate-path guard
+      // exists to reject elsewhere.
+      if (removed.has(relPath) || forced.has(relPath) || refused.has(relPath)) continue;
+      if (job.policy.force === true) {
+        forced.add(relPath);
+        forget.add(relPath);
+      } else {
+        // Deliberately NOT forgotten: the record is what makes the refusal
+        // repeat until someone resolves it.
+        refused.add(relPath);
+        refusedBy.set(relPath, job.generatorName);
+      }
+    }
+    // Nothing on disk to report — the file is already gone. Clear the stale
+    // record so this stops being reconsidered on every future run.
+    for (const relPath of decision.vanished) forget.add(relPath);
+  }
+
+  if (!args.dryRun) {
+    for (const relPath of [...removed, ...forced]) {
+      rmSync(resolve(args.projectRoot, relPath), { force: true });
+    }
+    // Batched: the per-path form rewrites the whole manifest each call, so clearing
+    // k orphans rewrote it k times for an identical result.
+    forgetGeneratedPaths(args.genStateDir, forget);
+  }
+
+  return {
+    removed: [...removed].sort(),
+    refused: [...refused].sort(),
+    forced: [...forced].sort(),
+    refusedBy,
+  };
+}