@intellectual-frontiers/docs 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +75 -0
- package/README.md +8 -2
- package/dist/build.d.ts +63 -0
- package/dist/build.js +103 -0
- package/dist/check.d.ts +63 -0
- package/dist/check.js +54 -0
- package/dist/cli.d.ts +51 -0
- package/dist/cli.js +165 -0
- package/dist/config.d.ts +196 -0
- package/dist/config.js +229 -0
- package/dist/emit/html.d.ts +67 -0
- package/dist/emit/html.js +338 -0
- package/dist/emit/markdown.d.ts +19 -0
- package/dist/emit/markdown.js +124 -0
- package/dist/emit/search.d.ts +15 -0
- package/dist/emit/search.js +29 -0
- package/dist/extract/api.d.ts +74 -0
- package/dist/extract/api.js +261 -0
- package/dist/extract/specs.d.ts +141 -0
- package/dist/extract/specs.js +208 -0
- package/dist/highlight.d.ts +22 -0
- package/dist/highlight.js +77 -0
- package/dist/layered.d.ts +94 -0
- package/dist/layered.js +14 -0
- package/dist/lens/guides.d.ts +23 -0
- package/dist/lens/guides.js +49 -0
- package/dist/lens/layered.d.ts +16 -0
- package/dist/lens/layered.js +354 -0
- package/dist/lens/program.d.ts +23 -0
- package/dist/lens/program.js +124 -0
- package/dist/lens/releases.d.ts +10 -0
- package/dist/lens/releases.js +37 -0
- package/dist/lens.d.ts +30 -0
- package/dist/lens.js +1 -0
- package/dist/links.d.ts +96 -0
- package/dist/links.js +182 -0
- package/dist/main.d.ts +1 -0
- package/dist/main.js +12 -0
- package/dist/markdown.d.ts +43 -0
- package/dist/markdown.js +301 -0
- package/dist/mod.d.ts +32 -0
- package/dist/mod.js +9 -0
- package/dist/model.d.ts +159 -0
- package/dist/model.js +39 -0
- package/dist/pages/api.d.ts +41 -0
- package/dist/pages/api.js +162 -0
- package/dist/pages/areas.d.ts +39 -0
- package/dist/pages/areas.js +119 -0
- package/dist/pages/overview.d.ts +24 -0
- package/dist/pages/overview.js +283 -0
- package/dist/pages/specs.d.ts +31 -0
- package/dist/pages/specs.js +358 -0
- package/dist/site.d.ts +31 -0
- package/dist/site.js +288 -0
- package/dist/sources.d.ts +53 -0
- package/dist/sources.js +159 -0
- package/dist/theme/site.css +275 -0
- package/dist/theme/site.js +174 -0
- package/dist/tsdoc.d.ts +67 -0
- package/dist/tsdoc.js +94 -0
- package/ifc-docs.mjs +4 -0
- package/package.json +66 -4
- package/src/build.ts +117 -0
- package/src/check.ts +84 -0
- package/src/cli.ts +145 -0
- package/src/config.ts +370 -0
- package/src/emit/html.ts +398 -0
- package/src/emit/markdown.ts +129 -0
- package/src/emit/search.ts +38 -0
- package/src/extract/api.ts +297 -0
- package/src/extract/specs.ts +299 -0
- package/src/highlight.ts +98 -0
- package/src/layered.ts +102 -0
- package/src/lens/guides.ts +70 -0
- package/src/lens/layered.ts +341 -0
- package/src/lens/program.ts +137 -0
- package/src/lens/releases.ts +54 -0
- package/src/lens.ts +34 -0
- package/src/links.ts +234 -0
- package/src/main.ts +12 -0
- package/src/markdown.ts +320 -0
- package/src/mod.ts +53 -0
- package/src/model.ts +154 -0
- package/src/pages/api.ts +179 -0
- package/src/pages/areas.ts +133 -0
- package/src/pages/overview.ts +276 -0
- package/src/pages/specs.ts +366 -0
- package/src/site.ts +285 -0
- package/src/sources.ts +157 -0
- package/src/theme/site.css +275 -0
- package/src/theme/site.js +174 -0
- package/src/tsdoc.ts +131 -0
package/src/highlight.ts
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* Code highlighted when the site is built (commons 0011-documentation FR-017, FR-037), so that a page needs no script to colour it: Shiki, with the grammars of the languages the site shows (TypeScript, SQL, shell, TOML, JSON,
|
|
4
|
+
* Turtle and YAML) and one theme for the light scheme and one for the dark, on the Oniguruma engine (WebAssembly, so the same on Bun and Node, with no native part). Each coloured run is a span whose two colours
|
|
5
|
+
* are custom properties (`--l`, `--d`), which the stylesheet picks between by the same rule as the rest of the site's colours; a run in the theme's own foreground is plain text. Text and diagrams are not coloured.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { highlightedHtml } from "./highlight.ts";
|
|
10
|
+
* highlightedHtml("const a = 1;", "ts");
|
|
11
|
+
* // '<span class="t" style="--l:#D73A49;--d:#F97583">const</span> a <span ...'
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
import { createHighlighterCore } from "shiki/core";
|
|
17
|
+
import { createOnigurumaEngine } from "shiki/engine/oniguruma";
|
|
18
|
+
import json from "shiki/langs/json.mjs";
|
|
19
|
+
import shellscript from "shiki/langs/shellscript.mjs";
|
|
20
|
+
import sql from "shiki/langs/sql.mjs";
|
|
21
|
+
import toml from "shiki/langs/toml.mjs";
|
|
22
|
+
import turtle from "shiki/langs/turtle.mjs";
|
|
23
|
+
import typescript from "shiki/langs/typescript.mjs";
|
|
24
|
+
import yaml from "shiki/langs/yaml.mjs";
|
|
25
|
+
import githubDark from "shiki/themes/github-dark.mjs";
|
|
26
|
+
import githubLight from "shiki/themes/github-light.mjs";
|
|
27
|
+
import type { Lang } from "./model.ts";
|
|
28
|
+
|
|
29
|
+
/** The themes of the two schemes. */
|
|
30
|
+
export const THEMES = { light: "github-light", dark: "github-dark" } as const;
|
|
31
|
+
|
|
32
|
+
/** The grammar each language of the site is read with; those not here are left plain. */
|
|
33
|
+
const GRAMMAR: Readonly<Partial<Record<Lang, string>>> = { ts: "typescript", sql: "sql", sh: "shellscript", toml: "toml", json: "json", turtle: "turtle", yaml: "yaml" };
|
|
34
|
+
|
|
35
|
+
/** Shiki, with the Oniguruma engine (WebAssembly, the same on Bun and Node) made once when the module is read; reading code with it is then synchronous. */
|
|
36
|
+
const highlighter = await createHighlighterCore({ themes: [githubLight, githubDark], langs: [typescript, sql, shellscript, toml, json, turtle, yaml], engine: createOnigurumaEngine(import("shiki/wasm")) });
|
|
37
|
+
|
|
38
|
+
/** Code longer than this many characters is shown plain: a computed type of thousands of characters costs more to colour than it helps a reader, and the page folds it. */
|
|
39
|
+
export const LONGEST_COLOURED = 6000;
|
|
40
|
+
|
|
41
|
+
// The first reading of a grammar by the engine can give runs that are not cut at its tokens (a comment left in the text before it). A reading of each grammar here, whose result is not used, makes the readings that are
|
|
42
|
+
// used the same whatever came first; the test of the highlighter holds this.
|
|
43
|
+
for (const [lang, sample] of [["typescript", 'const a = f("x"); // c'], ["sql", "SELECT 1 -- c"], ["shellscript", 'echo "$A" # c'], ["toml", '[a]\nb = "x" # c'], ["json", '{"a": [1, true, null]}'], ["turtle", 'a:b a c:D ; d:e "f"@en .'], ["yaml", "a: 1\nb: [x] # c"]] as const) {
|
|
44
|
+
for (const theme of [THEMES.light, THEMES.dark]) highlighter.codeToTokensBase(sample, { lang, theme });
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const escapeHtml = (s: string): string => s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
|
48
|
+
|
|
49
|
+
/** The colours that are the themes' own text, which are left as plain text. */
|
|
50
|
+
const FOREGROUND = { light: githubLight.colors?.["editor.foreground"]?.toLowerCase() ?? "#24292e", dark: githubDark.colors?.["editor.foreground"]?.toLowerCase() ?? "#e1e4e8" };
|
|
51
|
+
|
|
52
|
+
/** One coloured run of code. */
|
|
53
|
+
export interface Run {
|
|
54
|
+
readonly text: string;
|
|
55
|
+
/** Its colour in the light scheme and in the dark, or none where it is the theme's own text. */
|
|
56
|
+
readonly light?: string;
|
|
57
|
+
readonly dark?: string;
|
|
58
|
+
/** Italic, bold. */
|
|
59
|
+
readonly italic: boolean;
|
|
60
|
+
readonly bold: boolean;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** The runs of the lines of code, by line, in the language given; one plain run for a language that is not coloured. */
|
|
64
|
+
export function runs(code: string, lang: Lang): readonly (readonly Run[])[] {
|
|
65
|
+
const grammar = GRAMMAR[lang];
|
|
66
|
+
if (grammar === undefined || code.length > LONGEST_COLOURED) return code.split("\n").map((line) => [{ text: line, italic: false, bold: false }]);
|
|
67
|
+
const lines = highlighter.codeToTokensWithThemes(code, { lang: grammar, themes: THEMES });
|
|
68
|
+
return lines.map((line) => {
|
|
69
|
+
const out: Run[] = [];
|
|
70
|
+
for (const t of line) {
|
|
71
|
+
const l = t.variants["light"];
|
|
72
|
+
const d = t.variants["dark"];
|
|
73
|
+
const plain = (l?.color ?? "").toLowerCase() === FOREGROUND.light && (d?.color ?? "").toLowerCase() === FOREGROUND.dark && ((l?.fontStyle ?? 0) | (d?.fontStyle ?? 0)) === 0;
|
|
74
|
+
const run: Run = plain
|
|
75
|
+
? { text: t.content, italic: false, bold: false }
|
|
76
|
+
: { text: t.content, ...(l?.color === undefined ? {} : { light: l.color }), ...(d?.color === undefined ? {} : { dark: d.color }), italic: (((l?.fontStyle ?? 0) | (d?.fontStyle ?? 0)) & 1) !== 0, bold: (((l?.fontStyle ?? 0) | (d?.fontStyle ?? 0)) & 2) !== 0 };
|
|
77
|
+
const last = out[out.length - 1];
|
|
78
|
+
if (last !== undefined && last.light === run.light && last.dark === run.dark && last.italic === run.italic && last.bold === run.bold) out[out.length - 1] = { ...last, text: last.text + run.text };
|
|
79
|
+
else out.push(run);
|
|
80
|
+
}
|
|
81
|
+
return out;
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Code as HTML: coloured runs as spans with their two colours, the rest as escaped text. */
|
|
86
|
+
export function highlightedHtml(code: string, lang: Lang): string {
|
|
87
|
+
return runs(code, lang)
|
|
88
|
+
.map((line) =>
|
|
89
|
+
line
|
|
90
|
+
.map((r) =>
|
|
91
|
+
r.light === undefined && r.dark === undefined
|
|
92
|
+
? escapeHtml(r.text)
|
|
93
|
+
: `<span class="t${r.italic ? " i" : ""}${r.bold ? " b" : ""}" style="--l:${r.light ?? "inherit"};--d:${r.dark ?? "inherit"}">${escapeHtml(r.text)}</span>`
|
|
94
|
+
)
|
|
95
|
+
.join("")
|
|
96
|
+
)
|
|
97
|
+
.join("\n");
|
|
98
|
+
}
|
package/src/layered.ts
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The layered model (commons 0011-documentation FR-029): what a library that is built in layers (governance, logical, physical or surface) gives the generator to document it, as plain data and types only. A library keeps
|
|
4
|
+
* its own pure builder that makes a `LayeredModel` from its values; the generator's lens turns it into pages, a Markdown twin for each and the model as JSON. The generator depends on no library it shows: a builder's
|
|
5
|
+
* result is checked against these types where a configuration passes it, and by their shape alone.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* An element has a stable id (the same across builds, the key of a link and of a diff), a kind, a name, a definition (the words the model gives it), where it is written (a source location) and what is said of it as
|
|
9
|
+
* properties. A trace edge says that an element of one layer is made into an element of the next: a governance concept into a table, a table into the statements that make it and into the typed table that reads it.
|
|
10
|
+
* Operations are an element kind of their own that several libraries share: a governance action, a headless verb, and what they become (a SQL routine, a command, a tool, a route).
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** Where an element is written: a file of the repository and a line. */
|
|
16
|
+
export interface SourceLocation {
|
|
17
|
+
/** The path from the repository's root. */
|
|
18
|
+
readonly file: string;
|
|
19
|
+
/** The line, from 1, where it is declared. */
|
|
20
|
+
readonly line?: number;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** A layer of a model: what it is called, what it is for and the kinds of element it holds. */
|
|
24
|
+
export interface Layer {
|
|
25
|
+
/** Its name, as `governance`. */
|
|
26
|
+
readonly id: string;
|
|
27
|
+
/** What the layer is, in a sentence. */
|
|
28
|
+
readonly title: string;
|
|
29
|
+
/** What a reader may and may not do at this layer, in a sentence or two. */
|
|
30
|
+
readonly summary: string;
|
|
31
|
+
/** The kinds of element it holds. */
|
|
32
|
+
readonly kinds: readonly string[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** One thing a layer says: a module, a concept, an attribute, a table, a column, a statement, a command. */
|
|
36
|
+
export interface LayerElement {
|
|
37
|
+
/** Stable across builds: `governance:identity/principal`, `logical:table:principal`. */
|
|
38
|
+
readonly id: string;
|
|
39
|
+
/** The layer it is in. */
|
|
40
|
+
readonly layer: string;
|
|
41
|
+
/** What kind of thing it is, one of the layer's kinds. */
|
|
42
|
+
readonly kind: string;
|
|
43
|
+
/** What it is called. */
|
|
44
|
+
readonly name: string;
|
|
45
|
+
/** The words the model gives it; empty where it has none, which is a finding. */
|
|
46
|
+
readonly definition: string;
|
|
47
|
+
/** The element that holds it (an attribute's concept, a column's table). */
|
|
48
|
+
readonly parent?: string;
|
|
49
|
+
/** Where it is written. */
|
|
50
|
+
readonly source?: SourceLocation;
|
|
51
|
+
/** What is said of it, by name: types, multiplicity, annotations, the text of a statement. */
|
|
52
|
+
readonly properties: { readonly [name: string]: string | number | boolean | readonly string[] | null };
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** An element of one layer made into an element of another. */
|
|
56
|
+
export interface TraceEdge {
|
|
57
|
+
readonly from: string;
|
|
58
|
+
readonly to: string;
|
|
59
|
+
/** How: `projects to`, `written as`, `read by`. */
|
|
60
|
+
readonly how: string;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** What the model's builder found wrong. */
|
|
64
|
+
export interface LayeredFinding {
|
|
65
|
+
/** A rule's code, as `undescribed`. */
|
|
66
|
+
readonly rule: string;
|
|
67
|
+
readonly element: string;
|
|
68
|
+
readonly message: string;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** What a model applies to. */
|
|
72
|
+
export interface LayeredSubject {
|
|
73
|
+
/** Its id. */
|
|
74
|
+
readonly id: string;
|
|
75
|
+
/** Its title. */
|
|
76
|
+
readonly title: string;
|
|
77
|
+
/** What its models apply to, in a sentence. */
|
|
78
|
+
readonly about: string;
|
|
79
|
+
/** Its place among the subjects: lower first. */
|
|
80
|
+
readonly order: number;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/** A model that is built in layers, as the generator documents it. */
|
|
84
|
+
export interface LayeredModel {
|
|
85
|
+
/** Its name and the library it is of, as `arca`, `data`. */
|
|
86
|
+
readonly name: string;
|
|
87
|
+
readonly library: string;
|
|
88
|
+
readonly title: string;
|
|
89
|
+
readonly summary: string;
|
|
90
|
+
/** What the model applies to, where it has a subject: models are grouped by it. */
|
|
91
|
+
readonly subject?: LayeredSubject;
|
|
92
|
+
readonly layers: readonly Layer[];
|
|
93
|
+
readonly elements: readonly LayerElement[];
|
|
94
|
+
readonly trace: readonly TraceEdge[];
|
|
95
|
+
readonly findings: readonly LayeredFinding[];
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** A function that makes the layered models of a repository, and may be told where each element is written. */
|
|
99
|
+
export type LayeredSource = (locate: Locate) => Promise<readonly LayeredModel[]> | readonly LayeredModel[];
|
|
100
|
+
|
|
101
|
+
/** Where a value is written (and, for a member of it such as an attribute of a concept, where that is), found by the lens from the exports it knows: by the value's identity. */
|
|
102
|
+
export type Locate = (value: unknown, member?: string) => SourceLocation | undefined;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-002
|
|
2
|
+
/**
|
|
3
|
+
* The guides lens (commons 0011-documentation FR-032): pages that people write in Markdown for the reader who is new to a repository (a path for each kind of reader, the ideas the repository is built on, and how to do the
|
|
4
|
+
* common things), kept in the repository beside the code and checked like every page: its citations of a specification and its links to a file or a folder become links, an unknown requirement is a finding, and a page names
|
|
5
|
+
* the section and group it is in. The lens knows nothing of what the guides say.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { fs, path } from "@intellectual-frontiers/system";
|
|
10
|
+
import type { Lens, LensPages, Section } from "../mod.ts";
|
|
11
|
+
|
|
12
|
+
/** The first sentence of a text, cut at 200 characters. */
|
|
13
|
+
function firstSentence(t: string, max = 200): string {
|
|
14
|
+
const flat = t.replace(/\s+/g, " ").trim();
|
|
15
|
+
const s = /^(.+?[.!?])(\s|$)/.exec(flat)?.[1] ?? flat;
|
|
16
|
+
return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** One guide: its Markdown file and where it is in the site. */
|
|
20
|
+
export interface GuideSpec {
|
|
21
|
+
/** The Markdown file, from the repository's root. Its first heading is the page's title. */
|
|
22
|
+
readonly file: string;
|
|
23
|
+
/** The page's address on the site, as `start/new-developer.html`. */
|
|
24
|
+
readonly path: string;
|
|
25
|
+
/** The section it is in. */
|
|
26
|
+
readonly section: Extract<Section, "start" | "concepts" | "howto">;
|
|
27
|
+
/** The group of the navigation it is in. */
|
|
28
|
+
readonly group: string;
|
|
29
|
+
/** Its place in its group, lowest first. */
|
|
30
|
+
readonly order: number;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** What the guides lens is given. */
|
|
34
|
+
export interface GuidesOptions {
|
|
35
|
+
/** Its name, which the build reports it by. */
|
|
36
|
+
readonly name: string;
|
|
37
|
+
/** The guides, which include the index page of each section it uses. */
|
|
38
|
+
readonly guides: readonly GuideSpec[];
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** The guides lens. */
|
|
42
|
+
export function guidesLens(options: GuidesOptions): Lens {
|
|
43
|
+
return {
|
|
44
|
+
name: options.name,
|
|
45
|
+
read: async (b): Promise<LensPages> => {
|
|
46
|
+
const texts = new Map<string, string>();
|
|
47
|
+
for (const g of options.guides) {
|
|
48
|
+
try {
|
|
49
|
+
texts.set(g.file, await fs.readTextFile(path.join(b.root, g.file)));
|
|
50
|
+
} catch {
|
|
51
|
+
b.found.push({ where: g.file, problem: { kind: "undescribed", entity: `the guide ${g.file}, which the guides lens is told of, cannot be read` } });
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
for (const g of options.guides) if (texts.has(g.file)) b.files.set(g.file, g.path);
|
|
55
|
+
return (build, after) => {
|
|
56
|
+
for (const g of options.guides) {
|
|
57
|
+
const text = texts.get(g.file);
|
|
58
|
+
if (text === undefined) continue;
|
|
59
|
+
const m = /^#\s+(.+)\n+/.exec(text);
|
|
60
|
+
const title = m?.[1]?.trim() ?? g.path;
|
|
61
|
+
const body = m === null ? text : text.slice(m[0].length);
|
|
62
|
+
const blocks = build.md(body, { page: g.path, file: g.file });
|
|
63
|
+
const lead = /^(?![#>|`\-*\d])[^\n]+/m.exec(body)?.[0] ?? title;
|
|
64
|
+
build.add({ path: g.path, title, description: firstSentence(lead.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*_]/g, ""), 200), section: g.section, group: g.group, order: g.order, blocks });
|
|
65
|
+
}
|
|
66
|
+
return after;
|
|
67
|
+
};
|
|
68
|
+
},
|
|
69
|
+
};
|
|
70
|
+
}
|
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-002
|
|
2
|
+
/**
|
|
3
|
+
* The layered-model lens (commons 0011-documentation FR-029): the models of a library that is built in layers (governance, logical, physical or surface), as pages for a developer and an agent and as a Markdown twin
|
|
4
|
+
* and a JSON file for each. It is given a function that makes `LayeredModel` values (a library's own pure builder, such as commons data's `describeModels`) and knows nothing of the library: what the models say
|
|
5
|
+
* is read from the values, where they are written is found from the files that export them (by the identity of the value), and each page says which layer it is of and how that layer is used.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Pages: the models and the layers (what each layer is for, which code writes it, what may be edited, how to change a model and regenerate what follows); for each model its overview and a diagram of its concepts; for each
|
|
9
|
+
* concept its definition, where it is written (a link to the line), its attributes and relationships, what it projects to and the SQL and the typed table it is written as; for each code list its codes; and registers of
|
|
10
|
+
* what the models annotate (personal data, security, ownership). Every element has an anchor that is its id, so that a link and a diff can name it.
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import { fs, path } from "@intellectual-frontiers/system";
|
|
15
|
+
import { type Badge, type Block, type Build, type Href, type Inline, type LayerElement, type LayeredModel, type LayeredSource, type Lens, type LensPages, type Page, type SiteFile, slugOf, type SourceLocation } from "../mod.ts";
|
|
16
|
+
|
|
17
|
+
/** What the lens is given. */
|
|
18
|
+
export interface LayeredLensOptions {
|
|
19
|
+
/** Its name, which the build reports it by. */
|
|
20
|
+
readonly name: string;
|
|
21
|
+
/** The group of the Models section the pages are in. */
|
|
22
|
+
readonly group?: string;
|
|
23
|
+
/** Makes the models; it is told how to find where a value is written. */
|
|
24
|
+
readonly source: LayeredSource;
|
|
25
|
+
/** The files, from the repository's root, whose exports are the values the models are made of: where an element is written is found from them. */
|
|
26
|
+
readonly exports: readonly string[];
|
|
27
|
+
/** The command that regenerates what follows the top layer, and the file a person edits first, written into the page that says how to change a model. */
|
|
28
|
+
readonly regenerate?: readonly string[];
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** A name as a path: `identityAgent` is `identity-agent`. */
|
|
32
|
+
const kebab = (name: string): string => slugOf(name.replace(/([a-z0-9])([A-Z])/g, "$1-$2"));
|
|
33
|
+
|
|
34
|
+
const t = (text: string): Inline => ({ kind: "text", text });
|
|
35
|
+
const c = (text: string): Inline => ({ kind: "code", text });
|
|
36
|
+
const para = (...inlines: Inline[]): Block => ({ kind: "paragraph", inlines });
|
|
37
|
+
const heading = (level: 2 | 3 | 4, text: string, id = slugOf(text)): Block => ({ kind: "heading", level, id, text: [t(text)] });
|
|
38
|
+
const badge = (text: string, tone: Badge["tone"] = "neutral"): Badge => ({ text, tone });
|
|
39
|
+
const page = (b: Build, p: Omit<Page, "section">): void => b.add({ ...p, section: "models" });
|
|
40
|
+
|
|
41
|
+
/** The line of the declaration of an export in a file, from 1. */
|
|
42
|
+
function lineOf(text: string, name: string): number | undefined {
|
|
43
|
+
const lines = text.split("\n");
|
|
44
|
+
const i = lines.findIndex((l) => new RegExp(`^export (const|function|let) ${name}\\b`).test(l));
|
|
45
|
+
return i < 0 ? undefined : i + 1;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The line of a member (`attribute:` in an object) after the declaration, from 1. */
|
|
49
|
+
function memberLine(text: string, from: number, member: string): number | undefined {
|
|
50
|
+
const lines = text.split("\n");
|
|
51
|
+
for (let i = from; i < Math.min(lines.length, from + 400); i++) if (new RegExp(`^\\s*${member}\\s*[:(]`).test(lines[i] ?? "")) return i + 1;
|
|
52
|
+
return undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/** A locator that also finds the line of a member, from the same files. */
|
|
56
|
+
async function withMembers(b: Build, files: readonly string[]): Promise<(value: unknown, member?: string) => SourceLocation | undefined> {
|
|
57
|
+
const known = new Map<unknown, { file: string; line?: number; text: string }>();
|
|
58
|
+
for (const file of files) {
|
|
59
|
+
let text: string;
|
|
60
|
+
try {
|
|
61
|
+
text = await fs.readTextFile(path.join(b.root, file));
|
|
62
|
+
} catch {
|
|
63
|
+
b.found.push({ where: file, problem: { kind: "undescribed", entity: `the file ${file}, which the layered lens is told exports models, cannot be read` } });
|
|
64
|
+
continue;
|
|
65
|
+
}
|
|
66
|
+
const mod = (await import(path.join(b.root, file))) as Record<string, unknown>;
|
|
67
|
+
for (const [name, value] of Object.entries(mod)) {
|
|
68
|
+
if ((typeof value !== "object" && typeof value !== "function") || value === null) continue;
|
|
69
|
+
const line = lineOf(text, name);
|
|
70
|
+
// a file that declares a value is where it is written; one that re-exports it is not
|
|
71
|
+
if (known.has(value) && (known.get(value)?.line !== undefined || line === undefined)) continue;
|
|
72
|
+
known.set(value, { file, text, ...(line === undefined ? {} : { line }) });
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
return (value, member) => {
|
|
76
|
+
const k = known.get(value);
|
|
77
|
+
if (k === undefined) return undefined;
|
|
78
|
+
if (member === undefined || k.line === undefined) return { file: k.file, ...(k.line === undefined ? {} : { line: k.line }) };
|
|
79
|
+
const l = memberLine(k.text, k.line, member);
|
|
80
|
+
return { file: k.file, line: l ?? k.line };
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const sourceHref = (b: Build, s: SourceLocation): Href => ({ kind: "external", url: `${b.config.repository}/blob/${b.config.branch}/${s.file}${s.line === undefined ? "" : `#L${s.line}`}` });
|
|
85
|
+
const sourceLink = (b: Build, s: SourceLocation | undefined): Inline[] => (s === undefined ? [] : [{ kind: "link", href: sourceHref(b, s), children: [c(`${s.file}${s.line === undefined ? "" : `:${s.line}`}`)] }]);
|
|
86
|
+
|
|
87
|
+
/** An example of reading a typed table: the first two columns, as a program writes their keys. */
|
|
88
|
+
function typedExample(name: string, from: string, columns: readonly string[]): string {
|
|
89
|
+
const key = (k: string): string => k.replace(/_([a-z])/g, (_x, ch: string) => ch.toUpperCase());
|
|
90
|
+
const picked = columns.slice(0, 2).map((k) => `${key(k)}: s.${name}.${key(k)}`).join(", ");
|
|
91
|
+
// the import lines are made from pieces, so that the packer does not read these strings as imports of this module
|
|
92
|
+
const importOf = (what: string, source: string): string => ["import", `{ ${what} }`, "from", `"${source}";`].join(" ");
|
|
93
|
+
return [importOf("from", "@intellectual-frontiers/data/sql/typed"), importOf(name, from), "", `const rows = await from(${name}).select((s) => ({ ${picked} })).run(runner);`].join("\n");
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const prop = (e: LayerElement, k: string): string => {
|
|
97
|
+
const v = e.properties[k];
|
|
98
|
+
return Array.isArray(v) ? v.join(", ") : v === null || v === undefined ? "" : String(v);
|
|
99
|
+
};
|
|
100
|
+
const list = (e: LayerElement, k: string): readonly string[] => {
|
|
101
|
+
const v = e.properties[k];
|
|
102
|
+
return Array.isArray(v) ? (v as readonly string[]) : [];
|
|
103
|
+
};
|
|
104
|
+
|
|
105
|
+
/** The layered-model lens. */
|
|
106
|
+
export function layeredLens(options: LayeredLensOptions): Lens {
|
|
107
|
+
let models: readonly LayeredModel[] = [];
|
|
108
|
+
const group = options.group ?? "Models";
|
|
109
|
+
return {
|
|
110
|
+
name: options.name,
|
|
111
|
+
read: async (b): Promise<LensPages> => {
|
|
112
|
+
models = await options.source(await withMembers(b, options.exports));
|
|
113
|
+
const byId = new Map<string, { model: LayeredModel; element: LayerElement }>();
|
|
114
|
+
for (const m of models) for (const e of m.elements) byId.set(e.id, { model: m, element: e });
|
|
115
|
+
return (build, after) => {
|
|
116
|
+
const conceptPage = (m: LayeredModel, name: string): string => `models/${kebab(m.name)}/${kebab(name)}.html`;
|
|
117
|
+
const tableOfConcept = new Map<string, string>();
|
|
118
|
+
for (const m of models) for (const tr of m.trace) if (tr.how === "projects to" && tr.from.startsWith("governance:concept/") && tr.to.startsWith("logical:table")) tableOfConcept.set(tr.to, tr.from);
|
|
119
|
+
const pageOfElement = (id: string): Href | undefined => {
|
|
120
|
+
const hit = byId.get(id);
|
|
121
|
+
if (hit === undefined) return undefined;
|
|
122
|
+
const e = hit.element;
|
|
123
|
+
if (e.kind === "concept") return { kind: "page", path: conceptPage(hit.model, e.name) };
|
|
124
|
+
if (e.kind === "codelist") return { kind: "page", path: `models/${kebab(hit.model.name)}/list-${kebab(e.name)}.html` };
|
|
125
|
+
if (e.kind === "table") {
|
|
126
|
+
const cid = tableOfConcept.get(e.id);
|
|
127
|
+
const ch = cid === undefined ? undefined : byId.get(cid);
|
|
128
|
+
return ch === undefined ? undefined : { kind: "page", path: conceptPage(ch.model, ch.element.name) };
|
|
129
|
+
}
|
|
130
|
+
if (e.kind === "attribute" || e.kind === "relationship") {
|
|
131
|
+
const p = byId.get(e.parent ?? "");
|
|
132
|
+
return p === undefined ? undefined : { kind: "page", path: conceptPage(p.model, p.element.name), anchor: kebab(e.name) };
|
|
133
|
+
}
|
|
134
|
+
return undefined;
|
|
135
|
+
};
|
|
136
|
+
const link = (id: string, label: string): Inline => {
|
|
137
|
+
const h = pageOfElement(id);
|
|
138
|
+
return h === undefined ? c(label) : { kind: "link", href: h, children: [c(label)] };
|
|
139
|
+
};
|
|
140
|
+
// the page of the layers: what each is for, and how to change a model
|
|
141
|
+
const subjectOfIndex = (m: LayeredModel): { readonly id: string; readonly title: string; readonly about: string; readonly order: number } => m.subject ?? { id: "other", title: "Other models", about: "Models that name no subject.", order: 99 };
|
|
142
|
+
const findings = models.flatMap((m) => m.findings);
|
|
143
|
+
page(build, {
|
|
144
|
+
path: "models/index.html",
|
|
145
|
+
title: "Models",
|
|
146
|
+
description: "The data models, documented layer by layer: governance, the logical schema and the physical forms.",
|
|
147
|
+
group,
|
|
148
|
+
order: after,
|
|
149
|
+
blocks: [
|
|
150
|
+
para(t("Each model is documented in the layers it is written in. Governance says what the business means and is the only layer a person or an agent edits; the logical schema and the physical forms are made from it. "), { kind: "link", href: { kind: "page", path: "models/layers.html" }, children: [t("How the layers fit and how to change a model")] }, t(".")),
|
|
151
|
+
...[...new Map(models.map((m) => [subjectOfIndex(m).id, subjectOfIndex(m)] as const)).values()].sort((x, y) => x.order - y.order).flatMap((sub): Block[] => [
|
|
152
|
+
heading(2, sub.title, `subject-${sub.id}`),
|
|
153
|
+
para(t(sub.about)),
|
|
154
|
+
{
|
|
155
|
+
kind: "cards",
|
|
156
|
+
cards: models.filter((m) => subjectOfIndex(m).id === sub.id).map((m) => ({
|
|
157
|
+
title: m.title,
|
|
158
|
+
href: { kind: "page", path: `models/${kebab(m.name)}/index.html` } as Href,
|
|
159
|
+
text: [t(m.summary)],
|
|
160
|
+
badges: [badge(`${m.elements.filter((e) => e.kind === "concept").length} ${m.elements.filter((e) => e.kind === "concept").length === 1 ? "concept" : "concepts"}`, "info"), ...(m.findings.length > 0 ? [badge(`${m.findings.length} findings`, "warn")] : [])],
|
|
161
|
+
})),
|
|
162
|
+
},
|
|
163
|
+
]),
|
|
164
|
+
heading(2, "How the models depend on each other"),
|
|
165
|
+
{ kind: "diagram", source: `flowchart LR\n${models.flatMap((m) => list(m.elements.find((e) => e.kind === "module") ?? ({ properties: {} } as LayerElement), "requires").map((r) => ` ${m.name}[${m.title}] --> ${r}[${models.find((x) => x.name === r)?.title ?? r}]`)).join("\n")}`, caption: "A model points to the models it requires" },
|
|
166
|
+
heading(2, "Registers"),
|
|
167
|
+
para({ kind: "link", href: { kind: "page", path: "models/registers.html" }, children: [t("What the models annotate: personal data, security, ownership, lifecycle")] }),
|
|
168
|
+
...(findings.length === 0 ? [] : [heading(2, "Findings"), { kind: "list", ordered: false, items: findings.map((f) => [para(c(f.element), t(` ${f.message}`))]) } as Block]),
|
|
169
|
+
],
|
|
170
|
+
});
|
|
171
|
+
const layers = models[0]?.layers ?? [];
|
|
172
|
+
page(build, {
|
|
173
|
+
path: "models/layers.html",
|
|
174
|
+
title: "The layers",
|
|
175
|
+
description: "How governance, logical and physical fit together, and how to change a model and regenerate what follows.",
|
|
176
|
+
group,
|
|
177
|
+
order: after + 1,
|
|
178
|
+
blocks: [
|
|
179
|
+
para(t("A model is written once, in governance, and everything else is made from it. Read the layers from the top: each is made from the one above it, and each element says which element it came from.")),
|
|
180
|
+
{ kind: "diagram", source: "flowchart LR\n G[Governance: TypeScript, the definition DSL] -->|projects to| L[Logical: tables, columns, keys]\n L -->|written as| S[Physical: SQL for each dialect]\n L -->|read and written by| T[Physical: typed tables]", caption: "The layers: edit the first, generate the rest" },
|
|
181
|
+
...layers.flatMap((l): Block[] => [heading(2, l.title, l.id), para(t(l.summary)), para(t("Holds: "), ...l.kinds.flatMap((k, i) => (i === 0 ? [c(k)] : [t(", "), c(k)])))]),
|
|
182
|
+
heading(2, "How to change a model"),
|
|
183
|
+
{ kind: "list", ordered: true, items: [
|
|
184
|
+
[para(t("Find the concept in governance: its page shows the file and line where it is written."))],
|
|
185
|
+
[para(t("Edit it there: add an "), c("attribute(...)"), t(" or a "), c("relationship(...)"), t(", give it a "), c("definition"), t(" (the definition is the documentation), and annotate personal data with a purpose."))],
|
|
186
|
+
...(options.regenerate ?? []).map((cmd) => [para(t("Regenerate what follows: "), c(cmd))]),
|
|
187
|
+
[para(t("Never edit a generated file (its name has "), c(".auto."), t(") or the SQL: change governance and generate again. The pages of this site are made from the same values, so they follow."))],
|
|
188
|
+
[para(t("Check: a concept, attribute, relationship or code list with no definition, and personal data held for no purpose, are findings on the "), { kind: "link", href: { kind: "page", path: "models/index.html" }, children: [t("Models")] }, t(" page."))],
|
|
189
|
+
] },
|
|
190
|
+
heading(2, "For an agent"),
|
|
191
|
+
para(t("Every page of this site has a Markdown twin (the same path with "), c(".md"), t(") and each model is published as JSON ("), c("models/<name>.json"), t(", listed in "), c("llms.txt"), t("). An element's id is stable, so the JSON and the pages name the same things, and the trace lists what each element is made into.")),
|
|
192
|
+
],
|
|
193
|
+
});
|
|
194
|
+
let order = after + 2;
|
|
195
|
+
// the models are grouped by what they apply to: a group of the navigation for each subject, its models beneath it, and each model's concepts and code lists beneath the model while it is read (FR-040)
|
|
196
|
+
const OTHER = { id: "other", title: "Other models", about: "Models that name no subject.", order: 99 };
|
|
197
|
+
const subjectOf = (m: LayeredModel): { readonly id: string; readonly title: string; readonly about: string; readonly order: number } => m.subject ?? OTHER;
|
|
198
|
+
const known = (name: string): boolean => models.some((x) => x.name === name);
|
|
199
|
+
const usedBy = new Map<string, string[]>();
|
|
200
|
+
for (const m of models) for (const r of list(m.elements.find((e) => e.kind === "module") ?? ({ properties: {} } as LayerElement), "requires")) usedBy.set(r, [...(usedBy.get(r) ?? []), m.name]);
|
|
201
|
+
models.forEach((m, mi) => {
|
|
202
|
+
const subject = subjectOf(m);
|
|
203
|
+
const base = 100_000 * (subject.order + 1) + mi * 1000;
|
|
204
|
+
let k = 0;
|
|
205
|
+
const concepts = m.elements.filter((e) => e.kind === "concept");
|
|
206
|
+
const lists = m.elements.filter((e) => e.kind === "codelist");
|
|
207
|
+
const modEl = m.elements.find((e) => e.kind === "module");
|
|
208
|
+
const edges = concepts.flatMap((cn) => m.elements.filter((e) => e.kind === "relationship" && e.parent === cn.id).map((r) => ` ${kebab(cn.name).replaceAll("-", "_")} -->|${r.name}| ${prop(r, "to").replace(/[^A-Za-z0-9]/g, "_")}`));
|
|
209
|
+
const metaOf = (modEl: LayerElement): Inline[] => {
|
|
210
|
+
const by = usedBy.get(m.name) ?? [];
|
|
211
|
+
return [
|
|
212
|
+
...(modEl.source === undefined ? [] : [t("Written in "), ...sourceLink(build, modEl.source), t(". ")]),
|
|
213
|
+
...(list(modEl, "requires").length === 0 ? [t("Requires nothing. ")] : [t("Requires "), ...list(modEl, "requires").flatMap((r, i): Inline[] => [...(i === 0 ? [] : [t(", ")]), known(r) ? { kind: "link", href: { kind: "page", path: `models/${kebab(r)}/index.html` }, children: [c(r)] } : c(r)]), t(". ")]),
|
|
214
|
+
...(by.length === 0 ? [] : [t("Required by "), ...by.flatMap((u, i): Inline[] => [...(i === 0 ? [] : [t(", ")]), { kind: "link", href: { kind: "page", path: `models/${kebab(u)}/index.html` }, children: [c(u)] }]), t(". ")]),
|
|
215
|
+
t(`${concepts.length} ${concepts.length === 1 ? "concept" : "concepts"}, ${lists.length} code ${lists.length === 1 ? "list" : "lists"}.`),
|
|
216
|
+
];
|
|
217
|
+
};
|
|
218
|
+
page(build, {
|
|
219
|
+
path: `models/${kebab(m.name)}/index.html`,
|
|
220
|
+
title: m.title,
|
|
221
|
+
description: m.summary,
|
|
222
|
+
group: subject.title,
|
|
223
|
+
order: base + k++,
|
|
224
|
+
navTitle: m.title,
|
|
225
|
+
blocks: [
|
|
226
|
+
para(t(m.summary)),
|
|
227
|
+
para(t("Applies to: "), t(subject.title), t(". "), t(subject.about)),
|
|
228
|
+
...(modEl === undefined ? [] : [para(...metaOf(modEl))]),
|
|
229
|
+
...(edges.length === 0 ? [] : [{ kind: "diagram", source: `flowchart LR\n${edges.slice(0, 80).join("\n")}`, caption: `How the concepts of ${m.title} relate` } as Block]),
|
|
230
|
+
heading(2, "Concepts"),
|
|
231
|
+
{ kind: "table", head: [[t("Concept")], [t("Definition")], [t("Attributes")], [t("Written in")]], rows: concepts.map((cn) => [[{ kind: "link", href: { kind: "page", path: conceptPage(m, cn.name) }, children: [c(cn.name)] }], [t(cn.definition)], [t(String(list(cn, "attributes").length))], sourceLink(build, cn.source)]) },
|
|
232
|
+
...(lists.length === 0 ? [] : [heading(2, "Code lists"), { kind: "table", head: [[t("Code list")], [t("Definition")], [t("Codes")]], rows: lists.map((l) => [[{ kind: "link", href: { kind: "page", path: `models/${kebab(m.name)}/list-${kebab(l.name)}.html` }, children: [c(l.name)] }], [t(l.definition)], [t(String(list(l, "codes").length))]]) } as Block]),
|
|
233
|
+
...(m.findings.length === 0 ? [] : [heading(2, "Findings"), { kind: "list", ordered: false, items: m.findings.map((f) => [para(c(f.element), t(` ${f.message}`))]) } as Block]),
|
|
234
|
+
],
|
|
235
|
+
});
|
|
236
|
+
for (const cn of concepts) {
|
|
237
|
+
const attrs = m.elements.filter((e) => e.kind === "attribute" && e.parent === cn.id);
|
|
238
|
+
const rels = m.elements.filter((e) => e.kind === "relationship" && e.parent === cn.id);
|
|
239
|
+
const table = m.trace.filter((x) => x.from === cn.id && x.how === "projects to").map((x) => m.elements.find((e) => e.id === x.to)).find((e) => e?.kind === "table");
|
|
240
|
+
const cols = table === undefined ? [] : m.elements.filter((e) => e.kind === "column" && e.parent === table.id);
|
|
241
|
+
const ddl = table === undefined ? [] : m.elements.filter((e) => e.kind === "ddl" && e.parent === table.id);
|
|
242
|
+
const typedTable = table === undefined ? undefined : m.elements.find((e) => e.kind === "typed-table" && e.parent === table.id);
|
|
243
|
+
const colFor = (id: string): string => {
|
|
244
|
+
const hit = m.trace.filter((x) => x.from === id && x.to.startsWith("logical:column")).map((x) => m.elements.find((e) => e.id === x.to)?.name ?? "");
|
|
245
|
+
return hit.join(", ");
|
|
246
|
+
};
|
|
247
|
+
const personal = attrs.filter((a) => list(a, "annotations").some((x) => x.startsWith("privacy.personal")));
|
|
248
|
+
page(build, {
|
|
249
|
+
path: conceptPage(m, cn.name),
|
|
250
|
+
title: cn.name,
|
|
251
|
+
description: cn.definition,
|
|
252
|
+
group: subject.title,
|
|
253
|
+
order: base + k++,
|
|
254
|
+
parent: `models/${kebab(m.name)}/index.html`,
|
|
255
|
+
navKind: "Concepts",
|
|
256
|
+
navTitle: cn.name,
|
|
257
|
+
badges: [badge("concept", "info"), ...(personal.length > 0 ? [badge("personal data", "warn")] : [])],
|
|
258
|
+
blocks: [
|
|
259
|
+
para(t(cn.definition === "" ? "No definition: say what this concept means." : cn.definition)),
|
|
260
|
+
para(t("Model "), { kind: "link", href: { kind: "page", path: `models/${kebab(m.name)}/index.html` }, children: [c(m.name)] }, ...(cn.source === undefined ? [] : [t(". Written in "), ...sourceLink(build, cn.source)]), t(`. Identified by `), c(prop(cn, "identifiedBy")), t(".")),
|
|
261
|
+
heading(2, "Governance: attributes"),
|
|
262
|
+
...attrs.map((a): Block => ({
|
|
263
|
+
kind: "entry",
|
|
264
|
+
id: kebab(a.name),
|
|
265
|
+
name: a.name,
|
|
266
|
+
badges: [badge(prop(a, "type")), badge(prop(a, "multiplicity"), prop(a, "multiplicity") === "required" ? "good" : "neutral"), ...(list(a, "annotations").some((x) => x.startsWith("privacy.personal")) ? [badge("personal data", "warn")] : [])],
|
|
267
|
+
blocks: [
|
|
268
|
+
para(t(a.definition === "" ? "No definition." : a.definition)),
|
|
269
|
+
...(colFor(a.id) === "" ? [] : [para(t("Becomes the column "), c(colFor(a.id)), t(" of "), ...(table === undefined ? [] : [c(table.name)]), t("."))]),
|
|
270
|
+
...(list(a, "annotations").length === 0 ? [] : [para(t("Annotations: "), ...list(a, "annotations").flatMap((x, i) => (i === 0 ? [c(x)] : [t(" "), c(x)])))]),
|
|
271
|
+
...(a.source === undefined ? [] : [para(t("Written at "), ...sourceLink(build, a.source))]),
|
|
272
|
+
],
|
|
273
|
+
})),
|
|
274
|
+
...(rels.length === 0 ? [] : [heading(2, "Governance: relationships"), ...rels.map((r): Block => {
|
|
275
|
+
const target = [...byId.values()].find((x) => x.element.kind === "concept" && x.element.name === prop(r, "to"));
|
|
276
|
+
return {
|
|
277
|
+
kind: "entry",
|
|
278
|
+
id: kebab(r.name),
|
|
279
|
+
name: r.name,
|
|
280
|
+
badges: [badge(prop(r, "cardinality"))],
|
|
281
|
+
blocks: [para(t(r.definition === "" ? "No definition. " : `${r.definition} `), t("To "), target === undefined ? c(prop(r, "to")) : link(target.element.id, target.element.name), ...(r.source === undefined ? [] : [t(". Written at "), ...sourceLink(build, r.source)]))],
|
|
282
|
+
};
|
|
283
|
+
})]),
|
|
284
|
+
...(table === undefined ? [] : [
|
|
285
|
+
heading(2, "Logical: the table"),
|
|
286
|
+
para(t("Projects to the table "), c(table.name), t(" with the primary key "), c(prop(table, "primaryKey")), t(".")),
|
|
287
|
+
{ kind: "table", head: [[t("Column")], [t("Type")], [t("Null")], [t("Role")], [t("From")]], rows: cols.map((col) => [[c(col.name)], [t(prop(col, "type"))], [t(prop(col, "nullable"))], [t(prop(col, "role"))], (() => { const from = m.trace.find((x) => x.to === col.id)?.from; return from === undefined ? [] : [link(from, from.replace(/^governance:[a-z]+\//, ""))]; })()]) } as Block,
|
|
288
|
+
]),
|
|
289
|
+
...(ddl.length === 0 ? [] : [heading(2, "Physical: SQL"), { kind: "tabs", id: "sql", tabs: ddl.map((d) => ({ label: prop(d, "dialect"), blocks: [{ kind: "code", lang: "sql", text: prop(d, "sql") } as Block] })) } as Block]),
|
|
290
|
+
...(typedTable === undefined ? [] : [heading(2, "Physical: the typed table"), para(t("Read and written from TypeScript with the types the model gives: "), c(["import", `{ ${prop(typedTable, "export")} }`, "from", `"${prop(typedTable, "module")}"`].join(" ")), t(". Generated"), ...(typedTable.source === undefined ? [] : [t(" in "), ...sourceLink(build, typedTable.source)]), t(": do not edit.")), { kind: "code", lang: "ts", text: typedExample(prop(typedTable, "export"), prop(typedTable, "module"), list(table ?? cn, "columns")) } as Block]),
|
|
291
|
+
],
|
|
292
|
+
});
|
|
293
|
+
}
|
|
294
|
+
for (const l of lists) {
|
|
295
|
+
const codes = m.elements.filter((e) => e.kind === "code" && e.parent === l.id);
|
|
296
|
+
page(build, {
|
|
297
|
+
path: `models/${kebab(m.name)}/list-${kebab(l.name)}.html`,
|
|
298
|
+
title: l.name,
|
|
299
|
+
description: l.definition,
|
|
300
|
+
group: subject.title,
|
|
301
|
+
order: base + 500 + k++,
|
|
302
|
+
parent: `models/${kebab(m.name)}/index.html`,
|
|
303
|
+
navKind: "Code lists",
|
|
304
|
+
badges: [badge("code list", "info")],
|
|
305
|
+
blocks: [
|
|
306
|
+
para(t(l.definition === "" ? "No definition: say what this list means." : l.definition)),
|
|
307
|
+
para(t("Model "), { kind: "link", href: { kind: "page", path: `models/${kebab(m.name)}/index.html` }, children: [c(m.name)] }, ...(l.source === undefined ? [] : [t(". Written in "), ...sourceLink(build, l.source)])),
|
|
308
|
+
{ kind: "table", head: [[t("Code")], [t("Label")], [t("Meaning")]], rows: codes.map((cd) => [[c(cd.name)], [t(prop(cd, "label"))], [t(cd.definition)]]) },
|
|
309
|
+
],
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
});
|
|
313
|
+
// registers: what the models annotate
|
|
314
|
+
const byKind = new Map<string, { model: string; element: LayerElement; value: string }[]>();
|
|
315
|
+
for (const m of models) for (const e of m.elements) for (const a of list(e, "annotations")) {
|
|
316
|
+
const k = a.slice(0, a.indexOf("="));
|
|
317
|
+
byKind.set(k, [...(byKind.get(k) ?? []), { model: m.name, element: e, value: a.slice(a.indexOf("=") + 1) }]);
|
|
318
|
+
}
|
|
319
|
+
page(build, {
|
|
320
|
+
path: "models/registers.html",
|
|
321
|
+
title: "Registers",
|
|
322
|
+
description: "Everything the models annotate, by kind of annotation: personal data, security, ownership, lifecycle.",
|
|
323
|
+
group,
|
|
324
|
+
order,
|
|
325
|
+
blocks: [
|
|
326
|
+
para(t("Annotations are how governance says what an element holds and who answers for it. Each kind is listed with every element that carries it.")),
|
|
327
|
+
...[...byKind].sort(([a], [b]) => (a < b ? -1 : 1)).flatMap(([kind, rows]): Block[] => [
|
|
328
|
+
heading(2, kind),
|
|
329
|
+
{ kind: "table", head: [[t("Element")], [t("Model")], [t("Value")]], rows: rows.map((r) => [[link(r.element.id, r.element.id.replace(/^governance:[a-z]+\//, ""))], [t(r.model)], [c(r.value)]]) },
|
|
330
|
+
]),
|
|
331
|
+
],
|
|
332
|
+
});
|
|
333
|
+
return order + 1;
|
|
334
|
+
};
|
|
335
|
+
},
|
|
336
|
+
files: (): readonly SiteFile[] => [
|
|
337
|
+
...models.map((m): SiteFile => ({ path: `models/${kebab(m.name)}.json`, text: `${JSON.stringify(m, null, 2)}\n`, what: `the ${m.title} model in layers (governance, logical, physical) with its trace and findings` })),
|
|
338
|
+
{ path: "models/index.json", text: `${JSON.stringify(models.map((m) => ({ name: m.name, library: m.library, title: m.title, summary: m.summary, file: `models/${kebab(m.name)}.json`, elements: m.elements.length, findings: m.findings.length })), null, 2)}\n`, what: "the list of models with the file of each" },
|
|
339
|
+
],
|
|
340
|
+
};
|
|
341
|
+
}
|