@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/markdown.ts
ADDED
|
@@ -0,0 +1,320 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The Markdown of TSDoc and of specifications, read into the page model (commons 0011-documentation FR-016): paragraphs, headings, lists
|
|
4
|
+
* (nested by indentation), emphasis, code, fenced code with its language, links, autolinks and tables, and TSDoc's `{@link name}`.
|
|
5
|
+
* Anything else is kept as its text. Where a link goes, what `{@link}` names and which words are a citation of a specification are the
|
|
6
|
+
* caller's to say, through an `InlineContext`, so that this module knows nothing of the site.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { markdown, plainContext } from "./markdown.ts";
|
|
11
|
+
* markdown("Some `code` and a [link](https://example.com).", plainContext);
|
|
12
|
+
* // [{ kind: "paragraph", inlines: [text "Some ", code "code", text " and a ", link, text "."] }]
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* @module
|
|
16
|
+
*/
|
|
17
|
+
import type { Block, Href, Inline, Lang } from "./model.ts";
|
|
18
|
+
import { plain, slugOf } from "./model.ts";
|
|
19
|
+
|
|
20
|
+
/** What the reader asks of its caller: where a link goes, what `{@link}` names, and the citations in a run of text. */
|
|
21
|
+
export interface InlineContext {
|
|
22
|
+
/** Where a Markdown link's destination goes. */
|
|
23
|
+
readonly href: (raw: string) => Href;
|
|
24
|
+
/** The inlines `{@link name}` (or `{@link name | label}`) becomes. */
|
|
25
|
+
readonly link: (name: string, label: string | undefined) => readonly Inline[];
|
|
26
|
+
/** A run of text with its citations made links. */
|
|
27
|
+
readonly cite: (text: string) => readonly Inline[];
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** A context that links nothing it does not have to: destinations as given, `{@link}` as code, no citations. */
|
|
31
|
+
export const plainContext: InlineContext = {
|
|
32
|
+
href: (raw) => ({ kind: "external", url: raw }),
|
|
33
|
+
link: (name, label) => [{ kind: "code", text: label ?? name }],
|
|
34
|
+
cite: (t) => [{ kind: "text", text: t }],
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
/** The language a fence names, as the highlighter knows it. */
|
|
38
|
+
export function langOf(info: string): Lang {
|
|
39
|
+
switch (info.trim().split(/\s+/)[0]?.toLowerCase() ?? "") {
|
|
40
|
+
case "ts":
|
|
41
|
+
case "typescript":
|
|
42
|
+
case "js":
|
|
43
|
+
case "javascript":
|
|
44
|
+
case "tsx":
|
|
45
|
+
return "ts";
|
|
46
|
+
case "sql":
|
|
47
|
+
return "sql";
|
|
48
|
+
case "sh":
|
|
49
|
+
case "bash":
|
|
50
|
+
case "shell":
|
|
51
|
+
case "console":
|
|
52
|
+
return "sh";
|
|
53
|
+
case "toml":
|
|
54
|
+
return "toml";
|
|
55
|
+
case "json":
|
|
56
|
+
case "json5":
|
|
57
|
+
case "jsonc":
|
|
58
|
+
return "json";
|
|
59
|
+
case "ttl":
|
|
60
|
+
case "turtle":
|
|
61
|
+
return "turtle";
|
|
62
|
+
case "yaml":
|
|
63
|
+
case "yml":
|
|
64
|
+
return "yaml";
|
|
65
|
+
case "mermaid":
|
|
66
|
+
return "mermaid";
|
|
67
|
+
default:
|
|
68
|
+
return "text";
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const FENCE = /^(\s*)(`{3,}|~{3,})(.*)$/;
|
|
73
|
+
const HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
|
|
74
|
+
const BULLET = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/;
|
|
75
|
+
const TABLE_RULE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
|
|
76
|
+
|
|
77
|
+
/** The cells of a table's row. */
|
|
78
|
+
function cells(line: string): string[] {
|
|
79
|
+
const t = line.trim().replace(/^\|/, "").replace(/\|$/, "");
|
|
80
|
+
const out: string[] = [];
|
|
81
|
+
let cur = "";
|
|
82
|
+
let tick = false;
|
|
83
|
+
for (let i = 0; i < t.length; i++) {
|
|
84
|
+
const c = t[i] ?? "";
|
|
85
|
+
if (c === "\\" && t[i + 1] === "|") {
|
|
86
|
+
cur += "|";
|
|
87
|
+
i++;
|
|
88
|
+
} else if (c === "`") {
|
|
89
|
+
tick = !tick;
|
|
90
|
+
cur += c;
|
|
91
|
+
} else if (c === "|" && !tick) {
|
|
92
|
+
out.push(cur.trim());
|
|
93
|
+
cur = "";
|
|
94
|
+
} else cur += c;
|
|
95
|
+
}
|
|
96
|
+
out.push(cur.trim());
|
|
97
|
+
return out;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The blocks of a Markdown text.
|
|
102
|
+
*
|
|
103
|
+
* @param source - the text
|
|
104
|
+
* @param ctx - where links go and what is a citation
|
|
105
|
+
*/
|
|
106
|
+
export function markdown(source: string, ctx: InlineContext): Block[] {
|
|
107
|
+
const lines = source.replace(/\r\n?/g, "\n").split("\n");
|
|
108
|
+
const blocks: Block[] = [];
|
|
109
|
+
let i = 0;
|
|
110
|
+
const used = new Map<string, number>();
|
|
111
|
+
const anchor = (t: string): string => {
|
|
112
|
+
const base = slugOf(t) || "section";
|
|
113
|
+
const n = used.get(base) ?? 0;
|
|
114
|
+
used.set(base, n + 1);
|
|
115
|
+
return n === 0 ? base : `${base}-${n}`;
|
|
116
|
+
};
|
|
117
|
+
while (i < lines.length) {
|
|
118
|
+
const line = lines[i] ?? "";
|
|
119
|
+
if (line.trim() === "") {
|
|
120
|
+
i++;
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
const fence = FENCE.exec(line);
|
|
124
|
+
if (fence !== null) {
|
|
125
|
+
const marker = fence[2] ?? "```";
|
|
126
|
+
const indent = (fence[1] ?? "").length;
|
|
127
|
+
const body: string[] = [];
|
|
128
|
+
i++;
|
|
129
|
+
while (i < lines.length && !(lines[i] ?? "").trim().startsWith(marker)) {
|
|
130
|
+
const l = lines[i] ?? "";
|
|
131
|
+
body.push(l.slice(Math.min(indent, l.length - l.trimStart().length)));
|
|
132
|
+
i++;
|
|
133
|
+
}
|
|
134
|
+
i++;
|
|
135
|
+
const lang = langOf(fence[3] ?? "");
|
|
136
|
+
// a Mermaid fence is a diagram, drawn when the site is built (commons 0011-documentation FR-037); its source stays on the page
|
|
137
|
+
blocks.push(lang === "mermaid" ? { kind: "diagram", source: body.join("\n"), caption: "" } : { kind: "code", lang, text: body.join("\n") });
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
const heading = HEADING.exec(line);
|
|
141
|
+
if (heading !== null) {
|
|
142
|
+
const depth = (heading[1] ?? "#").length;
|
|
143
|
+
const inl = inlines(heading[2] ?? "", ctx);
|
|
144
|
+
const level = depth <= 2 ? 2 : depth === 3 ? 3 : 4;
|
|
145
|
+
blocks.push({ kind: "heading", level, id: anchor(plain(inl)), text: inl });
|
|
146
|
+
i++;
|
|
147
|
+
continue;
|
|
148
|
+
}
|
|
149
|
+
if (line.trimStart().startsWith("|") && TABLE_RULE.test(lines[i + 1] ?? "")) {
|
|
150
|
+
const head = cells(line).map((c) => inlines(c, ctx));
|
|
151
|
+
i += 2;
|
|
152
|
+
const rows: Inline[][][] = [];
|
|
153
|
+
while (i < lines.length && (lines[i] ?? "").trimStart().startsWith("|")) {
|
|
154
|
+
rows.push(cells(lines[i] ?? "").map((c) => inlines(c, ctx)));
|
|
155
|
+
i++;
|
|
156
|
+
}
|
|
157
|
+
blocks.push({ kind: "table", head, rows });
|
|
158
|
+
continue;
|
|
159
|
+
}
|
|
160
|
+
const bullet = BULLET.exec(line);
|
|
161
|
+
if (bullet !== null) {
|
|
162
|
+
const base = (bullet[1] ?? "").length;
|
|
163
|
+
const ordered = /\d/.test(bullet[2] ?? "");
|
|
164
|
+
const items: Block[][] = [];
|
|
165
|
+
while (i < lines.length) {
|
|
166
|
+
const b = BULLET.exec(lines[i] ?? "");
|
|
167
|
+
if (b === null || (b[1] ?? "").length !== base) break;
|
|
168
|
+
const body = [b[3] ?? ""];
|
|
169
|
+
i++;
|
|
170
|
+
while (i < lines.length) {
|
|
171
|
+
const l = lines[i] ?? "";
|
|
172
|
+
if (l.trim() === "") {
|
|
173
|
+
const next = lines[i + 1] ?? "";
|
|
174
|
+
if (next.length - next.trimStart().length > base && next.trim() !== "") {
|
|
175
|
+
body.push("");
|
|
176
|
+
i++;
|
|
177
|
+
continue;
|
|
178
|
+
}
|
|
179
|
+
break;
|
|
180
|
+
}
|
|
181
|
+
const ind = l.length - l.trimStart().length;
|
|
182
|
+
if (ind <= base && (BULLET.test(l) || FENCE.test(l) || HEADING.test(l))) break;
|
|
183
|
+
if (ind <= base && !BULLET.test(l)) {
|
|
184
|
+
body.push(l.trim());
|
|
185
|
+
i++;
|
|
186
|
+
continue;
|
|
187
|
+
}
|
|
188
|
+
body.push(l.slice(Math.min(ind, base + 2)));
|
|
189
|
+
i++;
|
|
190
|
+
}
|
|
191
|
+
items.push(markdown(body.join("\n"), ctx));
|
|
192
|
+
}
|
|
193
|
+
blocks.push({ kind: "list", ordered, items });
|
|
194
|
+
continue;
|
|
195
|
+
}
|
|
196
|
+
const para: string[] = [];
|
|
197
|
+
while (i < lines.length) {
|
|
198
|
+
const l = lines[i] ?? "";
|
|
199
|
+
if (l.trim() === "" || FENCE.test(l) || HEADING.test(l) || BULLET.test(l)) break;
|
|
200
|
+
if (l.trimStart().startsWith("|") && TABLE_RULE.test(lines[i + 1] ?? "")) break;
|
|
201
|
+
para.push(l.trim());
|
|
202
|
+
i++;
|
|
203
|
+
}
|
|
204
|
+
blocks.push({ kind: "paragraph", inlines: inlines(para.join(" "), ctx) });
|
|
205
|
+
}
|
|
206
|
+
return blocks;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The inlines of a run of Markdown: code spans, strong and emphasis, links, autolinks, `{@link}`, and escapes.
|
|
211
|
+
*
|
|
212
|
+
* @param source - the run
|
|
213
|
+
* @param ctx - where links go and what is a citation
|
|
214
|
+
*/
|
|
215
|
+
export function inlines(source: string, ctx: InlineContext): Inline[] {
|
|
216
|
+
const out: Inline[] = [];
|
|
217
|
+
let buf = "";
|
|
218
|
+
const flush = (): void => {
|
|
219
|
+
if (buf !== "") out.push(...ctx.cite(buf));
|
|
220
|
+
buf = "";
|
|
221
|
+
};
|
|
222
|
+
let i = 0;
|
|
223
|
+
while (i < source.length) {
|
|
224
|
+
const c = source[i] ?? "";
|
|
225
|
+
const rest = source.slice(i);
|
|
226
|
+
if (c === "\\" && i + 1 < source.length && /[\\`*_{}[\]()#+\-.!|<>~]/.test(source[i + 1] ?? "")) {
|
|
227
|
+
buf += source[i + 1] ?? "";
|
|
228
|
+
i += 2;
|
|
229
|
+
continue;
|
|
230
|
+
}
|
|
231
|
+
if (c === "`") {
|
|
232
|
+
const ticks = /^`+/.exec(rest)?.[0] ?? "`";
|
|
233
|
+
const end = source.indexOf(ticks, i + ticks.length);
|
|
234
|
+
if (end > 0) {
|
|
235
|
+
flush();
|
|
236
|
+
let code = source.slice(i + ticks.length, end);
|
|
237
|
+
if (code.startsWith(" ") && code.endsWith(" ") && code.trim() !== "") code = code.slice(1, -1);
|
|
238
|
+
out.push({ kind: "code", text: code });
|
|
239
|
+
i = end + ticks.length;
|
|
240
|
+
continue;
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
const tsdoc = /^\{@link(?:code|plain)?\s+([^}|\s]+)\s*(?:\|\s*([^}]*))?\}/.exec(rest);
|
|
244
|
+
if (tsdoc !== null) {
|
|
245
|
+
flush();
|
|
246
|
+
out.push(...ctx.link(tsdoc[1] ?? "", tsdoc[2]?.trim() || undefined));
|
|
247
|
+
i += tsdoc[0].length;
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
const auto = /^<(https?:\/\/[^\s>]+)>/.exec(rest);
|
|
251
|
+
if (auto !== null) {
|
|
252
|
+
flush();
|
|
253
|
+
const url = auto[1] ?? "";
|
|
254
|
+
out.push({ kind: "link", href: { kind: "external", url }, children: [{ kind: "text", text: url }] });
|
|
255
|
+
i += auto[0].length;
|
|
256
|
+
continue;
|
|
257
|
+
}
|
|
258
|
+
if (c === "[") {
|
|
259
|
+
const close = matching(source, i);
|
|
260
|
+
if (close > 0 && source[close + 1] === "(") {
|
|
261
|
+
const end = source.indexOf(")", close + 2);
|
|
262
|
+
if (end > 0) {
|
|
263
|
+
flush();
|
|
264
|
+
const dest = source.slice(close + 2, end).trim().split(/\s+/)[0] ?? "";
|
|
265
|
+
out.push({ kind: "link", href: ctx.href(dest), children: inlines(source.slice(i + 1, close), { ...ctx, cite: plainContext.cite }) });
|
|
266
|
+
i = end + 1;
|
|
267
|
+
continue;
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
if (rest.startsWith("**") || rest.startsWith("__")) {
|
|
272
|
+
const mark = rest.slice(0, 2);
|
|
273
|
+
const end = source.indexOf(mark, i + 2);
|
|
274
|
+
if (end > i + 2) {
|
|
275
|
+
flush();
|
|
276
|
+
out.push({ kind: "strong", children: inlines(source.slice(i + 2, end), ctx) });
|
|
277
|
+
i = end + 2;
|
|
278
|
+
continue;
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
if ((c === "*" || c === "_") && /\S/.test(source[i + 1] ?? "") && !/[\p{L}\p{N}]/u.test(source[i - 1] ?? "")) {
|
|
282
|
+
let end = i + 1;
|
|
283
|
+
while (end < source.length) {
|
|
284
|
+
end = source.indexOf(c, end);
|
|
285
|
+
if (end < 0) break;
|
|
286
|
+
if (/\S/.test(source[end - 1] ?? "") && !/[\p{L}\p{N}]/u.test(source[end + 1] ?? "")) break;
|
|
287
|
+
end++;
|
|
288
|
+
}
|
|
289
|
+
if (end > i + 1) {
|
|
290
|
+
flush();
|
|
291
|
+
out.push({ kind: "emphasis", children: inlines(source.slice(i + 1, end), ctx) });
|
|
292
|
+
i = end + 1;
|
|
293
|
+
continue;
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
buf += c;
|
|
297
|
+
i++;
|
|
298
|
+
}
|
|
299
|
+
flush();
|
|
300
|
+
return out;
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
/** Where the bracket that closes the one at `at` is, or -1. */
|
|
304
|
+
function matching(s: string, at: number): number {
|
|
305
|
+
let depth = 0;
|
|
306
|
+
for (let i = at; i < s.length; i++) {
|
|
307
|
+
const c = s[i];
|
|
308
|
+
if (c === "`") {
|
|
309
|
+
const end = s.indexOf("`", i + 1);
|
|
310
|
+
if (end > 0) i = end;
|
|
311
|
+
continue;
|
|
312
|
+
}
|
|
313
|
+
if (c === "[") depth++;
|
|
314
|
+
else if (c === "]") {
|
|
315
|
+
depth--;
|
|
316
|
+
if (depth === 0) return i;
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
return -1;
|
|
320
|
+
}
|
package/src/mod.ts
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-002
|
|
2
|
+
/**
|
|
3
|
+
* The library of IFC Docs, `@intellectual-frontiers/commons/docs` (commons 0011-documentation FR-021, FR-023, FR-026): the configuration's
|
|
4
|
+
* types and its check, the command line's parts, the build of a site and its writing, and what a lens is given and uses (the build, the
|
|
5
|
+
* areas and their API, the page model and its helpers). A repository's `docs.config.ts` needs only the types; a lens imports the rest
|
|
6
|
+
* from here.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { buildSite, loadConfig, report } from "@intellectual-frontiers/commons/docs";
|
|
11
|
+
* const config = await loadConfig("docs.config.ts");
|
|
12
|
+
* if (config.kind === "ok") console.log(report((await buildSite(config.value)).found));
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* @module
|
|
16
|
+
*/
|
|
17
|
+
export type {
|
|
18
|
+
About,
|
|
19
|
+
AboutArea,
|
|
20
|
+
AboutCommand,
|
|
21
|
+
AboutEnforcer,
|
|
22
|
+
AboutExample,
|
|
23
|
+
AboutFolder,
|
|
24
|
+
AboutPhase,
|
|
25
|
+
AboutPhaseState,
|
|
26
|
+
AboutRule,
|
|
27
|
+
AboutSpec,
|
|
28
|
+
CitationsConfig,
|
|
29
|
+
Config,
|
|
30
|
+
DocsConfig,
|
|
31
|
+
HomeConfig,
|
|
32
|
+
LinkedRepository,
|
|
33
|
+
PackageConfig,
|
|
34
|
+
PackageSource,
|
|
35
|
+
SpecKitConfig,
|
|
36
|
+
SpecKitSource,
|
|
37
|
+
} from "./config.ts";
|
|
38
|
+
export { isAbout, normalDir, resolveConfig, under } from "./config.ts";
|
|
39
|
+
export { Build } from "./build.ts";
|
|
40
|
+
export { type Finding, message, type Problem, report } from "./check.ts";
|
|
41
|
+
export type { ApiExport, ApiMember, AreaApi, ExportKind } from "./extract/api.ts";
|
|
42
|
+
export type { Constitution, Enforcement, Spec, SpecKit } from "./extract/specs.ts";
|
|
43
|
+
export type { LinkScope } from "./links.ts";
|
|
44
|
+
export { llmsIndex, markdownOf, twinOf } from "./emit/markdown.ts";
|
|
45
|
+
export type { Layer, LayerElement, LayeredFinding, LayeredModel, LayeredSource, LayeredSubject, Locate, SourceLocation, TraceEdge } from "./layered.ts";
|
|
46
|
+
export type { Lens, LensPages, SiteFile } from "./lens.ts";
|
|
47
|
+
export type { Badge, Block, Card, Href, Inline, Page, Section, Tab, TreeNode } from "./model.ts";
|
|
48
|
+
export { plain, possessive, slugOf } from "./model.ts";
|
|
49
|
+
export { areaPage, firstSentence } from "./pages/overview.ts";
|
|
50
|
+
export type { Area, Package } from "./sources.ts";
|
|
51
|
+
export { type DocComment, moduleComment } from "./tsdoc.ts";
|
|
52
|
+
export { type Built, buildSite, writeSite } from "./site.ts";
|
|
53
|
+
export { type Command, findConfig, loadConfig, main, parseArgs, USAGE } from "./cli.ts";
|
package/src/model.ts
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The page model (commons 0011-documentation FR-016): every page of the site is a value of these types before it is HTML. Readers (the
|
|
4
|
+
* Markdown of TSDoc and of specifications, the API reader, the lenses) make blocks and inlines; the HTML emitter is the one writer, and
|
|
5
|
+
* matches every case with a `switch` that ends in `absurd`, so that a case added here and left out there does not compile.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { absurd } from "@intellectual-frontiers/core";
|
|
10
|
+
|
|
11
|
+
/** Where a link goes: a page of the site (by its path from the site's root), or an address outside it. */
|
|
12
|
+
export type Href =
|
|
13
|
+
| { readonly kind: "page"; readonly path: string; readonly anchor?: string }
|
|
14
|
+
| { readonly kind: "external"; readonly url: string };
|
|
15
|
+
|
|
16
|
+
/** A run of text inside a block. */
|
|
17
|
+
export type Inline =
|
|
18
|
+
| { readonly kind: "text"; readonly text: string }
|
|
19
|
+
| { readonly kind: "code"; readonly text: string }
|
|
20
|
+
| { readonly kind: "emphasis"; readonly children: readonly Inline[] }
|
|
21
|
+
| { readonly kind: "strong"; readonly children: readonly Inline[] }
|
|
22
|
+
| { readonly kind: "link"; readonly href: Href; readonly children: readonly Inline[] };
|
|
23
|
+
|
|
24
|
+
/** The languages the highlighter knows; anything else is shown as plain text. */
|
|
25
|
+
export type Lang = "ts" | "sql" | "sh" | "toml" | "json" | "turtle" | "yaml" | "mermaid" | "text";
|
|
26
|
+
|
|
27
|
+
/** A colour of a badge: neutral, or one that says how something stands. */
|
|
28
|
+
export type Tone = "neutral" | "good" | "warn" | "info";
|
|
29
|
+
|
|
30
|
+
/** A small label beside a title: a kind, a status, a mechanism. */
|
|
31
|
+
export interface Badge {
|
|
32
|
+
/** What it says. */
|
|
33
|
+
readonly text: string;
|
|
34
|
+
/** Its colour. */
|
|
35
|
+
readonly tone: Tone;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** A card: a title that links somewhere, with a line under it. */
|
|
39
|
+
export interface Card {
|
|
40
|
+
/** The title. */
|
|
41
|
+
readonly title: string;
|
|
42
|
+
/** Where it goes. */
|
|
43
|
+
readonly href: Href;
|
|
44
|
+
/** The line under the title. */
|
|
45
|
+
readonly text: readonly Inline[];
|
|
46
|
+
/** Badges beside the title. */
|
|
47
|
+
readonly badges?: readonly Badge[];
|
|
48
|
+
/** Cards shown under this one, a level in. */
|
|
49
|
+
readonly children?: readonly Card[];
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** A node of a tree diagram: a label, a note, and what is under it. */
|
|
53
|
+
export interface TreeNode {
|
|
54
|
+
/** What the node is called, as code. */
|
|
55
|
+
readonly label: string;
|
|
56
|
+
/** A short note beside it. */
|
|
57
|
+
readonly note?: readonly Inline[];
|
|
58
|
+
/** The nodes under it. */
|
|
59
|
+
readonly children: readonly TreeNode[];
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** A tab of a set of tabs. */
|
|
63
|
+
export interface Tab {
|
|
64
|
+
/** Its label. */
|
|
65
|
+
readonly label: string;
|
|
66
|
+
/** What it shows. */
|
|
67
|
+
readonly blocks: readonly Block[];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** A part of a page. */
|
|
71
|
+
export type Block =
|
|
72
|
+
| { readonly kind: "heading"; readonly level: 2 | 3 | 4; readonly id: string; readonly text: readonly Inline[] }
|
|
73
|
+
| { readonly kind: "paragraph"; readonly inlines: readonly Inline[] }
|
|
74
|
+
| { readonly kind: "meta"; readonly inlines: readonly Inline[] }
|
|
75
|
+
| { readonly kind: "list"; readonly ordered: boolean; readonly items: readonly (readonly Block[])[] }
|
|
76
|
+
| { readonly kind: "code"; readonly lang: Lang; readonly text: string; readonly title?: string }
|
|
77
|
+
| { readonly kind: "table"; readonly head: readonly (readonly Inline[])[]; readonly rows: readonly (readonly (readonly Inline[])[])[]; readonly filter?: string; readonly compact?: boolean }
|
|
78
|
+
| { readonly kind: "callout"; readonly tone: "note" | "limit" | "warn"; readonly title: string; readonly blocks: readonly Block[] }
|
|
79
|
+
| {
|
|
80
|
+
readonly kind: "entry";
|
|
81
|
+
readonly id: string;
|
|
82
|
+
readonly name: string;
|
|
83
|
+
readonly badges: readonly Badge[];
|
|
84
|
+
readonly signature?: string;
|
|
85
|
+
readonly blocks: readonly Block[];
|
|
86
|
+
}
|
|
87
|
+
| { readonly kind: "tabs"; readonly id: string; readonly tabs: readonly Tab[] }
|
|
88
|
+
| { readonly kind: "diagram"; readonly source: string; readonly caption: string }
|
|
89
|
+
| { readonly kind: "cards"; readonly cards: readonly Card[] }
|
|
90
|
+
| { readonly kind: "badges"; readonly badges: readonly Badge[] }
|
|
91
|
+
| { readonly kind: "tree"; readonly nodes: readonly TreeNode[] };
|
|
92
|
+
|
|
93
|
+
/** The sections of the site (commons 0011-documentation FR-009 and FR-032): the guides, the concepts, the libraries, the how-to pages, and the reference (specifications, API and models). */
|
|
94
|
+
export type Section = "start" | "concepts" | "overview" | "howto" | "specs" | "api" | "models" | "programs";
|
|
95
|
+
|
|
96
|
+
/** A page: where it is, what it is called, which section and group of the navigation it is in, and its blocks. */
|
|
97
|
+
export interface Page {
|
|
98
|
+
/** Its path from the site's root, ending in `.html`. */
|
|
99
|
+
readonly path: string;
|
|
100
|
+
/** Its title. */
|
|
101
|
+
readonly title: string;
|
|
102
|
+
/** A sentence that says what it is, for the search and the page's description. */
|
|
103
|
+
readonly description: string;
|
|
104
|
+
/** Its section. */
|
|
105
|
+
readonly section: Section;
|
|
106
|
+
/** Its group in the section's navigation. */
|
|
107
|
+
readonly group: string;
|
|
108
|
+
/** Its place in the group: lower first, then by title. */
|
|
109
|
+
readonly order: number;
|
|
110
|
+
/** What the navigation calls it, where that is not its title. */
|
|
111
|
+
readonly navTitle?: string;
|
|
112
|
+
/** The page it is under in the navigation (its path): it is listed beneath that page, and only while that page or a page beneath it is the one being read. */
|
|
113
|
+
readonly parent?: string;
|
|
114
|
+
/** What kind of page it is, for the small heading that groups the pages beneath one page in the navigation (`Concepts`, `Code lists`). */
|
|
115
|
+
readonly navKind?: string;
|
|
116
|
+
/** Its badges, beside the title. */
|
|
117
|
+
readonly badges?: readonly Badge[];
|
|
118
|
+
/** What it holds. */
|
|
119
|
+
readonly blocks: readonly Block[];
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/** The text of inlines, with no markup: for a heading's anchor, the search and a page's description. */
|
|
123
|
+
export function plain(inlines: readonly Inline[]): string {
|
|
124
|
+
return inlines
|
|
125
|
+
.map((i) => {
|
|
126
|
+
switch (i.kind) {
|
|
127
|
+
case "text":
|
|
128
|
+
case "code":
|
|
129
|
+
return i.text;
|
|
130
|
+
case "emphasis":
|
|
131
|
+
case "strong":
|
|
132
|
+
case "link":
|
|
133
|
+
return plain(i.children);
|
|
134
|
+
default:
|
|
135
|
+
return absurd(i);
|
|
136
|
+
}
|
|
137
|
+
})
|
|
138
|
+
.join("");
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** A text as one inline. */
|
|
142
|
+
export const text = (t: string): Inline => ({ kind: "text", text: t });
|
|
143
|
+
|
|
144
|
+
/** An anchor made from a text: lower-case letters, digits and hyphens. */
|
|
145
|
+
export function slugOf(t: string): string {
|
|
146
|
+
return t
|
|
147
|
+
.toLowerCase()
|
|
148
|
+
.normalize("NFKD")
|
|
149
|
+
.replace(/[^\p{L}\p{N}]+/gu, "-")
|
|
150
|
+
.replace(/^-+|-+$/g, "");
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** A name as a possessive: `commons'`, `Stolos'`, `Erga's`. */
|
|
154
|
+
export const possessive = (name: string): string => (name.endsWith("s") ? `${name}'` : `${name}'s`);
|