Skip to content

Commit 79f2c02

Browse files
dmealingclaude
andcommitted
fix(docs): agent/ui.md described a UI tier the run does not emit
`meta docs --agent` promises "each page is skipped when its tier has nothing to describe". It emitted `agent/ui.md` for an estate with `generators: []`, no `view.*` node and no route anywhere — and the page was not empty, it was specific and wrong: a control/HTML-type/rules table per entity for forms that do not exist, and an `Endpoint` line per object for addresses nothing serves. The audience is an agent the surface explicitly instructs to read the page BEFORE touching a tier, which is the audience least able to check. The gate was `hasUiSurface(obj) = servesReadApi(obj)` — a METADATA predicate, which answers "could a UI be generated for this object?" and can never answer "does this run generate one?". Whether an artifact exists is a generator fact. So the page now gates on a generator marker, aggregated the way `emitsHonoRoutes` and `emitsNames` already are: `emitsUiTier` on each form/hook/grid generator, collected by the runner into `ResolvedGenConfig.includeUiTier`, with `runEmitsUiTier` as the ONE derivation both doors call — `meta gen`'s runner and `meta docs`, which is the other door onto this page. An owned copy ejected before the marker existed would otherwise lose the page in silence, so a name match keeps it emitting AND warns, naming the one-line fix; a config `includeUiTier` covers a copy that was also renamed. Nothing degrades quietly. Found while wiring the second door: `meta docs` read the RAW config, where a generator wired by stable name (`generators: ["routes-hono"]`, legal under ADR-0021 #1) is a string carrying no marker at all — so `api-docs` documented the Fastify-only surface for a project that had wired the Hono one. Both aggregations now run after `resolveGenerators`, and an unresolvable suite says so rather than silently answering "no". Gates: the marker/name parity pair in `cli` (the only package that depends on every UI codegen package), the aggregation and warning in `codegen-ts`, and the page's own emit asserted as a SET difference so suppressing ui.md cannot take a sibling page with it. Each proved by breaking it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NTcEKXTQMYt84fAjuw5A2M
1 parent c22d3da commit 79f2c02

24 files changed

Lines changed: 411 additions & 20 deletions

‎server/typescript/packages/cli/src/commands/docs.ts‎

