@metaobjectsdev/cli 1.0.2 → 1.0.4-rc.1

package/src/commands/gen.ts

@@ -2,6 +2,7 @@ import { relative } from "node:path";
 import { parseGenArgs } from "../lib/args.js";
 import { resolveGenConfig } from "../lib/config.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenCollection, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
+import { collectionLoadOptions } from "../lib/collection-load-options.js";
 import { formatGenResult, formatGenResultToon, type GenFileEntry, type GenFileStatus } from "../lib/output.js";
 import { formatGenResultJson } from "../lib/output-json.js";
 import type { OutputFormat } from "../lib/format.js";
@@ -14,9 +15,18 @@ import {
   type AdvisoryFindingRow, type AdvisorySection,
 } from "../lib/advisory.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
-import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
+import { runGen } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
+import { packageOfResolutionKey } from "@metaobjectsdev/metadata";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import type { Collection } from "@metaobjectsdev/sdk";
 import { reportLoadError } from "../lib/load-error.js";
+import {
+  buildCatalogListing, renderCatalogText, wiredGeneratorNames, ownedGeneratorNames,
+  declaredDepsOf,
+} from "../lib/catalog-listing.js";
+import { emitStructured } from "../lib/format.js";
+import { composeCatalog } from "../lib/catalog.js";
 
 /**
  * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
@@ -52,10 +62,16 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   try { flags = parseGenArgs(args); }
   catch (err) { log.error((err as Error).message); return 2; }
 
-  // ADR-0021 D3 — `meta gen --list`: print the stable-name generator registry
-  // and exit 0 WITHOUT running codegen (no config/metadata required).
+  // ADR-0021 D3 — `meta gen --list`: print the generator CATALOG and exit 0 WITHOUT
+  // running codegen. No project is required (like `meta types`): "what can this engine
+  // do" is a question about the installed engine. `--probe` adds "...and what would
+  // each emit for MY model", which does need one.
   if (flags.list) {
-    return listGeneratorsCommand();
+    return listCatalogCommand(cwd, fmt, flags.probe);
+  }
+  if (flags.probe) {
+    log.error("--probe is only meaningful with --list. Run: meta gen --list --probe");
+    return 2;
   }
 
   const cliConfig = resolveGenConfig(flags);
@@ -122,7 +138,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   let metadata;
   try {
     metadata = await loadMemory(genCollection.configDir, {
-      files: genCollection.files,
+      ...collectionLoadOptions(genCollection),
       ...loadMemoryOptionsFrom(forgeConfig),
     });
   } catch (err) {
@@ -130,12 +146,28 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     return 2;
   }
 
+  // FR-023 §11.1 item 2 — refuse a positional that names ONLY objects imported
+  // from a dependency and excluded from output by the default exclusion rule.
+  // Distinct from the runner's existing "no entities matched" WARNING
+  // (runner.ts): that path covers a name matching nothing loaded at all; this
+  // one covers a name that matches something real, just not something this
+  // project generates. A name matching nothing falls through untouched — the
+  // runner's own warning still covers it.
+  const importedRefusal = refuseImportedPositional(cliConfig.entities, metadata, genCollection);
+  if (importedRefusal !== undefined) {
+    log.error(importedRefusal);
+    return 2;
+  }
+
   let result;
   try {
     result = await runGen({
       config: forgeConfig,
       metadata,
       projectRoot,
+      // The COMPOSED catalog, so the requires / api-framework gates can see the react
+      // and tanstack entries too. codegen-ts only knows its own slice.
+      catalog: composeCatalog(),
       baseline: flags.baseline,
       // --dry-run must actually preview. This was previously passed only to the
       // display object below, so a "preview" run wrote every file.
@@ -145,6 +177,14 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       // passed: an unconfigured project's predicate admits everything, so this
       // is a no-op for the common case, not a behavior change.
       scope: genCollection.inScope,
+      // FR-023 §4.3 — the collection's own source files (never a dependency's
+      // snapshot artifact), so sharedModelFile() defaults its `files` selection
+      // to exactly what this project itself declares.
+      sourceFiles: genCollection.ownFiles,
+      // FR-043 §6 — the shipped-library selection. Always passed, including as `[]`:
+      // that is what tells the post-selection audit "this project opted into none",
+      // which is a different statement from a programmatic caller that never said.
+      libraries: genCollection.libraries,
       ...(cliConfig.entities.length > 0 ? { entityFilter: cliConfig.entities } : {}),
     });
   } catch (err) {
@@ -154,6 +194,21 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
 
   for (const w of result.warnings) { log.warn(w); }
 
+  // A first-run POINTER, not a warning: an empty selection is the designed state of a
+  // fresh `meta init`, so calling it a problem would make every new project start with
+  // one. It says what to do next and disappears the moment anything is wired.
+  if ((forgeConfig.generators?.length ?? 0) === 0) {
+    log.info(
+      "\nNothing is generated until you choose it — `generators: []` is what `meta init` " +
+        "scaffolds, by design.\n" +
+        "  meta gen --list --probe    the catalog, with how many files each generator " +
+        "would emit for YOUR model\n" +
+        "  meta eject <name>...       take the ones you want; it prints the import, the " +
+        "entry to wire, and what to install\n" +
+        "(`meta docs` needs none of this — documentation is on by default.)",
+    );
+  }
+
   // result.files[].path is the absolute full path from decideAndWrite. With
   // per-target output, show each path relative to the project root so files in
   // different targets are distinguishable.
@@ -220,6 +275,45 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
   return hasFailure ? 1 : 0;
 }
 
+/**
+ * FR-023 §11.1 item 2 — the error message for `meta gen <Name>` when EVERY
+ * loaded object named `<Name>` is imported from a dependency and excluded from
+ * output (imported metadata is load-only by default; only the consumer's own
+ * `scope.include` naming the package literally opts it in). Returns undefined
+ * for every other case, INCLUDING a name matching nothing at all — that stays
+ * the runner's existing "no entities matched" warning, unchanged.
+ *
+ * A bare positional is a NAME, not a fully-qualified one (`cliConfig.entities`
+ * is matched against `entity.name` elsewhere in this file the same way), so two
+ * packages declaring the same short name are both candidates; the refusal
+ * fires only when NONE of them would generate.
+ */
+function refuseImportedPositional(
+  entityNames: readonly string[],
+  metadata: MetaRoot,
+  collection: Collection,
+): string | undefined {
+  if (entityNames.length === 0) return undefined;
+  const allObjects = metadata.objects();
+  for (const name of entityNames) {
+    const matches = allObjects.filter((o) => o.name === name);
+    if (matches.length === 0) continue; // nothing loaded by this name — the runner's own warning covers it
+    const allExcludedImports = matches.every((o) => {
+      const fqn = o.resolutionKey();
+      return collection.imported(fqn) && !collection.inScope(fqn);
+    });
+    if (!allExcludedImports) continue;
+    const fqn = matches[0]!.resolutionKey();
+    const pkg = packageOfResolutionKey(fqn);
+    const dependencyName = collection.dependencies.find((d) => d.packages.includes(pkg))?.name ?? pkg;
+    return (
+      `meta gen: '${name}' (${fqn}) is imported from dependency '${dependencyName}' and is not ` +
+      `generated here — add its package to scope.include in .metaobjects/config.json to generate it`
+    );
+  }
+  return undefined;
+}
+
 /**
  * Run the advisory verify-as-teacher scan (same pass `meta verify` runs): surface
  * authored source that hand-rolls what the metadata could model. `gen` is the
@@ -251,34 +345,100 @@ function runAntiPatternScan(
 }
 
 /**
- * `meta gen --list` — print the stable-name generator registry (ADR-0021 D3).
+ * `meta gen --list` — the generator catalog (ADR-0021 D3; opt-in-codegen design §D3).
  *
- * Generators are grouped by tier: the recommended native `meta gen` suite
- * first, then neutral artifacts (owned by `meta docs` per D1). Each line is
- * `<stable-name>  —  <description>` plus an options summary and, for neutral
- * entries, a note pointing at the canonical door. Exits 0; no codegen runs.
+ * Codegen is opt-in, so this is the door: the tool describes what it can do and the
+ * builder decides what the app needs. Rows are grouped by `layer`, the axis you select
+ * by; `--format json|toon` emits the same catalog as ONE document (nothing else on
+ * stdout, per `meta types`' purity rule).
+ *
+ * With `--probe`, every catalog generator is constructed and dry-run against this
+ * project's real model, so the `capability` layer stops being a list of labels and
+ * becomes `output-parser: 3, callable: 0, requirement-tests: 7` — information that
+ * cannot go stale, because it does not describe the generators, it runs them.
  */
