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
1513import {
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";
4436import { docPageHref , docPageNode , effectivePackage } from "../docs-paths.js" ;
4537import { 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) . */
4840function 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. */
14145function 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