1818// `source.rdb @kind: view` (R5 allows one): that is the case that once leaked in C#, where
1919// it emitted a keyless DbSet, a GET route and a filter allowlist for an object with no fields.
2020//
21- // `meta docs` is still held to the Plan 1 rule here (controller ruling, 2026-10-03): every
22- // docs surface — model pages, agent pages, requirements, the HTML site, and the api surface
23- // — comes out identical with and without the reporting nodes, bar the one view entry.
21+ // `meta docs` documents reports since Plan 3 (Table G), and the last describe states the
22+ // difference exactly: a model page and a site page for every report, served or not; a
23+ // "Reporting" section on each entity that declares reporting nodes; one api unit, for the
24+ // served report alone; the schema page's one view entry. `agent/ui.md` does not move: no
25+ // UI tier is generated for a report. Everything else is byte-identical.
2426
2527import { describe , test , expect , beforeAll } from "bun:test" ;
2628import { mkdtempSync , mkdirSync , copyFileSync , rmSync , readFileSync , readdirSync , statSync } from "node:fs" ;
@@ -292,7 +294,7 @@ describe("FR-044 a sourceless report is inert in migrate; a view-backed report p
292294 } ) ;
293295} ) ;
294296
295- describe ( "FR-044 reporting nodes are inert in meta docs, bar the one view entry " , ( ) => {
297+ describe ( "FR-044 meta docs differs by exactly the report pages, the Reporting sections and one api unit " , ( ) => {
296298 /** Run `meta docs` over a project holding one variant, once per surface flag set, and
297299 * read back everything written. The project directory has the SAME basename for both
298300 * variants: the site stamps it into every page title. */
@@ -311,21 +313,101 @@ describe("FR-044 reporting nodes are inert in meta docs, bar the one view entry"
311313 const files : Record < string , string > = { } ;
312314 for ( const rel of walkFiles ( root ) ) {
313315 if ( rel . split ( sep ) [ 0 ] === "metaobjects" ) continue ;
314- files [ rel ] = readFileSync ( join ( root , rel ) , "utf8" ) ;
316+ files [ rel . split ( sep ) . join ( "/" ) ] = readFileSync ( join ( root , rel ) , "utf8" ) ;
315317 }
316318 return files ;
317319 } finally {
318320 rmSync ( parent , { recursive : true , force : true } ) ;
319321 }
320322 }
321323
322- test ( "model, agent, requirements and site output are identical" , async ( ) => {
324+ const REPORTS = [ "DailyRevenue" , "ProgramEngagement" , "StoreTotals" ] as const ;
325+ /** The entities that declare dimensions, measures or segments in the with-model. */
326+ const REPORTING_ENTITIES = [ "Purchase" , "WorkoutEvent" ] as const ;
327+ const SITE = "out--site/site" ;
328+ const SITE_PKG = `${ SITE } /acme/shop` ;
329+
330+ /** The lines of `after` that are not the next unmatched line of `before`: what was
331+ * inserted. Throws when `before` is not a subsequence of `after`, i.e. when a line
332+ * was removed or rewritten rather than added. */
333+ function insertedLines ( before : string , after : string ) : string [ ] {
334+ const want = before . split ( "\n" ) ;
335+ const added : string [ ] = [ ] ;
336+ let i = 0 ;
337+ for ( const line of after . split ( "\n" ) ) {
338+ if ( i < want . length && line === want [ i ] ) i ++ ;
339+ else added . push ( line ) ;
340+ }
341+ if ( i !== want . length ) throw new Error ( `a line was removed or rewritten: ${ JSON . stringify ( want [ i ] ) } ` ) ;
342+ return added ;
343+ }
344+
345+ test ( "model pages: a page per report, a Reports index list, a Reporting section on Purchase and WorkoutEvent" , async ( ) => {
323346 const expected = await docsOutput ( "without" ) ;
324347 const actual = await docsOutput ( "with" ) ;
325- expect ( Object . keys ( expected ) . some ( ( p ) => p . endsWith ( ".html" ) ) ) . toBe ( true ) ;
326- expect ( Object . keys ( expected ) . some ( ( p ) => p . endsWith ( ".md" ) ) ) . toBe ( true ) ;
327- expect ( Object . keys ( actual ) ) . toEqual ( Object . keys ( expected ) ) ;
328- expect ( actual ) . toEqual ( expected ) ;
348+ const model = ( files : Record < string , string > ) : string [ ] =>
349+ Object . keys ( files ) . filter ( ( p ) => p . startsWith ( "out/" ) ) ;
350+
351+ expect ( model ( actual ) . filter ( ( p ) => ! ( p in expected ) ) ) . toEqual ( REPORTS . map ( ( n ) => `out/${ n } .md` ) ) ;
352+ expect ( model ( expected ) . filter ( ( p ) => ! ( p in actual ) ) ) . toEqual ( [ ] ) ;
353+
354+ // A served report names its view; a sourceless one says it is not served (answer 7).
355+ expect ( actual [ "out/StoreTotals.md" ] ) . toContain ( "**View:** `v_store_totals`" ) ;
356+ for ( const name of SOURCELESS_REPORTS ) {
357+ expect ( actual [ `out/${ name } .md` ] ) . toContain ( "**View:** Not served: declares no view source" ) ;
358+ }
359+
360+ for ( const path of model ( expected ) ) {
361+ const before = expected [ path ] ! ;
362+ const after = actual [ path ] ! ;
363+ if ( path === "out/README.md" ) {
364+ // The index gains the Reports list and nothing else: no entity entry and no
365+ // diagram line moves.
366+ expect ( insertedLines ( before , after ) ) . toEqual ( [ "## Reports" , "" , ...REPORTS . map ( ( n ) => `- [${ n } ](./${ n } .md)` ) , "" ] ) ;
367+ } else if ( REPORTING_ENTITIES . some ( ( e ) => path === `out/${ e } .md` ) ) {
368+ // The page is what it was, with the Reporting section appended.
369+ expect ( after . startsWith ( before + "\n## Reporting\n" ) ) . toBe ( true ) ;
370+ } else {
371+ expect ( { path, content : after } ) . toEqual ( { path, content : before } ) ;
372+ }
373+ }
374+ } ) ;
375+
376+ test ( "agent and requirements output (no gen config) is identical" , async ( ) => {
377+ const expected = await docsOutput ( "without" ) ;
378+ const actual = await docsOutput ( "with" ) ;
379+ const other = ( files : Record < string , string > ) : Record < string , string > =>
380+ Object . fromEntries ( Object . entries ( files ) . filter ( ( [ p ] ) => ! p . startsWith ( "out/" ) && ! p . startsWith ( `${ SITE } /` ) ) ) ;
381+ expect ( other ( actual ) ) . toEqual ( other ( expected ) ) ;
382+ } ) ;
383+
384+ test ( "site: a page per report, the Reporting sections, and no page lost" , async ( ) => {
385+ const expected = await docsOutput ( "without" ) ;
386+ const actual = await docsOutput ( "with" ) ;
387+ const site = ( files : Record < string , string > ) : string [ ] =>
388+ Object . keys ( files ) . filter ( ( p ) => p . startsWith ( `${ SITE } /` ) ) ;
389+ expect ( site ( expected ) . some ( ( p ) => p . endsWith ( ".html" ) ) ) . toBe ( true ) ;
390+
391+ expect ( site ( actual ) . filter ( ( p ) => ! ( p in expected ) ) ) . toEqual ( REPORTS . map ( ( n ) => `${ SITE_PKG } /${ n } .html` ) ) ;
392+ expect ( site ( expected ) . filter ( ( p ) => ! ( p in actual ) ) ) . toEqual ( [ ] ) ;
393+
394+ expect ( actual [ `${ SITE_PKG } /StoreTotals.html` ] ) . toContain ( "<code>v_store_totals</code>" ) ;
395+ for ( const name of SOURCELESS_REPORTS ) {
396+ expect ( actual [ `${ SITE_PKG } /${ name } .html` ] ) . toContain ( "Not served: declares no view source" ) ;
397+ }
398+ for ( const name of REPORTING_ENTITIES ) {
399+ expect ( actual [ `${ SITE_PKG } /${ name } .html` ] ) . toContain ( 'id="s-reporting"' ) ;
400+ expect ( expected [ `${ SITE_PKG } /${ name } .html` ] ) . not . toContain ( 'id="s-reporting"' ) ;
401+ }
402+ // An entity with no reporting nodes changes by its sidebar alone: the three report
403+ // links, in the package it shares with them.
404+ const added = insertedLines ( expected [ `${ SITE_PKG } /Program.html` ] ! , actual [ `${ SITE_PKG } /Program.html` ] ! ) ;
405+ expect ( added . length ) . toBe ( REPORTS . length ) ;
406+ for ( const [ i , name ] of REPORTS . entries ( ) ) expect ( added [ i ] ) . toContain ( `${ name } .html` ) ;
407+ // The stylesheet and script are the same bytes either way.
408+ for ( const asset of [ `${ SITE } /assets/site.css` , `${ SITE } /assets/site.js` ] ) {
409+ expect ( actual [ asset ] ) . toBe ( expected [ asset ] ! ) ;
410+ }
329411 } ) ;
330412
331413 /** The GenContext `meta docs` builds, with a full generator suite wired: the Hono
@@ -351,7 +433,7 @@ describe("FR-044 reporting nodes are inert in meta docs, bar the one view entry"
351433 expect ( actual ) . toEqual ( expected ) ;
352434 } ;
353435
354- test ( "the api surface is identical " , async ( ) => {
436+ test ( "the api surface gains one unit, for the served report: its row model, list query and GET " , async ( ) => {
355437 // `meta docs --api` materializes only with a loadable gen config, which a temp project
356438 // cannot import; so drive the generator with the GenContext `meta docs` builds.
357439 const api = async ( metadata : MetaRoot ) : Promise < Record < string , string > > => {
@@ -361,7 +443,36 @@ describe("FR-044 reporting nodes are inert in meta docs, bar the one view entry"
361443 } ;
362444 const expected = await api ( withoutReporting ) ;
363445 expect ( Object . keys ( expected ) . length ) . toBeGreaterThan ( 2 ) ;
364- compare ( expected , await api ( withReporting ) ) ;
446+ const actual = await api ( withReporting ) ;
447+
448+ // One new page, and no page for a report that is not served (answer 7).
449+ expect ( Object . keys ( actual ) . filter ( ( p ) => ! ( p in expected ) ) ) . toEqual ( [ "api/StoreTotals.md" ] ) ;
450+ expect ( Object . keys ( expected ) . filter ( ( p ) => ! ( p in actual ) ) ) . toEqual ( [ ] ) ;
451+
452+ // Answer 6: the unit is the row model, the list query function and GET <served path>
453+ // (once per wired route surface). No by-id, no write, no schema, no hook.
454+ const page = actual [ "api/StoreTotals.md" ] ! ;
455+ expect ( page . split ( "\n" ) . filter ( ( l ) => l . startsWith ( "### " ) ) ) . toEqual ( [
456+ "### `interface StoreTotals`" ,
457+ "### `listStoreTotals(db: Db, opts?: { limit?: number; offset?: number }): Promise<StoreTotals[]>`" ,
458+ "### `GET /api/store_totals`" ,
459+ "### `GET /api/store_totals`" ,
460+ ] ) ;
461+ expect ( page ) . not . toMatch ( / \b u s e [ A - Z ] \w * / ) ;
462+
463+ // Every other page is byte-identical, bar the two indexes, which gain the report's
464+ // entry and lose nothing.
465+ for ( const [ path , before ] of Object . entries ( expected ) ) {
466+ const after = actual [ path ] ! ;
467+ if ( path === "api/README.md" || path === "api/AGENT-API.md" ) {
468+ const added = after . split ( "\n" ) . filter ( ( l ) => ! before . split ( "\n" ) . includes ( l ) ) ;
469+ expect ( added . length ) . toBeGreaterThan ( 0 ) ;
470+ for ( const l of added ) expect ( l ) . toContain ( "StoreTotals" ) ;
471+ for ( const name of SOURCELESS_REPORTS ) expect ( after ) . not . toContain ( name ) ;
472+ continue ;
473+ }
474+ expect ( { path, content : after } ) . toEqual ( { path, content : before } ) ;
475+ }
365476 } ) ;
366477
367478 test ( "the agent surface differs only by the schema page's v_store_totals view, with the UI tier wired" , async ( ) => {
@@ -407,5 +518,8 @@ describe("FR-044 reporting nodes are inert in meta docs, bar the one view entry"
407518 const rest = { ...expected } ;
408519 delete rest [ schemaPage ] ;
409520 compare ( rest , actual ) ;
521+ // Answer 6: no UI tier is generated for a report, so the UI page names none.
522+ const uiPage = Object . keys ( actual ) . find ( ( p ) => p . endsWith ( "ui.md" ) ) ! ;
523+ for ( const name of [ "StoreTotals" , ...SOURCELESS_REPORTS ] ) expect ( actual [ uiPage ] ) . not . toContain ( name ) ;
410524 } ) ;
411525} ) ;
0 commit comments