@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,283 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * The Overview section (commons 0011-documentation FR-009, FR-027): the home page, made from the configuration's home (in commons,
4
+ * `commons/about.ts`) and the spec kit (a card for each capability, under the capability it is part of), and a page for each package,
5
+ * made from its `about`: its summary, its areas, its folders and what each may import, its commands, and its rules with what enforces
6
+ * each.
7
+ *
8
+ * @module
9
+ */
10
+ import { absurd } from "@intellectual-frontiers/core";
11
+ import { under } from "../config.js";
12
+ import { specPage } from "../links.js";
13
+ import { possessive } from "../model.js";
14
+ import { areaFiles } from "../sources.js";
15
+ import { exampleBlocks } from "./areas.js";
16
+ import { numberOf } from "./specs.js";
17
+ /** The first sentence of a text, for a card. */
18
+ export function firstSentence(t, max = 240) {
19
+ const flat = t.replace(/\s+/g, " ").trim();
20
+ const m = /^(.+?[.!?])(\s|$)/.exec(flat);
21
+ const s = m?.[1] ?? flat;
22
+ if (s.length <= max)
23
+ return s;
24
+ const cut = s.slice(0, max);
25
+ return `${cut.slice(0, Math.max(cut.lastIndexOf(" "), max - 20))}…`;
26
+ }
27
+ /**
28
+ * What each package imports and what imports it, among the packages of the site: the packages its own sources (not its tests, tools or manifest) import by name, by slug.
29
+ */
30
+ export function dependenciesOf(b, packages) {
31
+ const nameOf = (p) => {
32
+ const file = under(p.dir, "package.json");
33
+ if (!b.exists(file))
34
+ return "";
35
+ return JSON.parse(b.read(file)).name ?? "";
36
+ };
37
+ const slugOf = new Map(packages.map((p) => [nameOf(p), p.slug]).filter(([n]) => n !== ""));
38
+ const uses = new Map();
39
+ const usedBy = new Map();
40
+ for (const p of packages) {
41
+ const found = new Set();
42
+ for (const f of areaFiles(b.root, p.dir)) {
43
+ const rel = f.slice(p.dir.length + 1);
44
+ if (/^(suite|tools|tests|node_modules|dist)\//.test(rel) || /^(library|about|release)\.ts$/.test(rel))
45
+ continue;
46
+ for (const m of b.read(f).matchAll(/from\s+"(@intellectual-frontiers\/[a-z0-9-]+)[/"]/g)) {
47
+ const other = slugOf.get(m[1] ?? "");
48
+ if (other !== undefined && other !== p.slug)
49
+ found.add(other);
50
+ }
51
+ }
52
+ const mine = [...found].sort();
53
+ uses.set(p.slug, mine);
54
+ for (const o of mine)
55
+ usedBy.set(o, [...(usedBy.get(o) ?? []), p.slug].sort());
56
+ }
57
+ return { uses, usedBy };
58
+ }
59
+ /** The imports of the libraries without the ones another import implies: A importing C is left out where A imports B and B imports C, at any distance. */
60
+ function reduced(libraries, uses) {
61
+ const reaches = (from, to, skip) => {
62
+ const seen = new Set([from]);
63
+ const stack = (uses.get(from) ?? []).filter((x) => x !== skip);
64
+ while (stack.length > 0) {
65
+ const at = stack.pop() ?? "";
66
+ if (at === to)
67
+ return true;
68
+ if (seen.has(at))
69
+ continue;
70
+ seen.add(at);
71
+ stack.push(...(uses.get(at) ?? []));
72
+ }
73
+ return false;
74
+ };
75
+ const out = [];
76
+ for (const p of libraries)
77
+ for (const c of uses.get(p.slug) ?? [])
78
+ if (!(uses.get(p.slug) ?? []).some((mid) => mid !== c && reaches(mid, c, "")))
79
+ out.push([p.slug, c]);
80
+ return out;
81
+ }
82
+ /** The page of a package. */
83
+ export const packagePage = (pkg) => `overview/${pkg.slug}.html`;
84
+ /** The overview page of an area. */
85
+ export const areaPage = (area) => `api/${area.slug}/index.html`;
86
+ const heading = (id, t) => ({ kind: "heading", level: 2, id, text: [{ kind: "text", text: t }] });
87
+ const code = (t) => [{ kind: "code", text: t }];
88
+ function enforcer(e) {
89
+ switch (e.kind) {
90
+ case "test":
91
+ return e.file;
92
+ case "lint":
93
+ return `lint rule ${e.rule}`;
94
+ case "compiler":
95
+ return `compiler option ${e.option}`;
96
+ case "review":
97
+ return "review";
98
+ default:
99
+ return absurd(e);
100
+ }
101
+ }
102
+ /** The tables an `about` holds: folders, commands and rules. */
103
+ function aboutTables(b, about, file, page) {
104
+ const scope = { page, file };
105
+ const out = [];
106
+ if (about.folders !== undefined && about.folders.length > 0) {
107
+ out.push(heading("folders", "Folders"), {
108
+ kind: "table",
109
+ head: [[{ kind: "text", text: "Folder" }], [{ kind: "text", text: "What it is" }], [{ kind: "text", text: "May import" }]],
110
+ rows: about.folders.map((f) => [code(f.path), b.line(f.what, scope), b.line(f.mayImport.join("; "), scope)]),
111
+ });
112
+ }
113
+ if (about.commands !== undefined && about.commands.length > 0) {
114
+ out.push(heading("commands", "Commands"), {
115
+ kind: "table",
116
+ head: [[{ kind: "text", text: "Command" }], [{ kind: "text", text: "What it does" }]],
117
+ rows: about.commands.map((c) => [code(c.run), b.line(c.does, scope)]),
118
+ });
119
+ }
120
+ if (about.rules !== undefined && about.rules.length > 0) {
121
+ out.push(heading("rules", "Rules"), {
122
+ kind: "table",
123
+ head: [[{ kind: "text", text: "Rule" }], [{ kind: "text", text: "Enforced by" }]],
124
+ rows: about.rules.map((r) => [
125
+ b.line(r.rule, scope),
126
+ r.enforcedBy.flatMap((e, i) => [...(i === 0 ? [] : [{ kind: "text", text: ", " }]), ...code(enforcer(e))]),
127
+ ]),
128
+ });
129
+ }
130
+ return out;
131
+ }
132
+ /** The capabilities as cards: each specification in force, under the one it is part of. */
133
+ function capabilityCards(b) {
134
+ const page = "index.html";
135
+ const cardOf = (id) => {
136
+ const s = b.kit.specs.find((x) => x.id === id);
137
+ const children = b.kit.specs.filter((x) => x.partOf === id).map((x) => cardOf(x.id));
138
+ return {
139
+ title: s?.title ?? id,
140
+ href: { kind: "page", path: specPage(id) },
141
+ text: b.line(firstSentence(s?.input ?? ""), { page, file: s?.file ?? "", spec: id }),
142
+ badges: [{ text: numberOf(id), tone: "neutral" }],
143
+ ...(children.length === 0 ? {} : { children }),
144
+ };
145
+ };
146
+ return b.kit.specs.filter((s) => s.partOf === undefined).map((s) => cardOf(s.id));
147
+ }
148
+ /**
149
+ * The home page and a page for each package.
150
+ *
151
+ * @param b - the build
152
+ * @param top - the home's package: the repository as a whole
153
+ * @param packages - the packages
154
+ * @param areas - their areas
155
+ */
156
+ export function overviewPages(b, top, packages, areas) {
157
+ const home = "index.html";
158
+ const homeScope = { page: home, file: top.file };
159
+ const subject = b.config.subject;
160
+ const ownFile = (p) => p.file !== b.config.fileFromRoot;
161
+ if (ownFile(top))
162
+ b.files.set(top.file, home);
163
+ if (top.dir !== "")
164
+ b.files.set(top.dir, home);
165
+ for (const p of packages) {
166
+ if (ownFile(p))
167
+ b.files.set(p.file, packagePage(p));
168
+ if (p.dir !== "")
169
+ b.files.set(p.dir, packagePage(p));
170
+ }
171
+ const capabilities = capabilityCards(b);
172
+ b.add({
173
+ path: home,
174
+ title: top.about.title,
175
+ description: firstSentence(top.about.summary),
176
+ section: "overview",
177
+ group: b.config.subject.charAt(0).toUpperCase() + b.config.subject.slice(1),
178
+ order: 0,
179
+ blocks: [
180
+ ...b.md(top.about.summary, homeScope),
181
+ heading("libraries", "Libraries"),
182
+ {
183
+ kind: "cards",
184
+ cards: packages.map((p) => ({
185
+ title: p.about.title,
186
+ href: { kind: "page", path: packagePage(p) },
187
+ text: b.line(firstSentence(p.about.summary), { page: home, file: p.file }),
188
+ })),
189
+ },
190
+ ...(capabilities.length === 0 ? [] : [
191
+ heading("capabilities", "Capabilities"),
192
+ { kind: "paragraph", inlines: [{ kind: "text", text: `Each capability is a specification of ${possessive(subject)} spec kit, under the one it is part of.` }] },
193
+ { kind: "cards", cards: capabilities },
194
+ ]),
195
+ ...aboutTables(b, top.about, top.file, home),
196
+ ],
197
+ });
198
+ const libraries = packages.filter((p) => b.exists(under(p.dir, "library.ts")));
199
+ const { uses, usedBy } = dependenciesOf(b, libraries);
200
+ const bySlug = new Map(libraries.map((p) => [p.slug, p]));
201
+ const linkList = (slugs) => ({
202
+ kind: "paragraph",
203
+ inlines: slugs.flatMap((sl, i) => {
204
+ const q = bySlug.get(sl);
205
+ return [...(i === 0 ? [] : [{ kind: "text", text: ", " }]), q === undefined ? { kind: "code", text: sl } : { kind: "link", href: { kind: "page", path: packagePage(q) }, children: [{ kind: "text", text: q.about.title }] }];
206
+ }),
207
+ });
208
+ if (libraries.length > 0) {
209
+ b.add({
210
+ path: "overview/map.html",
211
+ title: "Library map",
212
+ description: "What each library imports, and what imports it.",
213
+ section: "overview",
214
+ group: "Libraries",
215
+ order: 9,
216
+ blocks: [
217
+ { kind: "paragraph", inlines: [{ kind: "text", text: "A library imports another by its package name, and only the ones it lists here. Core imports nothing, and every other library imports it." }] },
218
+ { kind: "diagram", source: `flowchart LR\n${reduced(libraries, uses).map(([a, c]) => ` ${a.replaceAll("-", "_")}[${bySlug.get(a)?.about.title ?? a}] --> ${c.replaceAll("-", "_")}[${bySlug.get(c)?.about.title ?? c}]`).join("\n")}`, caption: "Which library imports which: an import that another import already implies is left out" },
219
+ {
220
+ kind: "table",
221
+ head: ["Library", "Imports", "Imported by"].map((h) => [{ kind: "text", text: h }]),
222
+ rows: libraries.map((p) => [
223
+ [{ kind: "link", href: { kind: "page", path: packagePage(p) }, children: [{ kind: "text", text: p.about.title }] }],
224
+ (uses.get(p.slug) ?? []).flatMap((u, i) => [...(i === 0 ? [] : [{ kind: "text", text: ", " }]), { kind: "code", text: u }]),
225
+ (usedBy.get(p.slug) ?? []).flatMap((u, i) => [...(i === 0 ? [] : [{ kind: "text", text: ", " }]), { kind: "code", text: u }]),
226
+ ]),
227
+ },
228
+ ],
229
+ });
230
+ }
231
+ packages.forEach((p, i) => {
232
+ const page = packagePage(p);
233
+ const file = p.file;
234
+ const scope = { page, file, ...(p.about.spec === undefined ? {} : { spec: p.about.spec.id }) };
235
+ const own = areas.filter((a) => a.pkg.slug === p.slug);
236
+ const blocks = [...b.md(p.about.summary, scope)];
237
+ if (p.about.spec !== undefined) {
238
+ blocks.push({ kind: "paragraph", inlines: [{ kind: "text", text: "Specification: " }, ...b.line(`${p.about.spec.repo} ${p.about.spec.id}`, scope)] });
239
+ }
240
+ if (p.about.facts !== undefined && p.about.facts.length > 0) {
241
+ blocks.push({ kind: "table", head: [[{ kind: "text", text: "Fact" }], [{ kind: "text", text: "Value" }]], rows: p.about.facts.map((f) => [[{ kind: "text", text: f.label }], b.line(f.value, scope)]) });
242
+ }
243
+ const kit = b.kit.sources.find((k) => k.dir === under(p.dir, "spec-kit"));
244
+ const specs = kit === undefined ? [] : b.kit.specs.filter((sp) => sp.file.startsWith(`${kit.dir}/`));
245
+ if (own.length > 0) {
246
+ blocks.push(heading("areas", "Areas"), {
247
+ kind: "cards",
248
+ cards: own.map((a) => ({
249
+ title: a.title,
250
+ href: { kind: "page", path: areaPage(a) },
251
+ text: [{ kind: "code", text: a.entryPoints.join(", ") }],
252
+ ...(a.spec === undefined ? {} : { badges: [{ text: numberOf(a.spec.id), tone: "neutral" }] }),
253
+ })),
254
+ });
255
+ }
256
+ if (p.about.layers !== undefined && p.about.layers.length > 0) {
257
+ const order = ["governance", "logical", "physical"];
258
+ const layers = [...p.about.layers].sort((x, y) => order.indexOf(x.layer) - order.indexOf(y.layer));
259
+ blocks.push(heading("layers", "Layers"), {
260
+ kind: "table",
261
+ head: [[{ kind: "text", text: "Layer" }], [{ kind: "text", text: "Folder" }], [{ kind: "text", text: "May import of this library" }]],
262
+ rows: layers.map((l) => [[{ kind: "strong", children: [{ kind: "text", text: l.layer }] }], [{ kind: "code", text: l.folder }], (l.mayImport ?? []).length === 0 ? [{ kind: "text", text: l.layer === "governance" ? "nothing" : l.layer === "logical" ? "governance" : "governance, logical" }] : (l.mayImport ?? []).flatMap((m, i) => [...(i === 0 ? [] : [{ kind: "text", text: ", " }]), { kind: "code", text: m }])]),
263
+ });
264
+ }
265
+ if ((uses.get(p.slug) ?? []).length > 0)
266
+ blocks.push(heading("imports", "Imports"), linkList(uses.get(p.slug) ?? []));
267
+ if ((usedBy.get(p.slug) ?? []).length > 0)
268
+ blocks.push(heading("imported-by", "Imported by"), linkList(usedBy.get(p.slug) ?? []));
269
+ if (specs.length > 0) {
270
+ blocks.push(heading("specifications", "Specifications"), {
271
+ kind: "table",
272
+ head: [[{ kind: "text", text: "Number" }], [{ kind: "text", text: "Specification" }], [{ kind: "text", text: "Requirements" }]],
273
+ rows: specs.map((sp) => [[{ kind: "code", text: numberOf(sp.id) }], [{ kind: "link", href: { kind: "page", path: specPage(sp.id) }, children: [{ kind: "text", text: sp.title }] }], [{ kind: "text", text: String(sp.requirements.length) }]]),
274
+ });
275
+ }
276
+ blocks.push(...aboutTables(b, p.about, file, page));
277
+ if ((p.about.examples ?? []).length > 0)
278
+ blocks.push(heading("examples", "Examples"));
279
+ for (const x of p.about.examples ?? [])
280
+ blocks.push(...exampleBlocks(b, under(p.dir, x.file), x.file, x.what, scope));
281
+ b.add({ path: page, title: p.about.title, description: firstSentence(p.about.summary), section: "overview", group: "Libraries", order: 10 + i, blocks });
282
+ });
283
+ }
@@ -0,0 +1,31 @@
1
+ import type { Build } from "../build.js";
2
+ import type { Spec } from "../extract/specs.js";
3
+ /** The most rows a page of the matrix holds: a page ends at a specification once it has this many. */
4
+ export declare const ROW_BUDGET = 150;
5
+ /** The folder that holds a kit's specifications, from the root, of the kit a specification was read from: `commons/core/spec-kit` for `commons/core/spec-kit/specs/0001-core/spec.md`. */
6
+ export declare function kitDirOf(b: Build, spec: Spec): string;
7
+ /** The library a spec kit belongs to, by the name of the folder that holds `spec-kit`: `core` for `commons/core/spec-kit`, and `commons` for the repository's own kit. */
8
+ export declare function kitNameOf(dir: string): string;
9
+ /** The files that prove a requirement (the tests that name it) and the files written to it (a `// Spec:` header names it), by requirement as `0009-example FR-001`. */
10
+ export interface Trace {
11
+ readonly tests: ReadonlyMap<string, readonly string[]>;
12
+ readonly code: ReadonlyMap<string, readonly string[]>;
13
+ }
14
+ /** Reads the trace from the files of the repository: a requirement named in a quoted string of a test file is proved by it, and one named in the `// Spec:` header of any other file is written there. */
15
+ export declare function traceOf(b: Build): Trace;
16
+ /** The number of a specification's id: `0009` of `0009-example`. */
17
+ export declare const numberOf: (id: string) => string;
18
+ /** The page of the constitution of a plain spec kit. */
19
+ export declare const CONSTITUTION_PAGE = "specs/constitution.html";
20
+ /**
21
+ * The register, the matrix and a page for each specification in force.
22
+ *
23
+ * @param b - the build
24
+ */
25
+ export declare function specPages(b: Build): void;
26
+ /**
27
+ * The pages that cite each specification and requirement, added to the specifications' pages once every other page is made.
28
+ *
29
+ * @param b - the build
30
+ */
31
+ export declare function citedBy(b: Build): void;