@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/config.d.ts
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The configuration a repository gives the generator (commons 0011-documentation FR-023 to FR-027, and 0001-docs FR-006), and the one place it is checked: a
|
|
3
|
+
* `docs.config.ts` exports a value of `DocsConfig` (its default export, or `config`), and `resolveConfig` checks it once into a `Config`,
|
|
4
|
+
* whose paths are absolute (the root, the output) or relative to the root (everything else), with every default filled. Nothing else reads
|
|
5
|
+
* the raw value. The `About` types are Core's (`@intellectual-frontiers/core/about`), re-exported here so that a
|
|
6
|
+
* repository's `about.ts` and its configuration are typed by this package alone.
|
|
7
|
+
*
|
|
8
|
+
* @example
|
|
9
|
+
* ```ts
|
|
10
|
+
* import type { DocsConfig } from "@intellectual-frontiers/commons/docs";
|
|
11
|
+
* export default {
|
|
12
|
+
* name: "Example",
|
|
13
|
+
* repository: "https://github.com/example/example",
|
|
14
|
+
* home: { dir: ".", about: { title: "Example", summary: "What the repository is." } },
|
|
15
|
+
* packages: [{ dir: ".", slug: "example", about: { title: "Example", summary: "Its one package.", areas: [{ title: "Core", slug: "core", entryPoints: ["src/mod.ts"] }] } }],
|
|
16
|
+
* specKits: [{ layout: "spec-kit", dir: "specs" }],
|
|
17
|
+
* citations: { prefix: "example", digits: 3 },
|
|
18
|
+
* } satisfies DocsConfig;
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* @module
|
|
22
|
+
*/
|
|
23
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
24
|
+
import type { Lens } from "./lens.js";
|
|
25
|
+
import type { About } from "@intellectual-frontiers/core/about";
|
|
26
|
+
export type { AboutSpec, AboutFolder, AboutCommand, AboutEnforcer, AboutRule, AboutPhaseState, AboutPhase, AboutExample, AboutArea, About, AboutLayer, AboutFact, } from "@intellectual-frontiers/core/about";
|
|
27
|
+
/** A package the site shows: its folder, its name in the site's addresses, and its `About`. */
|
|
28
|
+
export interface PackageConfig {
|
|
29
|
+
/** Its folder, from the repository's root (`.` for the root itself). */
|
|
30
|
+
readonly dir: string;
|
|
31
|
+
/** Its name in the site's addresses: lower-case words joined by hyphens. */
|
|
32
|
+
readonly slug: string;
|
|
33
|
+
/** The path of its `about.ts` from its folder (`about.ts` by default), or its `About` value itself (commons 0011-documentation FR-027). */
|
|
34
|
+
readonly about?: string | About;
|
|
35
|
+
}
|
|
36
|
+
/** The home page's source: a folder and its `About`. */
|
|
37
|
+
export interface HomeConfig {
|
|
38
|
+
/** Its folder, from the repository's root (`.` for the root itself). */
|
|
39
|
+
readonly dir: string;
|
|
40
|
+
/** The path of its `about.ts` from its folder (`about.ts` by default), or its `About` value itself. */
|
|
41
|
+
readonly about?: string | About;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* A spec kit and its layout (commons 0011-documentation FR-024): commons' (`registry.tsv`, `enforcement.tsv`, `specs/NNNN-slug/spec.md` under `dir`), or the plain
|
|
45
|
+
* layout of Spec Kit (`dir` holds `NNN-slug/spec.md`, each with an optional `reviewed.tsv`, and a constitution).
|
|
46
|
+
*/
|
|
47
|
+
export type SpecKitConfig = {
|
|
48
|
+
/** Commons' layout. */
|
|
49
|
+
readonly layout: "commons";
|
|
50
|
+
/** The folder that holds `registry.tsv`, from the repository's root. */
|
|
51
|
+
readonly dir: string;
|
|
52
|
+
} | {
|
|
53
|
+
/** The plain layout of Spec Kit. */
|
|
54
|
+
readonly layout: "spec-kit";
|
|
55
|
+
/** The folder that holds the specifications' folders, from the repository's root (`specs`). */
|
|
56
|
+
readonly dir: string;
|
|
57
|
+
/** The constitution, from the repository's root: `.specify/memory/constitution.md` by default, `false` for none. */
|
|
58
|
+
readonly constitution?: string | false;
|
|
59
|
+
};
|
|
60
|
+
/** A repository whose specifications may be linked: a public one whose site this generator makes (commons 0011-documentation FR-025). */
|
|
61
|
+
export interface LinkedRepository {
|
|
62
|
+
/** Its name, as a citation's qualifier (`commons`). */
|
|
63
|
+
readonly repo: string;
|
|
64
|
+
/** The address of its site, ending in `/`: a specification is `<site>specs/<id>.html`. */
|
|
65
|
+
readonly site: string;
|
|
66
|
+
/** The digits of its specifications' numbers. */
|
|
67
|
+
readonly digits: number;
|
|
68
|
+
}
|
|
69
|
+
/** How the repository's specifications are cited, and which other repositories' citations are links (commons 0011-documentation FR-025). */
|
|
70
|
+
export interface CitationsConfig {
|
|
71
|
+
/** The repository's own prefix: `commons 0011-documentation`. */
|
|
72
|
+
readonly prefix: string;
|
|
73
|
+
/** The digits of its specifications' numbers: 4 in commons, 3 in a plain Spec Kit. */
|
|
74
|
+
readonly digits: number;
|
|
75
|
+
/** The public repositories whose citations become links to their sites. */
|
|
76
|
+
readonly linked?: readonly LinkedRepository[];
|
|
77
|
+
/** The repositories whose citations are only shown as text. */
|
|
78
|
+
readonly text?: readonly string[];
|
|
79
|
+
}
|
|
80
|
+
/** The configuration a repository gives (commons 0011-documentation FR-023), as its `docs.config.ts` exports it. */
|
|
81
|
+
export interface DocsConfig {
|
|
82
|
+
/** The site's name, at the top of every page. */
|
|
83
|
+
readonly name: string;
|
|
84
|
+
/** How the site's prose names the repository (`commons`); the site's name by default. */
|
|
85
|
+
readonly subject?: string;
|
|
86
|
+
/** The repository's root, from the configuration's folder; `.` by default. */
|
|
87
|
+
readonly root?: string;
|
|
88
|
+
/** The repository's address on GitHub, for the top bar and the links to files the site does not show. */
|
|
89
|
+
readonly repository: string;
|
|
90
|
+
/** The branch the links to files name; `main` by default. */
|
|
91
|
+
readonly branch?: string;
|
|
92
|
+
/** Where the home page comes from. */
|
|
93
|
+
readonly home: HomeConfig;
|
|
94
|
+
/** The packages, in the order the site shows them. */
|
|
95
|
+
readonly packages: readonly PackageConfig[];
|
|
96
|
+
/** The spec kits; none by default. */
|
|
97
|
+
readonly specKits?: readonly SpecKitConfig[];
|
|
98
|
+
/** How specifications are cited. */
|
|
99
|
+
readonly citations: CitationsConfig;
|
|
100
|
+
/** The lenses (commons 0011-documentation FR-026); none by default. */
|
|
101
|
+
readonly lenses?: readonly Lens[];
|
|
102
|
+
/** The folder of the lint rules an `about` may name, as `<rule>.ts`, from the root; a lint rule is not checked without it. */
|
|
103
|
+
readonly lintRules?: string;
|
|
104
|
+
/** Names that must not appear on any page of the site (a retired library, a product that is gone): a page that names one is a finding. */
|
|
105
|
+
readonly retired?: readonly string[];
|
|
106
|
+
/** Words that must not appear on the pages that people write (the sections Start here, Concepts and How-to): a page that has one is a finding. */
|
|
107
|
+
readonly forbiddenInGuides?: readonly string[];
|
|
108
|
+
/** Where `build` writes the site, from the root; `_site` by default. */
|
|
109
|
+
readonly out?: string;
|
|
110
|
+
}
|
|
111
|
+
/** A package as the build reads it: its folder from the root (`""` for the root), its name, and where its `About` is. */
|
|
112
|
+
export interface PackageSource {
|
|
113
|
+
/** Its folder, from the root: `""` for the root itself. */
|
|
114
|
+
readonly dir: string;
|
|
115
|
+
/** Its name in the site's addresses. */
|
|
116
|
+
readonly slug: string;
|
|
117
|
+
/** Its `about.ts`, from the root, or its `About` value. */
|
|
118
|
+
readonly about: {
|
|
119
|
+
readonly kind: "file";
|
|
120
|
+
readonly file: string;
|
|
121
|
+
} | {
|
|
122
|
+
readonly kind: "value";
|
|
123
|
+
readonly value: About;
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
/** A spec kit as the build reads it, its folders from the root. */
|
|
127
|
+
export type SpecKitSource = {
|
|
128
|
+
readonly layout: "commons";
|
|
129
|
+
readonly dir: string;
|
|
130
|
+
} | {
|
|
131
|
+
readonly layout: "spec-kit";
|
|
132
|
+
readonly dir: string;
|
|
133
|
+
readonly constitution: string | undefined;
|
|
134
|
+
};
|
|
135
|
+
/** The configuration checked (commons 0011-documentation FR-023): every path absolute or from the root, every default filled. */
|
|
136
|
+
export interface Config {
|
|
137
|
+
/** The configuration's file, absolute. */
|
|
138
|
+
readonly file: string;
|
|
139
|
+
/** The configuration's file, from the root, for findings. */
|
|
140
|
+
readonly fileFromRoot: string;
|
|
141
|
+
/** The repository's root, absolute. */
|
|
142
|
+
readonly root: string;
|
|
143
|
+
/** The site's name. */
|
|
144
|
+
readonly name: string;
|
|
145
|
+
/** How the prose names the repository. */
|
|
146
|
+
readonly subject: string;
|
|
147
|
+
/** The repository's address on GitHub. */
|
|
148
|
+
readonly repository: string;
|
|
149
|
+
/** The branch of links to files. */
|
|
150
|
+
readonly branch: string;
|
|
151
|
+
/** The home page's source; its slug is unused. */
|
|
152
|
+
readonly home: PackageSource;
|
|
153
|
+
/** The packages. */
|
|
154
|
+
readonly packages: readonly PackageSource[];
|
|
155
|
+
/** The spec kits. */
|
|
156
|
+
readonly specKits: readonly SpecKitSource[];
|
|
157
|
+
/** How specifications are cited. */
|
|
158
|
+
readonly citations: {
|
|
159
|
+
readonly prefix: string;
|
|
160
|
+
readonly digits: number;
|
|
161
|
+
readonly linked: readonly LinkedRepository[];
|
|
162
|
+
readonly text: readonly string[];
|
|
163
|
+
};
|
|
164
|
+
/** The lenses. */
|
|
165
|
+
readonly lenses: readonly Lens[];
|
|
166
|
+
/** The folder of the lint rules, from the root. */
|
|
167
|
+
readonly lintRules: string | undefined;
|
|
168
|
+
/** Names that must not appear on any page. */
|
|
169
|
+
readonly retired: readonly string[];
|
|
170
|
+
/** Words that must not appear on the pages people write. */
|
|
171
|
+
readonly forbiddenInGuides: readonly string[];
|
|
172
|
+
/** Where `build` writes the site, absolute. */
|
|
173
|
+
readonly out: string;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* A folder from the root, as the build writes it: no `./`, no trailing `/`, and `""` for the root.
|
|
177
|
+
*
|
|
178
|
+
* @param dir - the folder as written
|
|
179
|
+
*/
|
|
180
|
+
export declare function normalDir(dir: string): string;
|
|
181
|
+
/**
|
|
182
|
+
* A path inside a folder from the root, where the folder may be the root (`""`).
|
|
183
|
+
*
|
|
184
|
+
* @param dir - the folder, from the root
|
|
185
|
+
* @param rel - the path inside it
|
|
186
|
+
*/
|
|
187
|
+
export declare function under(dir: string, rel: string): string;
|
|
188
|
+
/** Whether a value has the fields every `About` has, and areas of the right shape where it has them. */
|
|
189
|
+
export declare function isAbout(v: unknown): v is About;
|
|
190
|
+
/**
|
|
191
|
+
* A configuration checked into its resolved form, or every problem with it (commons 0011-documentation FR-023).
|
|
192
|
+
*
|
|
193
|
+
* @param value - what the configuration's module exports
|
|
194
|
+
* @param file - the configuration's file, absolute
|
|
195
|
+
*/
|
|
196
|
+
export declare function resolveConfig(value: unknown, file: string): Result<Config, string[]>;
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
// Spec: 0001-docs FR-006
|
|
2
|
+
/**
|
|
3
|
+
* The configuration a repository gives the generator (commons 0011-documentation FR-023 to FR-027, and 0001-docs FR-006), and the one place it is checked: a
|
|
4
|
+
* `docs.config.ts` exports a value of `DocsConfig` (its default export, or `config`), and `resolveConfig` checks it once into a `Config`,
|
|
5
|
+
* whose paths are absolute (the root, the output) or relative to the root (everything else), with every default filled. Nothing else reads
|
|
6
|
+
* the raw value. The `About` types are Core's (`@intellectual-frontiers/core/about`), re-exported here so that a
|
|
7
|
+
* repository's `about.ts` and its configuration are typed by this package alone.
|
|
8
|
+
*
|
|
9
|
+
* @example
|
|
10
|
+
* ```ts
|
|
11
|
+
* import type { DocsConfig } from "@intellectual-frontiers/commons/docs";
|
|
12
|
+
* export default {
|
|
13
|
+
* name: "Example",
|
|
14
|
+
* repository: "https://github.com/example/example",
|
|
15
|
+
* home: { dir: ".", about: { title: "Example", summary: "What the repository is." } },
|
|
16
|
+
* packages: [{ dir: ".", slug: "example", about: { title: "Example", summary: "Its one package.", areas: [{ title: "Core", slug: "core", entryPoints: ["src/mod.ts"] }] } }],
|
|
17
|
+
* specKits: [{ layout: "spec-kit", dir: "specs" }],
|
|
18
|
+
* citations: { prefix: "example", digits: 3 },
|
|
19
|
+
* } satisfies DocsConfig;
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* @module
|
|
23
|
+
*/
|
|
24
|
+
import { err, ok } from "@intellectual-frontiers/core";
|
|
25
|
+
import { path } from "@intellectual-frontiers/system";
|
|
26
|
+
const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
27
|
+
const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
28
|
+
/**
|
|
29
|
+
* A folder from the root, as the build writes it: no `./`, no trailing `/`, and `""` for the root.
|
|
30
|
+
*
|
|
31
|
+
* @param dir - the folder as written
|
|
32
|
+
*/
|
|
33
|
+
export function normalDir(dir) {
|
|
34
|
+
const parts = dir.split(/[\\/]+/).filter((p) => p !== "" && p !== ".");
|
|
35
|
+
return parts.join("/");
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* A path inside a folder from the root, where the folder may be the root (`""`).
|
|
39
|
+
*
|
|
40
|
+
* @param dir - the folder, from the root
|
|
41
|
+
* @param rel - the path inside it
|
|
42
|
+
*/
|
|
43
|
+
export function under(dir, rel) {
|
|
44
|
+
const r = normalDir(rel);
|
|
45
|
+
return dir === "" ? r : r === "" ? dir : `${dir}/${r}`;
|
|
46
|
+
}
|
|
47
|
+
/** Whether a value has the fields every `About` has, and areas of the right shape where it has them. */
|
|
48
|
+
export function isAbout(v) {
|
|
49
|
+
if (!isRecord(v) || typeof v["title"] !== "string" || typeof v["summary"] !== "string")
|
|
50
|
+
return false;
|
|
51
|
+
const areas = v["areas"];
|
|
52
|
+
if (areas === undefined)
|
|
53
|
+
return true;
|
|
54
|
+
return Array.isArray(areas) &&
|
|
55
|
+
areas.every((a) => isRecord(a) && typeof a["title"] === "string" && typeof a["slug"] === "string" && Array.isArray(a["entryPoints"]) &&
|
|
56
|
+
a["entryPoints"].every((e) => typeof e === "string"));
|
|
57
|
+
}
|
|
58
|
+
/** Whether a value is a lens: a name and a `read` function. */
|
|
59
|
+
function isLens(v) {
|
|
60
|
+
return isRecord(v) && typeof v["name"] === "string" && typeof v["read"] === "function";
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* A configuration checked into its resolved form, or every problem with it (commons 0011-documentation FR-023).
|
|
64
|
+
*
|
|
65
|
+
* @param value - what the configuration's module exports
|
|
66
|
+
* @param file - the configuration's file, absolute
|
|
67
|
+
*/
|
|
68
|
+
export function resolveConfig(value, file) {
|
|
69
|
+
const problems = [];
|
|
70
|
+
const bad = (what) => void problems.push(what);
|
|
71
|
+
if (!isRecord(value))
|
|
72
|
+
return err(["the configuration is not an object: export a value of DocsConfig as default, or as config"]);
|
|
73
|
+
const str = (key, where, v = value[key]) => {
|
|
74
|
+
if (typeof v === "string" && v.trim() !== "")
|
|
75
|
+
return v;
|
|
76
|
+
bad(`${where} must be a non-empty string`);
|
|
77
|
+
return undefined;
|
|
78
|
+
};
|
|
79
|
+
const optStr = (key, where, v = value[key]) => (v === undefined ? undefined : str(key, where, v));
|
|
80
|
+
const name = str("name", "name") ?? "";
|
|
81
|
+
const subject = optStr("subject", "subject") ?? name;
|
|
82
|
+
const root = path.resolve(path.dirname(file), optStr("root", "root") ?? ".");
|
|
83
|
+
const repository = str("repository", "repository") ?? "";
|
|
84
|
+
if (repository !== "" && !/^https:\/\/\S+[^/]$/.test(repository))
|
|
85
|
+
bad("repository must be an https address with no trailing /");
|
|
86
|
+
const branch = optStr("branch", "branch") ?? "main";
|
|
87
|
+
const aboutOf = (v, dir, where) => {
|
|
88
|
+
if (v === undefined || typeof v === "string")
|
|
89
|
+
return { kind: "file", file: under(dir, v ?? "about.ts") };
|
|
90
|
+
if (isAbout(v))
|
|
91
|
+
return { kind: "value", value: v };
|
|
92
|
+
bad(`${where}.about must be the path of an about.ts or an About value (a title, a summary, and areas with a title, a slug and entry points)`);
|
|
93
|
+
return { kind: "value", value: { title: "", summary: "" } };
|
|
94
|
+
};
|
|
95
|
+
const home = value["home"];
|
|
96
|
+
let homeSource = { dir: "", slug: "home", about: { kind: "value", value: { title: name, summary: "" } } };
|
|
97
|
+
if (!isRecord(home))
|
|
98
|
+
bad("home must be an object: { dir, about? }");
|
|
99
|
+
else {
|
|
100
|
+
const dir = normalDir(str("dir", "home.dir", home["dir"]) ?? ".");
|
|
101
|
+
homeSource = { dir, slug: "home", about: aboutOf(home["about"], dir, "home") };
|
|
102
|
+
}
|
|
103
|
+
const packages = [];
|
|
104
|
+
const rawPackages = value["packages"];
|
|
105
|
+
if (!Array.isArray(rawPackages))
|
|
106
|
+
bad("packages must be an array of { dir, slug, about? }");
|
|
107
|
+
else {
|
|
108
|
+
rawPackages.forEach((p, i) => {
|
|
109
|
+
const where = `packages[${i}]`;
|
|
110
|
+
if (!isRecord(p))
|
|
111
|
+
return bad(`${where} must be an object: { dir, slug, about? }`);
|
|
112
|
+
const dir = normalDir(str("dir", `${where}.dir`, p["dir"]) ?? ".");
|
|
113
|
+
const slug = str("slug", `${where}.slug`, p["slug"]);
|
|
114
|
+
if (slug === undefined)
|
|
115
|
+
return;
|
|
116
|
+
if (!SLUG.test(slug))
|
|
117
|
+
return bad(`${where}.slug ${JSON.stringify(slug)} must be lower-case words joined by hyphens`);
|
|
118
|
+
if (packages.some((q) => q.slug === slug))
|
|
119
|
+
return bad(`${where}.slug ${slug} names two packages`);
|
|
120
|
+
packages.push({ dir, slug, about: aboutOf(p["about"], dir, where) });
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
const specKits = [];
|
|
124
|
+
const rawKits = value["specKits"] ?? [];
|
|
125
|
+
if (!Array.isArray(rawKits))
|
|
126
|
+
bad("specKits must be an array");
|
|
127
|
+
else {
|
|
128
|
+
rawKits.forEach((k, i) => {
|
|
129
|
+
const where = `specKits[${i}]`;
|
|
130
|
+
if (!isRecord(k))
|
|
131
|
+
return bad(`${where} must be an object: { layout, dir }`);
|
|
132
|
+
const dir = normalDir(str("dir", `${where}.dir`, k["dir"]) ?? "");
|
|
133
|
+
const layout = k["layout"];
|
|
134
|
+
if (layout === "commons")
|
|
135
|
+
specKits.push({ layout, dir });
|
|
136
|
+
else if (layout === "spec-kit") {
|
|
137
|
+
const c = k["constitution"];
|
|
138
|
+
if (c !== undefined && c !== false && typeof c !== "string")
|
|
139
|
+
return bad(`${where}.constitution must be a path or false`);
|
|
140
|
+
specKits.push({ layout, dir, constitution: c === false ? undefined : normalDir(c ?? ".specify/memory/constitution.md") });
|
|
141
|
+
}
|
|
142
|
+
else
|
|
143
|
+
bad(`${where}.layout must be "commons" or "spec-kit"`);
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
const c = value["citations"];
|
|
147
|
+
const digitsOf = (v, where) => {
|
|
148
|
+
if (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 9)
|
|
149
|
+
return v;
|
|
150
|
+
bad(`${where} must be a whole number from 1 to 9`);
|
|
151
|
+
return 4;
|
|
152
|
+
};
|
|
153
|
+
let citations = { prefix: "", digits: 4, linked: [], text: [] };
|
|
154
|
+
if (!isRecord(c))
|
|
155
|
+
bad("citations must be an object: { prefix, digits, linked?, text? }");
|
|
156
|
+
else {
|
|
157
|
+
const prefix = (str("prefix", "citations.prefix", c["prefix"]) ?? "").toLowerCase();
|
|
158
|
+
const digits = digitsOf(c["digits"], "citations.digits");
|
|
159
|
+
const linked = [];
|
|
160
|
+
const rawLinked = c["linked"] ?? [];
|
|
161
|
+
if (!Array.isArray(rawLinked))
|
|
162
|
+
bad("citations.linked must be an array");
|
|
163
|
+
else {
|
|
164
|
+
rawLinked.forEach((l, i) => {
|
|
165
|
+
const where = `citations.linked[${i}]`;
|
|
166
|
+
if (!isRecord(l))
|
|
167
|
+
return bad(`${where} must be an object: { repo, site, digits }`);
|
|
168
|
+
const repo = str("repo", `${where}.repo`, l["repo"]);
|
|
169
|
+
const site = str("site", `${where}.site`, l["site"]);
|
|
170
|
+
const d = digitsOf(l["digits"], `${where}.digits`);
|
|
171
|
+
if (site !== undefined && !/^https:\/\/\S+\/$/.test(site))
|
|
172
|
+
return bad(`${where}.site must be an https address ending in /`);
|
|
173
|
+
if (repo !== undefined && site !== undefined)
|
|
174
|
+
linked.push({ repo: repo.toLowerCase(), site, digits: d });
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
const rawText = c["text"] ?? [];
|
|
178
|
+
const text = [];
|
|
179
|
+
if (!Array.isArray(rawText) || !rawText.every((t) => typeof t === "string"))
|
|
180
|
+
bad("citations.text must be an array of names");
|
|
181
|
+
else
|
|
182
|
+
for (const t of rawText)
|
|
183
|
+
text.push(String(t).toLowerCase());
|
|
184
|
+
for (const r of linked)
|
|
185
|
+
if (r.repo === prefix || text.includes(r.repo))
|
|
186
|
+
bad(`citations: ${r.repo} is named twice`);
|
|
187
|
+
citations = { prefix, digits, linked, text };
|
|
188
|
+
}
|
|
189
|
+
const rawLenses = value["lenses"] ?? [];
|
|
190
|
+
const lenses = [];
|
|
191
|
+
if (!Array.isArray(rawLenses))
|
|
192
|
+
bad("lenses must be an array of Lens values");
|
|
193
|
+
else
|
|
194
|
+
rawLenses.forEach((l, i) => (isLens(l) ? void lenses.push(l) : bad(`lenses[${i}] is not a Lens: { name, read }`)));
|
|
195
|
+
const names = (key) => {
|
|
196
|
+
const v = value[key];
|
|
197
|
+
if (v === undefined)
|
|
198
|
+
return [];
|
|
199
|
+
if (!Array.isArray(v) || !v.every((x) => typeof x === "string" && x !== "")) {
|
|
200
|
+
bad(`${key} must be an array of non-empty strings`);
|
|
201
|
+
return [];
|
|
202
|
+
}
|
|
203
|
+
return v.map(String);
|
|
204
|
+
};
|
|
205
|
+
const retired = names("retired");
|
|
206
|
+
const forbiddenInGuides = names("forbiddenInGuides");
|
|
207
|
+
const lint = optStr("lintRules", "lintRules");
|
|
208
|
+
const out = path.resolve(root, optStr("out", "out") ?? "_site");
|
|
209
|
+
if (problems.length > 0)
|
|
210
|
+
return err(problems);
|
|
211
|
+
return ok({
|
|
212
|
+
file,
|
|
213
|
+
fileFromRoot: path.relative(root, file).split(path.sep).join("/"),
|
|
214
|
+
root,
|
|
215
|
+
name,
|
|
216
|
+
subject,
|
|
217
|
+
repository,
|
|
218
|
+
branch,
|
|
219
|
+
home: homeSource,
|
|
220
|
+
packages,
|
|
221
|
+
specKits,
|
|
222
|
+
citations,
|
|
223
|
+
lenses,
|
|
224
|
+
lintRules: lint === undefined ? undefined : normalDir(lint),
|
|
225
|
+
retired,
|
|
226
|
+
forbiddenInGuides,
|
|
227
|
+
out,
|
|
228
|
+
});
|
|
229
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { Block, Href, Inline, Lang, Page, Section } from "../model.js";
|
|
2
|
+
/** What every page shares: the site's name, the navigation of each section, and the address of the repository. */
|
|
3
|
+
export interface Site {
|
|
4
|
+
/** The site's name, at the top of every page. */
|
|
5
|
+
readonly name: string;
|
|
6
|
+
/** The repository's address, for the link at the top. */
|
|
7
|
+
readonly repository: string;
|
|
8
|
+
/** Every page, for the navigation. */
|
|
9
|
+
readonly pages: readonly Page[];
|
|
10
|
+
/** The sections the top bar shows, where not all four: a site leaves out a section with no page (FR-009). */
|
|
11
|
+
readonly sections?: readonly Section[];
|
|
12
|
+
}
|
|
13
|
+
/** The names of the sections, in the order the top bar shows them, and the page each opens on. */
|
|
14
|
+
export declare const SECTIONS: readonly {
|
|
15
|
+
readonly section: Section;
|
|
16
|
+
readonly label: string;
|
|
17
|
+
readonly home: string;
|
|
18
|
+
}[];
|
|
19
|
+
/** Text made safe for HTML. */
|
|
20
|
+
export declare function escape(s: string): string;
|
|
21
|
+
/**
|
|
22
|
+
* The relative address from one page of the site to another.
|
|
23
|
+
*
|
|
24
|
+
* @param from - the path of the page the link is on
|
|
25
|
+
* @param to - the path of the page it goes to
|
|
26
|
+
*/
|
|
27
|
+
export declare function relative(from: string, to: string): string;
|
|
28
|
+
/** The address an `Href` is, seen from a page. */
|
|
29
|
+
export declare function hrefOf(h: Href, from: string): string;
|
|
30
|
+
/** Inlines without their links, for text that is itself inside a link (a card), where a link may not be. */
|
|
31
|
+
export declare function unlinked(xs: readonly Inline[]): Inline[];
|
|
32
|
+
/** Inlines as HTML. */
|
|
33
|
+
export declare const inlines: (xs: readonly Inline[], from: string) => string;
|
|
34
|
+
/** Code as highlighted HTML, coloured when the site is built (FR-037). */
|
|
35
|
+
export declare function highlighted(code: string, lang: Lang): string;
|
|
36
|
+
/** Whether a diagram can be drawn: its source is of a type the renderer draws (flowchart, state, sequence, class, entity-relationship). */
|
|
37
|
+
export declare function drawable(source: string): boolean;
|
|
38
|
+
/** The sources of the diagrams in blocks, at any depth. */
|
|
39
|
+
export declare function diagramSources(bs: readonly Block[]): string[];
|
|
40
|
+
/**
|
|
41
|
+
* A diagram as SVG, drawn when the site is built (FR-037): in the colours of the page, as custom properties, so that the light and the dark scheme need no second drawing; where the diagram cannot be drawn, its source in a code block.
|
|
42
|
+
*/
|
|
43
|
+
export declare function diagramSvg(source: string): string;
|
|
44
|
+
/** A block as HTML. */
|
|
45
|
+
export declare function block(b: Block, from: string): string;
|
|
46
|
+
/** Blocks as HTML; a list item's single paragraph is written without its `<p>`. */
|
|
47
|
+
export declare function blocks(bs: readonly Block[], from: string, tight?: boolean): string;
|
|
48
|
+
/** Whether blocks hold a diagram, anywhere in them. */
|
|
49
|
+
export declare function hasDiagram(bs: readonly Block[]): boolean;
|
|
50
|
+
/** The headings and entries of a page, for its table of contents. */
|
|
51
|
+
export declare function outline(bs: readonly Block[]): {
|
|
52
|
+
readonly id: string;
|
|
53
|
+
readonly text: string;
|
|
54
|
+
readonly level: number;
|
|
55
|
+
}[];
|
|
56
|
+
/** The navigation of a section: its groups, in the order of their pages, and the pages of each. */
|
|
57
|
+
export declare function navigation(pages: readonly Page[], section: Section): {
|
|
58
|
+
readonly group: string;
|
|
59
|
+
readonly pages: readonly Page[];
|
|
60
|
+
}[];
|
|
61
|
+
/**
|
|
62
|
+
* A page as a whole HTML document.
|
|
63
|
+
*
|
|
64
|
+
* @param page - the page
|
|
65
|
+
* @param site - what every page shares
|
|
66
|
+
*/
|
|
67
|
+
export declare function document(page: Page, site: Site): string;
|