Skip to content

Commit 8673606

Browse files
committed
fix(docs): one home for report wording; document only the writes a read-only object emits (FR-044)
The sentences meta docs prints about dimensions, measures, segments, row scopes and why a report is not served now live in one place, metadata's core/reporting/report-describe.ts, beside reportShape. The markdown model pages (codegen-ts) and the HTML site (docs-site) both read them from there; each keeps only its own markup step. An object's API unit documents create/update/delete, the write REST verbs and the Insert/Update schemas only when the generators emit them. The gate is the generators' own dispatch (a read-only-kind source and no writable one), so a view-backed projection and a report document reads alone, a keyless one without find-by-id, and a write-through object keeps its whole write surface. This is a named exception to no-churn: a read-only projection's API page loses symbols that were never generated. The accuracy gate now checks a keyed projection, a keyless projection and a write-through object against the emitted files in both directions. The site's coverage audit marks only the attributes the describers read, so an attribute on a reporting node that no page prints is reported as a gap. The report page narrows its node with isMetaObject.
1 parent 65a2b0a commit 8673606

8 files changed

Lines changed: 618 additions & 225 deletions

File tree

‎server/typescript/packages/codegen-ts/src/generators/api-model.ts‎

Lines changed: 35 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,11 @@
8383
// and nothing else: a report has no identity, so no by-id query and no `/:id`; no
8484
// write helper; no insert/update schema. No hook is documented for any object here
8585
// (see DEFERRALS), and none is generated for a report at all (`servesClientTier`).
86-
// • A KEYLESS projection (no identity and no `id` column) likewise documents no
86+
// • A READ-ONLY object (a read-only-kind source and no writable one: a view-backed
87+
// projection, a report's read model) documents reads only: no create/update/delete,
88+
// no write verb, no insert/update schema, because its generated files carry none
89+
// (`isReadOnlySurface`). A write-through object is not read-only and keeps them all.
90+
// • A KEYLESS read-only object (no identity and no `id` column) also documents no
8791
// `find<Name>ById` and no `/:id`: the read-only generators emit neither
8892
// (`hasItemRoute`).
8993
//
@@ -135,7 +139,7 @@ import { hasItemRoute, servedPath, servesReadApi } from "../api-surface.js";
135139
import { isProjection } from "../projection/projection-detector.js";
136140
import { buildPkMap } from "../pk-resolver.js";
137141
import { buildRelationMap, type RelationEntry, type RelationMap } from "../relation-resolver.js";
138-
import { generatableObjects, isReport } from "../source-detect.js";
142+
import { generatableObjects } from "../source-detect.js";
139143
import { effectivePackage } from "../docs-paths.js";
140144
import { entityOutputPath, type OutputLayout } from "../import-path.js";
141145
import type { RenderContext } from "../render-context.js";
@@ -392,14 +396,30 @@ function isQueryable(obj: MetaObject): boolean {
392396
}
393397

394398
/**
395-
* True for a READ-ONLY object the generators give no item surface: no `/:id` route and
399+
* True when the generators emit the READ-ONLY surface for the object: reads only, no
400+
* create/update/delete helper, no write verb, no insert or update schema.
401+
*
402+
* This is `isProjection` from `projection/projection-detector.ts`, the exact test
403+
* `entity-file.ts`, `queries-file.ts`, `routes-file.ts` and `routes-file-hono.ts`
404+
* dispatch on, and it is a test of SOURCES, not of the `object.projection` subtype: the
405+
* object declares a read-only-kind source and no writable one. So it is true for a
406+
* view-backed projection and for a report's read model, and FALSE for a write-through
407+
* object (a writable table plus a replica view), whose generated files really do carry
408+
* the write helpers, the write verbs and both schemas. Documenting writes for a
409+
* read-only object published functions and endpoints that were never generated.
410+
*/
411+
function isReadOnlySurface(obj: MetaObject): boolean {
412+
return isProjection(obj);
413+
}
414+
415+
/**
416+
* True for a read-only object the generators give no item surface: no `/:id` route and
396417
* no by-id query. That is a projection with no identity and no `id` column, and every
397-
* report (FR-044). `hasItemRoute` is the generators' own predicate; it is only meaningful
398-
* for the read-only surface, hence the `isProjection` guard (a report's read model
399-
* carries a read-only source, so it is one too).
418+
* report (FR-044). `hasItemRoute` is the generators' own predicate, and only the
419+
* read-only surface asks it (a writable entity's by-id helpers are unconditional).
400420
*/
401421
function lacksItemSurface(obj: MetaObject): boolean {
402-
return isProjection(obj) && !hasItemRoute(obj);
422+
return isReadOnlySurface(obj) && !hasItemRoute(obj);
403423
}
404424

