@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/src/config.ts
ADDED
|
@@ -0,0 +1,370 @@
|
|
|
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, type Result } from "@intellectual-frontiers/core";
|
|
25
|
+
import { path } from "@intellectual-frontiers/system";
|
|
26
|
+
import type { Lens } from "./lens.ts";
|
|
27
|
+
|
|
28
|
+
import type { About } from "@intellectual-frontiers/core/about";
|
|
29
|
+
|
|
30
|
+
export type {
|
|
31
|
+
AboutSpec,
|
|
32
|
+
AboutFolder,
|
|
33
|
+
AboutCommand,
|
|
34
|
+
AboutEnforcer,
|
|
35
|
+
AboutRule,
|
|
36
|
+
AboutPhaseState,
|
|
37
|
+
AboutPhase,
|
|
38
|
+
AboutExample,
|
|
39
|
+
AboutArea,
|
|
40
|
+
About,
|
|
41
|
+
AboutLayer,
|
|
42
|
+
AboutFact,
|
|
43
|
+
} from "@intellectual-frontiers/core/about";
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
/** A package the site shows: its folder, its name in the site's addresses, and its `About`. */
|
|
47
|
+
export interface PackageConfig {
|
|
48
|
+
/** Its folder, from the repository's root (`.` for the root itself). */
|
|
49
|
+
readonly dir: string;
|
|
50
|
+
/** Its name in the site's addresses: lower-case words joined by hyphens. */
|
|
51
|
+
readonly slug: string;
|
|
52
|
+
/** The path of its `about.ts` from its folder (`about.ts` by default), or its `About` value itself (commons 0011-documentation FR-027). */
|
|
53
|
+
readonly about?: string | About;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** The home page's source: a folder and its `About`. */
|
|
57
|
+
export interface HomeConfig {
|
|
58
|
+
/** Its folder, from the repository's root (`.` for the root itself). */
|
|
59
|
+
readonly dir: string;
|
|
60
|
+
/** The path of its `about.ts` from its folder (`about.ts` by default), or its `About` value itself. */
|
|
61
|
+
readonly about?: string | About;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* 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
|
|
66
|
+
* layout of Spec Kit (`dir` holds `NNN-slug/spec.md`, each with an optional `reviewed.tsv`, and a constitution).
|
|
67
|
+
*/
|
|
68
|
+
export type SpecKitConfig =
|
|
69
|
+
| {
|
|
70
|
+
/** Commons' layout. */
|
|
71
|
+
readonly layout: "commons";
|
|
72
|
+
/** The folder that holds `registry.tsv`, from the repository's root. */
|
|
73
|
+
readonly dir: string;
|
|
74
|
+
}
|
|
75
|
+
| {
|
|
76
|
+
/** The plain layout of Spec Kit. */
|
|
77
|
+
readonly layout: "spec-kit";
|
|
78
|
+
/** The folder that holds the specifications' folders, from the repository's root (`specs`). */
|
|
79
|
+
readonly dir: string;
|
|
80
|
+
/** The constitution, from the repository's root: `.specify/memory/constitution.md` by default, `false` for none. */
|
|
81
|
+
readonly constitution?: string | false;
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
/** A repository whose specifications may be linked: a public one whose site this generator makes (commons 0011-documentation FR-025). */
|
|
85
|
+
export interface LinkedRepository {
|
|
86
|
+
/** Its name, as a citation's qualifier (`commons`). */
|
|
87
|
+
readonly repo: string;
|
|
88
|
+
/** The address of its site, ending in `/`: a specification is `<site>specs/<id>.html`. */
|
|
89
|
+
readonly site: string;
|
|
90
|
+
/** The digits of its specifications' numbers. */
|
|
91
|
+
readonly digits: number;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** How the repository's specifications are cited, and which other repositories' citations are links (commons 0011-documentation FR-025). */
|
|
95
|
+
export interface CitationsConfig {
|
|
96
|
+
/** The repository's own prefix: `commons 0011-documentation`. */
|
|
97
|
+
readonly prefix: string;
|
|
98
|
+
/** The digits of its specifications' numbers: 4 in commons, 3 in a plain Spec Kit. */
|
|
99
|
+
readonly digits: number;
|
|
100
|
+
/** The public repositories whose citations become links to their sites. */
|
|
101
|
+
readonly linked?: readonly LinkedRepository[];
|
|
102
|
+
/** The repositories whose citations are only shown as text. */
|
|
103
|
+
readonly text?: readonly string[];
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** The configuration a repository gives (commons 0011-documentation FR-023), as its `docs.config.ts` exports it. */
|
|
107
|
+
export interface DocsConfig {
|
|
108
|
+
/** The site's name, at the top of every page. */
|
|
109
|
+
readonly name: string;
|
|
110
|
+
/** How the site's prose names the repository (`commons`); the site's name by default. */
|
|
111
|
+
readonly subject?: string;
|
|
112
|
+
/** The repository's root, from the configuration's folder; `.` by default. */
|
|
113
|
+
readonly root?: string;
|
|
114
|
+
/** The repository's address on GitHub, for the top bar and the links to files the site does not show. */
|
|
115
|
+
readonly repository: string;
|
|
116
|
+
/** The branch the links to files name; `main` by default. */
|
|
117
|
+
readonly branch?: string;
|
|
118
|
+
/** Where the home page comes from. */
|
|
119
|
+
readonly home: HomeConfig;
|
|
120
|
+
/** The packages, in the order the site shows them. */
|
|
121
|
+
readonly packages: readonly PackageConfig[];
|
|
122
|
+
/** The spec kits; none by default. */
|
|
123
|
+
readonly specKits?: readonly SpecKitConfig[];
|
|
124
|
+
/** How specifications are cited. */
|
|
125
|
+
readonly citations: CitationsConfig;
|
|
126
|
+
/** The lenses (commons 0011-documentation FR-026); none by default. */
|
|
127
|
+
readonly lenses?: readonly Lens[];
|
|
128
|
+
/** The folder of the lint rules an `about` may name, as `<rule>.ts`, from the root; a lint rule is not checked without it. */
|
|
129
|
+
readonly lintRules?: string;
|
|
130
|
+
/** 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. */
|
|
131
|
+
readonly retired?: readonly string[];
|
|
132
|
+
/** 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. */
|
|
133
|
+
readonly forbiddenInGuides?: readonly string[];
|
|
134
|
+
/** Where `build` writes the site, from the root; `_site` by default. */
|
|
135
|
+
readonly out?: string;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** A package as the build reads it: its folder from the root (`""` for the root), its name, and where its `About` is. */
|
|
139
|
+
export interface PackageSource {
|
|
140
|
+
/** Its folder, from the root: `""` for the root itself. */
|
|
141
|
+
readonly dir: string;
|
|
142
|
+
/** Its name in the site's addresses. */
|
|
143
|
+
readonly slug: string;
|
|
144
|
+
/** Its `about.ts`, from the root, or its `About` value. */
|
|
145
|
+
readonly about: { readonly kind: "file"; readonly file: string } | { readonly kind: "value"; readonly value: About };
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** A spec kit as the build reads it, its folders from the root. */
|
|
149
|
+
export type SpecKitSource =
|
|
150
|
+
| { readonly layout: "commons"; readonly dir: string }
|
|
151
|
+
| { readonly layout: "spec-kit"; readonly dir: string; readonly constitution: string | undefined };
|
|
152
|
+
|
|
153
|
+
/** The configuration checked (commons 0011-documentation FR-023): every path absolute or from the root, every default filled. */
|
|
154
|
+
export interface Config {
|
|
155
|
+
/** The configuration's file, absolute. */
|
|
156
|
+
readonly file: string;
|
|
157
|
+
/** The configuration's file, from the root, for findings. */
|
|
158
|
+
readonly fileFromRoot: string;
|
|
159
|
+
/** The repository's root, absolute. */
|
|
160
|
+
readonly root: string;
|
|
161
|
+
/** The site's name. */
|
|
162
|
+
readonly name: string;
|
|
163
|
+
/** How the prose names the repository. */
|
|
164
|
+
readonly subject: string;
|
|
165
|
+
/** The repository's address on GitHub. */
|
|
166
|
+
readonly repository: string;
|
|
167
|
+
/** The branch of links to files. */
|
|
168
|
+
readonly branch: string;
|
|
169
|
+
/** The home page's source; its slug is unused. */
|
|
170
|
+
readonly home: PackageSource;
|
|
171
|
+
/** The packages. */
|
|
172
|
+
readonly packages: readonly PackageSource[];
|
|
173
|
+
/** The spec kits. */
|
|
174
|
+
readonly specKits: readonly SpecKitSource[];
|
|
175
|
+
/** How specifications are cited. */
|
|
176
|
+
readonly citations: {
|
|
177
|
+
readonly prefix: string;
|
|
178
|
+
readonly digits: number;
|
|
179
|
+
readonly linked: readonly LinkedRepository[];
|
|
180
|
+
readonly text: readonly string[];
|
|
181
|
+
};
|
|
182
|
+
/** The lenses. */
|
|
183
|
+
readonly lenses: readonly Lens[];
|
|
184
|
+
/** The folder of the lint rules, from the root. */
|
|
185
|
+
readonly lintRules: string | undefined;
|
|
186
|
+
/** Names that must not appear on any page. */
|
|
187
|
+
readonly retired: readonly string[];
|
|
188
|
+
/** Words that must not appear on the pages people write. */
|
|
189
|
+
readonly forbiddenInGuides: readonly string[];
|
|
190
|
+
/** Where `build` writes the site, absolute. */
|
|
191
|
+
readonly out: string;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
195
|
+
const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* A folder from the root, as the build writes it: no `./`, no trailing `/`, and `""` for the root.
|
|
199
|
+
*
|
|
200
|
+
* @param dir - the folder as written
|
|
201
|
+
*/
|
|
202
|
+
export function normalDir(dir: string): string {
|
|
203
|
+
const parts = dir.split(/[\\/]+/).filter((p) => p !== "" && p !== ".");
|
|
204
|
+
return parts.join("/");
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* A path inside a folder from the root, where the folder may be the root (`""`).
|
|
209
|
+
*
|
|
210
|
+
* @param dir - the folder, from the root
|
|
211
|
+
* @param rel - the path inside it
|
|
212
|
+
*/
|
|
213
|
+
export function under(dir: string, rel: string): string {
|
|
214
|
+
const r = normalDir(rel);
|
|
215
|
+
return dir === "" ? r : r === "" ? dir : `${dir}/${r}`;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/** Whether a value has the fields every `About` has, and areas of the right shape where it has them. */
|
|
219
|
+
export function isAbout(v: unknown): v is About {
|
|
220
|
+
if (!isRecord(v) || typeof v["title"] !== "string" || typeof v["summary"] !== "string") return false;
|
|
221
|
+
const areas = v["areas"];
|
|
222
|
+
if (areas === undefined) return true;
|
|
223
|
+
return Array.isArray(areas) &&
|
|
224
|
+
areas.every((a: unknown) =>
|
|
225
|
+
isRecord(a) && typeof a["title"] === "string" && typeof a["slug"] === "string" && Array.isArray(a["entryPoints"]) &&
|
|
226
|
+
a["entryPoints"].every((e: unknown) => typeof e === "string")
|
|
227
|
+
);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/** Whether a value is a lens: a name and a `read` function. */
|
|
231
|
+
function isLens(v: unknown): v is Lens {
|
|
232
|
+
return isRecord(v) && typeof v["name"] === "string" && typeof v["read"] === "function";
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* A configuration checked into its resolved form, or every problem with it (commons 0011-documentation FR-023).
|
|
237
|
+
*
|
|
238
|
+
* @param value - what the configuration's module exports
|
|
239
|
+
* @param file - the configuration's file, absolute
|
|
240
|
+
*/
|
|
241
|
+
export function resolveConfig(value: unknown, file: string): Result<Config, string[]> {
|
|
242
|
+
const problems: string[] = [];
|
|
243
|
+
const bad = (what: string): void => void problems.push(what);
|
|
244
|
+
if (!isRecord(value)) return err(["the configuration is not an object: export a value of DocsConfig as default, or as config"]);
|
|
245
|
+
const str = (key: string, where: string, v: unknown = value[key]): string | undefined => {
|
|
246
|
+
if (typeof v === "string" && v.trim() !== "") return v;
|
|
247
|
+
bad(`${where} must be a non-empty string`);
|
|
248
|
+
return undefined;
|
|
249
|
+
};
|
|
250
|
+
const optStr = (key: string, where: string, v: unknown = value[key]): string | undefined => (v === undefined ? undefined : str(key, where, v));
|
|
251
|
+
const name = str("name", "name") ?? "";
|
|
252
|
+
const subject = optStr("subject", "subject") ?? name;
|
|
253
|
+
const root = path.resolve(path.dirname(file), optStr("root", "root") ?? ".");
|
|
254
|
+
const repository = str("repository", "repository") ?? "";
|
|
255
|
+
if (repository !== "" && !/^https:\/\/\S+[^/]$/.test(repository)) bad("repository must be an https address with no trailing /");
|
|
256
|
+
const branch = optStr("branch", "branch") ?? "main";
|
|
257
|
+
const aboutOf = (v: unknown, dir: string, where: string): PackageSource["about"] => {
|
|
258
|
+
if (v === undefined || typeof v === "string") return { kind: "file", file: under(dir, v ?? "about.ts") };
|
|
259
|
+
if (isAbout(v)) return { kind: "value", value: v };
|
|
260
|
+
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)`);
|
|
261
|
+
return { kind: "value", value: { title: "", summary: "" } };
|
|
262
|
+
};
|
|
263
|
+
const home = value["home"];
|
|
264
|
+
let homeSource: PackageSource = { dir: "", slug: "home", about: { kind: "value", value: { title: name, summary: "" } } };
|
|
265
|
+
if (!isRecord(home)) bad("home must be an object: { dir, about? }");
|
|
266
|
+
else {
|
|
267
|
+
const dir = normalDir(str("dir", "home.dir", home["dir"]) ?? ".");
|
|
268
|
+
homeSource = { dir, slug: "home", about: aboutOf(home["about"], dir, "home") };
|
|
269
|
+
}
|
|
270
|
+
const packages: PackageSource[] = [];
|
|
271
|
+
const rawPackages = value["packages"];
|
|
272
|
+
if (!Array.isArray(rawPackages)) bad("packages must be an array of { dir, slug, about? }");
|
|
273
|
+
else {
|
|
274
|
+
rawPackages.forEach((p: unknown, i) => {
|
|
275
|
+
const where = `packages[${i}]`;
|
|
276
|
+
if (!isRecord(p)) return bad(`${where} must be an object: { dir, slug, about? }`);
|
|
277
|
+
const dir = normalDir(str("dir", `${where}.dir`, p["dir"]) ?? ".");
|
|
278
|
+
const slug = str("slug", `${where}.slug`, p["slug"]);
|
|
279
|
+
if (slug === undefined) return;
|
|
280
|
+
if (!SLUG.test(slug)) return bad(`${where}.slug ${JSON.stringify(slug)} must be lower-case words joined by hyphens`);
|
|
281
|
+
if (packages.some((q) => q.slug === slug)) return bad(`${where}.slug ${slug} names two packages`);
|
|
282
|
+
packages.push({ dir, slug, about: aboutOf(p["about"], dir, where) });
|
|
283
|
+
});
|
|
284
|
+
}
|
|
285
|
+
const specKits: SpecKitSource[] = [];
|
|
286
|
+
const rawKits = value["specKits"] ?? [];
|
|
287
|
+
if (!Array.isArray(rawKits)) bad("specKits must be an array");
|
|
288
|
+
else {
|
|
289
|
+
rawKits.forEach((k: unknown, i) => {
|
|
290
|
+
const where = `specKits[${i}]`;
|
|
291
|
+
if (!isRecord(k)) return bad(`${where} must be an object: { layout, dir }`);
|
|
292
|
+
const dir = normalDir(str("dir", `${where}.dir`, k["dir"]) ?? "");
|
|
293
|
+
const layout = k["layout"];
|
|
294
|
+
if (layout === "commons") specKits.push({ layout, dir });
|
|
295
|
+
else if (layout === "spec-kit") {
|
|
296
|
+
const c = k["constitution"];
|
|
297
|
+
if (c !== undefined && c !== false && typeof c !== "string") return bad(`${where}.constitution must be a path or false`);
|
|
298
|
+
specKits.push({ layout, dir, constitution: c === false ? undefined : normalDir(c ?? ".specify/memory/constitution.md") });
|
|
299
|
+
} else bad(`${where}.layout must be "commons" or "spec-kit"`);
|
|
300
|
+
});
|
|
301
|
+
}
|
|
302
|
+
const c = value["citations"];
|
|
303
|
+
const digitsOf = (v: unknown, where: string): number => {
|
|
304
|
+
if (typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= 9) return v;
|
|
305
|
+
bad(`${where} must be a whole number from 1 to 9`);
|
|
306
|
+
return 4;
|
|
307
|
+
};
|
|
308
|
+
let citations: Config["citations"] = { prefix: "", digits: 4, linked: [], text: [] };
|
|
309
|
+
if (!isRecord(c)) bad("citations must be an object: { prefix, digits, linked?, text? }");
|
|
310
|
+
else {
|
|
311
|
+
const prefix = (str("prefix", "citations.prefix", c["prefix"]) ?? "").toLowerCase();
|
|
312
|
+
const digits = digitsOf(c["digits"], "citations.digits");
|
|
313
|
+
const linked: LinkedRepository[] = [];
|
|
314
|
+
const rawLinked = c["linked"] ?? [];
|
|
315
|
+
if (!Array.isArray(rawLinked)) bad("citations.linked must be an array");
|
|
316
|
+
else {
|
|
317
|
+
rawLinked.forEach((l: unknown, i) => {
|
|
318
|
+
const where = `citations.linked[${i}]`;
|
|
319
|
+
if (!isRecord(l)) return bad(`${where} must be an object: { repo, site, digits }`);
|
|
320
|
+
const repo = str("repo", `${where}.repo`, l["repo"]);
|
|
321
|
+
const site = str("site", `${where}.site`, l["site"]);
|
|
322
|
+
const d = digitsOf(l["digits"], `${where}.digits`);
|
|
323
|
+
if (site !== undefined && !/^https:\/\/\S+\/$/.test(site)) return bad(`${where}.site must be an https address ending in /`);
|
|
324
|
+
if (repo !== undefined && site !== undefined) linked.push({ repo: repo.toLowerCase(), site, digits: d });
|
|
325
|
+
});
|
|
326
|
+
}
|
|
327
|
+
const rawText = c["text"] ?? [];
|
|
328
|
+
const text: string[] = [];
|
|
329
|
+
if (!Array.isArray(rawText) || !rawText.every((t: unknown) => typeof t === "string")) bad("citations.text must be an array of names");
|
|
330
|
+
else for (const t of rawText) text.push(String(t).toLowerCase());
|
|
331
|
+
for (const r of linked) if (r.repo === prefix || text.includes(r.repo)) bad(`citations: ${r.repo} is named twice`);
|
|
332
|
+
citations = { prefix, digits, linked, text };
|
|
333
|
+
}
|
|
334
|
+
const rawLenses = value["lenses"] ?? [];
|
|
335
|
+
const lenses: Lens[] = [];
|
|
336
|
+
if (!Array.isArray(rawLenses)) bad("lenses must be an array of Lens values");
|
|
337
|
+
else rawLenses.forEach((l: unknown, i) => (isLens(l) ? void lenses.push(l) : bad(`lenses[${i}] is not a Lens: { name, read }`)));
|
|
338
|
+
const names = (key: string): string[] => {
|
|
339
|
+
const v = value[key];
|
|
340
|
+
if (v === undefined) return [];
|
|
341
|
+
if (!Array.isArray(v) || !v.every((x: unknown) => typeof x === "string" && x !== "")) {
|
|
342
|
+
bad(`${key} must be an array of non-empty strings`);
|
|
343
|
+
return [];
|
|
344
|
+
}
|
|
345
|
+
return v.map(String);
|
|
346
|
+
};
|
|
347
|
+
const retired = names("retired");
|
|
348
|
+
const forbiddenInGuides = names("forbiddenInGuides");
|
|
349
|
+
const lint = optStr("lintRules", "lintRules");
|
|
350
|
+
const out = path.resolve(root, optStr("out", "out") ?? "_site");
|
|
351
|
+
if (problems.length > 0) return err(problems);
|
|
352
|
+
return ok({
|
|
353
|
+
file,
|
|
354
|
+
fileFromRoot: path.relative(root, file).split(path.sep).join("/"),
|
|
355
|
+
root,
|
|
356
|
+
name,
|
|
357
|
+
subject,
|
|
358
|
+
repository,
|
|
359
|
+
branch,
|
|
360
|
+
home: homeSource,
|
|
361
|
+
packages,
|
|
362
|
+
specKits,
|
|
363
|
+
citations,
|
|
364
|
+
lenses,
|
|
365
|
+
lintRules: lint === undefined ? undefined : normalDir(lint),
|
|
366
|
+
retired,
|
|
367
|
+
forbiddenInGuides,
|
|
368
|
+
out,
|
|
369
|
+
});
|
|
370
|
+
}
|