@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/dist/tsdoc.d.ts
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* TSDoc read into its parts (commons 0011-documentation FR-006): the summary, `@remarks`, `@limits` (this repository's own block tag: what
|
|
3
|
+
* a module does not do, or does only in part), `@example`, `@see`, `@param`, `@returns` and `@deprecated`, from a comment's text or from
|
|
4
|
+
* the tags the TypeScript checker gives. The text of each part stays Markdown, for `markdown.ts` to read.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { moduleComment } from "./tsdoc.js";
|
|
9
|
+
* moduleComment("/**\n * What it is.\n *\n * @limits\n * What it is not.\n *\n * @module\n *\/\n")?.limits; // "What it is not."
|
|
10
|
+
* ```
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
/** A parameter's name and what the comment says of it. */
|
|
15
|
+
export interface DocParam {
|
|
16
|
+
/** Its name. */
|
|
17
|
+
readonly name: string;
|
|
18
|
+
/** What it is. */
|
|
19
|
+
readonly text: string;
|
|
20
|
+
}
|
|
21
|
+
/** The parts of a TSDoc comment. */
|
|
22
|
+
export interface DocComment {
|
|
23
|
+
/** What comes before the first block tag. */
|
|
24
|
+
readonly summary: string;
|
|
25
|
+
/** `@remarks`: the longer account. */
|
|
26
|
+
readonly remarks?: string;
|
|
27
|
+
/** `@limits`: what it does not do, or does only in part. */
|
|
28
|
+
readonly limits?: string;
|
|
29
|
+
/** Each `@example`. */
|
|
30
|
+
readonly examples: readonly string[];
|
|
31
|
+
/** Each `@see`. */
|
|
32
|
+
readonly see: readonly string[];
|
|
33
|
+
/** Each `@param`. */
|
|
34
|
+
readonly params: readonly DocParam[];
|
|
35
|
+
/** `@returns`. */
|
|
36
|
+
readonly returns?: string;
|
|
37
|
+
/** `@deprecated`, with why. */
|
|
38
|
+
readonly deprecated?: string;
|
|
39
|
+
/** Whether it says `@module`. */
|
|
40
|
+
readonly isModule: boolean;
|
|
41
|
+
}
|
|
42
|
+
/** A block tag and its text, as the checker gives it or as a comment's text holds it. */
|
|
43
|
+
export interface DocTag {
|
|
44
|
+
/** The tag's name, without `@`. */
|
|
45
|
+
readonly name: string;
|
|
46
|
+
/** Its text. */
|
|
47
|
+
readonly text: string;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* The parts of a comment, from its summary and its block tags.
|
|
51
|
+
*
|
|
52
|
+
* @param summary - the text before the first block tag
|
|
53
|
+
* @param tags - the block tags, in order
|
|
54
|
+
*/
|
|
55
|
+
export declare function docOf(summary: string, tags: readonly DocTag[]): DocComment;
|
|
56
|
+
/**
|
|
57
|
+
* The parts of a comment's text: the inside of `/** ... *\/`, its leading asterisks taken off.
|
|
58
|
+
*
|
|
59
|
+
* @param inside - the comment's text between its delimiters
|
|
60
|
+
*/
|
|
61
|
+
export declare function parseComment(inside: string): DocComment;
|
|
62
|
+
/**
|
|
63
|
+
* The module comment of a source file: its first `/** ... *\/` comment (after any `//` lines, such as a `// Spec:` header), where that comment says `@module`.
|
|
64
|
+
*
|
|
65
|
+
* @param source - the file's text
|
|
66
|
+
*/
|
|
67
|
+
export declare function moduleComment(source: string): DocComment | undefined;
|
package/dist/tsdoc.js
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* TSDoc read into its parts (commons 0011-documentation FR-006): the summary, `@remarks`, `@limits` (this repository's own block tag: what
|
|
4
|
+
* a module does not do, or does only in part), `@example`, `@see`, `@param`, `@returns` and `@deprecated`, from a comment's text or from
|
|
5
|
+
* the tags the TypeScript checker gives. The text of each part stays Markdown, for `markdown.ts` to read.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { moduleComment } from "./tsdoc.ts";
|
|
10
|
+
* moduleComment("/**\n * What it is.\n *\n * @limits\n * What it is not.\n *\n * @module\n *\/\n")?.limits; // "What it is not."
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
const dedent = (s) => {
|
|
16
|
+
const lines = s.replace(/^\n+|\s+$/g, "").split("\n");
|
|
17
|
+
const ind = Math.min(...lines.filter((l) => l.trim() !== "").map((l) => l.length - l.trimStart().length));
|
|
18
|
+
return lines.map((l) => l.slice(Number.isFinite(ind) ? ind : 0)).join("\n");
|
|
19
|
+
};
|
|
20
|
+
/** A `@param` tag's text, as `name - what` or `name what`. */
|
|
21
|
+
function param(text) {
|
|
22
|
+
const m = /^\s*([\w$.[\]]+)\s*(?:-\s*)?([\s\S]*)$/.exec(text);
|
|
23
|
+
return { name: m?.[1] ?? "", text: (m?.[2] ?? "").trim() };
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* The parts of a comment, from its summary and its block tags.
|
|
27
|
+
*
|
|
28
|
+
* @param summary - the text before the first block tag
|
|
29
|
+
* @param tags - the block tags, in order
|
|
30
|
+
*/
|
|
31
|
+
export function docOf(summary, tags) {
|
|
32
|
+
const all = (n) => tags.filter((t) => t.name === n).map((t) => dedent(t.text));
|
|
33
|
+
const one = (n) => {
|
|
34
|
+
const v = all(n);
|
|
35
|
+
return v.length === 0 ? undefined : v.join("\n\n");
|
|
36
|
+
};
|
|
37
|
+
const remarks = one("remarks");
|
|
38
|
+
const limits = one("limits");
|
|
39
|
+
const returns = one("returns");
|
|
40
|
+
const deprecated = one("deprecated");
|
|
41
|
+
return {
|
|
42
|
+
summary: dedent(summary),
|
|
43
|
+
...(remarks === undefined ? {} : { remarks }),
|
|
44
|
+
...(limits === undefined ? {} : { limits }),
|
|
45
|
+
examples: all("example"),
|
|
46
|
+
see: all("see"),
|
|
47
|
+
params: tags.filter((t) => t.name === "param").map((t) => param(t.text)),
|
|
48
|
+
...(returns === undefined ? {} : { returns }),
|
|
49
|
+
...(deprecated === undefined ? {} : { deprecated }),
|
|
50
|
+
isModule: tags.some((t) => t.name === "module"),
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* The parts of a comment's text: the inside of `/** ... *\/`, its leading asterisks taken off.
|
|
55
|
+
*
|
|
56
|
+
* @param inside - the comment's text between its delimiters
|
|
57
|
+
*/
|
|
58
|
+
export function parseComment(inside) {
|
|
59
|
+
const lines = inside.split("\n").map((l) => l.replace(/^\s*\* ?/, ""));
|
|
60
|
+
const tags = [];
|
|
61
|
+
const summary = [];
|
|
62
|
+
let current;
|
|
63
|
+
let fenced = false;
|
|
64
|
+
for (const l of lines) {
|
|
65
|
+
if (/^\s*(```|~~~)/.test(l))
|
|
66
|
+
fenced = !fenced;
|
|
67
|
+
const tag = fenced ? null : /^@(\w+)\s?(.*)$/.exec(l.trim());
|
|
68
|
+
if (tag !== null) {
|
|
69
|
+
if (current !== undefined)
|
|
70
|
+
tags.push({ name: current.name, text: current.lines.join("\n") });
|
|
71
|
+
current = { name: tag[1] ?? "", lines: tag[2] === undefined || tag[2] === "" ? [] : [tag[2]] };
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
if (current === undefined)
|
|
75
|
+
summary.push(l);
|
|
76
|
+
else
|
|
77
|
+
current.lines.push(l);
|
|
78
|
+
}
|
|
79
|
+
if (current !== undefined)
|
|
80
|
+
tags.push({ name: current.name, text: current.lines.join("\n") });
|
|
81
|
+
return docOf(summary.join("\n"), tags);
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The module comment of a source file: its first `/** ... *\/` comment (after any `//` lines, such as a `// Spec:` header), where that comment says `@module`.
|
|
85
|
+
*
|
|
86
|
+
* @param source - the file's text
|
|
87
|
+
*/
|
|
88
|
+
export function moduleComment(source) {
|
|
89
|
+
const m = /^\s*(?:#![^\n]*\n\s*)?(?:\/\/[^\n]*\n\s*)*\/\*\*([\s\S]*?)\*\//.exec(source);
|
|
90
|
+
if (m === null)
|
|
91
|
+
return undefined;
|
|
92
|
+
const doc = parseComment(m[1] ?? "");
|
|
93
|
+
return doc.isModule ? doc : undefined;
|
|
94
|
+
}
|
package/ifc-docs.mjs
ADDED
package/package.json
CHANGED
|
@@ -1,6 +1,68 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/docs",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "IFC Docs: the generator of a repository's documentation site, made from its TypeScript and its spec kit alone: typed configuration, an API reference for every export, the specifications with the tests that prove them, and lenses for layered models, programs, guides and releases; one command, ifc-docs, builds or checks the static site.",
|
|
5
|
+
"license": "PolyForm-Noncommercial-1.0.0",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=26"
|
|
9
|
+
},
|
|
10
|
+
"sideEffects": false,
|
|
11
|
+
"bin": {
|
|
12
|
+
"ifc-docs": "./ifc-docs.mjs"
|
|
13
|
+
},
|
|
14
|
+
"types": "./dist/mod.d.ts",
|
|
15
|
+
"exports": {
|
|
16
|
+
".": {
|
|
17
|
+
"types": "./dist/mod.d.ts",
|
|
18
|
+
"bun": "./src/mod.ts",
|
|
19
|
+
"default": "./dist/mod.js"
|
|
20
|
+
},
|
|
21
|
+
"./lens/layered": {
|
|
22
|
+
"types": "./dist/lens/layered.d.ts",
|
|
23
|
+
"bun": "./src/lens/layered.ts",
|
|
24
|
+
"default": "./dist/lens/layered.js"
|
|
25
|
+
},
|
|
26
|
+
"./lens/program": {
|
|
27
|
+
"types": "./dist/lens/program.d.ts",
|
|
28
|
+
"bun": "./src/lens/program.ts",
|
|
29
|
+
"default": "./dist/lens/program.js"
|
|
30
|
+
},
|
|
31
|
+
"./lens/guides": {
|
|
32
|
+
"types": "./dist/lens/guides.d.ts",
|
|
33
|
+
"bun": "./src/lens/guides.ts",
|
|
34
|
+
"default": "./dist/lens/guides.js"
|
|
35
|
+
},
|
|
36
|
+
"./lens/releases": {
|
|
37
|
+
"types": "./dist/lens/releases.d.ts",
|
|
38
|
+
"bun": "./src/lens/releases.ts",
|
|
39
|
+
"default": "./dist/lens/releases.js"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"dependencies": {
|
|
43
|
+
"@intellectual-frontiers/core": "0.2.0",
|
|
44
|
+
"@intellectual-frontiers/system": "0.2.0",
|
|
45
|
+
"beautiful-mermaid": "1.1.3",
|
|
46
|
+
"shiki": "4.5.0",
|
|
47
|
+
"typescript": "7.1.0-beta"
|
|
48
|
+
},
|
|
49
|
+
"files": [
|
|
50
|
+
"dist",
|
|
51
|
+
"src",
|
|
52
|
+
"ifc-docs.mjs",
|
|
53
|
+
"README.md",
|
|
54
|
+
"LICENSE"
|
|
55
|
+
],
|
|
56
|
+
"repository": {
|
|
57
|
+
"type": "git",
|
|
58
|
+
"url": "git+https://github.com/intellectual-frontiers/.github.git",
|
|
59
|
+
"directory": "commons/docs"
|
|
60
|
+
},
|
|
61
|
+
"homepage": "https://github.com/intellectual-frontiers/.github/tree/main/commons/docs",
|
|
62
|
+
"bugs": {
|
|
63
|
+
"url": "https://github.com/intellectual-frontiers/.github/issues"
|
|
64
|
+
},
|
|
65
|
+
"publishConfig": {
|
|
66
|
+
"access": "public"
|
|
67
|
+
}
|
|
68
|
+
}
|
package/src/build.ts
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* The state of one build of the site (commons 0011-documentation FR-003, FR-023): the configuration and the repository it reads, its spec kit, the pages made so far, the
|
|
4
|
+
* findings, and what links can reach (the specifications and their requirements, the page that shows each file, and each export's page),
|
|
5
|
+
* with every citation that became a link, so that a specification's page can say which pages cite it.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { fs, path } from "@intellectual-frontiers/system";
|
|
10
|
+
import type { Finding } from "./check.ts";
|
|
11
|
+
import type { Config } from "./config.ts";
|
|
12
|
+
import type { SpecKit } from "./extract/specs.ts";
|
|
13
|
+
import { contextFor, type LinkIndex, type LinkScope, specPage } from "./links.ts";
|
|
14
|
+
import { markdown } from "./markdown.ts";
|
|
15
|
+
import type { Block, Inline, Page } from "./model.ts";
|
|
16
|
+
|
|
17
|
+
/** One build: what it reads, what it has made, and what it has found. */
|
|
18
|
+
export class Build {
|
|
19
|
+
/** The configuration. */
|
|
20
|
+
readonly config: Config;
|
|
21
|
+
/** The repository's root. */
|
|
22
|
+
readonly root: string;
|
|
23
|
+
/** The spec kit. */
|
|
24
|
+
readonly kit: SpecKit;
|
|
25
|
+
/** The pages made so far. */
|
|
26
|
+
readonly pages: Page[] = [];
|
|
27
|
+
/** What has been found. */
|
|
28
|
+
readonly found: Finding[] = [];
|
|
29
|
+
/** The page that shows each file of the repository, by its path from the root. */
|
|
30
|
+
readonly files: Map<string, string> = new Map();
|
|
31
|
+
/** The API page of each source file, by its path from the root: where its exports have their anchors. */
|
|
32
|
+
readonly apiFiles: Map<string, string> = new Map();
|
|
33
|
+
/** Where each export is shown on the page of the file it is declared in, by `file#name` (the name it is declared with). */
|
|
34
|
+
readonly declared: Map<string, { readonly path: string; readonly anchor: string }> = new Map();
|
|
35
|
+
/** Each export's page and anchor, by area and name. */
|
|
36
|
+
readonly exports: Map<string, Map<string, { readonly path: string; readonly anchor: string }>> = new Map();
|
|
37
|
+
/** The page that shows a model's entity, by its area and export name (`arca!party`). */
|
|
38
|
+
readonly entityPages: Map<string, string> = new Map();
|
|
39
|
+
/** The pages that cite each specification (key `0009-example`) and each requirement (key `0009-example FR-001`). */
|
|
40
|
+
readonly citations: Map<string, Set<string>> = new Map();
|
|
41
|
+
/** The title of each package, by its slug: what the pages of its specifications and the register call it. */
|
|
42
|
+
readonly packageTitles: Map<string, string> = new Map();
|
|
43
|
+
/** What links can reach. */
|
|
44
|
+
readonly index: LinkIndex;
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* A build of a repository.
|
|
48
|
+
*
|
|
49
|
+
* @param config - its configuration
|
|
50
|
+
* @param kit - its spec kits, read
|
|
51
|
+
*/
|
|
52
|
+
constructor(config: Config, kit: SpecKit) {
|
|
53
|
+
this.config = config;
|
|
54
|
+
this.root = config.root;
|
|
55
|
+
this.kit = kit;
|
|
56
|
+
const specs = new Map(kit.specs.map((s) => [s.id, new Set(itemsOf(s.body))] as const));
|
|
57
|
+
for (const s of kit.specs) {
|
|
58
|
+
this.files.set(s.file, specPage(s.id));
|
|
59
|
+
this.files.set(s.file.split("/").slice(0, -1).join("/"), specPage(s.id));
|
|
60
|
+
}
|
|
61
|
+
this.index = {
|
|
62
|
+
specs,
|
|
63
|
+
files: this.files,
|
|
64
|
+
exports: this.exports,
|
|
65
|
+
citations: config.citations,
|
|
66
|
+
blob: (p) => `${config.repository}/blob/${config.branch}/${p}`,
|
|
67
|
+
cited: (spec, req, page) => {
|
|
68
|
+
for (const key of req === undefined ? [spec] : [spec, `${spec} ${req}`]) {
|
|
69
|
+
const set = this.citations.get(key) ?? new Set<string>();
|
|
70
|
+
set.add(page);
|
|
71
|
+
this.citations.set(key, set);
|
|
72
|
+
}
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Markdown read with this build's links, for a scope. */
|
|
78
|
+
md(text: string, scope: LinkScope): Block[] {
|
|
79
|
+
return markdown(text, contextFor(this.index, scope, this.found));
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** An example of TSDoc: Markdown where it has a fence, else TypeScript. */
|
|
83
|
+
example(text: string, scope: LinkScope): Block[] {
|
|
84
|
+
return /^\s*(```|~~~)/m.test(text) ? this.md(text, scope) : [{ kind: "code", lang: "ts", text: text.replace(/^\n+|\s+$/g, "") }];
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** A run of Markdown with this build's links, as inlines. */
|
|
88
|
+
line(text: string, scope: LinkScope): Inline[] {
|
|
89
|
+
const first = this.md(text, scope)[0];
|
|
90
|
+
return first !== undefined && first.kind === "paragraph" ? [...first.inlines] : [{ kind: "text", text }];
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** A page made. */
|
|
94
|
+
add(page: Page): void {
|
|
95
|
+
this.pages.push(page);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** A path of the repository, absolute, from its path from the root. */
|
|
99
|
+
abs(rel: string): string {
|
|
100
|
+
return path.join(this.root, rel);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/** Whether a path of the repository exists. */
|
|
104
|
+
exists(rel: string): boolean {
|
|
105
|
+
return fs.existsSync(this.abs(rel));
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** The text of a file of the repository. */
|
|
109
|
+
read(rel: string): string {
|
|
110
|
+
return fs.readTextFileSync(this.abs(rel));
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** The numbered items of a specification's text: its requirements and success criteria. */
|
|
115
|
+
export function itemsOf(body: string): string[] {
|
|
116
|
+
return [...body.matchAll(/^- \*\*((?:FR|SC)-\d{3}[a-z]?)\*\*/gm)].map((m) => m[1] ?? "");
|
|
117
|
+
}
|
package/src/check.ts
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* What `check` finds (commons 0011-documentation FR-018), as a tagged union with one sentence for each case, and the place each is found:
|
|
4
|
+
* a file of the repository, a page of the site or an export. The generator gathers findings while it builds; `check` prints them and
|
|
5
|
+
* fails where there is one.
|
|
6
|
+
*
|
|
7
|
+
* @module
|
|
8
|
+
*/
|
|
9
|
+
import { absurd } from "@intellectual-frontiers/core";
|
|
10
|
+
|
|
11
|
+
/** What is wrong. */
|
|
12
|
+
export type Problem =
|
|
13
|
+
| { readonly kind: "undocumented"; readonly name: string }
|
|
14
|
+
| { readonly kind: "no-about" }
|
|
15
|
+
| { readonly kind: "folder-missing"; readonly folder: string }
|
|
16
|
+
| { readonly kind: "command-missing"; readonly command: string }
|
|
17
|
+
| { readonly kind: "enforcer-missing"; readonly enforcer: string }
|
|
18
|
+
| { readonly kind: "entry-point-missing"; readonly file: string }
|
|
19
|
+
| { readonly kind: "example-missing"; readonly file: string }
|
|
20
|
+
| { readonly kind: "unknown-spec"; readonly cite: string }
|
|
21
|
+
| { readonly kind: "unknown-requirement"; readonly cite: string }
|
|
22
|
+
| { readonly kind: "unknown-link"; readonly name: string }
|
|
23
|
+
| { readonly kind: "undescribed"; readonly entity: string }
|
|
24
|
+
| { readonly kind: "import-failed"; readonly error: string }
|
|
25
|
+
| { readonly kind: "broken-link"; readonly href: string }
|
|
26
|
+
| { readonly kind: "duplicate-spec"; readonly id: string }
|
|
27
|
+
| { readonly kind: "diagram-undrawable"; readonly first: string }
|
|
28
|
+
| { readonly kind: "retired-name"; readonly name: string }
|
|
29
|
+
| { readonly kind: "forbidden-word"; readonly word: string };
|
|
30
|
+
|
|
31
|
+
/** A problem and where it is. */
|
|
32
|
+
export interface Finding {
|
|
33
|
+
/** The file, page or export it is found in. */
|
|
34
|
+
readonly where: string;
|
|
35
|
+
/** What is wrong there. */
|
|
36
|
+
readonly problem: Problem;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** The sentence a finding is printed with. */
|
|
40
|
+
export function message(p: Problem): string {
|
|
41
|
+
switch (p.kind) {
|
|
42
|
+
case "undocumented":
|
|
43
|
+
return `${p.name} is exported with no TSDoc`;
|
|
44
|
+
case "no-about":
|
|
45
|
+
return "the package has no about.ts that exports about";
|
|
46
|
+
case "folder-missing":
|
|
47
|
+
return `about names the folder ${p.folder}, which does not exist`;
|
|
48
|
+
case "command-missing":
|
|
49
|
+
return `about names the command '${p.command}', which is not a script of package.json`;
|
|
50
|
+
case "enforcer-missing":
|
|
51
|
+
return `about says a rule is enforced by ${p.enforcer}, which does not exist`;
|
|
52
|
+
case "entry-point-missing":
|
|
53
|
+
return `about names the entry point ${p.file}, which does not exist`;
|
|
54
|
+
case "example-missing":
|
|
55
|
+
return `about names the example ${p.file}, which does not exist`;
|
|
56
|
+
case "unknown-spec":
|
|
57
|
+
return `cites ${p.cite}, which is not a specification of the spec kit`;
|
|
58
|
+
case "unknown-requirement":
|
|
59
|
+
return `cites ${p.cite}, which its specification does not have`;
|
|
60
|
+
case "unknown-link":
|
|
61
|
+
return `{@link ${p.name}} names nothing exported`;
|
|
62
|
+
case "undescribed":
|
|
63
|
+
return `${p.entity} has no description`;
|
|
64
|
+
case "import-failed":
|
|
65
|
+
return `the module could not be imported: ${p.error}`;
|
|
66
|
+
case "broken-link":
|
|
67
|
+
return `links to ${p.href}, which is not a page or an anchor of the site`;
|
|
68
|
+
case "duplicate-spec":
|
|
69
|
+
return `holds ${p.id}, which a spec kit before it holds too`;
|
|
70
|
+
case "diagram-undrawable":
|
|
71
|
+
return `has a diagram that cannot be drawn (it is not a flowchart, state, sequence, class or entity-relationship diagram, or it is not valid): ${p.first}`;
|
|
72
|
+
case "retired-name":
|
|
73
|
+
return `names ${p.name}, which is retired`;
|
|
74
|
+
case "forbidden-word":
|
|
75
|
+
return `has the word "${p.word}", which a page people write does not use`;
|
|
76
|
+
default:
|
|
77
|
+
return absurd(p);
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The findings as the lines `check` prints, sorted and each once. */
|
|
82
|
+
export function report(found: readonly Finding[]): string[] {
|
|
83
|
+
return [...new Set(found.map((f) => `${f.where}: ${message(f.problem)}`))].sort();
|
|
84
|
+
}
|
package/src/cli.ts
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-003
|
|
2
|
+
/**
|
|
3
|
+
* The parts of the command line of the documentation generator, `ifc-docs` (commons 0011-documentation FR-003, FR-023): `ifc-docs build [--out DIR]`
|
|
4
|
+
* writes the site into DIR (the configuration's `out` by default, `_site` at the repository's root unless it says otherwise);
|
|
5
|
+
* `ifc-docs check` builds it into a temporary folder, prints every finding as `where: message` on standard error, writes nothing in the
|
|
6
|
+
* repository, and exits 1 where there is one. Both read the configuration given by `--config FILE`, or else the first `docs.config.ts`
|
|
7
|
+
* found from the working folder up to the repository's root. A command line or a configuration that is not valid is refused with exit
|
|
8
|
+
* status 2. It runs on Bun, the runtime of record, and on Node 26; in commons, `bun main.ts build` and `bun main.ts check` in
|
|
9
|
+
* `commons/docs/` run it from the source.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { err, ok, type Result } from "@intellectual-frontiers/core";
|
|
14
|
+
import { fs, path, proc } from "@intellectual-frontiers/system";
|
|
15
|
+
import { report } from "./check.ts";
|
|
16
|
+
import { type Config, resolveConfig } from "./config.ts";
|
|
17
|
+
import { buildSite, writeSite } from "./site.ts";
|
|
18
|
+
|
|
19
|
+
/** What the command line asks for. */
|
|
20
|
+
export type Command =
|
|
21
|
+
| { readonly kind: "build"; readonly out: string | undefined; readonly config: string | undefined }
|
|
22
|
+
| { readonly kind: "check"; readonly config: string | undefined }
|
|
23
|
+
| { readonly kind: "help" };
|
|
24
|
+
|
|
25
|
+
/** The usage, printed by `--help` and with a refusal. */
|
|
26
|
+
export const USAGE = `usage: ifc-docs build [--out DIR] [--config FILE]
|
|
27
|
+
ifc-docs check [--config FILE]
|
|
28
|
+
|
|
29
|
+
build writes the site into DIR (the configuration's out, else _site at the repository's root)
|
|
30
|
+
check builds the site into a temporary folder, prints every finding, and exits 1 where there is one
|
|
31
|
+
--config FILE the configuration (default: the first docs.config.ts from here up to the repository's root)`;
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The command a command line asks for, or why it is not one.
|
|
35
|
+
*
|
|
36
|
+
* @param args - its arguments
|
|
37
|
+
*/
|
|
38
|
+
export function parseArgs(args: readonly string[]): Result<Command, string> {
|
|
39
|
+
const [verb, ...rest] = args;
|
|
40
|
+
if (verb === undefined || verb === "--help" || verb === "-h" || verb === "help") return ok({ kind: "help" });
|
|
41
|
+
let out: string | undefined;
|
|
42
|
+
let config: string | undefined;
|
|
43
|
+
for (let i = 0; i < rest.length; i++) {
|
|
44
|
+
const a = rest[i];
|
|
45
|
+
const value = rest[i + 1];
|
|
46
|
+
if (a === "--out" || a === "--config") {
|
|
47
|
+
if (value === undefined || value.startsWith("--")) return err(`${a} needs a value`);
|
|
48
|
+
if (a === "--out") out = value;
|
|
49
|
+
else config = value;
|
|
50
|
+
i++;
|
|
51
|
+
} else return err(`unknown argument ${JSON.stringify(a)}`);
|
|
52
|
+
}
|
|
53
|
+
switch (verb) {
|
|
54
|
+
case "build":
|
|
55
|
+
return ok({ kind: "build", out, config });
|
|
56
|
+
case "check":
|
|
57
|
+
if (out !== undefined) return err("check writes nothing: --out is for build");
|
|
58
|
+
return ok({ kind: "check", config });
|
|
59
|
+
default:
|
|
60
|
+
return err(`unknown command ${JSON.stringify(verb)}: build or check`);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The configuration's file: the first `docs.config.ts` from a folder up to the repository's root (the first folder that holds `.git`).
|
|
66
|
+
*
|
|
67
|
+
* @param from - the folder to start from
|
|
68
|
+
*/
|
|
69
|
+
export function findConfig(from: string): string | undefined {
|
|
70
|
+
let dir = path.resolve(from);
|
|
71
|
+
for (;;) {
|
|
72
|
+
const file = path.join(dir, "docs.config.ts");
|
|
73
|
+
if (fs.existsSync(file)) return file;
|
|
74
|
+
const parent = path.dirname(dir);
|
|
75
|
+
if (fs.existsSync(path.join(dir, ".git")) || parent === dir) return undefined;
|
|
76
|
+
dir = parent;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* A configuration's module loaded and checked: its default export, or its export `config`.
|
|
82
|
+
*
|
|
83
|
+
* @param file - the configuration's file
|
|
84
|
+
*/
|
|
85
|
+
export async function loadConfig(file: string): Promise<Result<Config, string[]>> {
|
|
86
|
+
const abs = path.resolve(file);
|
|
87
|
+
if (!fs.existsSync(abs)) return err([`${abs} does not exist`]);
|
|
88
|
+
let mod: unknown;
|
|
89
|
+
try {
|
|
90
|
+
mod = await import(path.toFileUrl(abs).href);
|
|
91
|
+
} catch (e) {
|
|
92
|
+
return err([`${abs} could not be imported: ${e instanceof Error ? e.message : String(e)}`]);
|
|
93
|
+
}
|
|
94
|
+
const value = typeof mod === "object" && mod !== null ? ("default" in mod && mod.default !== undefined ? mod.default : "config" in mod ? mod.config : undefined) : undefined;
|
|
95
|
+
return resolveConfig(value, abs);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The generator run: the site built, written or checked; the exit status (0, 1 where `check` finds something, 2 where it is refused).
|
|
100
|
+
*
|
|
101
|
+
* @param args - the command line's arguments
|
|
102
|
+
* @param cwd - the working folder, where the search for the configuration starts
|
|
103
|
+
*/
|
|
104
|
+
export async function main(args: readonly string[], cwd: string = proc.cwd()): Promise<number> {
|
|
105
|
+
const parsed = parseArgs(args);
|
|
106
|
+
if (parsed.kind === "err") {
|
|
107
|
+
console.error(`ifc-docs: ${parsed.error}\n${USAGE}`);
|
|
108
|
+
return 2;
|
|
109
|
+
}
|
|
110
|
+
const c = parsed.value;
|
|
111
|
+
if (c.kind === "help") {
|
|
112
|
+
console.log(USAGE);
|
|
113
|
+
return 0;
|
|
114
|
+
}
|
|
115
|
+
const file = c.config === undefined ? findConfig(cwd) : path.resolve(cwd, c.config);
|
|
116
|
+
if (file === undefined) {
|
|
117
|
+
console.error(`ifc-docs: no docs.config.ts from ${cwd} up to the repository's root; give one with --config`);
|
|
118
|
+
return 2;
|
|
119
|
+
}
|
|
120
|
+
const loaded = await loadConfig(file);
|
|
121
|
+
if (loaded.kind === "err") {
|
|
122
|
+
for (const p of loaded.error) console.error(`${file}: ${p}`);
|
|
123
|
+
return 2;
|
|
124
|
+
}
|
|
125
|
+
const config = loaded.value;
|
|
126
|
+
const built = await buildSite(config);
|
|
127
|
+
const lines = report(built.found);
|
|
128
|
+
if (c.kind === "check") {
|
|
129
|
+
const tmp = await fs.makeTempDir({ prefix: "ifc-docs-" });
|
|
130
|
+
try {
|
|
131
|
+
await writeSite(config, built, tmp);
|
|
132
|
+
} finally {
|
|
133
|
+
await fs.remove(tmp, { recursive: true });
|
|
134
|
+
}
|
|
135
|
+
for (const l of lines) console.error(l);
|
|
136
|
+
console.error(`${built.pages.length} pages, ${lines.length} findings`);
|
|
137
|
+
return lines.length > 0 ? 1 : 0;
|
|
138
|
+
}
|
|
139
|
+
const out = c.out === undefined ? config.out : path.resolve(cwd, c.out);
|
|
140
|
+
await writeSite(config, built, out);
|
|
141
|
+
for (const l of lines) console.error(l);
|
|
142
|
+
console.error(`${built.pages.length} pages written to ${out}; ${lines.length} findings`);
|
|
143
|
+
return 0;
|
|
144
|
+
}
|
|
145
|
+
|