@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
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-002
|
|
2
|
+
/**
|
|
3
|
+
* The program lens (commons 0011-documentation FR-030): the command-line, tool and route programs of a library built on commons headless, as pages for a person and an agent and as a Markdown twin and a JSON file for each. It is
|
|
4
|
+
* given a function that makes `LayeredModel` values (headless's own `describe`, which gives one model for each tier of a program) and knows nothing of headless: what a program says is read from the values. The models of
|
|
5
|
+
* the tiers of one program have the same element ids, so each model is read by itself and never merged with another, and every tier has its own pages.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* Pages: the programs and their tiers; for each tier its verbs (what each does, its effect, and which surfaces draw it or why one does not), the problem codes and exit statuses it can give, the plugins that contribute verbs and
|
|
9
|
+
* the findings of the builder; and for each verb its action as governance says it, its options and operands, examples, and the command, tool and route it becomes.
|
|
10
|
+
*
|
|
11
|
+
* @module
|
|
12
|
+
*/
|
|
13
|
+
import { type Badge, type Block, type Href, type Inline, type LayerElement, type LayeredModel, type Lens, type LensPages, type Page, type SiteFile, slugOf } from "../mod.ts";
|
|
14
|
+
|
|
15
|
+
/** What the lens is given. */
|
|
16
|
+
export interface ProgramLensOptions {
|
|
17
|
+
/** Its name, which the build reports it by. */
|
|
18
|
+
readonly name: string;
|
|
19
|
+
/** The group of the section the pages are in. */
|
|
20
|
+
readonly group?: string;
|
|
21
|
+
/** Makes the models of the programs: one for each tier of each program. */
|
|
22
|
+
readonly source: () => Promise<readonly LayeredModel[]> | readonly LayeredModel[];
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const t = (text: string): Inline => ({ kind: "text", text });
|
|
26
|
+
const c = (text: string): Inline => ({ kind: "code", text });
|
|
27
|
+
const para = (...inlines: Inline[]): Block => ({ kind: "paragraph", inlines });
|
|
28
|
+
const heading = (level: 2 | 3 | 4, text: string, id = slugOf(text)): Block => ({ kind: "heading", level, id, text: [t(text)] });
|
|
29
|
+
const badge = (text: string, tone: Badge["tone"] = "neutral"): Badge => ({ text, tone });
|
|
30
|
+
const slug = (s: string): string => slugOf(s.replace(/[^A-Za-z0-9]+/g, "-"));
|
|
31
|
+
const value = (v: LayerElement["properties"][string] | undefined): string => (Array.isArray(v) ? v.join(", ") : v === null || v === undefined ? "" : String(v));
|
|
32
|
+
const prop = (e: LayerElement, k: string): string => value(e.properties[k]);
|
|
33
|
+
const list = (e: LayerElement, k: string): readonly string[] => {
|
|
34
|
+
const v = e.properties[k];
|
|
35
|
+
return Array.isArray(v) ? (v as readonly string[]) : [];
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
/** The properties of an element as a table, leaving out those a page shows in another way. */
|
|
39
|
+
function propertiesTable(e: LayerElement, skip: readonly string[] = []): readonly Block[] {
|
|
40
|
+
const rows = Object.entries(e.properties).filter(([k, v]) => !skip.includes(k) && !(Array.isArray(v) && v.length === 0) && v !== null && v !== "");
|
|
41
|
+
return rows.length === 0 ? [] : [{ kind: "table", head: [[t("Property")], [t("Value")]], rows: rows.map(([k, v]) => [[c(k)], [t(value(v))]]) }];
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** The program lens. */
|
|
45
|
+
export function programLens(options: ProgramLensOptions): Lens {
|
|
46
|
+
let models: readonly LayeredModel[] = [];
|
|
47
|
+
const group = options.group ?? "Programs";
|
|
48
|
+
/** The program a model is of: the name of the model without the tier at its end (`ergonex-operator` is of `ergonex`). */
|
|
49
|
+
const programOf = (m: LayeredModel): string => m.name.replace(/-[^-]+$/, "");
|
|
50
|
+
/** The tier of a model: what follows the program in its name. */
|
|
51
|
+
const tierOf = (m: LayeredModel): string => `${m.name.slice(programOf(m).length + 1)} tier`;
|
|
52
|
+
const dir = (m: LayeredModel): string => `programs/${slug(m.name)}`;
|
|
53
|
+
const verbPage = (m: LayeredModel, v: LayerElement): string => `${dir(m)}/verb-${slug(v.name)}.html`;
|
|
54
|
+
return {
|
|
55
|
+
name: options.name,
|
|
56
|
+
read: async (): Promise<LensPages> => {
|
|
57
|
+
models = await options.source();
|
|
58
|
+
return (build, after) => {
|
|
59
|
+
const add = (p: Omit<Page, "section">): void => build.add({ ...p, section: "programs" });
|
|
60
|
+
add({
|
|
61
|
+
path: "programs/index.html",
|
|
62
|
+
title: "Programs",
|
|
63
|
+
description: "The command-line programs, tools and routes of the libraries, documented from their own descriptions, one page set for each tier.",
|
|
64
|
+
group,
|
|
65
|
+
order: after,
|
|
66
|
+
blocks: [
|
|
67
|
+
para(t("Each program is described once, in governance, as actions that say what they do and may do, and is drawn as a command, a tool and a route. A program has one description for each tier of its audience: a verb a tier cannot see is listed in that tier with the reason, and is not drawn.")),
|
|
68
|
+
heading(2, "Programs"),
|
|
69
|
+
{ kind: "cards", cards: models.map((m) => ({ title: m.title, href: { kind: "page", path: `${dir(m)}/index.html` } as Href, text: [t(m.summary)], badges: [badge(`${m.elements.filter((e) => e.kind === "verb").length} verbs`, "info"), ...(m.findings.length > 0 ? [badge(`${m.findings.length} findings`, "warn")] : [])] })) },
|
|
70
|
+
],
|
|
71
|
+
});
|
|
72
|
+
let order = after + 1;
|
|
73
|
+
for (const m of models) {
|
|
74
|
+
const byId = new Map(m.elements.map((e) => [e.id, e]));
|
|
75
|
+
const verbs = m.elements.filter((e) => e.kind === "verb");
|
|
76
|
+
const surfaces = (v: LayerElement): readonly LayerElement[] => m.trace.filter((x) => x.from === v.id && x.how === "projects to").map((x) => byId.get(x.to)).filter((e): e is LayerElement => e !== undefined);
|
|
77
|
+
const kindsOfVerb = (v: LayerElement): string[] => [...new Set(surfaces(v).map((s) => s.kind.replace("-command", "").replace("-tool", "").replace("-route", "")))];
|
|
78
|
+
const codes = m.elements.filter((e) => e.kind === "problem-code");
|
|
79
|
+
const outcomes = m.elements.filter((e) => e.kind === "outcome");
|
|
80
|
+
const plugins = m.elements.filter((e) => e.kind === "plugin");
|
|
81
|
+
add({
|
|
82
|
+
path: `${dir(m)}/index.html`,
|
|
83
|
+
title: m.title,
|
|
84
|
+
description: m.summary,
|
|
85
|
+
group: programOf(m),
|
|
86
|
+
order: order++,
|
|
87
|
+
navTitle: tierOf(m),
|
|
88
|
+
blocks: [
|
|
89
|
+
para(t(m.summary)),
|
|
90
|
+
heading(2, "Verbs"),
|
|
91
|
+
{ kind: "table", head: [[t("Verb")], [t("What it does")], [t("Effect")], [t("Drawn as")], [t("Not drawn")]], rows: verbs.map((v) => [[{ kind: "link", href: { kind: "page", path: verbPage(m, v) }, children: [c(v.name)] }], [t(v.definition)], [t(prop(v, "effect"))], [t(kindsOfVerb(v).join(", ") || "none")], [t(list(v, "notProjected").join("; "))]]) },
|
|
92
|
+
...(plugins.length === 0 ? [] : [heading(2, "Plugins"), { kind: "table", head: [[t("Plugin")], [t("Contributes")]], rows: plugins.map((p) => [[c(p.name)], [t(p.definition)]]) } as Block]),
|
|
93
|
+
...(codes.length === 0 ? [] : [heading(2, "Problem codes"), { kind: "table", head: [[t("Code")], [t("Meaning")]], rows: codes.map((e) => [[c(e.name)], [t(e.definition)]]) } as Block]),
|
|
94
|
+
...(outcomes.length === 0 ? [] : [heading(2, "Exit statuses"), { kind: "table", head: [[t("Outcome")], [t("Meaning")]], rows: outcomes.map((e) => [[c(e.name)], [t(e.definition)]]) } as Block]),
|
|
95
|
+
...(m.findings.length === 0 ? [] : [heading(2, "Findings"), { kind: "list", ordered: false, items: m.findings.map((f) => [para(c(f.element), t(` ${f.rule}: ${f.message}`))]) } as Block]),
|
|
96
|
+
],
|
|
97
|
+
});
|
|
98
|
+
for (const v of verbs) {
|
|
99
|
+
const options_ = m.elements.filter((e) => e.kind === "option" && e.parent === v.id);
|
|
100
|
+
const operands = m.elements.filter((e) => e.kind === "operand" && e.parent === v.id);
|
|
101
|
+
const action = m.trace.filter((x) => x.to === v.id && x.how !== undefined).map((x) => byId.get(x.from)).find((e) => e?.kind === "action");
|
|
102
|
+
const drawn = surfaces(v);
|
|
103
|
+
add({
|
|
104
|
+
path: verbPage(m, v),
|
|
105
|
+
title: v.name,
|
|
106
|
+
description: v.definition,
|
|
107
|
+
group: programOf(m),
|
|
108
|
+
order: order++,
|
|
109
|
+
parent: `${dir(m)}/index.html`,
|
|
110
|
+
navKind: "Verbs",
|
|
111
|
+
navTitle: v.name,
|
|
112
|
+
badges: [badge("verb", "info"), ...(prop(v, "effect") === "" ? [] : [badge(prop(v, "effect"))])],
|
|
113
|
+
blocks: [
|
|
114
|
+
para(t(v.definition)),
|
|
115
|
+
para(t("Program "), { kind: "link", href: { kind: "page", path: `${dir(m)}/index.html` }, children: [c(m.name)] }, t(`. Origin `), c(prop(v, "origin")), t(".")),
|
|
116
|
+
heading(2, "Governance: the action"),
|
|
117
|
+
para(t("What the verb is and may do, as governance says it. Each annotation is expressed by the surfaces or says why it is not.")),
|
|
118
|
+
...propertiesTable(action ?? v, ["path", "origin", "examples", "offered", "projections", "notProjected"]),
|
|
119
|
+
...(operands.length === 0 ? [] : [heading(2, "Operands"), { kind: "table", head: [[t("Operand")], [t("Meaning")]], rows: operands.map((o) => [[c(o.name)], [t(o.definition)]]) } as Block]),
|
|
120
|
+
...(options_.length === 0 ? [] : [heading(2, "Options"), { kind: "table", head: [[t("Option")], [t("Meaning")], [t("Properties")]], rows: options_.map((o) => [[c(o.name)], [t(o.definition)], [t(Object.entries(o.properties).filter(([, x]) => x !== null && x !== "" && !(Array.isArray(x) && x.length === 0)).map(([k, x]) => `${k}=${value(x)}`).join(", "))]]) } as Block]),
|
|
121
|
+
...(list(v, "examples").length === 0 ? [] : [heading(2, "Examples"), { kind: "code", lang: "sh", text: list(v, "examples").join("\n") } as Block]),
|
|
122
|
+
heading(2, "Physical: what it is drawn as"),
|
|
123
|
+
...(drawn.length === 0 ? [para(t("Not drawn by any surface for this tier."))] : drawn.flatMap((s): Block[] => [heading(3, s.name, slug(`${s.kind}-${s.name}`)), para(t(`${s.kind}. `), t(s.definition)), ...propertiesTable(s)])),
|
|
124
|
+
...(list(v, "notProjected").length === 0 ? [] : [heading(3, "Not drawn"), { kind: "list", ordered: false, items: list(v, "notProjected").map((x) => [para(t(x))]) } as Block]),
|
|
125
|
+
],
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return order;
|
|
130
|
+
};
|
|
131
|
+
},
|
|
132
|
+
files: (): readonly SiteFile[] => [
|
|
133
|
+
...models.map((m): SiteFile => ({ path: `programs/${slug(m.name)}.json`, text: `${JSON.stringify(m, null, 2)}\n`, what: `the ${m.title} program in layers (governance, logical, surfaces) with its trace and findings` })),
|
|
134
|
+
{ path: "programs/index.json", text: `${JSON.stringify(models.map((m) => ({ name: m.name, library: m.library, title: m.title, summary: m.summary, file: `programs/${slug(m.name)}.json`, elements: m.elements.length, findings: m.findings.length })), null, 2)}\n`, what: "the list of programs with the file of each" },
|
|
135
|
+
],
|
|
136
|
+
};
|
|
137
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-002
|
|
2
|
+
/**
|
|
3
|
+
* The releases lens (commons 0011-documentation FR-035): the record of the next release, read from the file the release command writes (`commons/generated/release.auto.json`): each library it publishes, at which version, under which tag
|
|
4
|
+
* and in which order, with a link to the library's page. The lens knows nothing of how the record is made.
|
|
5
|
+
*
|
|
6
|
+
* @module
|
|
7
|
+
*/
|
|
8
|
+
import { fs, path } from "@intellectual-frontiers/system";
|
|
9
|
+
import type { Block, Inline, Lens, LensPages } from "../mod.ts";
|
|
10
|
+
|
|
11
|
+
/** What the releases lens is given. */
|
|
12
|
+
export interface ReleasesOptions {
|
|
13
|
+
/** Its name, which the build reports it by. */
|
|
14
|
+
readonly name: string;
|
|
15
|
+
/** The record, from the repository's root. */
|
|
16
|
+
readonly file: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** One row of the record. */
|
|
20
|
+
interface Row {
|
|
21
|
+
readonly slug: string;
|
|
22
|
+
readonly version: string;
|
|
23
|
+
readonly tag: string;
|
|
24
|
+
readonly publish: boolean;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** The releases lens. */
|
|
28
|
+
export function releasesLens(options: ReleasesOptions): Lens {
|
|
29
|
+
return {
|
|
30
|
+
name: options.name,
|
|
31
|
+
read: async (b): Promise<LensPages> => {
|
|
32
|
+
let rows: Row[] = [];
|
|
33
|
+
try {
|
|
34
|
+
const record = JSON.parse(await fs.readTextFile(path.join(b.root, options.file))) as { readonly releases?: readonly Row[] };
|
|
35
|
+
rows = [...(record.releases ?? [])];
|
|
36
|
+
} catch {
|
|
37
|
+
b.found.push({ where: options.file, problem: { kind: "undescribed", entity: `the release record ${options.file}, which the releases lens is told of, cannot be read` } });
|
|
38
|
+
}
|
|
39
|
+
return (build, after) => {
|
|
40
|
+
const text = (t: string): Inline => ({ kind: "text", text: t });
|
|
41
|
+
const blocks: Block[] = [
|
|
42
|
+
{ kind: "paragraph", inlines: [text("What the next release publishes and tags, in the order of the imports: a library comes after the libraries it imports. The record is written by the release command and read by the release workflow.")] },
|
|
43
|
+
{
|
|
44
|
+
kind: "table",
|
|
45
|
+
head: ["Order", "Library", "Version", "Tag", "Published"].map((h) => [text(h)]),
|
|
46
|
+
rows: rows.map((r, i) => [[text(String(i + 1))], [{ kind: "link", href: { kind: "page", path: `overview/${r.slug}.html` }, children: [{ kind: "code", text: r.slug }] }], [{ kind: "code", text: r.version }], [{ kind: "code", text: r.tag }], [text(r.publish ? "yes" : "tag only")]]),
|
|
47
|
+
},
|
|
48
|
+
];
|
|
49
|
+
build.add({ path: "overview/releases.html", title: "Releases", description: "What the next release publishes and tags, library by library.", section: "overview", group: "Libraries", order: 8, blocks });
|
|
50
|
+
return after;
|
|
51
|
+
};
|
|
52
|
+
},
|
|
53
|
+
};
|
|
54
|
+
}
|
package/src/lens.ts
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* What a lens is (commons 0011-documentation FR-013, FR-026): a value a configuration passes, which knows one library. Its `read` is given
|
|
4
|
+
* the build, the areas and their API once every API page is registered; it recognises the library's exports by the type the checker gives
|
|
5
|
+
* each, imports their module, registers the page each entity is shown on (so that an API page can link to it), and returns what makes its
|
|
6
|
+
* pages once every other page is made. The package ships no lens and depends on no library it shows.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
import type { Build } from "./build.ts";
|
|
11
|
+
import type { AreaApi } from "./extract/api.ts";
|
|
12
|
+
import type { Area } from "./sources.ts";
|
|
13
|
+
|
|
14
|
+
/** What makes a lens's pages: given the order its first group of pages takes in the Models section, it returns the order after its last. */
|
|
15
|
+
export type LensPages = (b: Build, after: number) => number;
|
|
16
|
+
|
|
17
|
+
/** A file a lens adds to the site beside its pages: the JSON of a model. */
|
|
18
|
+
export interface SiteFile {
|
|
19
|
+
/** Where it is, from the site's root. */
|
|
20
|
+
readonly path: string;
|
|
21
|
+
readonly text: string;
|
|
22
|
+
/** What it is, in a few words, for the index of the site that a program reads (`llms.txt`). */
|
|
23
|
+
readonly what: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** A lens: its name, and what reads its library's values and makes their pages. */
|
|
27
|
+
export interface Lens {
|
|
28
|
+
/** Its name, as `data`. */
|
|
29
|
+
readonly name: string;
|
|
30
|
+
/** Reads the values of the areas whose exports are its library's, and returns what makes their pages. */
|
|
31
|
+
readonly read: (b: Build, areas: readonly Area[], apis: readonly AreaApi[]) => Promise<LensPages>;
|
|
32
|
+
/** The files it adds to the site once its pages are made (commons 0011-documentation FR-028). */
|
|
33
|
+
readonly files?: (b: Build) => readonly SiteFile[];
|
|
34
|
+
}
|
package/src/links.ts
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-001
|
|
2
|
+
/**
|
|
3
|
+
* Where the words of documentation link to (commons 0011-documentation FR-011, FR-012, FR-025): a citation of a specification of the
|
|
4
|
+
* repository (its prefix and an id, as `commons 0009-example`; a bare id of its own form, as `0009-example` in commons or
|
|
5
|
+
* `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
|
|
6
|
+
* 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
|
|
7
|
+
* specification) becomes a link to the specification's page and the requirement's anchor; a citation of a repository the configuration
|
|
8
|
+
* lists as linked goes to that repository's site; one of any other repository (`erga 009-machine-bootstrap`) stays text; a Markdown link
|
|
9
|
+
* 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
|
|
10
|
+
* names. What does not resolve is a finding.
|
|
11
|
+
*
|
|
12
|
+
* @module
|
|
13
|
+
*/
|
|
14
|
+
import type { Finding } from "./check.ts";
|
|
15
|
+
import type { LinkedRepository } from "./config.ts";
|
|
16
|
+
import { type InlineContext, plainContext } from "./markdown.ts";
|
|
17
|
+
import type { Href, Inline } from "./model.ts";
|
|
18
|
+
|
|
19
|
+
/** How specifications are cited: the repository's own prefix and digits, the repositories linked, and those shown as text. */
|
|
20
|
+
export interface CitationRules {
|
|
21
|
+
/** The repository's own prefix, in lower case. */
|
|
22
|
+
readonly prefix: string;
|
|
23
|
+
/** The digits of its specifications' numbers. */
|
|
24
|
+
readonly digits: number;
|
|
25
|
+
/** The repositories whose citations go to their sites. */
|
|
26
|
+
readonly linked: readonly LinkedRepository[];
|
|
27
|
+
/** The repositories whose citations are text, in lower case. */
|
|
28
|
+
readonly text: readonly string[];
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** What the links of a page can reach: the specifications and their requirements, the pages of source files, and the exports. */
|
|
32
|
+
export interface LinkIndex {
|
|
33
|
+
/** Each specification of the repository, by its folder's name, with its requirements and criteria. */
|
|
34
|
+
readonly specs: ReadonlyMap<string, ReadonlySet<string>>;
|
|
35
|
+
/** How specifications are cited. */
|
|
36
|
+
readonly citations: CitationRules;
|
|
37
|
+
/** The page that shows each file of the repository, by its path from the root. */
|
|
38
|
+
readonly files: ReadonlyMap<string, string>;
|
|
39
|
+
/** Each export's page and anchor, by area and name. */
|
|
40
|
+
readonly exports: ReadonlyMap<string, ReadonlyMap<string, { readonly path: string; readonly anchor: string }>>;
|
|
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
|
+
|
|
47
|
+
/** Where a page's words are: the page, the file they come from, the area and the specification a bare requirement names. */
|
|
48
|
+
export interface LinkScope {
|
|
49
|
+
/** The page the links are on. */
|
|
50
|
+
readonly page: string;
|
|
51
|
+
/** The file of the repository the words are in, from the root, for relative links and for findings. */
|
|
52
|
+
readonly file: string;
|
|
53
|
+
/** The area whose exports `{@link name}` names first. */
|
|
54
|
+
readonly area?: string;
|
|
55
|
+
/** The specification a bare `FR-nnn` is a requirement of. */
|
|
56
|
+
readonly spec?: string;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** The page of a specification. */
|
|
60
|
+
export const specPage = (id: string): string => `specs/${id}.html`;
|
|
61
|
+
|
|
62
|
+
// A qualifier and an id (`commons 0009-example`), a requirement (`FR-026`), or a number alone after `spec` or before a requirement
|
|
63
|
+
// (`spec 004`, `038 FR-014`), which names the specification with that number.
|
|
64
|
+
const CITE =
|
|
65
|
+
/(?:(?<![\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;
|
|
66
|
+
|
|
67
|
+
/** A qualifier as the configuration names repositories: lower case, with a possessive `'s` or `'` taken off. */
|
|
68
|
+
export const qualifierOf = (q: string): string => q.toLowerCase().replace(/'s?$/, "");
|
|
69
|
+
|
|
70
|
+
/** Whether an id has a number of so many digits. */
|
|
71
|
+
const hasDigits = (id: string, digits: number): boolean => new RegExp(`^\\d{${digits}}-`).test(id);
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The citations of a run of text, made links.
|
|
75
|
+
*
|
|
76
|
+
* @param text - the run
|
|
77
|
+
* @param index - what links can reach
|
|
78
|
+
* @param scope - where the run is
|
|
79
|
+
* @param found - where findings go
|
|
80
|
+
*/
|
|
81
|
+
export function cite(text: string, index: LinkIndex, scope: LinkScope, found: Finding[]): Inline[] {
|
|
82
|
+
const out: Inline[] = [];
|
|
83
|
+
let last = 0;
|
|
84
|
+
const rules = index.citations;
|
|
85
|
+
let current = scope.spec;
|
|
86
|
+
let other = false;
|
|
87
|
+
let away: { readonly site: string; readonly id: string } | undefined;
|
|
88
|
+
const plainText = (t: string): void => {
|
|
89
|
+
if (t === "") return;
|
|
90
|
+
const prev = out[out.length - 1];
|
|
91
|
+
if (prev !== undefined && prev.kind === "text") out[out.length - 1] = { kind: "text", text: prev.text + t };
|
|
92
|
+
else out.push({ kind: "text", text: t });
|
|
93
|
+
};
|
|
94
|
+
for (const m of text.matchAll(CITE)) {
|
|
95
|
+
const at = m.index;
|
|
96
|
+
const [whole, qualifier, id, req, afterSpec, beforeReq] = m;
|
|
97
|
+
const number = afterSpec ?? beforeReq;
|
|
98
|
+
if (number !== undefined) {
|
|
99
|
+
const numbered = number.length === rules.digits ? [...index.specs.keys()].find((k) => k.startsWith(`${number}-`)) : undefined;
|
|
100
|
+
away = undefined;
|
|
101
|
+
other = numbered === undefined;
|
|
102
|
+
if (numbered === undefined) continue;
|
|
103
|
+
current = numbered;
|
|
104
|
+
index.cited?.(numbered, undefined, scope.page);
|
|
105
|
+
plainText(text.slice(last, at));
|
|
106
|
+
out.push({ kind: "link", href: { kind: "page", path: specPage(numbered) }, children: [{ kind: "text", text: whole }] });
|
|
107
|
+
last = at + whole.length;
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
110
|
+
if (id !== undefined) {
|
|
111
|
+
const q = qualifier?.toLowerCase();
|
|
112
|
+
const named = q === undefined ? undefined : qualifierOf(q);
|
|
113
|
+
const linked = rules.linked.find((r) => r.repo === named);
|
|
114
|
+
away = undefined;
|
|
115
|
+
if (linked !== undefined && hasDigits(id, linked.digits)) {
|
|
116
|
+
other = false;
|
|
117
|
+
away = { site: linked.site, id };
|
|
118
|
+
plainText(text.slice(last, at));
|
|
119
|
+
out.push({ kind: "link", href: { kind: "external", url: `${linked.site}${specPage(id)}` }, children: [{ kind: "text", text: whole }] });
|
|
120
|
+
last = at + whole.length;
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
if ((named !== undefined && (rules.text.includes(named) || linked !== undefined)) || !hasDigits(id, rules.digits)) {
|
|
124
|
+
other = true;
|
|
125
|
+
continue;
|
|
126
|
+
}
|
|
127
|
+
other = false;
|
|
128
|
+
const start = q === rules.prefix ? at : at + whole.length - id.length;
|
|
129
|
+
plainText(text.slice(last, start));
|
|
130
|
+
if (index.specs.has(id)) {
|
|
131
|
+
current = id;
|
|
132
|
+
index.cited?.(id, undefined, scope.page);
|
|
133
|
+
out.push({ kind: "link", href: { kind: "page", path: specPage(id) }, children: [{ kind: "text", text: text.slice(start, at + whole.length) }] });
|
|
134
|
+
} else {
|
|
135
|
+
found.push({ where: scope.file, problem: { kind: "unknown-spec", cite: id } });
|
|
136
|
+
plainText(text.slice(start, at + whole.length));
|
|
137
|
+
}
|
|
138
|
+
last = at + whole.length;
|
|
139
|
+
continue;
|
|
140
|
+
}
|
|
141
|
+
if (req === undefined || other) continue;
|
|
142
|
+
if (away !== undefined) {
|
|
143
|
+
plainText(text.slice(last, at));
|
|
144
|
+
out.push({ kind: "link", href: { kind: "external", url: `${away.site}${specPage(away.id)}#${req.toLowerCase()}` }, children: [{ kind: "text", text: req }] });
|
|
145
|
+
last = at + whole.length;
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
if (current === undefined) continue;
|
|
149
|
+
plainText(text.slice(last, at));
|
|
150
|
+
const has = index.specs.get(current)?.has(req) ?? false;
|
|
151
|
+
if (has) index.cited?.(current, req, scope.page);
|
|
152
|
+
if (has) out.push({ kind: "link", href: { kind: "page", path: specPage(current), anchor: req.toLowerCase() }, children: [{ kind: "text", text: req }] });
|
|
153
|
+
else {
|
|
154
|
+
found.push({ where: scope.file, problem: { kind: "unknown-requirement", cite: `${current} ${req}` } });
|
|
155
|
+
plainText(req);
|
|
156
|
+
}
|
|
157
|
+
last = at + whole.length;
|
|
158
|
+
}
|
|
159
|
+
plainText(text.slice(last));
|
|
160
|
+
return out;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/** A path of the checkout, from a link's destination written in a file. */
|
|
164
|
+
function resolveFrom(file: string, dest: string): string {
|
|
165
|
+
const parts = file.split("/").slice(0, -1);
|
|
166
|
+
for (const seg of dest.split("/")) {
|
|
167
|
+
if (seg === "..") parts.pop();
|
|
168
|
+
else if (seg !== "." && seg !== "") parts.push(seg);
|
|
169
|
+
}
|
|
170
|
+
return parts.join("/");
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Where a Markdown link's destination goes, from the file it is written in.
|
|
175
|
+
*
|
|
176
|
+
* @param dest - the destination as written
|
|
177
|
+
* @param index - what links can reach
|
|
178
|
+
* @param scope - where the link is
|
|
179
|
+
*/
|
|
180
|
+
export function hrefFor(dest: string, index: LinkIndex, scope: LinkScope): Href {
|
|
181
|
+
if (/^[a-z][a-z0-9+.-]*:/i.test(dest)) return { kind: "external", url: dest };
|
|
182
|
+
if (dest.startsWith("#")) return { kind: "page", path: scope.page, anchor: dest.slice(1) };
|
|
183
|
+
const [p = "", anchor] = dest.split("#");
|
|
184
|
+
const target = resolveFrom(scope.file, p);
|
|
185
|
+
const page = index.files.get(target) ?? index.files.get(target.replace(/\/$/, ""));
|
|
186
|
+
if (page !== undefined) return { kind: "page", path: page, ...(anchor === undefined ? {} : { anchor }) };
|
|
187
|
+
return { kind: "external", url: index.blob(target) };
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* 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
|
|
192
|
+
* export of that name in any area.
|
|
193
|
+
*
|
|
194
|
+
* @param name - what it names: `table`, or `data!table`
|
|
195
|
+
* @param label - the text to show, where one is given
|
|
196
|
+
* @param index - what links can reach
|
|
197
|
+
* @param scope - where the link is
|
|
198
|
+
* @param found - where findings go
|
|
199
|
+
*/
|
|
200
|
+
export function linkFor(name: string, label: string | undefined, index: LinkIndex, scope: LinkScope, found: Finding[]): Inline[] {
|
|
201
|
+
const bang = name.indexOf("!");
|
|
202
|
+
const area = bang < 0 ? scope.area : name.slice(0, bang);
|
|
203
|
+
const sym = bang < 0 ? name : name.slice(bang + 1);
|
|
204
|
+
const base = sym.split(".")[0] ?? "";
|
|
205
|
+
const own = area === undefined ? undefined : index.exports.get(area)?.get(base);
|
|
206
|
+
const elsewhere = bang >= 0 || own !== undefined ? [] : [...index.exports.values()].flatMap((m) => {
|
|
207
|
+
const t = m.get(base);
|
|
208
|
+
return t === undefined ? [] : [t];
|
|
209
|
+
});
|
|
210
|
+
const unique = new Set(elsewhere.map((t) => `${t.path}#${t.anchor}`)).size === 1 ? elsewhere[0] : undefined;
|
|
211
|
+
const target = own ?? unique;
|
|
212
|
+
const shown: Inline = { kind: "code", text: label ?? sym };
|
|
213
|
+
if (target === undefined) {
|
|
214
|
+
found.push({ where: scope.file, problem: { kind: "unknown-link", name } });
|
|
215
|
+
return [shown];
|
|
216
|
+
}
|
|
217
|
+
return [{ kind: "link", href: { kind: "page", path: target.path, anchor: target.anchor }, children: [shown] }];
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* The context `markdown.ts` reads a page's words with: citations, file links and `{@link}` resolved through the index.
|
|
222
|
+
*
|
|
223
|
+
* @param index - what links can reach
|
|
224
|
+
* @param scope - where the words are
|
|
225
|
+
* @param found - where findings go
|
|
226
|
+
*/
|
|
227
|
+
export function contextFor(index: LinkIndex, scope: LinkScope, found: Finding[]): InlineContext {
|
|
228
|
+
return {
|
|
229
|
+
...plainContext,
|
|
230
|
+
href: (dest) => hrefFor(dest, index, scope),
|
|
231
|
+
link: (name, label) => linkFor(name, label, index, scope, found),
|
|
232
|
+
cite: (t) => cite(t, index, scope, found),
|
|
233
|
+
};
|
|
234
|
+
}
|
package/src/main.ts
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.ts";
|
|
11
|
+
|
|
12
|
+
if (import.meta.main) proc.exit(await main(proc.args));
|