-function listGeneratorsCommand(): number {
-  const entries = listGenerators();
-  const native = entries.filter((e) => e.tier === "native");
-  const neutral = entries.filter((e) => e.tier === "neutral");
-  const width = Math.max(...entries.map((e) => e.name.length));
+async function listCatalogCommand(
+  cwd: string,
+  fmt: OutputFormat,
+  probe: boolean,
+): Promise<number> {
+  let opts: Parameters<typeof buildCatalogListing>[0] = {};
 
-  const lines: string[] = [];
-  lines.push("Available generators (select by stable name):");
-  lines.push("");
-  lines.push("Native (recommended `meta gen` suite):");
-  for (const e of native) {
-    lines.push(`  ${e.name.padEnd(width)}  —  ${e.description}`);
-    if (e.options) lines.push(`  ${" ".repeat(width)}     options: ${e.options}`);
-  }
-  lines.push("");
-  lines.push("Neutral (owned by `meta docs`; not part of the native suite):");
-  for (const e of neutral) {
-    lines.push(`  ${e.name.padEnd(width)}  —  ${e.description}`);
-    if (e.note) lines.push(`  ${" ".repeat(width)}     ${e.note}`);
+  if (probe) {
+    // A probe reports what YOUR model would produce, so a project is mandatory here
+    // even though it is optional for a bare --list. Failing loudly beats a listing of
+    // zeros that reads like "none of these apply to you".
+    let collection;
+    try {
+      collection = await resolveCollection(cwd);
+    } catch (err) {
+      log.error(
+        `meta gen --list --probe needs a project to probe: ${(err as Error).message}\n` +
+          "Run `meta gen --list` (no --probe) for the catalog on its own.",
+      );
+      return 2;
+    }
+    const projectRoot = resolveGenConfigDir(cwd, collection.configDir);
+    const genCollection = await resolveGenCollection(collection, projectRoot);
+
+    let forgeConfig;
+    try {
+      forgeConfig = await loadMetaobjectsConfig(projectRoot);
+    } catch (err) {
+      log.error((err as Error).message);
+      return 2;
+    }
+
+    let metadata;
+    try {
+      metadata = await loadMemory(genCollection.configDir, {
+        ...collectionLoadOptions(genCollection),
+        ...loadMemoryOptionsFrom(forgeConfig),
+      });
+    } catch (err) {
+      reportLoadError(log, "failed to load metadata", err);
+      return 2;
+    }
+
+    opts = {
+      project: {
+        projectRoot,
+        config: forgeConfig,
+        wiredNames: wiredGeneratorNames(forgeConfig),
+        ownedNames: ownedGeneratorNames(projectRoot),
+        declaredDeps: declaredDepsOf(projectRoot),
+        // FR-043 — the library rows read the selection from the COLLECTION, which is
+        // where `libraries` lives now (`.metaobjects/config.json`), not from the
+        // codegen config it was moved out of.
+        libraries: genCollection.libraries,
+      },
+      probe: { metadata, scope: genCollection.inScope },
+    };
+  } else {
+    // No probe: still report `wired` / `owned` when a project happens to be here, since
+    // both are free. A directory with no config is not an error — the catalog is a fact
+    // about the installed engine.
+    try {
+      const collection = await resolveCollection(cwd);
+      const projectRoot = resolveGenConfigDir(cwd, collection.configDir);
+      const forgeConfig = await loadMetaobjectsConfig(projectRoot);
+      opts = {
+        project: {
+          projectRoot,
+          config: forgeConfig,
+          wiredNames: wiredGeneratorNames(forgeConfig),
+          ownedNames: ownedGeneratorNames(projectRoot),
+          declaredDeps: declaredDepsOf(projectRoot),
+          libraries: collection.libraries,
+        },
+      };
+    } catch {
+      // No project here — the catalog stands on its own.
+    }
   }
 
-  log.info(lines.join("\n"));
+  const rows = await buildCatalogListing(opts);
+  if (fmt === "text") log.info(renderCatalogText(rows, probe));
+  else emitStructured(rows, fmt);
   return 0;
 }