@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,77 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * Code highlighted when the site is built (commons 0011-documentation FR-017, FR-037), so that a page needs no script to colour it: Shiki, with the grammars of the languages the site shows (TypeScript, SQL, shell, TOML, JSON,
4
+ * Turtle and YAML) and one theme for the light scheme and one for the dark, on the Oniguruma engine (WebAssembly, so the same on Bun and Node, with no native part). Each coloured run is a span whose two colours
5
+ * are custom properties (`--l`, `--d`), which the stylesheet picks between by the same rule as the rest of the site's colours; a run in the theme's own foreground is plain text. Text and diagrams are not coloured.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { highlightedHtml } from "./highlight.ts";
10
+ * highlightedHtml("const a = 1;", "ts");
11
+ * // '<span class="t" style="--l:#D73A49;--d:#F97583">const</span> a <span ...'
12
+ * ```
13
+ *
14
+ * @module
15
+ */
16
+ import { createHighlighterCore } from "shiki/core";
17
+ import { createOnigurumaEngine } from "shiki/engine/oniguruma";
18
+ import json from "shiki/langs/json.mjs";
19
+ import shellscript from "shiki/langs/shellscript.mjs";
20
+ import sql from "shiki/langs/sql.mjs";
21
+ import toml from "shiki/langs/toml.mjs";
22
+ import turtle from "shiki/langs/turtle.mjs";
23
+ import typescript from "shiki/langs/typescript.mjs";
24
+ import yaml from "shiki/langs/yaml.mjs";
25
+ import githubDark from "shiki/themes/github-dark.mjs";
26
+ import githubLight from "shiki/themes/github-light.mjs";
27
+ /** The themes of the two schemes. */
28
+ export const THEMES = { light: "github-light", dark: "github-dark" };
29
+ /** The grammar each language of the site is read with; those not here are left plain. */
30
+ const GRAMMAR = { ts: "typescript", sql: "sql", sh: "shellscript", toml: "toml", json: "json", turtle: "turtle", yaml: "yaml" };
31
+ /** Shiki, with the Oniguruma engine (WebAssembly, the same on Bun and Node) made once when the module is read; reading code with it is then synchronous. */
32
+ const highlighter = await createHighlighterCore({ themes: [githubLight, githubDark], langs: [typescript, sql, shellscript, toml, json, turtle, yaml], engine: createOnigurumaEngine(import("shiki/wasm")) });
33
+ /** Code longer than this many characters is shown plain: a computed type of thousands of characters costs more to colour than it helps a reader, and the page folds it. */
34
+ export const LONGEST_COLOURED = 6000;
35
+ // The first reading of a grammar by the engine can give runs that are not cut at its tokens (a comment left in the text before it). A reading of each grammar here, whose result is not used, makes the readings that are
36
+ // used the same whatever came first; the test of the highlighter holds this.
37
+ for (const [lang, sample] of [["typescript", 'const a = f("x"); // c'], ["sql", "SELECT 1 -- c"], ["shellscript", 'echo "$A" # c'], ["toml", '[a]\nb = "x" # c'], ["json", '{"a": [1, true, null]}'], ["turtle", 'a:b a c:D ; d:e "f"@en .'], ["yaml", "a: 1\nb: [x] # c"]]) {
38
+ for (const theme of [THEMES.light, THEMES.dark])
39
+ highlighter.codeToTokensBase(sample, { lang, theme });
40
+ }
41
+ const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
42
+ /** The colours that are the themes' own text, which are left as plain text. */
43
+ const FOREGROUND = { light: githubLight.colors?.["editor.foreground"]?.toLowerCase() ?? "#24292e", dark: githubDark.colors?.["editor.foreground"]?.toLowerCase() ?? "#e1e4e8" };
44
+ /** The runs of the lines of code, by line, in the language given; one plain run for a language that is not coloured. */
45
+ export function runs(code, lang) {
46
+ const grammar = GRAMMAR[lang];
47
+ if (grammar === undefined || code.length > LONGEST_COLOURED)
48
+ return code.split("\n").map((line) => [{ text: line, italic: false, bold: false }]);
49
+ const lines = highlighter.codeToTokensWithThemes(code, { lang: grammar, themes: THEMES });
50
+ return lines.map((line) => {
51
+ const out = [];
52
+ for (const t of line) {
53
+ const l = t.variants["light"];
54
+ const d = t.variants["dark"];
55
+ const plain = (l?.color ?? "").toLowerCase() === FOREGROUND.light && (d?.color ?? "").toLowerCase() === FOREGROUND.dark && ((l?.fontStyle ?? 0) | (d?.fontStyle ?? 0)) === 0;
56
+ const run = plain
57
+ ? { text: t.content, italic: false, bold: false }
58
+ : { text: t.content, ...(l?.color === undefined ? {} : { light: l.color }), ...(d?.color === undefined ? {} : { dark: d.color }), italic: (((l?.fontStyle ?? 0) | (d?.fontStyle ?? 0)) & 1) !== 0, bold: (((l?.fontStyle ?? 0) | (d?.fontStyle ?? 0)) & 2) !== 0 };
59
+ const last = out[out.length - 1];
60
+ if (last !== undefined && last.light === run.light && last.dark === run.dark && last.italic === run.italic && last.bold === run.bold)
61
+ out[out.length - 1] = { ...last, text: last.text + run.text };
62
+ else
63
+ out.push(run);
64
+ }
65
+ return out;
66
+ });
67
+ }
68
+ /** Code as HTML: coloured runs as spans with their two colours, the rest as escaped text. */
69
+ export function highlightedHtml(code, lang) {
70
+ return runs(code, lang)
71
+ .map((line) => line
72
+ .map((r) => r.light === undefined && r.dark === undefined
73
+ ? escapeHtml(r.text)
74
+ : `<span class="t${r.italic ? " i" : ""}${r.bold ? " b" : ""}" style="--l:${r.light ?? "inherit"};--d:${r.dark ?? "inherit"}">${escapeHtml(r.text)}</span>`)
75
+ .join(""))
76
+ .join("\n");
77
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The layered model (commons 0011-documentation FR-029): what a library that is built in layers (governance, logical, physical or surface) gives the generator to document it, as plain data and types only. A library keeps
3
+ * its own pure builder that makes a `LayeredModel` from its values; the generator's lens turns it into pages, a Markdown twin for each and the model as JSON. The generator depends on no library it shows: a builder's
4
+ * result is checked against these types where a configuration passes it, and by their shape alone.
5
+ *
6
+ * @remarks
7
+ * An element has a stable id (the same across builds, the key of a link and of a diff), a kind, a name, a definition (the words the model gives it), where it is written (a source location) and what is said of it as
8
+ * properties. A trace edge says that an element of one layer is made into an element of the next: a governance concept into a table, a table into the statements that make it and into the typed table that reads it.
9
+ * Operations are an element kind of their own that several libraries share: a governance action, a headless verb, and what they become (a SQL routine, a command, a tool, a route).
10
+ *
11
+ * @module
12
+ */
13
+ /** Where an element is written: a file of the repository and a line. */
14
+ export interface SourceLocation {
15
+ /** The path from the repository's root. */
16
+ readonly file: string;
17
+ /** The line, from 1, where it is declared. */
18
+ readonly line?: number;
19
+ }
20
+ /** A layer of a model: what it is called, what it is for and the kinds of element it holds. */
21
+ export interface Layer {
22
+ /** Its name, as `governance`. */
23
+ readonly id: string;
24
+ /** What the layer is, in a sentence. */
25
+ readonly title: string;
26
+ /** What a reader may and may not do at this layer, in a sentence or two. */
27
+ readonly summary: string;
28
+ /** The kinds of element it holds. */
29
+ readonly kinds: readonly string[];
30
+ }
31
+ /** One thing a layer says: a module, a concept, an attribute, a table, a column, a statement, a command. */
32
+ export interface LayerElement {
33
+ /** Stable across builds: `governance:identity/principal`, `logical:table:principal`. */
34
+ readonly id: string;
35
+ /** The layer it is in. */
36
+ readonly layer: string;
37
+ /** What kind of thing it is, one of the layer's kinds. */
38
+ readonly kind: string;
39
+ /** What it is called. */
40
+ readonly name: string;
41
+ /** The words the model gives it; empty where it has none, which is a finding. */
42
+ readonly definition: string;
43
+ /** The element that holds it (an attribute's concept, a column's table). */
44
+ readonly parent?: string;
45
+ /** Where it is written. */
46
+ readonly source?: SourceLocation;
47
+ /** What is said of it, by name: types, multiplicity, annotations, the text of a statement. */
48
+ readonly properties: {
49
+ readonly [name: string]: string | number | boolean | readonly string[] | null;
50
+ };
51
+ }
52
+ /** An element of one layer made into an element of another. */
53
+ export interface TraceEdge {
54
+ readonly from: string;
55
+ readonly to: string;
56
+ /** How: `projects to`, `written as`, `read by`. */
57
+ readonly how: string;
58
+ }
59
+ /** What the model's builder found wrong. */
60
+ export interface LayeredFinding {
61
+ /** A rule's code, as `undescribed`. */
62
+ readonly rule: string;
63
+ readonly element: string;
64
+ readonly message: string;
65
+ }
66
+ /** What a model applies to. */
67
+ export interface LayeredSubject {
68
+ /** Its id. */
69
+ readonly id: string;
70
+ /** Its title. */
71
+ readonly title: string;
72
+ /** What its models apply to, in a sentence. */
73
+ readonly about: string;
74
+ /** Its place among the subjects: lower first. */
75
+ readonly order: number;
76
+ }
77
+ /** A model that is built in layers, as the generator documents it. */
78
+ export interface LayeredModel {
79
+ /** Its name and the library it is of, as `arca`, `data`. */
80
+ readonly name: string;
81
+ readonly library: string;
82
+ readonly title: string;
83
+ readonly summary: string;
84
+ /** What the model applies to, where it has a subject: models are grouped by it. */
85
+ readonly subject?: LayeredSubject;
86
+ readonly layers: readonly Layer[];
87
+ readonly elements: readonly LayerElement[];
88
+ readonly trace: readonly TraceEdge[];
89
+ readonly findings: readonly LayeredFinding[];
90
+ }
91
+ /** A function that makes the layered models of a repository, and may be told where each element is written. */
92
+ export type LayeredSource = (locate: Locate) => Promise<readonly LayeredModel[]> | readonly LayeredModel[];
93
+ /** Where a value is written (and, for a member of it such as an attribute of a concept, where that is), found by the lens from the exports it knows: by the value's identity. */
94
+ export type Locate = (value: unknown, member?: string) => SourceLocation | undefined;
@@ -0,0 +1,14 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * The layered model (commons 0011-documentation FR-029): what a library that is built in layers (governance, logical, physical or surface) gives the generator to document it, as plain data and types only. A library keeps
4
+ * its own pure builder that makes a `LayeredModel` from its values; the generator's lens turns it into pages, a Markdown twin for each and the model as JSON. The generator depends on no library it shows: a builder's
5
+ * result is checked against these types where a configuration passes it, and by their shape alone.
6
+ *
7
+ * @remarks
8
+ * An element has a stable id (the same across builds, the key of a link and of a diff), a kind, a name, a definition (the words the model gives it), where it is written (a source location) and what is said of it as
9
+ * properties. A trace edge says that an element of one layer is made into an element of the next: a governance concept into a table, a table into the statements that make it and into the typed table that reads it.
10
+ * Operations are an element kind of their own that several libraries share: a governance action, a headless verb, and what they become (a SQL routine, a command, a tool, a route).
11
+ *
12
+ * @module
13
+ */
14
+ export {};
@@ -0,0 +1,23 @@
1
+ import type { Lens, Section } from "../mod.js";
2
+ /** One guide: its Markdown file and where it is in the site. */
3
+ export interface GuideSpec {
4
+ /** The Markdown file, from the repository's root. Its first heading is the page's title. */
5
+ readonly file: string;
6
+ /** The page's address on the site, as `start/new-developer.html`. */
7
+ readonly path: string;
8
+ /** The section it is in. */
9
+ readonly section: Extract<Section, "start" | "concepts" | "howto">;
10
+ /** The group of the navigation it is in. */
11
+ readonly group: string;
12
+ /** Its place in its group, lowest first. */
13
+ readonly order: number;
14
+ }
15
+ /** What the guides lens is given. */
16
+ export interface GuidesOptions {
17
+ /** Its name, which the build reports it by. */
18
+ readonly name: string;
19
+ /** The guides, which include the index page of each section it uses. */
20
+ readonly guides: readonly GuideSpec[];
21
+ }
22
+ /** The guides lens. */
23
+ export declare function guidesLens(options: GuidesOptions): Lens;
@@ -0,0 +1,49 @@
1
+ // Spec: 0001-docs FR-002
2
+ /**
3
+ * The guides lens (commons 0011-documentation FR-032): pages that people write in Markdown for the reader who is new to a repository (a path for each kind of reader, the ideas the repository is built on, and how to do the
4
+ * common things), kept in the repository beside the code and checked like every page: its citations of a specification and its links to a file or a folder become links, an unknown requirement is a finding, and a page names
5
+ * the section and group it is in. The lens knows nothing of what the guides say.
6
+ *
7
+ * @module
8
+ */
9
+ import { fs, path } from "@intellectual-frontiers/system";
10
+ /** The first sentence of a text, cut at 200 characters. */
11
+ function firstSentence(t, max = 200) {
12
+ const flat = t.replace(/\s+/g, " ").trim();
13
+ const s = /^(.+?[.!?])(\s|$)/.exec(flat)?.[1] ?? flat;
14
+ return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
15
+ }
16
+ /** The guides lens. */
17
+ export function guidesLens(options) {
18
+ return {
19
+ name: options.name,
20
+ read: async (b) => {
21
+ const texts = new Map();
22
+ for (const g of options.guides) {
23
+ try {
24
+ texts.set(g.file, await fs.readTextFile(path.join(b.root, g.file)));
25
+ }
26
+ catch {
27
+ b.found.push({ where: g.file, problem: { kind: "undescribed", entity: `the guide ${g.file}, which the guides lens is told of, cannot be read` } });
28
+ }
29
+ }
30
+ for (const g of options.guides)
31
+ if (texts.has(g.file))
32
+ b.files.set(g.file, g.path);
33
+ return (build, after) => {
34
+ for (const g of options.guides) {
35
+ const text = texts.get(g.file);
36
+ if (text === undefined)
37
+ continue;
38
+ const m = /^#\s+(.+)\n+/.exec(text);
39
+ const title = m?.[1]?.trim() ?? g.path;
40
+ const body = m === null ? text : text.slice(m[0].length);
41
+ const blocks = build.md(body, { page: g.path, file: g.file });
42
+ const lead = /^(?![#>|`\-*\d])[^\n]+/m.exec(body)?.[0] ?? title;
43
+ build.add({ path: g.path, title, description: firstSentence(lead.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*_]/g, ""), 200), section: g.section, group: g.group, order: g.order, blocks });
44
+ }
45
+ return after;
46
+ };
47
+ },
48
+ };
49
+ }
@@ -0,0 +1,16 @@
1
+ import { type LayeredSource, type Lens } from "../mod.js";
2
+ /** What the lens is given. */
3
+ export interface LayeredLensOptions {
4
+ /** Its name, which the build reports it by. */
5
+ readonly name: string;
6
+ /** The group of the Models section the pages are in. */
7
+ readonly group?: string;
8
+ /** Makes the models; it is told how to find where a value is written. */
9
+ readonly source: LayeredSource;
10
+ /** The files, from the repository's root, whose exports are the values the models are made of: where an element is written is found from them. */
11
+ readonly exports: readonly string[];
12
+ /** The command that regenerates what follows the top layer, and the file a person edits first, written into the page that says how to change a model. */
13
+ readonly regenerate?: readonly string[];
14
+ }
15
+ /** The layered-model lens. */
16
+ export declare function layeredLens(options: LayeredLensOptions): Lens;