@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,96 @@
1
+ /**
2
+ * Where the words of documentation link to (commons 0011-documentation FR-011, FR-012, FR-025): a citation of a specification of the
3
+ * repository (its prefix and an id, as `commons 0009-example`; a bare id of its own form, as `0009-example` in commons or
4
+ * `096-bun-runtime` in Stolos; a number of its digits after `spec` or before a requirement, as `spec 004` or `038 FR-014`, where a
5
+ * specification has that number; `FR-026` after any of these; or a bare `FR-045` in an area, which names a requirement of the area's
6
+ * specification) becomes a link to the specification's page and the requirement's anchor; a citation of a repository the configuration
7
+ * lists as linked goes to that repository's site; one of any other repository (`erga 009-machine-bootstrap`) stays text; a Markdown link
8
+ * to a file of the repository goes to the page that shows the file, or to the file on GitHub; and `{@link name}` goes to the export it
9
+ * names. What does not resolve is a finding.
10
+ *
11
+ * @module
12
+ */
13
+ import type { Finding } from "./check.js";
14
+ import type { LinkedRepository } from "./config.js";
15
+ import { type InlineContext } from "./markdown.js";
16
+ import type { Href, Inline } from "./model.js";
17
+ /** How specifications are cited: the repository's own prefix and digits, the repositories linked, and those shown as text. */
18
+ export interface CitationRules {
19
+ /** The repository's own prefix, in lower case. */
20
+ readonly prefix: string;
21
+ /** The digits of its specifications' numbers. */
22
+ readonly digits: number;
23
+ /** The repositories whose citations go to their sites. */
24
+ readonly linked: readonly LinkedRepository[];
25
+ /** The repositories whose citations are text, in lower case. */
26
+ readonly text: readonly string[];
27
+ }
28
+ /** What the links of a page can reach: the specifications and their requirements, the pages of source files, and the exports. */
29
+ export interface LinkIndex {
30
+ /** Each specification of the repository, by its folder's name, with its requirements and criteria. */
31
+ readonly specs: ReadonlyMap<string, ReadonlySet<string>>;
32
+ /** How specifications are cited. */
33
+ readonly citations: CitationRules;
34
+ /** The page that shows each file of the repository, by its path from the root. */
35
+ readonly files: ReadonlyMap<string, string>;
36
+ /** Each export's page and anchor, by area and name. */
37
+ readonly exports: ReadonlyMap<string, ReadonlyMap<string, {
38
+ readonly path: string;
39
+ readonly anchor: string;
40
+ }>>;
41
+ /** The address of a file of the repository on GitHub. */
42
+ readonly blob: (repoPath: string) => string;
43
+ /** Told of every citation that became a link: the specification, the requirement where one is named, and the page it is on. */
44
+ readonly cited?: (spec: string, requirement: string | undefined, page: string) => void;
45
+ }
46
+ /** Where a page's words are: the page, the file they come from, the area and the specification a bare requirement names. */
47
+ export interface LinkScope {
48
+ /** The page the links are on. */
49
+ readonly page: string;
50
+ /** The file of the repository the words are in, from the root, for relative links and for findings. */
51
+ readonly file: string;
52
+ /** The area whose exports `{@link name}` names first. */
53
+ readonly area?: string;
54
+ /** The specification a bare `FR-nnn` is a requirement of. */
55
+ readonly spec?: string;
56
+ }
57
+ /** The page of a specification. */
58
+ export declare const specPage: (id: string) => string;
59
+ /** A qualifier as the configuration names repositories: lower case, with a possessive `'s` or `'` taken off. */
60
+ export declare const qualifierOf: (q: string) => string;
61
+ /**
62
+ * The citations of a run of text, made links.
63
+ *
64
+ * @param text - the run
65
+ * @param index - what links can reach
66
+ * @param scope - where the run is
67
+ * @param found - where findings go
68
+ */
69
+ export declare function cite(text: string, index: LinkIndex, scope: LinkScope, found: Finding[]): Inline[];
70
+ /**
71
+ * Where a Markdown link's destination goes, from the file it is written in.
72
+ *
73
+ * @param dest - the destination as written
74
+ * @param index - what links can reach
75
+ * @param scope - where the link is
76
+ */
77
+ export declare function hrefFor(dest: string, index: LinkIndex, scope: LinkScope): Href;
78
+ /**
79
+ * The inlines `{@link name}` becomes: a link to the export, in the area named before `!`, or else in the scope's area, or else the one
80
+ * export of that name in any area.
81
+ *
82
+ * @param name - what it names: `table`, or `data!table`
83
+ * @param label - the text to show, where one is given
84
+ * @param index - what links can reach
85
+ * @param scope - where the link is
86
+ * @param found - where findings go
87
+ */
88
+ export declare function linkFor(name: string, label: string | undefined, index: LinkIndex, scope: LinkScope, found: Finding[]): Inline[];
89
+ /**
90
+ * The context `markdown.ts` reads a page's words with: citations, file links and `{@link}` resolved through the index.
91
+ *
92
+ * @param index - what links can reach
93
+ * @param scope - where the words are
94
+ * @param found - where findings go
95
+ */
96
+ export declare function contextFor(index: LinkIndex, scope: LinkScope, found: Finding[]): InlineContext;
package/dist/links.js ADDED
@@ -0,0 +1,182 @@
1
+ import { plainContext } from "./markdown.js";
2
+ /** The page of a specification. */
3
+ export const specPage = (id) => `specs/${id}.html`;
4
+ // A qualifier and an id (`commons 0009-example`), a requirement (`FR-026`), or a number alone after `spec` or before a requirement
5
+ // (`spec 004`, `038 FR-014`), which names the specification with that number.
6
+ const CITE = /(?:(?<![\w-])([A-Za-z][\w.'-]*) )?(?<![\w-])(\d{3,}-[a-z][a-z0-9]*(?:-[a-z0-9]+)*)|(?<![\w-])((?:FR|SC)-\d{3}[a-z]?)(?![\w-])|(?<![\w-])(?:[Ss]pecs? (\d{3,})|(\d{3,})(?= (?:FR|SC)-\d{3}))(?![\w-])/g;
7
+ /** A qualifier as the configuration names repositories: lower case, with a possessive `'s` or `'` taken off. */
8
+ export const qualifierOf = (q) => q.toLowerCase().replace(/'s?$/, "");
9
+ /** Whether an id has a number of so many digits. */
10
+ const hasDigits = (id, digits) => new RegExp(`^\\d{${digits}}-`).test(id);
11
+ /**
12
+ * The citations of a run of text, made links.
13
+ *
14
+ * @param text - the run
15
+ * @param index - what links can reach
16
+ * @param scope - where the run is
17
+ * @param found - where findings go
18
+ */
19
+ export function cite(text, index, scope, found) {
20
+ const out = [];
21
+ let last = 0;
22
+ const rules = index.citations;
23
+ let current = scope.spec;
24
+ let other = false;
25
+ let away;
26
+ const plainText = (t) => {
27
+ if (t === "")
28
+ return;
29
+ const prev = out[out.length - 1];
30
+ if (prev !== undefined && prev.kind === "text")
31
+ out[out.length - 1] = { kind: "text", text: prev.text + t };
32
+ else
33
+ out.push({ kind: "text", text: t });
34
+ };
35
+ for (const m of text.matchAll(CITE)) {
36
+ const at = m.index;
37
+ const [whole, qualifier, id, req, afterSpec, beforeReq] = m;
38
+ const number = afterSpec ?? beforeReq;
39
+ if (number !== undefined) {
40
+ const numbered = number.length === rules.digits ? [...index.specs.keys()].find((k) => k.startsWith(`${number}-`)) : undefined;
41
+ away = undefined;
42
+ other = numbered === undefined;
43
+ if (numbered === undefined)
44
+ continue;
45
+ current = numbered;
46
+ index.cited?.(numbered, undefined, scope.page);
47
+ plainText(text.slice(last, at));
48
+ out.push({ kind: "link", href: { kind: "page", path: specPage(numbered) }, children: [{ kind: "text", text: whole }] });
49
+ last = at + whole.length;
50
+ continue;
51
+ }
52
+ if (id !== undefined) {
53
+ const q = qualifier?.toLowerCase();
54
+ const named = q === undefined ? undefined : qualifierOf(q);
55
+ const linked = rules.linked.find((r) => r.repo === named);
56
+ away = undefined;
57
+ if (linked !== undefined && hasDigits(id, linked.digits)) {
58
+ other = false;
59
+ away = { site: linked.site, id };
60
+ plainText(text.slice(last, at));
61
+ out.push({ kind: "link", href: { kind: "external", url: `${linked.site}${specPage(id)}` }, children: [{ kind: "text", text: whole }] });
62
+ last = at + whole.length;
63
+ continue;
64
+ }
65
+ if ((named !== undefined && (rules.text.includes(named) || linked !== undefined)) || !hasDigits(id, rules.digits)) {
66
+ other = true;
67
+ continue;
68
+ }
69
+ other = false;
70
+ const start = q === rules.prefix ? at : at + whole.length - id.length;
71
+ plainText(text.slice(last, start));
72
+ if (index.specs.has(id)) {
73
+ current = id;
74
+ index.cited?.(id, undefined, scope.page);
75
+ out.push({ kind: "link", href: { kind: "page", path: specPage(id) }, children: [{ kind: "text", text: text.slice(start, at + whole.length) }] });
76
+ }
77
+ else {
78
+ found.push({ where: scope.file, problem: { kind: "unknown-spec", cite: id } });
79
+ plainText(text.slice(start, at + whole.length));
80
+ }
81
+ last = at + whole.length;
82
+ continue;
83
+ }
84
+ if (req === undefined || other)
85
+ continue;
86
+ if (away !== undefined) {
87
+ plainText(text.slice(last, at));
88
+ out.push({ kind: "link", href: { kind: "external", url: `${away.site}${specPage(away.id)}#${req.toLowerCase()}` }, children: [{ kind: "text", text: req }] });
89
+ last = at + whole.length;
90
+ continue;
91
+ }
92
+ if (current === undefined)
93
+ continue;
94
+ plainText(text.slice(last, at));
95
+ const has = index.specs.get(current)?.has(req) ?? false;
96
+ if (has)
97
+ index.cited?.(current, req, scope.page);
98
+ if (has)
99
+ out.push({ kind: "link", href: { kind: "page", path: specPage(current), anchor: req.toLowerCase() }, children: [{ kind: "text", text: req }] });
100
+ else {
101
+ found.push({ where: scope.file, problem: { kind: "unknown-requirement", cite: `${current} ${req}` } });
102
+ plainText(req);
103
+ }
104
+ last = at + whole.length;
105
+ }
106
+ plainText(text.slice(last));
107
+ return out;
108
+ }
109
+ /** A path of the checkout, from a link's destination written in a file. */
110
+ function resolveFrom(file, dest) {
111
+ const parts = file.split("/").slice(0, -1);
112
+ for (const seg of dest.split("/")) {
113
+ if (seg === "..")
114
+ parts.pop();
115
+ else if (seg !== "." && seg !== "")
116
+ parts.push(seg);
117
+ }
118
+ return parts.join("/");
119
+ }
120
+ /**
121
+ * Where a Markdown link's destination goes, from the file it is written in.
122
+ *
123
+ * @param dest - the destination as written
124
+ * @param index - what links can reach
125
+ * @param scope - where the link is
126
+ */
127
+ export function hrefFor(dest, index, scope) {
128
+ if (/^[a-z][a-z0-9+.-]*:/i.test(dest))
129
+ return { kind: "external", url: dest };
130
+ if (dest.startsWith("#"))
131
+ return { kind: "page", path: scope.page, anchor: dest.slice(1) };
132
+ const [p = "", anchor] = dest.split("#");
133
+ const target = resolveFrom(scope.file, p);
134
+ const page = index.files.get(target) ?? index.files.get(target.replace(/\/$/, ""));
135
+ if (page !== undefined)
136
+ return { kind: "page", path: page, ...(anchor === undefined ? {} : { anchor }) };
137
+ return { kind: "external", url: index.blob(target) };
138
+ }
139
+ /**
140
+ * The inlines `{@link name}` becomes: a link to the export, in the area named before `!`, or else in the scope's area, or else the one
141
+ * export of that name in any area.
142
+ *
143
+ * @param name - what it names: `table`, or `data!table`
144
+ * @param label - the text to show, where one is given
145
+ * @param index - what links can reach
146
+ * @param scope - where the link is
147
+ * @param found - where findings go
148
+ */
149
+ export function linkFor(name, label, index, scope, found) {
150
+ const bang = name.indexOf("!");
151
+ const area = bang < 0 ? scope.area : name.slice(0, bang);
152
+ const sym = bang < 0 ? name : name.slice(bang + 1);
153
+ const base = sym.split(".")[0] ?? "";
154
+ const own = area === undefined ? undefined : index.exports.get(area)?.get(base);
155
+ const elsewhere = bang >= 0 || own !== undefined ? [] : [...index.exports.values()].flatMap((m) => {
156
+ const t = m.get(base);
157
+ return t === undefined ? [] : [t];
158
+ });
159
+ const unique = new Set(elsewhere.map((t) => `${t.path}#${t.anchor}`)).size === 1 ? elsewhere[0] : undefined;
160
+ const target = own ?? unique;
161
+ const shown = { kind: "code", text: label ?? sym };
162
+ if (target === undefined) {
163
+ found.push({ where: scope.file, problem: { kind: "unknown-link", name } });
164
+ return [shown];
165
+ }
166
+ return [{ kind: "link", href: { kind: "page", path: target.path, anchor: target.anchor }, children: [shown] }];
167
+ }
168
+ /**
169
+ * The context `markdown.ts` reads a page's words with: citations, file links and `{@link}` resolved through the index.
170
+ *
171
+ * @param index - what links can reach
172
+ * @param scope - where the words are
173
+ * @param found - where findings go
174
+ */
175
+ export function contextFor(index, scope, found) {
176
+ return {
177
+ ...plainContext,
178
+ href: (dest) => hrefFor(dest, index, scope),
179
+ link: (name, label) => linkFor(name, label, index, scope, found),
180
+ cite: (t) => cite(t, index, scope, found),
181
+ };
182
+ }
package/dist/main.d.ts ADDED
@@ -0,0 +1 @@
1
+ export {};
package/dist/main.js ADDED
@@ -0,0 +1,12 @@
1
+ // Spec: 0001-docs FR-003
2
+ /**
3
+ * The `ifc-docs` command from the source (commons 0011-documentation FR-003): `bun main.ts build [--out DIR] [--config FILE]` and
4
+ * `bun main.ts check [--config FILE]`, run in `commons/docs/`, as `cli.ts` reads them. The package's command is `ifc-docs.mjs`, which
5
+ * registers the Node hook first, so that it runs from `node_modules` on Node 26 too (FR-021).
6
+ *
7
+ * @module
8
+ */
9
+ import { proc } from "@intellectual-frontiers/system";
10
+ import { main } from "./cli.js";
11
+ if (import.meta.main)
12
+ proc.exit(await main(proc.args));
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The Markdown of TSDoc and of specifications, read into the page model (commons 0011-documentation FR-016): paragraphs, headings, lists
3
+ * (nested by indentation), emphasis, code, fenced code with its language, links, autolinks and tables, and TSDoc's `{@link name}`.
4
+ * 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
5
+ * caller's to say, through an `InlineContext`, so that this module knows nothing of the site.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { markdown, plainContext } from "./markdown.js";
10
+ * markdown("Some `code` and a [link](https://example.com).", plainContext);
11
+ * // [{ kind: "paragraph", inlines: [text "Some ", code "code", text " and a ", link, text "."] }]
12
+ * ```
13
+ *
14
+ * @module
15
+ */
16
+ import type { Block, Href, Inline, Lang } from "./model.js";
17
+ /** What the reader asks of its caller: where a link goes, what `{@link}` names, and the citations in a run of text. */
18
+ export interface InlineContext {
19
+ /** Where a Markdown link's destination goes. */
20
+ readonly href: (raw: string) => Href;
21
+ /** The inlines `{@link name}` (or `{@link name | label}`) becomes. */
22
+ readonly link: (name: string, label: string | undefined) => readonly Inline[];
23
+ /** A run of text with its citations made links. */
24
+ readonly cite: (text: string) => readonly Inline[];
25
+ }
26
+ /** A context that links nothing it does not have to: destinations as given, `{@link}` as code, no citations. */
27
+ export declare const plainContext: InlineContext;
28
+ /** The language a fence names, as the highlighter knows it. */
29
+ export declare function langOf(info: string): Lang;
30
+ /**
31
+ * The blocks of a Markdown text.
32
+ *
33
+ * @param source - the text
34
+ * @param ctx - where links go and what is a citation
35
+ */
36
+ export declare function markdown(source: string, ctx: InlineContext): Block[];
37
+ /**
38
+ * The inlines of a run of Markdown: code spans, strong and emphasis, links, autolinks, `{@link}`, and escapes.
39
+ *
40
+ * @param source - the run
41
+ * @param ctx - where links go and what is a citation
42
+ */
43
+ export declare function inlines(source: string, ctx: InlineContext): Inline[];
@@ -0,0 +1,301 @@
1
+ import { plain, slugOf } from "./model.js";
2
+ /** A context that links nothing it does not have to: destinations as given, `{@link}` as code, no citations. */
3
+ export const plainContext = {
4
+ href: (raw) => ({ kind: "external", url: raw }),
5
+ link: (name, label) => [{ kind: "code", text: label ?? name }],
6
+ cite: (t) => [{ kind: "text", text: t }],
7
+ };
8
+ /** The language a fence names, as the highlighter knows it. */
9
+ export function langOf(info) {
10
+ switch (info.trim().split(/\s+/)[0]?.toLowerCase() ?? "") {
11
+ case "ts":
12
+ case "typescript":
13
+ case "js":
14
+ case "javascript":
15
+ case "tsx":
16
+ return "ts";
17
+ case "sql":
18
+ return "sql";
19
+ case "sh":
20
+ case "bash":
21
+ case "shell":
22
+ case "console":
23
+ return "sh";
24
+ case "toml":
25
+ return "toml";
26
+ case "json":
27
+ case "json5":
28
+ case "jsonc":
29
+ return "json";
30
+ case "ttl":
31
+ case "turtle":
32
+ return "turtle";
33
+ case "yaml":
34
+ case "yml":
35
+ return "yaml";
36
+ case "mermaid":
37
+ return "mermaid";
38
+ default:
39
+ return "text";
40
+ }
41
+ }
42
+ const FENCE = /^(\s*)(`{3,}|~{3,})(.*)$/;
43
+ const HEADING = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
44
+ const BULLET = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/;
45
+ const TABLE_RULE = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
46
+ /** The cells of a table's row. */
47
+ function cells(line) {
48
+ const t = line.trim().replace(/^\|/, "").replace(/\|$/, "");
49
+ const out = [];
50
+ let cur = "";
51
+ let tick = false;
52
+ for (let i = 0; i < t.length; i++) {
53
+ const c = t[i] ?? "";
54
+ if (c === "\\" && t[i + 1] === "|") {
55
+ cur += "|";
56
+ i++;
57
+ }
58
+ else if (c === "`") {
59
+ tick = !tick;
60
+ cur += c;
61
+ }
62
+ else if (c === "|" && !tick) {
63
+ out.push(cur.trim());
64
+ cur = "";
65
+ }
66
+ else
67
+ cur += c;
68
+ }
69
+ out.push(cur.trim());
70
+ return out;
71
+ }
72
+ /**
73
+ * The blocks of a Markdown text.
74
+ *
75
+ * @param source - the text
76
+ * @param ctx - where links go and what is a citation
77
+ */
78
+ export function markdown(source, ctx) {
79
+ const lines = source.replace(/\r\n?/g, "\n").split("\n");
80
+ const blocks = [];
81
+ let i = 0;
82
+ const used = new Map();
83
+ const anchor = (t) => {
84
+ const base = slugOf(t) || "section";
85
+ const n = used.get(base) ?? 0;
86
+ used.set(base, n + 1);
87
+ return n === 0 ? base : `${base}-${n}`;
88
+ };
89
+ while (i < lines.length) {
90
+ const line = lines[i] ?? "";
91
+ if (line.trim() === "") {
92
+ i++;
93
+ continue;
94
+ }
95
+ const fence = FENCE.exec(line);
96
+ if (fence !== null) {
97
+ const marker = fence[2] ?? "```";
98
+ const indent = (fence[1] ?? "").length;
99
+ const body = [];
100
+ i++;
101
+ while (i < lines.length && !(lines[i] ?? "").trim().startsWith(marker)) {
102
+ const l = lines[i] ?? "";
103
+ body.push(l.slice(Math.min(indent, l.length - l.trimStart().length)));
104
+ i++;
105
+ }
106
+ i++;
107
+ const lang = langOf(fence[3] ?? "");
108
+ // a Mermaid fence is a diagram, drawn when the site is built (commons 0011-documentation FR-037); its source stays on the page
109
+ blocks.push(lang === "mermaid" ? { kind: "diagram", source: body.join("\n"), caption: "" } : { kind: "code", lang, text: body.join("\n") });
110
+ continue;
111
+ }
112
+ const heading = HEADING.exec(line);
113
+ if (heading !== null) {
114
+ const depth = (heading[1] ?? "#").length;
115
+ const inl = inlines(heading[2] ?? "", ctx);
116
+ const level = depth <= 2 ? 2 : depth === 3 ? 3 : 4;
117
+ blocks.push({ kind: "heading", level, id: anchor(plain(inl)), text: inl });
118
+ i++;
119
+ continue;
120
+ }
121
+ if (line.trimStart().startsWith("|") && TABLE_RULE.test(lines[i + 1] ?? "")) {
122
+ const head = cells(line).map((c) => inlines(c, ctx));
123
+ i += 2;
124
+ const rows = [];
125
+ while (i < lines.length && (lines[i] ?? "").trimStart().startsWith("|")) {
126
+ rows.push(cells(lines[i] ?? "").map((c) => inlines(c, ctx)));
127
+ i++;
128
+ }
129
+ blocks.push({ kind: "table", head, rows });
130
+ continue;
131
+ }
132
+ const bullet = BULLET.exec(line);
133
+ if (bullet !== null) {
134
+ const base = (bullet[1] ?? "").length;
135
+ const ordered = /\d/.test(bullet[2] ?? "");
136
+ const items = [];
137
+ while (i < lines.length) {
138
+ const b = BULLET.exec(lines[i] ?? "");
139
+ if (b === null || (b[1] ?? "").length !== base)
140
+ break;
141
+ const body = [b[3] ?? ""];
142
+ i++;
143
+ while (i < lines.length) {
144
+ const l = lines[i] ?? "";
145
+ if (l.trim() === "") {
146
+ const next = lines[i + 1] ?? "";
147
+ if (next.length - next.trimStart().length > base && next.trim() !== "") {
148
+ body.push("");
149
+ i++;
150
+ continue;
151
+ }
152
+ break;
153
+ }
154
+ const ind = l.length - l.trimStart().length;
155
+ if (ind <= base && (BULLET.test(l) || FENCE.test(l) || HEADING.test(l)))
156
+ break;
157
+ if (ind <= base && !BULLET.test(l)) {
158
+ body.push(l.trim());
159
+ i++;
160
+ continue;
161
+ }
162
+ body.push(l.slice(Math.min(ind, base + 2)));
163
+ i++;
164
+ }
165
+ items.push(markdown(body.join("\n"), ctx));
166
+ }
167
+ blocks.push({ kind: "list", ordered, items });
168
+ continue;
169
+ }
170
+ const para = [];
171
+ while (i < lines.length) {
172
+ const l = lines[i] ?? "";
173
+ if (l.trim() === "" || FENCE.test(l) || HEADING.test(l) || BULLET.test(l))
174
+ break;
175
+ if (l.trimStart().startsWith("|") && TABLE_RULE.test(lines[i + 1] ?? ""))
176
+ break;
177
+ para.push(l.trim());
178
+ i++;
179
+ }
180
+ blocks.push({ kind: "paragraph", inlines: inlines(para.join(" "), ctx) });
181
+ }
182
+ return blocks;
183
+ }
184
+ /**
185
+ * The inlines of a run of Markdown: code spans, strong and emphasis, links, autolinks, `{@link}`, and escapes.
186
+ *
187
+ * @param source - the run
188
+ * @param ctx - where links go and what is a citation
189
+ */
190
+ export function inlines(source, ctx) {
191
+ const out = [];
192
+ let buf = "";
193
+ const flush = () => {
194
+ if (buf !== "")
195
+ out.push(...ctx.cite(buf));
196
+ buf = "";
197
+ };
198
+ let i = 0;
199
+ while (i < source.length) {
200
+ const c = source[i] ?? "";
201
+ const rest = source.slice(i);
202
+ if (c === "\\" && i + 1 < source.length && /[\\`*_{}[\]()#+\-.!|<>~]/.test(source[i + 1] ?? "")) {
203
+ buf += source[i + 1] ?? "";
204
+ i += 2;
205
+ continue;
206
+ }
207
+ if (c === "`") {
208
+ const ticks = /^`+/.exec(rest)?.[0] ?? "`";
209
+ const end = source.indexOf(ticks, i + ticks.length);
210
+ if (end > 0) {
211
+ flush();
212
+ let code = source.slice(i + ticks.length, end);
213
+ if (code.startsWith(" ") && code.endsWith(" ") && code.trim() !== "")
214
+ code = code.slice(1, -1);
215
+ out.push({ kind: "code", text: code });
216
+ i = end + ticks.length;
217
+ continue;
218
+ }
219
+ }
220
+ const tsdoc = /^\{@link(?:code|plain)?\s+([^}|\s]+)\s*(?:\|\s*([^}]*))?\}/.exec(rest);
221
+ if (tsdoc !== null) {
222
+ flush();
223
+ out.push(...ctx.link(tsdoc[1] ?? "", tsdoc[2]?.trim() || undefined));
224
+ i += tsdoc[0].length;
225
+ continue;
226
+ }
227
+ const auto = /^<(https?:\/\/[^\s>]+)>/.exec(rest);
228
+ if (auto !== null) {
229
+ flush();
230
+ const url = auto[1] ?? "";
231
+ out.push({ kind: "link", href: { kind: "external", url }, children: [{ kind: "text", text: url }] });
232
+ i += auto[0].length;
233
+ continue;
234
+ }
235
+ if (c === "[") {
236
+ const close = matching(source, i);
237
+ if (close > 0 && source[close + 1] === "(") {
238
+ const end = source.indexOf(")", close + 2);
239
+ if (end > 0) {
240
+ flush();
241
+ const dest = source.slice(close + 2, end).trim().split(/\s+/)[0] ?? "";
242
+ out.push({ kind: "link", href: ctx.href(dest), children: inlines(source.slice(i + 1, close), { ...ctx, cite: plainContext.cite }) });
243
+ i = end + 1;
244
+ continue;
245
+ }
246
+ }
247
+ }
248
+ if (rest.startsWith("**") || rest.startsWith("__")) {
249
+ const mark = rest.slice(0, 2);
250
+ const end = source.indexOf(mark, i + 2);
251
+ if (end > i + 2) {
252
+ flush();
253
+ out.push({ kind: "strong", children: inlines(source.slice(i + 2, end), ctx) });
254
+ i = end + 2;
255
+ continue;
256
+ }
257
+ }
258
+ if ((c === "*" || c === "_") && /\S/.test(source[i + 1] ?? "") && !/[\p{L}\p{N}]/u.test(source[i - 1] ?? "")) {
259
+ let end = i + 1;
260
+ while (end < source.length) {
261
+ end = source.indexOf(c, end);
262
+ if (end < 0)
263
+ break;
264
+ if (/\S/.test(source[end - 1] ?? "") && !/[\p{L}\p{N}]/u.test(source[end + 1] ?? ""))
265
+ break;
266
+ end++;
267
+ }
268
+ if (end > i + 1) {
269
+ flush();
270
+ out.push({ kind: "emphasis", children: inlines(source.slice(i + 1, end), ctx) });
271
+ i = end + 1;
272
+ continue;
273
+ }
274
+ }
275
+ buf += c;
276
+ i++;
277
+ }
278
+ flush();
279
+ return out;
280
+ }
281
+ /** Where the bracket that closes the one at `at` is, or -1. */
282
+ function matching(s, at) {
283
+ let depth = 0;
284
+ for (let i = at; i < s.length; i++) {
285
+ const c = s[i];
286
+ if (c === "`") {
287
+ const end = s.indexOf("`", i + 1);
288
+ if (end > 0)
289
+ i = end;
290
+ continue;
291
+ }
292
+ if (c === "[")
293
+ depth++;
294
+ else if (c === "]") {
295
+ depth--;
296
+ if (depth === 0)
297
+ return i;
298
+ }
299
+ }
300
+ return -1;
301
+ }
package/dist/mod.d.ts ADDED
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The library of IFC Docs, `@intellectual-frontiers/commons/docs` (commons 0011-documentation FR-021, FR-023, FR-026): the configuration's
3
+ * 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
4
+ * 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
5
+ * from here.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { buildSite, loadConfig, report } from "@intellectual-frontiers/commons/docs";
10
+ * const config = await loadConfig("docs.config.ts");
11
+ * if (config.kind === "ok") console.log(report((await buildSite(config.value)).found));
12
+ * ```
13
+ *
14
+ * @module
15
+ */
16
+ export type { About, AboutArea, AboutCommand, AboutEnforcer, AboutExample, AboutFolder, AboutPhase, AboutPhaseState, AboutRule, AboutSpec, CitationsConfig, Config, DocsConfig, HomeConfig, LinkedRepository, PackageConfig, PackageSource, SpecKitConfig, SpecKitSource, } from "./config.js";
17
+ export { isAbout, normalDir, resolveConfig, under } from "./config.js";
18
+ export { Build } from "./build.js";
19
+ export { type Finding, message, type Problem, report } from "./check.js";
20
+ export type { ApiExport, ApiMember, AreaApi, ExportKind } from "./extract/api.js";
21
+ export type { Constitution, Enforcement, Spec, SpecKit } from "./extract/specs.js";
22
+ export type { LinkScope } from "./links.js";
23
+ export { llmsIndex, markdownOf, twinOf } from "./emit/markdown.js";
24
+ export type { Layer, LayerElement, LayeredFinding, LayeredModel, LayeredSource, LayeredSubject, Locate, SourceLocation, TraceEdge } from "./layered.js";
25
+ export type { Lens, LensPages, SiteFile } from "./lens.js";
26
+ export type { Badge, Block, Card, Href, Inline, Page, Section, Tab, TreeNode } from "./model.js";
27
+ export { plain, possessive, slugOf } from "./model.js";
28
+ export { areaPage, firstSentence } from "./pages/overview.js";
29
+ export type { Area, Package } from "./sources.js";
30
+ export { type DocComment, moduleComment } from "./tsdoc.js";
31
+ export { type Built, buildSite, writeSite } from "./site.js";
32
+ export { type Command, findConfig, loadConfig, main, parseArgs, USAGE } from "./cli.js";