@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/pages/api.ts
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The API pages of each area (commons 0011-documentation FR-010): a page for each source file its exports come from, in the order its
|
|
4
|
+
* entry points export them, with the file's module comment (what it is, its account, its examples, its limits) and an entry for each
|
|
5
|
+
* export: its kinds, its signature, its TSDoc (summary, remarks, parameters, what it returns, examples, see also, deprecation) and the
|
|
6
|
+
* members of an interface. Pages and anchors are registered first, so that every other page's `{@link}` and file links reach them.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import type { Build } from "../build.ts";
|
|
11
|
+
import type { ApiExport, AreaApi } from "../extract/api.ts";
|
|
12
|
+
import type { LinkScope } from "../links.ts";
|
|
13
|
+
import type { Badge, Block, Inline } from "../model.ts";
|
|
14
|
+
import { type Area, inside } from "../sources.ts";
|
|
15
|
+
import { moduleComment } from "../tsdoc.ts";
|
|
16
|
+
import { firstSentence } from "./overview.ts";
|
|
17
|
+
|
|
18
|
+
/** A module page of an area: its page, its title and the first sentence of its module comment. */
|
|
19
|
+
export interface ModulePage {
|
|
20
|
+
/** The page. */
|
|
21
|
+
readonly page: string;
|
|
22
|
+
/** The file, from the checkout's root. */
|
|
23
|
+
readonly file: string;
|
|
24
|
+
/** Its title: the file's path in the area, without `.ts`. */
|
|
25
|
+
readonly title: string;
|
|
26
|
+
/** The first sentence of its module comment. */
|
|
27
|
+
readonly summary: string;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** The anchor of an export on its page. */
|
|
31
|
+
export const anchorOf = (name: string): string => name.replace(/[^\w.-]/g, "-");
|
|
32
|
+
|
|
33
|
+
/** The title of a file in an area: its path from the area's folder (or the package's), without `.ts`. */
|
|
34
|
+
function titleOf(area: Area, file: string): string {
|
|
35
|
+
const from = (dir: string): string => (dir === "" ? file : file.slice(dir.length + 1));
|
|
36
|
+
const base = inside(area.dir, file) ? from(area.dir) : inside(area.pkg.dir, file) ? from(area.pkg.dir) : file;
|
|
37
|
+
return base.replace(/\.ts$/, "");
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Whether a file is the area's own, or one it re-exports from elsewhere. */
|
|
41
|
+
const own = (area: Area, file: string): boolean => inside(area.dir, file);
|
|
42
|
+
|
|
43
|
+
/** The page of a file of an area; what the area re-exports from elsewhere is on one page. */
|
|
44
|
+
const pageOf = (area: Area, file: string): string =>
|
|
45
|
+
own(area, file) ? `api/${area.slug}/${titleOf(area, file).replace(/\//g, "-")}.html` : `api/${area.slug}/re-exports.html`;
|
|
46
|
+
|
|
47
|
+
/** The pages of an area's exports, in the order of their first export, each with its file (none for the re-exports). */
|
|
48
|
+
function pagesOf(area: Area, api: AreaApi): (readonly [string, string | undefined])[] {
|
|
49
|
+
const out = new Map<string, string | undefined>();
|
|
50
|
+
for (const e of api.exports) {
|
|
51
|
+
const page = pageOf(area, e.file);
|
|
52
|
+
if (!out.has(page)) out.set(page, own(area, e.file) ? e.file : undefined);
|
|
53
|
+
}
|
|
54
|
+
return [...out];
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The pages and anchors of every area's API, registered before any page is made.
|
|
59
|
+
*
|
|
60
|
+
* @param b - the build
|
|
61
|
+
* @param areas - the areas
|
|
62
|
+
* @param apis - their APIs
|
|
63
|
+
*/
|
|
64
|
+
export function registerApi(b: Build, areas: readonly Area[], apis: readonly AreaApi[]): Map<string, ModulePage[]> {
|
|
65
|
+
const modules = new Map<string, ModulePage[]>();
|
|
66
|
+
for (const area of areas) {
|
|
67
|
+
const api = apis.find((a) => a.slug === area.slug);
|
|
68
|
+
if (api === undefined) continue;
|
|
69
|
+
const names = new Map<string, { path: string; anchor: string }>();
|
|
70
|
+
const list: ModulePage[] = [];
|
|
71
|
+
for (const [page, file] of pagesOf(area, api)) {
|
|
72
|
+
if (file === undefined) {
|
|
73
|
+
list.push({ page, file: "", title: "re-exports", summary: `What ${area.title} exports from elsewhere, so that its users need import nothing else.` });
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
if (!b.files.has(file)) b.files.set(file, page);
|
|
77
|
+
if (!b.apiFiles.has(file)) b.apiFiles.set(file, page);
|
|
78
|
+
const doc = b.exists(file) ? moduleComment(b.read(file)) : undefined;
|
|
79
|
+
list.push({ page, file, title: titleOf(area, file), summary: doc === undefined ? "" : firstSentence(doc.summary, 200) });
|
|
80
|
+
}
|
|
81
|
+
for (const e of api.exports) {
|
|
82
|
+
const entry = { path: pageOf(area, e.file), anchor: anchorOf(e.name) };
|
|
83
|
+
names.set(e.name, entry);
|
|
84
|
+
const key = `${e.file}#${e.declared ?? e.name.split(".").pop() ?? e.name}`;
|
|
85
|
+
if (own(area, e.file) && !b.declared.has(key)) b.declared.set(key, entry);
|
|
86
|
+
const short = e.name.split(".").pop();
|
|
87
|
+
if (short !== undefined && !names.has(short)) names.set(short, entry);
|
|
88
|
+
}
|
|
89
|
+
b.exports.set(area.slug, names);
|
|
90
|
+
modules.set(area.slug, list);
|
|
91
|
+
}
|
|
92
|
+
return modules;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const textInl = (t: string): Inline => ({ kind: "text", text: t });
|
|
96
|
+
|
|
97
|
+
/** The blocks of an export's entry. */
|
|
98
|
+
function entryBlocks(b: Build, e: ApiExport, scope: LinkScope): Block[] {
|
|
99
|
+
const d = e.doc;
|
|
100
|
+
const out: Block[] = [];
|
|
101
|
+
if (d.deprecated !== undefined) out.push({ kind: "callout", tone: "warn", title: "Deprecated", blocks: b.md(d.deprecated, scope) });
|
|
102
|
+
out.push(...b.md(d.summary, scope));
|
|
103
|
+
if (d.remarks !== undefined) out.push(...b.md(d.remarks, scope));
|
|
104
|
+
if (d.params.length > 0) {
|
|
105
|
+
out.push({
|
|
106
|
+
kind: "table",
|
|
107
|
+
head: [[textInl("Parameter")], [textInl("What it is")]],
|
|
108
|
+
rows: d.params.map((p) => [[{ kind: "code", text: p.name }], b.line(p.text, scope)]),
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
if (d.returns !== undefined) out.push({ kind: "paragraph", inlines: [{ kind: "strong", children: [textInl("Returns: ")] }, ...b.line(d.returns, scope)] });
|
|
112
|
+
if (e.members.length > 0) {
|
|
113
|
+
out.push({
|
|
114
|
+
kind: "table",
|
|
115
|
+
head: [[textInl("Member")], [textInl("Type")], [textInl("What it is")]],
|
|
116
|
+
rows: e.members.map((m) => [[{ kind: "code", text: `${m.name}${m.optional ? "?" : ""}` }], [{ kind: "code", text: m.type }], b.line(m.doc, scope)]),
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
for (const x of d.examples) out.push(...b.example(x, scope));
|
|
120
|
+
if (d.limits !== undefined) out.push({ kind: "callout", tone: "limit", title: "Limits", blocks: b.md(d.limits, scope) });
|
|
121
|
+
if (d.see.length > 0) {
|
|
122
|
+
out.push({ kind: "paragraph", inlines: [{ kind: "strong", children: [textInl("See also: ")] }, ...d.see.flatMap((s, i) => [...(i === 0 ? [] : [textInl("; ")]), ...b.line(s, scope)])] });
|
|
123
|
+
}
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* A page for each source file of each area's exports.
|
|
129
|
+
*
|
|
130
|
+
* @param b - the build
|
|
131
|
+
* @param areas - the areas
|
|
132
|
+
* @param apis - their APIs
|
|
133
|
+
* @param modules - the module pages `registerApi` gave
|
|
134
|
+
*/
|
|
135
|
+
export function apiPages(b: Build, areas: readonly Area[], apis: readonly AreaApi[], modules: ReadonlyMap<string, readonly ModulePage[]>): void {
|
|
136
|
+
areas.forEach((area, ai) => {
|
|
137
|
+
const api = apis.find((a) => a.slug === area.slug);
|
|
138
|
+
if (api === undefined) return;
|
|
139
|
+
const spec = area.spec?.id ?? area.pkg.about.spec?.id;
|
|
140
|
+
(modules.get(area.slug) ?? []).forEach((m, mi) => {
|
|
141
|
+
const scope: LinkScope = { page: m.page, file: m.file || (area.dir === "" ? "" : `${area.dir}/`), area: area.slug, ...(spec === undefined ? {} : { spec }) };
|
|
142
|
+
const doc = m.file !== "" && b.exists(m.file) ? moduleComment(b.read(m.file)) : undefined;
|
|
143
|
+
const blocks: Block[] = [];
|
|
144
|
+
if (doc !== undefined) {
|
|
145
|
+
blocks.push(...b.md(doc.summary, scope));
|
|
146
|
+
if (doc.remarks !== undefined) blocks.push(...b.md(doc.remarks, scope));
|
|
147
|
+
for (const x of doc.examples) blocks.push(...b.example(x, scope));
|
|
148
|
+
if (doc.limits !== undefined) blocks.push({ kind: "callout", tone: "limit", title: "Limits", blocks: b.md(doc.limits, scope) });
|
|
149
|
+
}
|
|
150
|
+
if (m.file === "") blocks.push({ kind: "paragraph", inlines: [textInl(m.summary)] });
|
|
151
|
+
else blocks.push({ kind: "meta", inlines: [textInl("Source: "), { kind: "link", href: { kind: "external", url: b.index.blob(m.file) }, children: [{ kind: "code", text: m.file }] }] });
|
|
152
|
+
for (const e of api.exports.filter((x) => pageOf(area, x.file) === m.page)) {
|
|
153
|
+
if (!e.documented) b.found.push({ where: `${m.file} (${area.slug})`, problem: { kind: "undocumented", name: e.name } });
|
|
154
|
+
const badges: Badge[] = e.kinds.map((k) => ({ text: k, tone: "neutral" }));
|
|
155
|
+
const at = b.declared.get(`${e.file}#${e.declared ?? e.name.split(".").pop() ?? e.name}`);
|
|
156
|
+
const home = b.apiFiles.get(e.file) ?? b.files.get(e.file);
|
|
157
|
+
const target = at ?? (home === undefined ? undefined : { path: home, anchor: anchorOf(e.name) });
|
|
158
|
+
const declared: Block[] = m.file === ""
|
|
159
|
+
? [{ kind: "meta", inlines: [textInl("Declared in "), target === undefined ? { kind: "code", text: e.file } : { kind: "link", href: { kind: "page", ...target }, children: [{ kind: "code", text: e.file }] }] }]
|
|
160
|
+
: [];
|
|
161
|
+
const shown = b.entityPages.get(`${area.slug}!${e.name}`);
|
|
162
|
+
const model: Block[] = shown === undefined
|
|
163
|
+
? []
|
|
164
|
+
: [{ kind: "meta", inlines: [textInl("A table of the model: "), { kind: "link", href: { kind: "page", path: shown }, children: [textInl("columns, diagram, SQL and governance")] }] }];
|
|
165
|
+
const body = e.kinds.includes("namespace") ? [] : [...declared, ...model, ...entryBlocks(b, e, { ...scope, file: e.file })];
|
|
166
|
+
blocks.push({ kind: "entry", id: anchorOf(e.name), name: e.name, badges, signature: e.signature, blocks: body });
|
|
167
|
+
}
|
|
168
|
+
b.add({
|
|
169
|
+
path: m.page,
|
|
170
|
+
title: m.title,
|
|
171
|
+
description: m.summary || `${area.title}: ${m.title}`,
|
|
172
|
+
section: "api",
|
|
173
|
+
group: area.title,
|
|
174
|
+
order: 100 + ai * 100 + mi + 1,
|
|
175
|
+
blocks,
|
|
176
|
+
});
|
|
177
|
+
});
|
|
178
|
+
});
|
|
179
|
+
}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The overview of each area (commons 0011-documentation FR-009): the module comment of its first entry point (what the area is, its
|
|
4
|
+
* longer account and its examples), its entry points, its phases, its examples as the compiler checks them, and the limits of every
|
|
5
|
+
* module of the area, gathered from their `@limits`, each under the file it is about.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import type { Build } from "../build.ts";
|
|
10
|
+
import { under } from "../config.ts";
|
|
11
|
+
import type { LinkScope } from "../links.ts";
|
|
12
|
+
import type { Block, Inline } from "../model.ts";
|
|
13
|
+
import type { Area } from "../sources.ts";
|
|
14
|
+
import { areaFiles, inside } from "../sources.ts";
|
|
15
|
+
import { moduleComment } from "../tsdoc.ts";
|
|
16
|
+
import type { ModulePage } from "./api.ts";
|
|
17
|
+
import { areaPage, firstSentence } from "./overview.ts";
|
|
18
|
+
import { numberOf } from "./specs.ts";
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* How a file is named on a page: its path from the outermost package that holds it (`arca/party.ts` in commons' `commons/data`), or
|
|
22
|
+
* from the root where no package does.
|
|
23
|
+
*
|
|
24
|
+
* @param b - the build
|
|
25
|
+
* @param file - the file, from the root
|
|
26
|
+
*/
|
|
27
|
+
export function shownPath(b: Build, file: string): string {
|
|
28
|
+
const dirs = b.config.packages.map((p) => p.dir).filter((d) => d !== "" && inside(d, file)).sort((x, y) => x.length - y.length);
|
|
29
|
+
const outer = dirs[0];
|
|
30
|
+
return outer === undefined ? file : file.slice(outer.length + 1);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Where a file of an area is shown: its page of the API where there is one, else its overview. */
|
|
34
|
+
const fileLink = (b: Build, file: string, fallback: string): Inline => ({
|
|
35
|
+
kind: "link",
|
|
36
|
+
href: { kind: "page", path: b.files.get(file) ?? fallback },
|
|
37
|
+
children: [{ kind: "code", text: shownPath(b, file) }],
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
const heading = (id: string, t: string): Block => ({ kind: "heading", level: 2, id, text: [{ kind: "text", text: t }] });
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* An example file as the site shows it: a heading that names it, what it shows, its module comment as prose, and its code without the
|
|
44
|
+
* comment.
|
|
45
|
+
*
|
|
46
|
+
* @param b - the build
|
|
47
|
+
* @param file - the file, from the checkout's root
|
|
48
|
+
* @param shown - its name as the heading shows it
|
|
49
|
+
* @param what - what it shows
|
|
50
|
+
* @param scope - where the words are
|
|
51
|
+
*/
|
|
52
|
+
export function exampleBlocks(b: Build, file: string, shown: string, what: string, scope: LinkScope): Block[] {
|
|
53
|
+
const text = b.exists(file) ? b.read(file) : "";
|
|
54
|
+
const doc = moduleComment(text);
|
|
55
|
+
const code = text.replace(/^\s*\/\*\*[\s\S]*?\*\/\s*/, "").trimEnd();
|
|
56
|
+
return [
|
|
57
|
+
{ kind: "heading", level: 3, id: `example-${shown.replace(/\W+/g, "-")}`, text: [{ kind: "text", text: "Example: " }, { kind: "code", text: shown }] },
|
|
58
|
+
{ kind: "paragraph", inlines: b.line(what, scope) },
|
|
59
|
+
...(doc === undefined ? [] : b.md(doc.summary, { ...scope, file })),
|
|
60
|
+
{ kind: "code", lang: "ts", title: shown, text: code },
|
|
61
|
+
];
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The overview page of each area, after the API's pages, so that a limit links to the page of its file.
|
|
66
|
+
*
|
|
67
|
+
* @param b - the build
|
|
68
|
+
* @param areas - the areas
|
|
69
|
+
* @param modules - the module pages of each area
|
|
70
|
+
*/
|
|
71
|
+
export function areaPages(b: Build, areas: readonly Area[], modules: ReadonlyMap<string, readonly ModulePage[]>): void {
|
|
72
|
+
areas.forEach((area, i) => {
|
|
73
|
+
const page = areaPage(area);
|
|
74
|
+
const entry = under(area.pkg.dir, area.entryPoints[0] ?? "");
|
|
75
|
+
const spec = area.spec?.id ?? area.pkg.about.spec?.id;
|
|
76
|
+
const scope = { page, file: entry, area: area.slug, ...(spec === undefined ? {} : { spec }) };
|
|
77
|
+
const doc = b.exists(entry) ? moduleComment(b.read(entry)) : undefined;
|
|
78
|
+
const blocks: Block[] = [];
|
|
79
|
+
if (doc !== undefined) {
|
|
80
|
+
blocks.push(...b.md(doc.summary, scope));
|
|
81
|
+
if (doc.remarks !== undefined) blocks.push(...b.md(doc.remarks, scope));
|
|
82
|
+
}
|
|
83
|
+
if (area.spec !== undefined) {
|
|
84
|
+
blocks.push({ kind: "paragraph", inlines: [{ kind: "text", text: "Specification: " }, ...b.line(`${area.spec.repo} ${area.spec.id}`, scope)] });
|
|
85
|
+
}
|
|
86
|
+
blocks.push(heading("entry-points", "Entry points"), {
|
|
87
|
+
kind: "list",
|
|
88
|
+
ordered: false,
|
|
89
|
+
items: area.entryPoints.map((e) => [{ kind: "paragraph", inlines: [fileLink(b, under(area.pkg.dir, e), page)] }]),
|
|
90
|
+
});
|
|
91
|
+
const mods = modules.get(area.slug) ?? [];
|
|
92
|
+
if (mods.length > 0) {
|
|
93
|
+
blocks.push(heading("modules", "Modules"), {
|
|
94
|
+
kind: "cards",
|
|
95
|
+
cards: mods.map((m) => ({ title: m.title, href: { kind: "page", path: m.page }, text: b.line(m.summary, { ...scope, file: m.file }) })),
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
if ((doc?.examples.length ?? 0) + (area.examples?.length ?? 0) > 0) blocks.push(heading("examples", "Examples"));
|
|
99
|
+
for (const x of doc?.examples ?? []) blocks.push(...b.example(x, scope));
|
|
100
|
+
for (const x of area.examples ?? []) blocks.push(...exampleBlocks(b, under(area.pkg.dir, x.file), x.file, x.what, scope));
|
|
101
|
+
if (area.phases !== undefined && area.phases.length > 0) {
|
|
102
|
+
blocks.push(heading("phases", "Phases"), {
|
|
103
|
+
kind: "table",
|
|
104
|
+
head: ["Phase", "What", "State"].map((h) => [{ kind: "text", text: h }]),
|
|
105
|
+
rows: area.phases.map((p) => [[{ kind: "text", text: String(p.n) }], b.line(p.what, scope), [{ kind: "text", text: p.state }]]),
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
const limits = areaFiles(b.root, area.dir)
|
|
109
|
+
.map((f) => [f, moduleComment(b.read(f))?.limits] as const)
|
|
110
|
+
.filter((x): x is readonly [string, string] => x[1] !== undefined);
|
|
111
|
+
if (limits.length > 0) {
|
|
112
|
+
blocks.push(heading("limits", "Limits"), {
|
|
113
|
+
kind: "paragraph",
|
|
114
|
+
inlines: [{ kind: "text", text: "What the modules of this area do not do, or do only in part, as each module's @limits says." }],
|
|
115
|
+
});
|
|
116
|
+
for (const [f, text] of limits) {
|
|
117
|
+
const fileScope = { ...scope, file: f };
|
|
118
|
+
blocks.push({ kind: "callout", tone: "limit", title: f.split("/").slice(-2).join("/"), blocks: [{ kind: "paragraph", inlines: [fileLink(b, f, page)] }, ...b.md(text, fileScope)] });
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
b.add({
|
|
122
|
+
path: page,
|
|
123
|
+
title: area.title,
|
|
124
|
+
description: doc === undefined ? area.title : firstSentence(doc.summary),
|
|
125
|
+
section: "api",
|
|
126
|
+
group: area.title,
|
|
127
|
+
order: 100 + i * 100,
|
|
128
|
+
navTitle: "Overview",
|
|
129
|
+
...(spec === undefined ? {} : { badges: [{ text: numberOf(spec), tone: "neutral" as const }] }),
|
|
130
|
+
blocks,
|
|
131
|
+
});
|
|
132
|
+
});
|
|
133
|
+
}
|
|
@@ -0,0 +1,276 @@
|
|
|
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 type { Build } from "../build.ts";
|
|
12
|
+
import { type About, type AboutEnforcer, under } from "../config.ts";
|
|
13
|
+
import { specPage } from "../links.ts";
|
|
14
|
+
import { type Block, type Card, type Inline, possessive } from "../model.ts";
|
|
15
|
+
import { type Area, areaFiles, type Package } from "../sources.ts";
|
|
16
|
+
import { exampleBlocks } from "./areas.ts";
|
|
17
|
+
import { numberOf } from "./specs.ts";
|
|
18
|
+
|
|
19
|
+
/** The first sentence of a text, for a card. */
|
|
20
|
+
export function firstSentence(t: string, max = 240): string {
|
|
21
|
+
const flat = t.replace(/\s+/g, " ").trim();
|
|
22
|
+
const m = /^(.+?[.!?])(\s|$)/.exec(flat);
|
|
23
|
+
const s = m?.[1] ?? flat;
|
|
24
|
+
if (s.length <= max) return s;
|
|
25
|
+
const cut = s.slice(0, max);
|
|
26
|
+
return `${cut.slice(0, Math.max(cut.lastIndexOf(" "), max - 20))}…`;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* 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.
|
|
31
|
+
*/
|
|
32
|
+
export function dependenciesOf(b: Build, packages: readonly Package[]): { readonly uses: ReadonlyMap<string, readonly string[]>; readonly usedBy: ReadonlyMap<string, readonly string[]> } {
|
|
33
|
+
const nameOf = (p: Package): string => {
|
|
34
|
+
const file = under(p.dir, "package.json");
|
|
35
|
+
if (!b.exists(file)) return "";
|
|
36
|
+
return (JSON.parse(b.read(file)) as { name?: string }).name ?? "";
|
|
37
|
+
};
|
|
38
|
+
const slugOf = new Map(packages.map((p) => [nameOf(p), p.slug] as const).filter(([n]) => n !== ""));
|
|
39
|
+
const uses = new Map<string, string[]>();
|
|
40
|
+
const usedBy = new Map<string, string[]>();
|
|
41
|
+
for (const p of packages) {
|
|
42
|
+
const found = new Set<string>();
|
|
43
|
+
for (const f of areaFiles(b.root, p.dir)) {
|
|
44
|
+
const rel = f.slice(p.dir.length + 1);
|
|
45
|
+
if (/^(suite|tools|tests|node_modules|dist)\//.test(rel) || /^(library|about|release)\.ts$/.test(rel)) 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) found.add(other);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
const mine = [...found].sort();
|
|
52
|
+
uses.set(p.slug, mine);
|
|
53
|
+
for (const o of mine) usedBy.set(o, [...(usedBy.get(o) ?? []), p.slug].sort());
|
|
54
|
+
}
|
|
55
|
+
return { uses, usedBy };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** 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. */
|
|
59
|
+
function reduced(libraries: readonly Package[], uses: ReadonlyMap<string, readonly string[]>): [string, string][] {
|
|
60
|
+
const reaches = (from: string, to: string, skip: string): boolean => {
|
|
61
|
+
const seen = new Set<string>([from]);
|
|
62
|
+
const stack = (uses.get(from) ?? []).filter((x) => x !== skip);
|
|
63
|
+
while (stack.length > 0) {
|
|
64
|
+
const at = stack.pop() ?? "";
|
|
65
|
+
if (at === to) return true;
|
|
66
|
+
if (seen.has(at)) continue;
|
|
67
|
+
seen.add(at);
|
|
68
|
+
stack.push(...(uses.get(at) ?? []));
|
|
69
|
+
}
|
|
70
|
+
return false;
|
|
71
|
+
};
|
|
72
|
+
const out: [string, string][] = [];
|
|
73
|
+
for (const p of libraries) for (const c of uses.get(p.slug) ?? []) if (!(uses.get(p.slug) ?? []).some((mid) => mid !== c && reaches(mid, c, ""))) out.push([p.slug, c]);
|
|
74
|
+
return out;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** The page of a package. */
|
|
78
|
+
export const packagePage = (pkg: Package): string => `overview/${pkg.slug}.html`;
|
|
79
|
+
|
|
80
|
+
/** The overview page of an area. */
|
|
81
|
+
export const areaPage = (area: Area): string => `api/${area.slug}/index.html`;
|
|
82
|
+
|
|
83
|
+
const heading = (id: string, t: string): Block => ({ kind: "heading", level: 2, id, text: [{ kind: "text", text: t }] });
|
|
84
|
+
const code = (t: string): Inline[] => [{ kind: "code", text: t }];
|
|
85
|
+
|
|
86
|
+
function enforcer(e: AboutEnforcer): string {
|
|
87
|
+
switch (e.kind) {
|
|
88
|
+
case "test":
|
|
89
|
+
return e.file;
|
|
90
|
+
case "lint":
|
|
91
|
+
return `lint rule ${e.rule}`;
|
|
92
|
+
case "compiler":
|
|
93
|
+
return `compiler option ${e.option}`;
|
|
94
|
+
case "review":
|
|
95
|
+
return "review";
|
|
96
|
+
default:
|
|
97
|
+
return absurd(e);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** The tables an `about` holds: folders, commands and rules. */
|
|
102
|
+
function aboutTables(b: Build, about: About, file: string, page: string): Block[] {
|
|
103
|
+
const scope = { page, file };
|
|
104
|
+
const out: Block[] = [];
|
|
105
|
+
if (about.folders !== undefined && about.folders.length > 0) {
|
|
106
|
+
out.push(heading("folders", "Folders"), {
|
|
107
|
+
kind: "table",
|
|
108
|
+
head: [[{ kind: "text", text: "Folder" }], [{ kind: "text", text: "What it is" }], [{ kind: "text", text: "May import" }]],
|
|
109
|
+
rows: about.folders.map((f) => [code(f.path), b.line(f.what, scope), b.line(f.mayImport.join("; "), scope)]),
|
|
110
|
+
});
|
|
111
|
+
}
|
|
112
|
+
if (about.commands !== undefined && about.commands.length > 0) {
|
|
113
|
+
out.push(heading("commands", "Commands"), {
|
|
114
|
+
kind: "table",
|
|
115
|
+
head: [[{ kind: "text", text: "Command" }], [{ kind: "text", text: "What it does" }]],
|
|
116
|
+
rows: about.commands.map((c) => [code(c.run), b.line(c.does, scope)]),
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
if (about.rules !== undefined && about.rules.length > 0) {
|
|
120
|
+
out.push(heading("rules", "Rules"), {
|
|
121
|
+
kind: "table",
|
|
122
|
+
head: [[{ kind: "text", text: "Rule" }], [{ kind: "text", text: "Enforced by" }]],
|
|
123
|
+
rows: about.rules.map((r) => [
|
|
124
|
+
b.line(r.rule, scope),
|
|
125
|
+
r.enforcedBy.flatMap((e, i): Inline[] => [...(i === 0 ? [] : [{ kind: "text", text: ", " } as const]), ...code(enforcer(e))]),
|
|
126
|
+
]),
|
|
127
|
+
});
|
|
128
|
+
}
|
|
129
|
+
return out;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** The capabilities as cards: each specification in force, under the one it is part of. */
|
|
133
|
+
function capabilityCards(b: Build): Card[] {
|
|
134
|
+
const page = "index.html";
|
|
135
|
+
const cardOf = (id: string): Card => {
|
|
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
|
+
/**
|
|
150
|
+
* The home page and a page for each package.
|
|
151
|
+
*
|
|
152
|
+
* @param b - the build
|
|
153
|
+
* @param top - the home's package: the repository as a whole
|
|
154
|
+
* @param packages - the packages
|
|
155
|
+
* @param areas - their areas
|
|
156
|
+
*/
|
|
157
|
+
export function overviewPages(b: Build, top: Package, packages: readonly Package[], areas: readonly Area[]): void {
|
|
158
|
+
const home = "index.html";
|
|
159
|
+
const homeScope = { page: home, file: top.file };
|
|
160
|
+
const subject = b.config.subject;
|
|
161
|
+
const ownFile = (p: Package): boolean => p.file !== b.config.fileFromRoot;
|
|
162
|
+
if (ownFile(top)) b.files.set(top.file, home);
|
|
163
|
+
if (top.dir !== "") b.files.set(top.dir, home);
|
|
164
|
+
for (const p of packages) {
|
|
165
|
+
if (ownFile(p)) b.files.set(p.file, packagePage(p));
|
|
166
|
+
if (p.dir !== "") b.files.set(p.dir, packagePage(p));
|
|
167
|
+
}
|
|
168
|
+
const capabilities = capabilityCards(b);
|
|
169
|
+
b.add({
|
|
170
|
+
path: home,
|
|
171
|
+
title: top.about.title,
|
|
172
|
+
description: firstSentence(top.about.summary),
|
|
173
|
+
section: "overview",
|
|
174
|
+
group: b.config.subject.charAt(0).toUpperCase() + b.config.subject.slice(1),
|
|
175
|
+
order: 0,
|
|
176
|
+
blocks: [
|
|
177
|
+
...b.md(top.about.summary, homeScope),
|
|
178
|
+
heading("libraries", "Libraries"),
|
|
179
|
+
{
|
|
180
|
+
kind: "cards",
|
|
181
|
+
cards: packages.map((p) => ({
|
|
182
|
+
title: p.about.title,
|
|
183
|
+
href: { kind: "page", path: packagePage(p) },
|
|
184
|
+
text: b.line(firstSentence(p.about.summary), { page: home, file: p.file }),
|
|
185
|
+
})),
|
|
186
|
+
},
|
|
187
|
+
...(capabilities.length === 0 ? [] : [
|
|
188
|
+
heading("capabilities", "Capabilities"),
|
|
189
|
+
{ kind: "paragraph", inlines: [{ kind: "text", text: `Each capability is a specification of ${possessive(subject)} spec kit, under the one it is part of.` }] } satisfies Block,
|
|
190
|
+
{ kind: "cards", cards: capabilities } satisfies Block,
|
|
191
|
+
]),
|
|
192
|
+
...aboutTables(b, top.about, top.file, home),
|
|
193
|
+
],
|
|
194
|
+
});
|
|
195
|
+
const libraries = packages.filter((p) => b.exists(under(p.dir, "library.ts")));
|
|
196
|
+
const { uses, usedBy } = dependenciesOf(b, libraries);
|
|
197
|
+
const bySlug = new Map(libraries.map((p) => [p.slug, p] as const));
|
|
198
|
+
const linkList = (slugs: readonly string[]): Block => ({
|
|
199
|
+
kind: "paragraph",
|
|
200
|
+
inlines: slugs.flatMap((sl, i): Inline[] => {
|
|
201
|
+
const q = bySlug.get(sl);
|
|
202
|
+
return [...(i === 0 ? [] : [{ kind: "text", text: ", " } as Inline]), q === undefined ? { kind: "code", text: sl } : { kind: "link", href: { kind: "page", path: packagePage(q) }, children: [{ kind: "text", text: q.about.title }] }];
|
|
203
|
+
}),
|
|
204
|
+
});
|
|
205
|
+
if (libraries.length > 0) {
|
|
206
|
+
b.add({
|
|
207
|
+
path: "overview/map.html",
|
|
208
|
+
title: "Library map",
|
|
209
|
+
description: "What each library imports, and what imports it.",
|
|
210
|
+
section: "overview",
|
|
211
|
+
group: "Libraries",
|
|
212
|
+
order: 9,
|
|
213
|
+
blocks: [
|
|
214
|
+
{ 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." }] },
|
|
215
|
+
{ 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" },
|
|
216
|
+
{
|
|
217
|
+
kind: "table",
|
|
218
|
+
head: ["Library", "Imports", "Imported by"].map((h) => [{ kind: "text", text: h } as Inline]),
|
|
219
|
+
rows: libraries.map((p) => [
|
|
220
|
+
[{ kind: "link", href: { kind: "page", path: packagePage(p) }, children: [{ kind: "text", text: p.about.title }] }],
|
|
221
|
+
(uses.get(p.slug) ?? []).flatMap((u, i): Inline[] => [...(i === 0 ? [] : [{ kind: "text", text: ", " } as Inline]), { kind: "code", text: u }]),
|
|
222
|
+
(usedBy.get(p.slug) ?? []).flatMap((u, i): Inline[] => [...(i === 0 ? [] : [{ kind: "text", text: ", " } as Inline]), { kind: "code", text: u }]),
|
|
223
|
+
]),
|
|
224
|
+
},
|
|
225
|
+
],
|
|
226
|
+
});
|
|
227
|
+
}
|
|
228
|
+
packages.forEach((p, i) => {
|
|
229
|
+
const page = packagePage(p);
|
|
230
|
+
const file = p.file;
|
|
231
|
+
const scope = { page, file, ...(p.about.spec === undefined ? {} : { spec: p.about.spec.id }) };
|
|
232
|
+
const own = areas.filter((a) => a.pkg.slug === p.slug);
|
|
233
|
+
const blocks: Block[] = [...b.md(p.about.summary, scope)];
|
|
234
|
+
if (p.about.spec !== undefined) {
|
|
235
|
+
blocks.push({ kind: "paragraph", inlines: [{ kind: "text", text: "Specification: " }, ...b.line(`${p.about.spec.repo} ${p.about.spec.id}`, scope)] });
|
|
236
|
+
}
|
|
237
|
+
if (p.about.facts !== undefined && p.about.facts.length > 0) {
|
|
238
|
+
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)]) });
|
|
239
|
+
}
|
|
240
|
+
const kit = b.kit.sources.find((k) => k.dir === under(p.dir, "spec-kit"));
|
|
241
|
+
const specs = kit === undefined ? [] : b.kit.specs.filter((sp) => sp.file.startsWith(`${kit.dir}/`));
|
|
242
|
+
if (own.length > 0) {
|
|
243
|
+
blocks.push(heading("areas", "Areas"), {
|
|
244
|
+
kind: "cards",
|
|
245
|
+
cards: own.map((a) => ({
|
|
246
|
+
title: a.title,
|
|
247
|
+
href: { kind: "page", path: areaPage(a) },
|
|
248
|
+
text: [{ kind: "code", text: a.entryPoints.join(", ") }],
|
|
249
|
+
...(a.spec === undefined ? {} : { badges: [{ text: numberOf(a.spec.id), tone: "neutral" as const }] }),
|
|
250
|
+
})),
|
|
251
|
+
});
|
|
252
|
+
}
|
|
253
|
+
if (p.about.layers !== undefined && p.about.layers.length > 0) {
|
|
254
|
+
const order = ["governance", "logical", "physical"];
|
|
255
|
+
const layers = [...p.about.layers].sort((x, y) => order.indexOf(x.layer) - order.indexOf(y.layer));
|
|
256
|
+
blocks.push(heading("layers", "Layers"), {
|
|
257
|
+
kind: "table",
|
|
258
|
+
head: [[{ kind: "text", text: "Layer" }], [{ kind: "text", text: "Folder" }], [{ kind: "text", text: "May import of this library" }]],
|
|
259
|
+
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): Inline[] => [...(i === 0 ? [] : [{ kind: "text", text: ", " } as Inline]), { kind: "code", text: m }])]),
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
if ((uses.get(p.slug) ?? []).length > 0) blocks.push(heading("imports", "Imports"), linkList(uses.get(p.slug) ?? []));
|
|
263
|
+
if ((usedBy.get(p.slug) ?? []).length > 0) blocks.push(heading("imported-by", "Imported by"), linkList(usedBy.get(p.slug) ?? []));
|
|
264
|
+
if (specs.length > 0) {
|
|
265
|
+
blocks.push(heading("specifications", "Specifications"), {
|
|
266
|
+
kind: "table",
|
|
267
|
+
head: [[{ kind: "text", text: "Number" }], [{ kind: "text", text: "Specification" }], [{ kind: "text", text: "Requirements" }]],
|
|
268
|
+
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) }]]),
|
|
269
|
+
});
|
|
270
|
+
}
|
|
271
|
+
blocks.push(...aboutTables(b, p.about, file, page));
|
|
272
|
+
if ((p.about.examples ?? []).length > 0) blocks.push(heading("examples", "Examples"));
|
|
273
|
+
for (const x of p.about.examples ?? []) blocks.push(...exampleBlocks(b, under(p.dir, x.file), x.file, x.what, scope));
|
|
274
|
+
b.add({ path: page, title: p.about.title, description: firstSentence(p.about.summary), section: "overview", group: "Libraries", order: 10 + i, blocks });
|
|
275
|
+
});
|
|
276
|
+
}
|