@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.
Files changed (92) hide show
  1. package/LICENSE +75 -0
  2. package/README.md +8 -2
  3. package/dist/build.d.ts +63 -0
  4. package/dist/build.js +103 -0
  5. package/dist/check.d.ts +63 -0
  6. package/dist/check.js +54 -0
  7. package/dist/cli.d.ts +51 -0
  8. package/dist/cli.js +165 -0
  9. package/dist/config.d.ts +196 -0
  10. package/dist/config.js +229 -0
  11. package/dist/emit/html.d.ts +67 -0
  12. package/dist/emit/html.js +338 -0
  13. package/dist/emit/markdown.d.ts +19 -0
  14. package/dist/emit/markdown.js +124 -0
  15. package/dist/emit/search.d.ts +15 -0
  16. package/dist/emit/search.js +29 -0
  17. package/dist/extract/api.d.ts +74 -0
  18. package/dist/extract/api.js +261 -0
  19. package/dist/extract/specs.d.ts +141 -0
  20. package/dist/extract/specs.js +208 -0
  21. package/dist/highlight.d.ts +22 -0
  22. package/dist/highlight.js +77 -0
  23. package/dist/layered.d.ts +94 -0
  24. package/dist/layered.js +14 -0
  25. package/dist/lens/guides.d.ts +23 -0
  26. package/dist/lens/guides.js +49 -0
  27. package/dist/lens/layered.d.ts +16 -0
  28. package/dist/lens/layered.js +354 -0
  29. package/dist/lens/program.d.ts +23 -0
  30. package/dist/lens/program.js +124 -0
  31. package/dist/lens/releases.d.ts +10 -0
  32. package/dist/lens/releases.js +37 -0
  33. package/dist/lens.d.ts +30 -0
  34. package/dist/lens.js +1 -0
  35. package/dist/links.d.ts +96 -0
  36. package/dist/links.js +182 -0
  37. package/dist/main.d.ts +1 -0
  38. package/dist/main.js +12 -0
  39. package/dist/markdown.d.ts +43 -0
  40. package/dist/markdown.js +301 -0
  41. package/dist/mod.d.ts +32 -0
  42. package/dist/mod.js +9 -0
  43. package/dist/model.d.ts +159 -0
  44. package/dist/model.js +39 -0
  45. package/dist/pages/api.d.ts +41 -0
  46. package/dist/pages/api.js +162 -0
  47. package/dist/pages/areas.d.ts +39 -0
  48. package/dist/pages/areas.js +119 -0
  49. package/dist/pages/overview.d.ts +24 -0
  50. package/dist/pages/overview.js +283 -0
  51. package/dist/pages/specs.d.ts +31 -0
  52. package/dist/pages/specs.js +358 -0
  53. package/dist/site.d.ts +31 -0
  54. package/dist/site.js +288 -0
  55. package/dist/sources.d.ts +53 -0
  56. package/dist/sources.js +159 -0
  57. package/dist/theme/site.css +275 -0
  58. package/dist/theme/site.js +174 -0
  59. package/dist/tsdoc.d.ts +67 -0
  60. package/dist/tsdoc.js +94 -0
  61. package/ifc-docs.mjs +4 -0
  62. package/package.json +66 -4
  63. package/src/build.ts +117 -0
  64. package/src/check.ts +84 -0
  65. package/src/cli.ts +145 -0
  66. package/src/config.ts +370 -0
  67. package/src/emit/html.ts +398 -0
  68. package/src/emit/markdown.ts +129 -0
  69. package/src/emit/search.ts +38 -0
  70. package/src/extract/api.ts +297 -0
  71. package/src/extract/specs.ts +299 -0
  72. package/src/highlight.ts +98 -0
  73. package/src/layered.ts +102 -0
  74. package/src/lens/guides.ts +70 -0
  75. package/src/lens/layered.ts +341 -0
  76. package/src/lens/program.ts +137 -0
  77. package/src/lens/releases.ts +54 -0
  78. package/src/lens.ts +34 -0
  79. package/src/links.ts +234 -0
  80. package/src/main.ts +12 -0
  81. package/src/markdown.ts +320 -0
  82. package/src/mod.ts +53 -0
  83. package/src/model.ts +154 -0
  84. package/src/pages/api.ts +179 -0
  85. package/src/pages/areas.ts +133 -0
  86. package/src/pages/overview.ts +276 -0
  87. package/src/pages/specs.ts +366 -0
  88. package/src/site.ts +285 -0
  89. package/src/sources.ts +157 -0
  90. package/src/theme/site.css +275 -0
  91. package/src/theme/site.js +174 -0
  92. package/src/tsdoc.ts +131 -0