405425
function buildEntityUnit(
@@ -432,9 +452,9 @@ function buildEntityUnit(
432452

433453
if (isQueryable(obj)) {
434454
symbols.push(...dataAccessSymbols(obj, ctx, root, layout));
435-
// A report's entity module exports a read schema only: no insert or update schema
436-
// exists to document (FR-044).
437-
if (!isReport(obj)) symbols.push(...validationSymbols(obj, entityMod));
455+
// A read-only object's entity module exports a read schema only: no insert or update
456+
// schema exists to document.
457+
if (!isReadOnlySurface(obj)) symbols.push(...validationSymbols(obj, entityMod));
438458
// REST needs no gate of its own: the routes generator's built-in filter is
439459
// `servesReadApi && !isTphSubtype` — exactly isQueryable — so every queryable
440460
// object gets routes. (Its `filter` option can narrow that further; this builder
@@ -532,9 +552,9 @@ function dataAccessSymbols(
532552
// entity's queries file emits its by-id helpers unconditionally.
533553
const reads: ApiSymbol[] = lacksItemSurface(obj) ? [listSymbol] : [findSymbol, listSymbol];
534554

535-
// FR-044: a report is served by its list and nothing else. No create, update or delete
536-
// exists on any generated seam, so none is documented.
537-
if (isReport(obj)) {
555+
// A read-only object is served by its reads and nothing else: the read-only queries
556+
// file emits no create, update or delete, so none is documented.
557+
if (isReadOnlySurface(obj)) {
538558
return reads;
539559
}
540560

@@ -650,7 +670,7 @@ function restSymbols(
650670
): ApiSymbol[] {
651671
const name = obj.name;
652672
const path = servedPath(obj, apiPrefix);
653-
const readOnly = isProjection(obj) || isTphDiscriminatorBase(obj, root);
673+
const readOnly = isReadOnlySurface(obj) || isTphDiscriminatorBase(obj, root);
654674

655675
// REST endpoints are not importable functions — to WIRE them an adopter
656676
// imports the entity's route registrar (`<entity>Routes`) from the routes
@@ -867,7 +887,7 @@ function restHonoSymbols(
867887
): ApiSymbol[] {
868888
const name = obj.name;
869889
const path = servedPath(obj, apiPrefix);
870-
const readOnly = isProjection(obj);
890+
const readOnly = isReadOnlySurface(obj);
871891

872892
const honoMod = entityModulePath(layout, obj, `${name}.routes.hono`);
873893
const registrar = `register${name}Routes`;

‎server/typescript/packages/codegen-ts/src/generators/report-doc.ts‎

Lines changed: 13 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -6,36 +6,28 @@
66
// • the `@from` ENTITY's page: a "Reporting" section listing the dimensions, measures
77
// and segments it declares and the reports that name it.
88
//
9-
// Everything is read from declared metadata. No SQL is derived here: a definition says
10-
// what a column means ("sum of `Invoice.amountCents` where segment `paid`"), never how
11-
// the view computes it. `docs-site` renders the same sentences on the HTML site from its
12-
// own copy of these rules (it does not depend on this package); its tests hold the two
13-
// together.
9+
// The SENTENCES come from `@metaobjectsdev/metadata` (`core/reporting/report-describe.ts`),
10+
// which `docs-site` reads too, so the markdown pages and the HTML site cannot disagree.
11+
// This module only lays them out as markdown.
1412

1513
import {
16-
type MetaData,
1714
type MetaObject,
1815
type MetaRoot,
19-
type ReportField,
2016
DIMENSION_SUBTYPE_TIME,
21-
MEASURE_SUBTYPE_RATIO,
2217
OBJECT_REPORT_ATTR_FILTER,
2318
OBJECT_REPORT_ATTR_SEGMENT,
24-
REPORTING_ATTR_AGG,
25-
REPORTING_ATTR_DENOMINATOR,
26-
REPORTING_ATTR_DISTINCT,
27-
REPORTING_ATTR_FILTER,
28-
REPORTING_ATTR_GRAINS,
29-
REPORTING_ATTR_NUMERATOR,
30-
REPORTING_ATTR_OF,
31-
REPORTING_ATTR_SEGMENT,
32-
REPORTING_ATTR_VIA,
33-
SOURCE_KIND_VIEW,
3419
TYPE_DIMENSION,
3520
TYPE_MEASURE,
3621
TYPE_SEGMENT,
22+
describeDimension,
23+
describeMeasure,
24+
describeReportField,
25+
describeRowScope,
26+
describeSegment,
3727
isMetaObject,
28+
reportFieldTypeName,
3829
reportFrom,
30+
reportNotServedReason,
3931
reportReadSource,
4032
reportShape,
4133
resolveObjectRef,
@@ -44,99 +36,11 @@ import type { OutputLayout } from "../import-path.js";
4436
import { docPageHref, docPageNode, effectivePackage } from "../docs-paths.js";
4537
import { isReport } from "../source-detect.js";
4638

47-
/** Inline code. A backtick cannot sit inside a single-backtick span, so it is dropped. */
39+
/** Inline code for a name this module prints itself (the describers return theirs ready). */
4840
function tick(text: string): string {
4941
return `\`${text.replace(/`/g, "")}\``;
5042
}
5143

52-
/** A row-scope filter as authored: compact JSON, in the order it was declared. */
53-
function filterText(filter: unknown): string {
54-
return tick(JSON.stringify(filter));
55-
}
56-
57-
function stringList(v: unknown): string[] {
58-
if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string");
59-
return typeof v === "string" ? [v] : [];
60-
}
61-
62-
/**
63-
* "segment `paid` and filter `{…}`": the rows a measure or a report is scoped to, or
64-
* undefined when it declares neither. The two combine by AND, which is what the lowering
65-
* does with them.
66-
*/
67-
export function describeRowScope(segment: unknown, filter: unknown): string | undefined {
68-
const parts: string[] = [];
69-
if (typeof segment === "string" && segment !== "") parts.push(`segment ${tick(segment)}`);
70-
if (filter !== undefined && filter !== null) parts.push(`filter ${filterText(filter)}`);
71-
return parts.length > 0 ? parts.join(" and ") : undefined;
72-
}
73-
74-
/** "`Program.title` via `Purchase.program`": the column a dimension groups by. */
75-
function dimensionColumn(dim: MetaData): string {
76-
// ADR-0039: resolving, so a dimension that extends another reads its effective @of/@via.
77-
const of = dim.attr(REPORTING_ATTR_OF);
78-
const via = dim.attr(REPORTING_ATTR_VIA);
79-
const column = tick(typeof of === "string" ? of : "");
80-
return typeof via === "string" && via !== "" ? `${column} via ${tick(via)}` : column;
81-
}
82-
83-
/** A dimension as its entity declares it: the column, and for a time dimension its grains. */
84-
export function describeDimension(dim: MetaData): string {
85-
const column = dimensionColumn(dim);
86-
if (dim.subType !== DIMENSION_SUBTYPE_TIME) return column;
87-
return `${column}; grains: ${stringList(dim.attr(REPORTING_ATTR_GRAINS)).join(", ")}`;
88-
}
89-
90-
/** A dimension as ONE report column: a time dimension is truncated to the report's grain. */
91-
function describeDimensionColumn(dim: MetaData, grain: string | undefined): string {
92-
const column = dimensionColumn(dim);
93-
if (grain === undefined) return column;
94-
// Reports are UTC only (Plan 3 global constraint): there is no time-zone vocabulary.
95-
const joiner = column.includes(" via ") ? "," : "";
96-
return `${column}${joiner} truncated to ${grain}, UTC`;
97-
}
98-
99-
/** A measure in words: the aggregate and its row scope, or the ratio and its null rule. */
100-
export function describeMeasure(measure: MetaData): string {
101-
// ADR-0039: resolving reads throughout, as for a dimension.
102-
if (measure.subType === MEASURE_SUBTYPE_RATIO) {
103-
const numerator = measure.attr(REPORTING_ATTR_NUMERATOR);
104-
const denominator = measure.attr(REPORTING_ATTR_DENOMINATOR);
105-
return `${tick(String(numerator ?? ""))} / ${tick(String(denominator ?? ""))}, null when the denominator is 0`;
106-
}
107-
const columns = stringList(measure.attr(REPORTING_ATTR_OF)).map(tick);
108-
const of = columns.length === 1 ? columns[0]! : `(${columns.join(", ")})`;
109-
const distinct = measure.attr(REPORTING_ATTR_DISTINCT) === true ? "distinct " : "";
110-
const scope = describeRowScope(measure.attr(REPORTING_ATTR_SEGMENT), measure.attr(REPORTING_ATTR_FILTER));
111-
return `${String(measure.attr(REPORTING_ATTR_AGG) ?? "")} of ${distinct}${of}${scope !== undefined ? ` where ${scope}` : ""}`;
112-
}
113-
114-
/** One derived column's definition, from the dimension or measure it comes from. */
115-
export function describeReportField(field: ReportField): string {
116-
if (field.dimension !== undefined) return describeDimensionColumn(field.dimension, field.grain);
117-
return field.measure !== undefined ? describeMeasure(field.measure) : "";
118-
}
119-
120-
/** The neutral logical type of a derived column: its Table B subtype, `[]` for an array. */
121-
export function reportFieldType(field: ReportField): string {
122-
// ADR-0039: resolvedIsArray() is the resolving read of the native array flag.
123-
return field.typeSource?.resolvedIsArray() === true ? `${field.subType}[]` : field.subType;
124-
}
125-
126-
/**
127-
* Why a report is not served, or undefined when it is (Table A). The wording is the
128-
* spec's for the common case: a report that declares no source at all.
129-
*/
130-
export function reportNotServedReason(report: MetaObject): string | undefined {
131-
if (report.isAbstract === true) return "Not served: the report is abstract";
132-
const source = reportReadSource(report);
133-
if (source === undefined) return "Not served: declares no view source";
134-
if (source.effectiveKind !== SOURCE_KIND_VIEW) {
135-
return `Not served: its source is a ${source.effectiveKind}, not a view`;
136-
}
137-
return undefined;
138-
}
139-
14044
/** A markdown table cell: a pipe would end the cell. */
14145
function cell(text: string): string {
14246
return text.replace(/\|/g, "\\|");
@@ -163,7 +67,7 @@ export function buildReportBlock(report: MetaObject, root: MetaRoot, layout: Out
16367
lines.push("", "| Column | Type | Nullable | Role | Definition |", "|---|---|---|---|---|");
16468
for (const f of shape.fields) {
16569
lines.push(
166-
`| ${tick(f.name)} | ${tick(reportFieldType(f))} | ${f.required ? "no" : "yes"} | ${f.role} | ${cell(describeReportField(f))} |`,
70+
`| ${tick(f.name)} | ${tick(reportFieldTypeName(f))} | ${f.required ? "no" : "yes"} | ${f.role} | ${cell(describeReportField(f))} |`,
16771
);
16872
}
16973
}
@@ -198,7 +102,7 @@ export function buildReportingBlock(entity: MetaObject, root: MetaRoot, layout:
198102
["Measures", members.filter((c) => c.type === TYPE_MEASURE).map((m) =>
199103
`- ${tick(m.name)} — ${describeMeasure(m)}`)],
200104
["Segments", members.filter((c) => c.type === TYPE_SEGMENT).map((s) =>
201-
`- ${tick(s.name)} — ${filterText(s.attr(REPORTING_ATTR_FILTER) ?? {})}`)],
105+
`- ${tick(s.name)} — ${describeSegment(s)}`)],
202106
["Reports", reportsFrom(entity, root)
203107
.sort((a, b) => a.name.localeCompare(b.name))
204108
.map((r) => `- [${r.name}](${docPageHref(layout, docPageNode(entity), docPageNode(r))})`)],

0 commit comments

Comments
 (0)