Lines changed: 42 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
import type {
3030
GenContext,
3131
EmittedFile,
32+
Generator,
3233
ResolvedDocsConfig,
3334
DocsSurface,
3435
Dialect,
@@ -41,7 +42,7 @@ import {
4142
DEFAULT_COLUMN_NAMING_STRATEGY,
4243
renderCoreMetamodelDocs,
4344
} from "@metaobjectsdev/metadata";
44-
import { dbEmittingObjects, DEFAULT_DIALECT, missingDialectMessage } from "@metaobjectsdev/codegen-ts";
45+
import { dbEmittingObjects, DEFAULT_DIALECT, DEFAULT_DOCS_DIR, missingDialectMessage, resolveGenerators, runEmitsHonoRoutes, runEmitsUiTier } from "@metaobjectsdev/codegen-ts";
4546
import type { MetaDataTypeProvider, MetaRoot } from "@metaobjectsdev/metadata";
4647
import { generateSite, SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } from "@metaobjectsdev/docs-site";
4748
// The `agent` schema surface takes the physical schema as an ARGUMENT with its resolvers
@@ -219,9 +220,14 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
219220
// cwd (mirrors how migrate/gen treat the working directory as the root).
220221
projectRoot: projectRoot ?? cwd,
221222
projectRootProvided: projectRoot !== undefined,
222-
// Default out dir, resolved against the project root below. In --metamodel
223-
// mode the renderer writes under <out>/metamodel/, default ./docs/metamodel.
224-
out: out ?? (wantMetamodel ? "./docs/metamodel" : "./docs"),
223+
// Default out dir, resolved against the project root below. ONE spelling of the
224+
// default, shared with resolveDocsConfig — two spellings is how a flag default and
225+
// a config default come to disagree about where the pages are.
226+
//
227+
// --metamodel keeps its own sub-path: the renderer writes under <out>/metamodel/,
228+
// and it is a different artifact (the metamodel reference, not this project's
229+
// pages), so it is not swept into the generated-docs directory.
230+
out: out ?? (wantMetamodel ? "./docs/metamodel" : DEFAULT_DOCS_DIR),
225231
// Default flat preserves today's single-package output (+ existing goldens).
226232
layout: layout ?? "flat",
227233
metamodel: wantMetamodel,
@@ -481,7 +487,7 @@ export async function docsCommand(
481487

482488
// Merge the config `docs:` block with CLI overrides over documented defaults.
483489
// CLI --out/--layout only override when explicitly passed; surfaces/baseUrl
484-
// override whenever present. The resolver supplies defaults (outDir ./docs,
490+
// override whenever present. The resolver supplies defaults (outDir ./docs/generated,
485491
// layout = fallback, surfaces = both) so config-less + flag-less runs are
486492
// unchanged.
487493
const cliOverrides: Partial<ResolvedDocsConfig> = {
@@ -544,6 +550,29 @@ export async function docsCommand(
544550
pkMap: buildPkMap(root),
545551
relationMap: buildRelationMap(root),
546552
});
553+
// The generator suite, with stable-name STRINGS resolved to the generators they name
554+
// (ADR-0021 #1 allows `generators: ["routes-hono"]`). Both aggregations below read a
555+
// generator MARKER, and a string carries none — so reading the raw array answered
556+
// "no Hono routes / no UI tier" for a project that wires them by name, which is the
557+
// same two-doors-one-question defect these flags exist to close. `meta gen` resolves
558+
// the identical array through `normalizeConfig`.
559+
//
560+
// An unknown name throws (the message names it and lists the valid ones). `meta gen`
561+
// fails on it; `meta docs` has never had to load the suite at all, so it degrades to
562+
// the already-typed entries rather than becoming a new failure — and SAYS it did,
563+
// because a page quietly losing a section is exactly what this whole fix is about.
564+
let suite: Generator[];
565+
try {
566+
suite = resolveGenerators(loadedConfig?.generators ?? []);
567+
} catch (err) {
568+
log.warn(
569+
`docs: could not resolve the generator suite (${(err as Error).message}) — the agent ` +
570+
`pages fall back to the generators declared as values, so a tier wired by name may ` +
571+
`be missing from them.`,
572+
);
573+
suite = (loadedConfig?.generators ?? []).filter((g): g is Generator => typeof g !== "string");
574+
}
575+
547576
const ctx: GenContext = {
548577
entities: root.objects(),
549578
loadedRoot: root,
@@ -558,12 +587,14 @@ export async function docsCommand(
558587
// surface. Aggregate it from the generator set exactly as the gen runner
559588
// does (a generator opts in via emitsHonoRoutes), so `meta docs` auto-detects
560589
// routesFileHono() rather than relying on a field users don't normally set.
561-
includeHonoRoutes:
562-
loadedConfig?.includeHonoRoutes ??
563-
(loadedConfig?.generators?.some(
564-
(g) => typeof g !== "string" && g.emitsHonoRoutes === true,
565-
) ??
566-
false),
590+
includeHonoRoutes: loadedConfig?.includeHonoRoutes ?? runEmitsHonoRoutes(suite),
591+
// `agent/ui.md` describes forms, grids and the endpoints their hooks call. Whether
592+
// any of that is emitted is a GENERATOR fact — the page's own predicate is
593+
// metadata-only and answered "could a UI be generated?", so a project with
594+
// `generators: []` got a confident page naming endpoints nothing serves. Aggregate
595+
// it through the same helper the gen runner uses, so `meta docs` and `meta gen` —
596+
// the two doors onto this page — cannot answer it differently.
597+
includeUiTier: loadedConfig?.includeUiTier ?? runEmitsUiTier(suite),
567598
} as never,
568599
renderContext,
569600
projectRoot,

‎server/typescript/packages/cli/test/docs-command.test.ts‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -622,6 +622,12 @@ const PREFIXED_CONFIG = [
622622
` dialect: "sqlite",`,
623623
` apiPrefix: "/api",`,
624624
` generators: ["entity"],`,
625+
// agent/ui.md is gated on the RUN emitting a UI tier, and no UI generator has a stable
626+
// NAME (they live in codegen-ts-react / codegen-ts-tanstack, which codegen-ts cannot
627+
// depend on) — so a string suite cannot declare one. The config override is the
628+
// declared way to say it, and it is also the escape hatch for an owned copy whose name
629+
// was changed. What this test is about is the PREFIX on the page, not the gate.
630+
` includeUiTier: true,`,
625631
`});`,
626632
].join("\n");
627633

@@ -649,3 +655,38 @@ describe("meta docs --agent — the endpoint is the address the routes actually
649655
expect(ui).not.toMatch(/`\/authors`/);
650656
});
651657
});
658+
659+
// A generator wired by STABLE NAME carries no marker, and `meta docs` was reading the raw
660+
// config — so `generators: ["routes-hono"]`, legal under ADR-0021 #1, aggregated to "no
661+
// Hono routes" and `api-docs` documented the Fastify-only surface for a project that had
662+
// wired the Hono one. `meta gen` resolves the identical array through `normalizeConfig`.
663+
// Found while gating agent/ui.md on the same kind of marker.
664+
describe("meta docs — the generator suite is resolved before its markers are read", () => {
665+
const honoConfig = (generators: string) => [
666+
`import { defineConfig } from "@metaobjectsdev/codegen-ts";`,
667+
`export default defineConfig({`,
668+
` outDir: "gen",`,
669+
` dialect: "sqlite",`,
670+
` generators: ${generators},`,
671+
`});`,
672+
].join("\n");
673+
674+
async function apiDocsFor(generators: string): Promise<string> {
675+
const root = await mkdtemp(join(tmpdir(), "meta-docs-hono-"));
676+
dirs.push(root);
677+
await mkdir(join(root, "metaobjects"), { recursive: true });
678+
await writeFile(join(root, "metaobjects", "meta.json"), JSON.stringify(PREFIXED_META), "utf8");
679+
await writeFile(join(root, "metaobjects.config.ts"), honoConfig(generators), "utf8");
680+
const out = join(root, "out-docs");
681+
expect(await docsCommand([root, "--out", out, "--api"], root)).toBe(0);
682+
return await readFile(join(out, "api", "Author.md"), "utf8");
683+
}
684+
685+
test("routes-hono wired BY NAME is documented", async () => {
686+
expect(await apiDocsFor(`["entity", "routes-hono"]`)).toContain("[Hono]");
687+
});
688+
689+
test("a suite without it still documents Fastify only — the flag is not stuck on", async () => {
690+
expect(await apiDocsFor(`["entity", "routes"]`)).not.toContain("[Hono]");
691+
});
692+
});
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// F75 — the two halves of "does this run emit a client UI tier?" must agree.
2+
//
3+
// `agent/ui.md` gates on that answer. The declared half is each generator's
4+
// `emitsUiTier` marker; the compatibility half is `UI_TIER_GENERATOR_NAMES`, which keeps
5+
// a copy ejected before the marker existed from silently losing the page. A generator
6+
// present in one half and not the other is the bug this file exists to catch: add a UI
7+
// generator without the marker and the page stops emitting for everyone who wires it;
8+
// add the marker without the name and an ejected copy of it degrades in silence.
9+
//
10+
// It lives in `cli` because `cli` is the only package that depends on every UI codegen
11+
// package AND is the second door onto the page (`meta docs` aggregates the same fact).
12+
13+
import { describe, test, expect } from "bun:test";
14+
import { UI_TIER_GENERATOR_NAMES, runEmitsUiTier } from "@metaobjectsdev/codegen-ts";
15+
import type { Generator } from "@metaobjectsdev/codegen-ts";
16+
import { formFile } from "@metaobjectsdev/codegen-ts-react";
17+
import { tanstackQuery, tanstackGrid, tanstackGridHook } from "@metaobjectsdev/codegen-ts-tanstack";
18+
19+
const SHIPPED: Generator[] = [formFile(), tanstackQuery(), tanstackGrid(), tanstackGridHook()];
20+
21+
describe("UI-tier marker parity", () => {
22+
test("every shipped UI generator declares emitsUiTier", () => {
23+
expect(SHIPPED.map((g) => [g.name, g.emitsUiTier])).toEqual(
24+
SHIPPED.map((g) => [g.name, true]),
25+
);
26+
});
27+
28+
test("every shipped UI generator's name is in the ejected-copy compatibility set", () => {
29+
expect(SHIPPED.filter((g) => !UI_TIER_GENERATOR_NAMES.has(g.name)).map((g) => g.name))
30+
.toEqual([]);
31+
});
32+
33+
test("the shipped suite makes the run emit a UI tier; a server-only suite does not", () => {
34+
expect(runEmitsUiTier(SHIPPED)).toBe(true);
35+
expect(runEmitsUiTier([{ name: "entity-file", generate: () => [] }])).toBe(false);
36+
});
37+
});