@@ -0,0 +1,354 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx, extraExtensions, ignoreCase) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ if (extraExtensions) {
4
+ for (var extension in extraExtensions) {
5
+ var suffix = path.slice(-extension.length);
6
+ if (suffix === extension || ignoreCase && suffix.toLowerCase() === extension.toLowerCase()) {
7
+ var output = extraExtensions[extension];
8
+ return output === extension ? path : path.slice(0, -extension.length) + output;
9
+ }
10
+ }
11
+ }
12
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
13
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
14
+ });
15
+ }
16
+ return path;
17
+ };
18
+ // Spec: 0001-docs FR-002
19
+ /**
20
+ * 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
21
+ * 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
22
+ * 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.
23
+ *
24
+ * @remarks
25
+ * 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
26
+ * 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
27
+ * 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.
28
+ *
29
+ * @module
30
+ */
31
+ import { fs, path } from "@intellectual-frontiers/system";
32
+ import { slugOf } from "../mod.js";
33
+ /** A name as a path: `identityAgent` is `identity-agent`. */
34
+ const kebab = (name) => slugOf(name.replace(/([a-z0-9])([A-Z])/g, "$1-$2"));
35
+ const t = (text) => ({ kind: "text", text });
36
+ const c = (text) => ({ kind: "code", text });
37
+ const para = (...inlines) => ({ kind: "paragraph", inlines });
38
+ const heading = (level, text, id = slugOf(text)) => ({ kind: "heading", level, id, text: [t(text)] });
39
+ const badge = (text, tone = "neutral") => ({ text, tone });
40
+ const page = (b, p) => b.add({ ...p, section: "models" });
41
+ /** The line of the declaration of an export in a file, from 1. */
42
+ function lineOf(text, name) {
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
+ /** The line of a member (`attribute:` in an object) after the declaration, from 1. */
48
+ function memberLine(text, from, member) {
49
+ const lines = text.split("\n");
50
+ for (let i = from; i < Math.min(lines.length, from + 400); i++)
51
+ if (new RegExp(`^\\s*${member}\\s*[:(]`).test(lines[i] ?? ""))
52
+ return i + 1;
53
+ return undefined;
54
+ }
55
+ /** A locator that also finds the line of a member, from the same files. */
56
+ async function withMembers(b, files) {
57
+ const known = new Map();
58
+ for (const file of files) {
59
+ let text;
60
+ try {
61
+ text = await fs.readTextFile(path.join(b.root, file));
62
+ }
63
+ catch {
64
+ b.found.push({ where: file, problem: { kind: "undescribed", entity: `the file ${file}, which the layered lens is told exports models, cannot be read` } });
65
+ continue;
66
+ }
67
+ const mod = (await import(__rewriteRelativeImportExtension(path.join(b.root, file))));
68
+ for (const [name, value] of Object.entries(mod)) {
69
+ if ((typeof value !== "object" && typeof value !== "function") || value === null)
70
+ continue;
71
+ const line = lineOf(text, name);
72
+ // a file that declares a value is where it is written; one that re-exports it is not
73
+ if (known.has(value) && (known.get(value)?.line !== undefined || line === undefined))
74
+ continue;
75
+ known.set(value, { file, text, ...(line === undefined ? {} : { line }) });
76
+ }
77
+ }
78
+ return (value, member) => {
79
+ const k = known.get(value);
80
+ if (k === undefined)
81
+ return undefined;
82
+ if (member === undefined || k.line === undefined)
83
+ return { file: k.file, ...(k.line === undefined ? {} : { line: k.line }) };
84
+ const l = memberLine(k.text, k.line, member);
85
+ return { file: k.file, line: l ?? k.line };
86
+ };
87
+ }
88
+ const sourceHref = (b, s) => ({ kind: "external", url: `${b.config.repository}/blob/${b.config.branch}/${s.file}${s.line === undefined ? "" : `#L${s.line}`}` });
89
+ const sourceLink = (b, s) => (s === undefined ? [] : [{ kind: "link", href: sourceHref(b, s), children: [c(`${s.file}${s.line === undefined ? "" : `:${s.line}`}`)] }]);
90
+ /** An example of reading a typed table: the first two columns, as a program writes their keys. */
91
+ function typedExample(name, from, columns) {
92
+ const key = (k) => k.replace(/_([a-z])/g, (_x, ch) => ch.toUpperCase());
93
+ const picked = columns.slice(0, 2).map((k) => `${key(k)}: s.${name}.${key(k)}`).join(", ");
94
+ // the import lines are made from pieces, so that the packer does not read these strings as imports of this module
95
+ const importOf = (what, source) => ["import", `{ ${what} }`, "from", `"${source}";`].join(" ");
96
+ return [importOf("from", "@intellectual-frontiers/data/sql/typed"), importOf(name, from), "", `const rows = await from(${name}).select((s) => ({ ${picked} })).run(runner);`].join("\n");
97
+ }
98
+ const prop = (e, k) => {
99
+ const v = e.properties[k];
100
+ return Array.isArray(v) ? v.join(", ") : v === null || v === undefined ? "" : String(v);
101
+ };
102
+ const list = (e, k) => {
103
+ const v = e.properties[k];
104
+ return Array.isArray(v) ? v : [];
105
+ };
106
+ /** The layered-model lens. */
107
+ export function layeredLens(options) {
108
+ let models = [];
109
+ const group = options.group ?? "Models";
110
+ return {
111
+ name: options.name,
112
+ read: async (b) => {
113
+ models = await options.source(await withMembers(b, options.exports));
114
+ const byId = new Map();
115
+ for (const m of models)
116
+ for (const e of m.elements)
117
+ byId.set(e.id, { model: m, element: e });
118
+ return (build, after) => {
119
+ const conceptPage = (m, name) => `models/${kebab(m.name)}/${kebab(name)}.html`;
120
+ const tableOfConcept = new Map();
121
+ for (const m of models)
122
+ for (const tr of m.trace)
123
+ if (tr.how === "projects to" && tr.from.startsWith("governance:concept/") && tr.to.startsWith("logical:table"))
124
+ tableOfConcept.set(tr.to, tr.from);
125
+ const pageOfElement = (id) => {
126
+ const hit = byId.get(id);
127
+ if (hit === undefined)
128
+ return undefined;
129
+ const e = hit.element;
130
+ if (e.kind === "concept")
131
+ return { kind: "page", path: conceptPage(hit.model, e.name) };
132
+ if (e.kind === "codelist")
133
+ return { kind: "page", path: `models/${kebab(hit.model.name)}/list-${kebab(e.name)}.html` };
134
+ if (e.kind === "table") {
135
+ const cid = tableOfConcept.get(e.id);
136
+ const ch = cid === undefined ? undefined : byId.get(cid);
137
+ return ch === undefined ? undefined : { kind: "page", path: conceptPage(ch.model, ch.element.name) };
138
+ }
139
+ if (e.kind === "attribute" || e.kind === "relationship") {
140
+ const p = byId.get(e.parent ?? "");
141
+ return p === undefined ? undefined : { kind: "page", path: conceptPage(p.model, p.element.name), anchor: kebab(e.name) };
142
+ }
143
+ return undefined;
144
+ };
145
+ const link = (id, label) => {
146
+ const h = pageOfElement(id);
147
+ return h === undefined ? c(label) : { kind: "link", href: h, children: [c(label)] };
148
+ };
149
+ // the page of the layers: what each is for, and how to change a model
150
+ const subjectOfIndex = (m) => m.subject ?? { id: "other", title: "Other models", about: "Models that name no subject.", order: 99 };
151
+ const findings = models.flatMap((m) => m.findings);
152
+ page(build, {
153
+ path: "models/index.html",
154
+ title: "Models",
155
+ description: "The data models, documented layer by layer: governance, the logical schema and the physical forms.",
156
+ group,
157
+ order: after,
158
+ blocks: [
159
+ 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(".")),
160
+ ...[...new Map(models.map((m) => [subjectOfIndex(m).id, subjectOfIndex(m)])).values()].sort((x, y) => x.order - y.order).flatMap((sub) => [
161
+ heading(2, sub.title, `subject-${sub.id}`),
162
+ para(t(sub.about)),
163
+ {
164
+ kind: "cards",
165
+ cards: models.filter((m) => subjectOfIndex(m).id === sub.id).map((m) => ({
166
+ title: m.title,
167
+ href: { kind: "page", path: `models/${kebab(m.name)}/index.html` },
168
+ text: [t(m.summary)],
169
+ 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")] : [])],
170
+ })),
171
+ },
172
+ ]),
173
+ heading(2, "How the models depend on each other"),
174
+ { kind: "diagram", source: `flowchart LR\n${models.flatMap((m) => list(m.elements.find((e) => e.kind === "module") ?? { properties: {} }, "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" },
175
+ heading(2, "Registers"),
176
+ para({ kind: "link", href: { kind: "page", path: "models/registers.html" }, children: [t("What the models annotate: personal data, security, ownership, lifecycle")] }),
177
+ ...(findings.length === 0 ? [] : [heading(2, "Findings"), { kind: "list", ordered: false, items: findings.map((f) => [para(c(f.element), t(` ${f.message}`))]) }]),
178
+ ],
179
+ });
180
+ const layers = models[0]?.layers ?? [];
181
+ page(build, {
182
+ path: "models/layers.html",
183
+ title: "The layers",
184
+ description: "How governance, logical and physical fit together, and how to change a model and regenerate what follows.",
185
+ group,
186
+ order: after + 1,
187
+ blocks: [
188
+ 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.")),
189
+ { 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" },
190
+ ...layers.flatMap((l) => [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)])))]),
191
+ heading(2, "How to change a model"),
192
+ { kind: "list", ordered: true, items: [
193
+ [para(t("Find the concept in governance: its page shows the file and line where it is written."))],
194
+ [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."))],
195
+ ...(options.regenerate ?? []).map((cmd) => [para(t("Regenerate what follows: "), c(cmd))]),
196
+ [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."))],
197
+ [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."))],
198
+ ] },
199
+ heading(2, "For an agent"),
200
+ 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.")),
201
+ ],
202
+ });
203
+ let order = after + 2;
204
+ // 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)
205
+ const OTHER = { id: "other", title: "Other models", about: "Models that name no subject.", order: 99 };
206
+ const subjectOf = (m) => m.subject ?? OTHER;
207
+ const known = (name) => models.some((x) => x.name === name);
208
+ const usedBy = new Map();
209
+ for (const m of models)
210
+ for (const r of list(m.elements.find((e) => e.kind === "module") ?? { properties: {} }, "requires"))
211
+ usedBy.set(r, [...(usedBy.get(r) ?? []), m.name]);
212
+ models.forEach((m, mi) => {
213
+ const subject = subjectOf(m);
214
+ const base = 100_000 * (subject.order + 1) + mi * 1000;
215
+ let k = 0;
216
+ const concepts = m.elements.filter((e) => e.kind === "concept");
217
+ const lists = m.elements.filter((e) => e.kind === "codelist");
218
+ const modEl = m.elements.find((e) => e.kind === "module");
219
+ 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, "_")}`));
220
+ const metaOf = (modEl) => {
221
+ const by = usedBy.get(m.name) ?? [];
222
+ return [
223
+ ...(modEl.source === undefined ? [] : [t("Written in "), ...sourceLink(build, modEl.source), t(". ")]),
224
+ ...(list(modEl, "requires").length === 0 ? [t("Requires nothing. ")] : [t("Requires "), ...list(modEl, "requires").flatMap((r, i) => [...(i === 0 ? [] : [t(", ")]), known(r) ? { kind: "link", href: { kind: "page", path: `models/${kebab(r)}/index.html` }, children: [c(r)] } : c(r)]), t(". ")]),
225
+ ...(by.length === 0 ? [] : [t("Required by "), ...by.flatMap((u, i) => [...(i === 0 ? [] : [t(", ")]), { kind: "link", href: { kind: "page", path: `models/${kebab(u)}/index.html` }, children: [c(u)] }]), t(". ")]),
226
+ t(`${concepts.length} ${concepts.length === 1 ? "concept" : "concepts"}, ${lists.length} code ${lists.length === 1 ? "list" : "lists"}.`),
227
+ ];
228
+ };
229
+ page(build, {
230
+ path: `models/${kebab(m.name)}/index.html`,
231
+ title: m.title,
232
+ description: m.summary,
233
+ group: subject.title,
234
+ order: base + k++,
235
+ navTitle: m.title,
236
+ blocks: [
237
+ para(t(m.summary)),
238
+ para(t("Applies to: "), t(subject.title), t(". "), t(subject.about)),
239
+ ...(modEl === undefined ? [] : [para(...metaOf(modEl))]),
240
+ ...(edges.length === 0 ? [] : [{ kind: "diagram", source: `flowchart LR\n${edges.slice(0, 80).join("\n")}`, caption: `How the concepts of ${m.title} relate` }]),
241
+ heading(2, "Concepts"),
242
+ { 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)]) },
243
+ ...(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))]]) }]),
244
+ ...(m.findings.length === 0 ? [] : [heading(2, "Findings"), { kind: "list", ordered: false, items: m.findings.map((f) => [para(c(f.element), t(` ${f.message}`))]) }]),
245
+ ],
246
+ });
247
+ for (const cn of concepts) {
248
+ const attrs = m.elements.filter((e) => e.kind === "attribute" && e.parent === cn.id);
249
+ const rels = m.elements.filter((e) => e.kind === "relationship" && e.parent === cn.id);
250
+ 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");
251
+ const cols = table === undefined ? [] : m.elements.filter((e) => e.kind === "column" && e.parent === table.id);
252
+ const ddl = table === undefined ? [] : m.elements.filter((e) => e.kind === "ddl" && e.parent === table.id);
253
+ const typedTable = table === undefined ? undefined : m.elements.find((e) => e.kind === "typed-table" && e.parent === table.id);
254
+ const colFor = (id) => {
255
+ 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 ?? "");
256
+ return hit.join(", ");
257
+ };
258
+ const personal = attrs.filter((a) => list(a, "annotations").some((x) => x.startsWith("privacy.personal")));
259
+ page(build, {
260
+ path: conceptPage(m, cn.name),
261
+ title: cn.name,
262
+ description: cn.definition,
263
+ group: subject.title,
264
+ order: base + k++,
265
+ parent: `models/${kebab(m.name)}/index.html`,
266
+ navKind: "Concepts",
267
+ navTitle: cn.name,
268
+ badges: [badge("concept", "info"), ...(personal.length > 0 ? [badge("personal data", "warn")] : [])],
269
+ blocks: [
270
+ para(t(cn.definition === "" ? "No definition: say what this concept means." : cn.definition)),
271
+ 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(".")),
272
+ heading(2, "Governance: attributes"),
273
+ ...attrs.map((a) => ({
274
+ kind: "entry",
275
+ id: kebab(a.name),
276
+ name: a.name,
277
+ 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")] : [])],
278
+ blocks: [
279
+ para(t(a.definition === "" ? "No definition." : a.definition)),
280
+ ...(colFor(a.id) === "" ? [] : [para(t("Becomes the column "), c(colFor(a.id)), t(" of "), ...(table === undefined ? [] : [c(table.name)]), t("."))]),
281
+ ...(list(a, "annotations").length === 0 ? [] : [para(t("Annotations: "), ...list(a, "annotations").flatMap((x, i) => (i === 0 ? [c(x)] : [t(" "), c(x)])))]),
282
+ ...(a.source === undefined ? [] : [para(t("Written at "), ...sourceLink(build, a.source))]),
283
+ ],
284
+ })),
285
+ ...(rels.length === 0 ? [] : [heading(2, "Governance: relationships"), ...rels.map((r) => {
286
+ const target = [...byId.values()].find((x) => x.element.kind === "concept" && x.element.name === prop(r, "to"));
287
+ return {
288
+ kind: "entry",
289
+ id: kebab(r.name),
290
+ name: r.name,
291
+ badges: [badge(prop(r, "cardinality"))],
292
+ 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)]))],
293
+ };
294
+ })]),
295
+ ...(table === undefined ? [] : [
296
+ heading(2, "Logical: the table"),
297
+ para(t("Projects to the table "), c(table.name), t(" with the primary key "), c(prop(table, "primaryKey")), t(".")),
298
+ { 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]+\//, ""))]; })()]) },
299
+ ]),
300
+ ...(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") }] })) }]),
301
+ ...(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")) }]),
302
+ ],
303
+ });
304
+ }
305
+ for (const l of lists) {
306
+ const codes = m.elements.filter((e) => e.kind === "code" && e.parent === l.id);
307
+ page(build, {
308
+ path: `models/${kebab(m.name)}/list-${kebab(l.name)}.html`,
309
+ title: l.name,
310
+ description: l.definition,
311
+ group: subject.title,
312
+ order: base + 500 + k++,
313
+ parent: `models/${kebab(m.name)}/index.html`,
314
+ navKind: "Code lists",
315
+ badges: [badge("code list", "info")],
316
+ blocks: [
317
+ para(t(l.definition === "" ? "No definition: say what this list means." : l.definition)),
318
+ 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)])),
319
+ { kind: "table", head: [[t("Code")], [t("Label")], [t("Meaning")]], rows: codes.map((cd) => [[c(cd.name)], [t(prop(cd, "label"))], [t(cd.definition)]]) },
320
+ ],
321
+ });
322
+ }
323
+ });
324
+ // registers: what the models annotate
325
+ const byKind = new Map();
326
+ for (const m of models)
327
+ for (const e of m.elements)
328
+ for (const a of list(e, "annotations")) {
329
+ const k = a.slice(0, a.indexOf("="));
330
+ byKind.set(k, [...(byKind.get(k) ?? []), { model: m.name, element: e, value: a.slice(a.indexOf("=") + 1) }]);
331
+ }
332
+ page(build, {
333
+ path: "models/registers.html",
334
+ title: "Registers",
335
+ description: "Everything the models annotate, by kind of annotation: personal data, security, ownership, lifecycle.",
336
+ group,
337
+ order,
338
+ blocks: [
339
+ 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.")),
340
+ ...[...byKind].sort(([a], [b]) => (a < b ? -1 : 1)).flatMap(([kind, rows]) => [
341
+ heading(2, kind),
342
+ { 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)]]) },
343
+ ]),
344
+ ],
345
+ });
346
+ return order + 1;
347
+ };
348
+ },
349
+ files: () => [
350
+ ...models.map((m) => ({ 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` })),
351
+ { 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" },
352
+ ],
353
+ };
354
+ }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The program lens (commons 0011-documentation FR-030): the command-line, tool and route programs of a library built on commons headless, as pages for a person and an agent and as a Markdown twin and a JSON file for each. It is
3
+ * given a function that makes `LayeredModel` values (headless's own `describe`, which gives one model for each tier of a program) and knows nothing of headless: what a program says is read from the values. The models of
4
+ * the tiers of one program have the same element ids, so each model is read by itself and never merged with another, and every tier has its own pages.
5
+ *
6
+ * @remarks
7
+ * Pages: the programs and their tiers; for each tier its verbs (what each does, its effect, and which surfaces draw it or why one does not), the problem codes and exit statuses it can give, the plugins that contribute verbs and
8
+ * the findings of the builder; and for each verb its action as governance says it, its options and operands, examples, and the command, tool and route it becomes.
9
+ *
10
+ * @module
11
+ */
12
+ import { type LayeredModel, type Lens } from "../mod.js";
13
+ /** What the lens is given. */
14
+ export interface ProgramLensOptions {
15
+ /** Its name, which the build reports it by. */
16
+ readonly name: string;
17
+ /** The group of the section the pages are in. */
18
+ readonly group?: string;
19
+ /** Makes the models of the programs: one for each tier of each program. */
20
+ readonly source: () => Promise<readonly LayeredModel[]> | readonly LayeredModel[];
21
+ }
22
+ /** The program lens. */
23
+ export declare function programLens(options: ProgramLensOptions): Lens;
@@ -0,0 +1,124 @@
1
+ // Spec: 0001-docs FR-002
2
+ /**
3
+ * The program lens (commons 0011-documentation FR-030): the command-line, tool and route programs of a library built on commons headless, as pages for a person and an agent and as a Markdown twin and a JSON file for each. It is
4
+ * given a function that makes `LayeredModel` values (headless's own `describe`, which gives one model for each tier of a program) and knows nothing of headless: what a program says is read from the values. The models of
5
+ * the tiers of one program have the same element ids, so each model is read by itself and never merged with another, and every tier has its own pages.
6
+ *
7
+ * @remarks
8
+ * Pages: the programs and their tiers; for each tier its verbs (what each does, its effect, and which surfaces draw it or why one does not), the problem codes and exit statuses it can give, the plugins that contribute verbs and
9
+ * the findings of the builder; and for each verb its action as governance says it, its options and operands, examples, and the command, tool and route it becomes.
10
+ *
11
+ * @module
12
+ */
13
+ import { slugOf } from "../mod.js";
14
+ const t = (text) => ({ kind: "text", text });
15
+ const c = (text) => ({ kind: "code", text });
16
+ const para = (...inlines) => ({ kind: "paragraph", inlines });
17
+ const heading = (level, text, id = slugOf(text)) => ({ kind: "heading", level, id, text: [t(text)] });
18
+ const badge = (text, tone = "neutral") => ({ text, tone });
19
+ const slug = (s) => slugOf(s.replace(/[^A-Za-z0-9]+/g, "-"));
20
+ const value = (v) => (Array.isArray(v) ? v.join(", ") : v === null || v === undefined ? "" : String(v));
21
+ const prop = (e, k) => value(e.properties[k]);
22
+ const list = (e, k) => {
23
+ const v = e.properties[k];
24
+ return Array.isArray(v) ? v : [];
25
+ };
26
+ /** The properties of an element as a table, leaving out those a page shows in another way. */
27
+ function propertiesTable(e, skip = []) {
28
+ const rows = Object.entries(e.properties).filter(([k, v]) => !skip.includes(k) && !(Array.isArray(v) && v.length === 0) && v !== null && v !== "");
29
+ return rows.length === 0 ? [] : [{ kind: "table", head: [[t("Property")], [t("Value")]], rows: rows.map(([k, v]) => [[c(k)], [t(value(v))]]) }];
30
+ }
31
+ /** The program lens. */
32
+ export function programLens(options) {
33
+ let models = [];
34
+ const group = options.group ?? "Programs";
35
+ /** The program a model is of: the name of the model without the tier at its end (`ergonex-operator` is of `ergonex`). */
36
+ const programOf = (m) => m.name.replace(/-[^-]+$/, "");
37
+ /** The tier of a model: what follows the program in its name. */
38
+ const tierOf = (m) => `${m.name.slice(programOf(m).length + 1)} tier`;
39
+ const dir = (m) => `programs/${slug(m.name)}`;
40
+ const verbPage = (m, v) => `${dir(m)}/verb-${slug(v.name)}.html`;
41
+ return {
42
+ name: options.name,
43
+ read: async () => {
44
+ models = await options.source();
45
+ return (build, after) => {
46
+ const add = (p) => build.add({ ...p, section: "programs" });
47
+ add({
48
+ path: "programs/index.html",
49
+ title: "Programs",
50
+ description: "The command-line programs, tools and routes of the libraries, documented from their own descriptions, one page set for each tier.",
51
+ group,
52
+ order: after,
53
+ blocks: [
54
+ para(t("Each program is described once, in governance, as actions that say what they do and may do, and is drawn as a command, a tool and a route. A program has one description for each tier of its audience: a verb a tier cannot see is listed in that tier with the reason, and is not drawn.")),
55
+ heading(2, "Programs"),
56
+ { kind: "cards", cards: models.map((m) => ({ title: m.title, href: { kind: "page", path: `${dir(m)}/index.html` }, text: [t(m.summary)], badges: [badge(`${m.elements.filter((e) => e.kind === "verb").length} verbs`, "info"), ...(m.findings.length > 0 ? [badge(`${m.findings.length} findings`, "warn")] : [])] })) },
57
+ ],
58
+ });
59
+ let order = after + 1;
60
+ for (const m of models) {
61
+ const byId = new Map(m.elements.map((e) => [e.id, e]));
62
+ const verbs = m.elements.filter((e) => e.kind === "verb");
63
+ const surfaces = (v) => m.trace.filter((x) => x.from === v.id && x.how === "projects to").map((x) => byId.get(x.to)).filter((e) => e !== undefined);
64
+ const kindsOfVerb = (v) => [...new Set(surfaces(v).map((s) => s.kind.replace("-command", "").replace("-tool", "").replace("-route", "")))];
65
+ const codes = m.elements.filter((e) => e.kind === "problem-code");
66
+ const outcomes = m.elements.filter((e) => e.kind === "outcome");
67
+ const plugins = m.elements.filter((e) => e.kind === "plugin");
68
+ add({
69
+ path: `${dir(m)}/index.html`,
70
+ title: m.title,
71
+ description: m.summary,
72
+ group: programOf(m),
73
+ order: order++,
74
+ navTitle: tierOf(m),
75
+ blocks: [
76
+ para(t(m.summary)),
77
+ heading(2, "Verbs"),
78
+ { kind: "table", head: [[t("Verb")], [t("What it does")], [t("Effect")], [t("Drawn as")], [t("Not drawn")]], rows: verbs.map((v) => [[{ kind: "link", href: { kind: "page", path: verbPage(m, v) }, children: [c(v.name)] }], [t(v.definition)], [t(prop(v, "effect"))], [t(kindsOfVerb(v).join(", ") || "none")], [t(list(v, "notProjected").join("; "))]]) },
79
+ ...(plugins.length === 0 ? [] : [heading(2, "Plugins"), { kind: "table", head: [[t("Plugin")], [t("Contributes")]], rows: plugins.map((p) => [[c(p.name)], [t(p.definition)]]) }]),
80
+ ...(codes.length === 0 ? [] : [heading(2, "Problem codes"), { kind: "table", head: [[t("Code")], [t("Meaning")]], rows: codes.map((e) => [[c(e.name)], [t(e.definition)]]) }]),
81
+ ...(outcomes.length === 0 ? [] : [heading(2, "Exit statuses"), { kind: "table", head: [[t("Outcome")], [t("Meaning")]], rows: outcomes.map((e) => [[c(e.name)], [t(e.definition)]]) }]),
82
+ ...(m.findings.length === 0 ? [] : [heading(2, "Findings"), { kind: "list", ordered: false, items: m.findings.map((f) => [para(c(f.element), t(` ${f.rule}: ${f.message}`))]) }]),
83
+ ],
84
+ });
85
+ for (const v of verbs) {
86
+ const options_ = m.elements.filter((e) => e.kind === "option" && e.parent === v.id);
87
+ const operands = m.elements.filter((e) => e.kind === "operand" && e.parent === v.id);
88
+ const action = m.trace.filter((x) => x.to === v.id && x.how !== undefined).map((x) => byId.get(x.from)).find((e) => e?.kind === "action");
89
+ const drawn = surfaces(v);
90
+ add({
91
+ path: verbPage(m, v),
92
+ title: v.name,
93
+ description: v.definition,
94
+ group: programOf(m),
95
+ order: order++,
96
+ parent: `${dir(m)}/index.html`,
97
+ navKind: "Verbs",
98
+ navTitle: v.name,
99
+ badges: [badge("verb", "info"), ...(prop(v, "effect") === "" ? [] : [badge(prop(v, "effect"))])],
100
+ blocks: [
101
+ para(t(v.definition)),
102
+ para(t("Program "), { kind: "link", href: { kind: "page", path: `${dir(m)}/index.html` }, children: [c(m.name)] }, t(`. Origin `), c(prop(v, "origin")), t(".")),
103
+ heading(2, "Governance: the action"),
104
+ para(t("What the verb is and may do, as governance says it. Each annotation is expressed by the surfaces or says why it is not.")),
105
+ ...propertiesTable(action ?? v, ["path", "origin", "examples", "offered", "projections", "notProjected"]),
106
+ ...(operands.length === 0 ? [] : [heading(2, "Operands"), { kind: "table", head: [[t("Operand")], [t("Meaning")]], rows: operands.map((o) => [[c(o.name)], [t(o.definition)]]) }]),
107
+ ...(options_.length === 0 ? [] : [heading(2, "Options"), { kind: "table", head: [[t("Option")], [t("Meaning")], [t("Properties")]], rows: options_.map((o) => [[c(o.name)], [t(o.definition)], [t(Object.entries(o.properties).filter(([, x]) => x !== null && x !== "" && !(Array.isArray(x) && x.length === 0)).map(([k, x]) => `${k}=${value(x)}`).join(", "))]]) }]),
108
+ ...(list(v, "examples").length === 0 ? [] : [heading(2, "Examples"), { kind: "code", lang: "sh", text: list(v, "examples").join("\n") }]),
109
+ heading(2, "Physical: what it is drawn as"),
110
+ ...(drawn.length === 0 ? [para(t("Not drawn by any surface for this tier."))] : drawn.flatMap((s) => [heading(3, s.name, slug(`${s.kind}-${s.name}`)), para(t(`${s.kind}. `), t(s.definition)), ...propertiesTable(s)])),
111
+ ...(list(v, "notProjected").length === 0 ? [] : [heading(3, "Not drawn"), { kind: "list", ordered: false, items: list(v, "notProjected").map((x) => [para(t(x))]) }]),
112
+ ],
113
+ });
114
+ }
115
+ }
116
+ return order;
117
+ };
118
+ },
119
+ files: () => [
120
+ ...models.map((m) => ({ path: `programs/${slug(m.name)}.json`, text: `${JSON.stringify(m, null, 2)}\n`, what: `the ${m.title} program in layers (governance, logical, surfaces) with its trace and findings` })),
121
+ { path: "programs/index.json", text: `${JSON.stringify(models.map((m) => ({ name: m.name, library: m.library, title: m.title, summary: m.summary, file: `programs/${slug(m.name)}.json`, elements: m.elements.length, findings: m.findings.length })), null, 2)}\n`, what: "the list of programs with the file of each" },
122
+ ],
123
+ };
124
+ }
@@ -0,0 +1,10 @@
1
+ import type { Lens } from "../mod.js";
2
+ /** What the releases lens is given. */
3
+ export interface ReleasesOptions {
4
+ /** Its name, which the build reports it by. */
5
+ readonly name: string;
6
+ /** The record, from the repository's root. */
7
+ readonly file: string;
8
+ }
9
+ /** The releases lens. */
10
+ export declare function releasesLens(options: ReleasesOptions): Lens;
@@ -0,0 +1,37 @@
1
+ // Spec: 0001-docs FR-002
2
+ /**
3
+ * The releases lens (commons 0011-documentation FR-035): the record of the next release, read from the file the release command writes (`commons/generated/release.auto.json`): each library it publishes, at which version, under which tag
4
+ * and in which order, with a link to the library's page. The lens knows nothing of how the record is made.
5
+ *
6
+ * @module
7
+ */
8
+ import { fs, path } from "@intellectual-frontiers/system";
9
+ /** The releases lens. */
10
+ export function releasesLens(options) {
11
+ return {
12
+ name: options.name,
13
+ read: async (b) => {
14
+ let rows = [];
15
+ try {
16
+ const record = JSON.parse(await fs.readTextFile(path.join(b.root, options.file)));
17
+ rows = [...(record.releases ?? [])];
18
+ }
19
+ catch {
20
+ b.found.push({ where: options.file, problem: { kind: "undescribed", entity: `the release record ${options.file}, which the releases lens is told of, cannot be read` } });
21
+ }
22
+ return (build, after) => {
23
+ const text = (t) => ({ kind: "text", text: t });
24
+ const blocks = [
25
+ { kind: "paragraph", inlines: [text("What the next release publishes and tags, in the order of the imports: a library comes after the libraries it imports. The record is written by the release command and read by the release workflow.")] },
26
+ {
27
+ kind: "table",
28
+ head: ["Order", "Library", "Version", "Tag", "Published"].map((h) => [text(h)]),
29
+ rows: rows.map((r, i) => [[text(String(i + 1))], [{ kind: "link", href: { kind: "page", path: `overview/${r.slug}.html` }, children: [{ kind: "code", text: r.slug }] }], [{ kind: "code", text: r.version }], [{ kind: "code", text: r.tag }], [text(r.publish ? "yes" : "tag only")]]),
30
+ },
31
+ ];
32
+ build.add({ path: "overview/releases.html", title: "Releases", description: "What the next release publishes and tags, library by library.", section: "overview", group: "Libraries", order: 8, blocks });
33
+ return after;
34
+ };
35
+ },
36
+ };
37
+ }
package/dist/lens.d.ts ADDED
@@ -0,0 +1,30 @@
1
+ /**
2
+ * What a lens is (commons 0011-documentation FR-013, FR-026): a value a configuration passes, which knows one library. Its `read` is given
3
+ * the build, the areas and their API once every API page is registered; it recognises the library's exports by the type the checker gives
4
+ * each, imports their module, registers the page each entity is shown on (so that an API page can link to it), and returns what makes its
5
+ * pages once every other page is made. The package ships no lens and depends on no library it shows.
6
+ *
7
+ * @module
8
+ */
9
+ import type { Build } from "./build.js";
10
+ import type { AreaApi } from "./extract/api.js";
11
+ import type { Area } from "./sources.js";
12
+ /** What makes a lens's pages: given the order its first group of pages takes in the Models section, it returns the order after its last. */
13
+ export type LensPages = (b: Build, after: number) => number;
14
+ /** A file a lens adds to the site beside its pages: the JSON of a model. */
15
+ export interface SiteFile {
16
+ /** Where it is, from the site's root. */
17
+ readonly path: string;
18
+ readonly text: string;
19
+ /** What it is, in a few words, for the index of the site that a program reads (`llms.txt`). */
20
+ readonly what: string;
21
+ }
22
+ /** A lens: its name, and what reads its library's values and makes their pages. */
23
+ export interface Lens {
24
+ /** Its name, as `data`. */
25
+ readonly name: string;
26
+ /** Reads the values of the areas whose exports are its library's, and returns what makes their pages. */
27
+ readonly read: (b: Build, areas: readonly Area[], apis: readonly AreaApi[]) => Promise<LensPages>;
28
+ /** The files it adds to the site once its pages are made (commons 0011-documentation FR-028). */
29
+ readonly files?: (b: Build) => readonly SiteFile[];
30
+ }
package/dist/lens.js ADDED
@@ -0,0 +1 @@
1
+ export {};