@metaobjectsdev/codegen-ts 0.23.2 → 0.24.1

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,
+  };
+}