‎server/typescript/packages/cli/test/unit/docs-command-surfaces.test.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ const CONFIG_NO_DIALECT = [
4343
`export default defineConfig({`,
4444
` outDir: "out",`,
4545
` generators: ["entity"],`,
46+
// Declares a UI tier, so the test below can assert that skipping the SCHEMA page did
47+
// not suppress the agent surface wholesale. Without it this project has no UI tier and
48+
// no requirements, so schema.md is the only agent page it would ever have — and the
49+
// control assertion would pass for the wrong reason.
50+
` includeUiTier: true,`,
4651
`});`,
4752
].join("\n");
4853

‎server/typescript/packages/codegen-ts-angular/src/generators/angular-form.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ export const angularFormFile = function angularFormFile(
3333
const userFilter = opts?.filter ?? (() => true);
3434
const generator: Generator = {
3535
name: "angular-form",
36+
// Marks this generator as part of the CLIENT UI tier — the runner aggregates it
37+
// into ctx.config.includeUiTier so `agent/ui.md` describes a tier that this run
38+
// actually emits, rather than one the metadata merely permits.
39+
emitsUiTier: true,
3640
// A form is a client of generated WRITE endpoints — no writable source, no form
3741
// (mirrors codegen-ts-react's formFile; see api-surface.ts). `!isProjection`
3842
// stays explicit: a read-only view has nothing to submit even where write

‎server/typescript/packages/codegen-ts-angular/src/generators/angular-grid.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ export const angularGridFile = function angularGridFile(
3838
const userFilter = opts?.filter ?? (() => true);
3939
const generator: Generator = {
4040
name: "angular-grid",
41+
// Marks this generator as part of the CLIENT UI tier — the runner aggregates it
42+
// into ctx.config.includeUiTier so `agent/ui.md` describes a tier that this run
43+
// actually emits, rather than one the metadata merely permits.
44+
emitsUiTier: true,
4145
filter: (e: MetaObject) =>
4246
// A grid renders what a generated READ endpoint returns — no endpoint, no grid
4347
// (see api-surface.ts).

‎server/typescript/packages/codegen-ts-angular/src/generators/angular-service.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ export const angularServiceFile = function angularServiceFile(
3131
const userFilter = opts?.filter ?? (() => true);
3232
const generator: Generator = {
3333
name: "angular-service",
34+
// Marks this generator as part of the CLIENT UI tier — the runner aggregates it
35+
// into ctx.config.includeUiTier so `agent/ui.md` describes a tier that this run
36+
// actually emits, rather than one the metadata merely permits.
37+
emitsUiTier: true,
3438
// A service is a client of a generated READ endpoint — no endpoint, no service
3539
// (an `object.value`, a sourceless entity/projection or an abstract object has
3640
// nothing to fetch, and its emitted output could never compile; see api-surface.ts).

‎server/typescript/packages/codegen-ts-react/src/form-file.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ export const formFile = function formFile(opts?: FormFileOpts): Generator {
2222
const userFilter = opts?.filter ?? (() => true);
2323
const generator: Generator = {
2424
name: "form-file",
25+
// Marks this generator as part of the CLIENT UI tier — the runner aggregates it
26+
// into ctx.config.includeUiTier so `agent/ui.md` describes a tier that this run
27+
// actually emits, rather than one the metadata merely permits.
28+
emitsUiTier: true,
2529
// Always set: AND-composes the framework write-artifact guard
2630
// (skips abstract types — no instance — and read-only projections —
2731
// instantiable for read, never for write) with the optional user filter.

‎server/typescript/packages/codegen-ts-react/src/reference/form.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ export const formFile = function formFile(opts?: FormFileOpts): Generator {
4747
const userFilter = opts?.filter ?? (() => true);
4848
const generator: Generator = {
4949
name: "form-file",
50+
// Marks this generator as part of the CLIENT UI tier — the runner aggregates it
51+
// into ctx.config.includeUiTier so `agent/ui.md` describes a tier that this run
52+
// actually emits, rather than one the metadata merely permits.
53+
emitsUiTier: true,
5054
// Always set: AND-composes the framework write-artifact guard
5155
// (skips abstract types — no instance — and read-only projections —
5256
// instantiable for read, never for write) with the optional user filter.

‎server/typescript/packages/codegen-ts-tanstack/src/reference/grid-hook.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,10 @@ export const tanstackGridHook = function tanstackGridHook(opts?: TanstackGridHoo
143143
});
144144
const generator: Generator = {
145145
name: "tanstack-grid-hook",
146+
// Marks this generator as part of the CLIENT UI tier — the runner aggregates it
147+
// into ctx.config.includeUiTier so `agent/ui.md` describes a tier that this run
148+
// actually emits, rather than one the metadata merely permits.
149+
emitsUiTier: true,
146150
filter: (e: MetaObject) => passesOtherGates(e) && hasDataGridLayout(e),
147151
generate: async (ctx) => {
148152
warnMissingDataGridLayout(ctx, passesOtherGates, "<Entity>.grid.ts");

0 commit comments

Comments
 (0)