@intellectual-frontiers/docs 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +75 -0
  2. package/README.md +8 -2
  3. package/dist/build.d.ts +63 -0
  4. package/dist/build.js +103 -0
  5. package/dist/check.d.ts +63 -0
  6. package/dist/check.js +54 -0
  7. package/dist/cli.d.ts +51 -0
  8. package/dist/cli.js +165 -0
  9. package/dist/config.d.ts +196 -0
  10. package/dist/config.js +229 -0
  11. package/dist/emit/html.d.ts +67 -0
  12. package/dist/emit/html.js +338 -0
  13. package/dist/emit/markdown.d.ts +19 -0
  14. package/dist/emit/markdown.js +124 -0
  15. package/dist/emit/search.d.ts +15 -0
  16. package/dist/emit/search.js +29 -0
  17. package/dist/extract/api.d.ts +74 -0
  18. package/dist/extract/api.js +261 -0
  19. package/dist/extract/specs.d.ts +141 -0
  20. package/dist/extract/specs.js +208 -0
  21. package/dist/highlight.d.ts +22 -0
  22. package/dist/highlight.js +77 -0
  23. package/dist/layered.d.ts +94 -0
  24. package/dist/layered.js +14 -0
  25. package/dist/lens/guides.d.ts +23 -0
  26. package/dist/lens/guides.js +49 -0
  27. package/dist/lens/layered.d.ts +16 -0
  28. package/dist/lens/layered.js +354 -0
  29. package/dist/lens/program.d.ts +23 -0
  30. package/dist/lens/program.js +124 -0
  31. package/dist/lens/releases.d.ts +10 -0
  32. package/dist/lens/releases.js +37 -0
  33. package/dist/lens.d.ts +30 -0
  34. package/dist/lens.js +1 -0
  35. package/dist/links.d.ts +96 -0
  36. package/dist/links.js +182 -0
  37. package/dist/main.d.ts +1 -0
  38. package/dist/main.js +12 -0
  39. package/dist/markdown.d.ts +43 -0
  40. package/dist/markdown.js +301 -0
  41. package/dist/mod.d.ts +32 -0
  42. package/dist/mod.js +9 -0
  43. package/dist/model.d.ts +159 -0
  44. package/dist/model.js +39 -0
  45. package/dist/pages/api.d.ts +41 -0
  46. package/dist/pages/api.js +162 -0
  47. package/dist/pages/areas.d.ts +39 -0
  48. package/dist/pages/areas.js +119 -0
  49. package/dist/pages/overview.d.ts +24 -0
  50. package/dist/pages/overview.js +283 -0
  51. package/dist/pages/specs.d.ts +31 -0
  52. package/dist/pages/specs.js +358 -0
  53. package/dist/site.d.ts +31 -0
  54. package/dist/site.js +288 -0
  55. package/dist/sources.d.ts +53 -0
  56. package/dist/sources.js +159 -0
  57. package/dist/theme/site.css +275 -0
  58. package/dist/theme/site.js +174 -0
  59. package/dist/tsdoc.d.ts +67 -0
  60. package/dist/tsdoc.js +94 -0
  61. package/ifc-docs.mjs +4 -0
  62. package/package.json +66 -4
  63. package/src/build.ts +117 -0
  64. package/src/check.ts +84 -0
  65. package/src/cli.ts +145 -0
  66. package/src/config.ts +370 -0
  67. package/src/emit/html.ts +398 -0
  68. package/src/emit/markdown.ts +129 -0
  69. package/src/emit/search.ts +38 -0
  70. package/src/extract/api.ts +297 -0
  71. package/src/extract/specs.ts +299 -0
  72. package/src/highlight.ts +98 -0
  73. package/src/layered.ts +102 -0
  74. package/src/lens/guides.ts +70 -0
  75. package/src/lens/layered.ts +341 -0
  76. package/src/lens/program.ts +137 -0
  77. package/src/lens/releases.ts +54 -0
  78. package/src/lens.ts +34 -0
  79. package/src/links.ts +234 -0
  80. package/src/main.ts +12 -0
  81. package/src/markdown.ts +320 -0
  82. package/src/mod.ts +53 -0
  83. package/src/model.ts +154 -0
  84. package/src/pages/api.ts +179 -0
  85. package/src/pages/areas.ts +133 -0
  86. package/src/pages/overview.ts +276 -0
  87. package/src/pages/specs.ts +366 -0
  88. package/src/site.ts +285 -0
  89. package/src/sources.ts +157 -0
  90. package/src/theme/site.css +275 -0
  91. package/src/theme/site.js +174 -0
  92. package/src/tsdoc.ts +131 -0
package/LICENSE ADDED
@@ -0,0 +1,75 @@
1
+ Required Notice: Copyright Intellectual Frontiers LLC (https://github.com/intellectual-frontiers/.github)
2
+
3
+ # PolyForm Noncommercial License 1.0.0
4
+
5
+ <https://polyformproject.org/licenses/noncommercial/1.0.0>
6
+
7
+ ## Acceptance
8
+
9
+ In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
10
+
11
+ ## Copyright License
12
+
13
+ The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
14
+
15
+ ## Distribution License
16
+
17
+ The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
18
+
19
+ ## Notices
20
+
21
+ You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
22
+
23
+ > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
24
+
25
+ ## Changes and New Works License
26
+
27
+ The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
28
+
29
+ ## Patent License
30
+
31
+ The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
32
+
33
+ ## Noncommercial Purposes
34
+
35
+ Any noncommercial purpose is a permitted purpose.
36
+
37
+ ## Personal Uses
38
+
39
+ Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
40
+
41
+ ## Noncommercial Organizations
42
+
43
+ Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
44
+
45
+ ## Fair Use
46
+
47
+ You may have "fair use" rights for the software under the law. These terms do not limit them.
48
+
49
+ ## No Other Rights
50
+
51
+ These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
52
+
53
+ ## Patent Defense
54
+
55
+ If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
56
+
57
+ ## Violations
58
+
59
+ The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
60
+
61
+ ## No Liability
62
+
63
+ ***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
64
+
65
+ ## Definitions
66
+
67
+ The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
68
+
69
+ **You** refers to the individual or entity agreeing to these terms.
70
+
71
+ **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
72
+
73
+ **Your licenses** are all the licenses granted to you for the software under these terms.
74
+
75
+ **Use** means anything you do with the software requiring one of your licenses.
package/README.md CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ # @intellectual-frontiers/docs
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 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.
4
+
5
+ ```sh
6
+ bun add @intellectual-frontiers/docs # or: npm install @intellectual-frontiers/docs
7
+ ```
8
+
9
+ Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/docs
@@ -0,0 +1,63 @@
1
+ import type { Finding } from "./check.js";
2
+ import type { Config } from "./config.js";
3
+ import type { SpecKit } from "./extract/specs.js";
4
+ import { type LinkIndex, type LinkScope } from "./links.js";
5
+ import type { Block, Inline, Page } from "./model.js";
6
+ /** One build: what it reads, what it has made, and what it has found. */
7
+ export declare class Build {
8
+ /** The configuration. */
9
+ readonly config: Config;
10
+ /** The repository's root. */
11
+ readonly root: string;
12
+ /** The spec kit. */
13
+ readonly kit: SpecKit;
14
+ /** The pages made so far. */
15
+ readonly pages: Page[];
16
+ /** What has been found. */
17
+ readonly found: Finding[];
18
+ /** The page that shows each file of the repository, by its path from the root. */
19
+ readonly files: Map<string, string>;
20
+ /** The API page of each source file, by its path from the root: where its exports have their anchors. */
21
+ readonly apiFiles: Map<string, string>;
22
+ /** Where each export is shown on the page of the file it is declared in, by `file#name` (the name it is declared with). */
23
+ readonly declared: Map<string, {
24
+ readonly path: string;
25
+ readonly anchor: string;
26
+ }>;
27
+ /** Each export's page and anchor, by area and name. */
28
+ readonly exports: Map<string, Map<string, {
29
+ readonly path: string;
30
+ readonly anchor: string;
31
+ }>>;
32
+ /** The page that shows a model's entity, by its area and export name (`arca!party`). */
33
+ readonly entityPages: Map<string, string>;
34
+ /** The pages that cite each specification (key `0009-example`) and each requirement (key `0009-example FR-001`). */
35
+ readonly citations: Map<string, Set<string>>;
36
+ /** The title of each package, by its slug: what the pages of its specifications and the register call it. */
37
+ readonly packageTitles: Map<string, string>;
38
+ /** What links can reach. */
39
+ readonly index: LinkIndex;
40
+ /**
41
+ * A build of a repository.
42
+ *
43
+ * @param config - its configuration
44
+ * @param kit - its spec kits, read
45
+ */
46
+ constructor(config: Config, kit: SpecKit);
47
+ /** Markdown read with this build's links, for a scope. */
48
+ md(text: string, scope: LinkScope): Block[];
49
+ /** An example of TSDoc: Markdown where it has a fence, else TypeScript. */
50
+ example(text: string, scope: LinkScope): Block[];
51
+ /** A run of Markdown with this build's links, as inlines. */
52
+ line(text: string, scope: LinkScope): Inline[];
53
+ /** A page made. */
54
+ add(page: Page): void;
55
+ /** A path of the repository, absolute, from its path from the root. */
56
+ abs(rel: string): string;
57
+ /** Whether a path of the repository exists. */
58
+ exists(rel: string): boolean;
59
+ /** The text of a file of the repository. */
60
+ read(rel: string): string;
61
+ }
62
+ /** The numbered items of a specification's text: its requirements and success criteria. */
63
+ export declare function itemsOf(body: string): string[];
package/dist/build.js ADDED
@@ -0,0 +1,103 @@
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 { contextFor, specPage } from "./links.js";
11
+ import { markdown } from "./markdown.js";
12
+ /** One build: what it reads, what it has made, and what it has found. */
13
+ export class Build {
14
+ /** The configuration. */
15
+ config;
16
+ /** The repository's root. */
17
+ root;
18
+ /** The spec kit. */
19
+ kit;
20
+ /** The pages made so far. */
21
+ pages = [];
22
+ /** What has been found. */
23
+ found = [];
24
+ /** The page that shows each file of the repository, by its path from the root. */
25
+ files = new Map();
26
+ /** The API page of each source file, by its path from the root: where its exports have their anchors. */
27
+ apiFiles = new Map();
28
+ /** Where each export is shown on the page of the file it is declared in, by `file#name` (the name it is declared with). */
29
+ declared = new Map();
30
+ /** Each export's page and anchor, by area and name. */
31
+ exports = new Map();
32
+ /** The page that shows a model's entity, by its area and export name (`arca!party`). */
33
+ entityPages = new Map();
34
+ /** The pages that cite each specification (key `0009-example`) and each requirement (key `0009-example FR-001`). */
35
+ citations = new Map();
36
+ /** The title of each package, by its slug: what the pages of its specifications and the register call it. */
37
+ packageTitles = new Map();
38
+ /** What links can reach. */
39
+ index;
40
+ /**
41
+ * A build of a repository.
42
+ *
43
+ * @param config - its configuration
44
+ * @param kit - its spec kits, read
45
+ */
46
+ constructor(config, kit) {
47
+ this.config = config;
48
+ this.root = config.root;
49
+ this.kit = kit;
50
+ const specs = new Map(kit.specs.map((s) => [s.id, new Set(itemsOf(s.body))]));
51
+ for (const s of kit.specs) {
52
+ this.files.set(s.file, specPage(s.id));
53
+ this.files.set(s.file.split("/").slice(0, -1).join("/"), specPage(s.id));
54
+ }
55
+ this.index = {
56
+ specs,
57
+ files: this.files,
58
+ exports: this.exports,
59
+ citations: config.citations,
60
+ blob: (p) => `${config.repository}/blob/${config.branch}/${p}`,
61
+ cited: (spec, req, page) => {
62
+ for (const key of req === undefined ? [spec] : [spec, `${spec} ${req}`]) {
63
+ const set = this.citations.get(key) ?? new Set();
64
+ set.add(page);
65
+ this.citations.set(key, set);
66
+ }
67
+ },
68
+ };
69
+ }
70
+ /** Markdown read with this build's links, for a scope. */
71
+ md(text, scope) {
72
+ return markdown(text, contextFor(this.index, scope, this.found));
73
+ }
74
+ /** An example of TSDoc: Markdown where it has a fence, else TypeScript. */
75
+ example(text, scope) {
76
+ return /^\s*(```|~~~)/m.test(text) ? this.md(text, scope) : [{ kind: "code", lang: "ts", text: text.replace(/^\n+|\s+$/g, "") }];
77
+ }
78
+ /** A run of Markdown with this build's links, as inlines. */
79
+ line(text, scope) {
80
+ const first = this.md(text, scope)[0];
81
+ return first !== undefined && first.kind === "paragraph" ? [...first.inlines] : [{ kind: "text", text }];
82
+ }
83
+ /** A page made. */
84
+ add(page) {
85
+ this.pages.push(page);
86
+ }
87
+ /** A path of the repository, absolute, from its path from the root. */
88
+ abs(rel) {
89
+ return path.join(this.root, rel);
90
+ }
91
+ /** Whether a path of the repository exists. */
92
+ exists(rel) {
93
+ return fs.existsSync(this.abs(rel));
94
+ }
95
+ /** The text of a file of the repository. */
96
+ read(rel) {
97
+ return fs.readTextFileSync(this.abs(rel));
98
+ }
99
+ }
100
+ /** The numbered items of a specification's text: its requirements and success criteria. */
101
+ export function itemsOf(body) {
102
+ return [...body.matchAll(/^- \*\*((?:FR|SC)-\d{3}[a-z]?)\*\*/gm)].map((m) => m[1] ?? "");
103
+ }
@@ -0,0 +1,63 @@
1
+ /** What is wrong. */
2
+ export type Problem = {
3
+ readonly kind: "undocumented";
4
+ readonly name: string;
5
+ } | {
6
+ readonly kind: "no-about";
7
+ } | {
8
+ readonly kind: "folder-missing";
9
+ readonly folder: string;
10
+ } | {
11
+ readonly kind: "command-missing";
12
+ readonly command: string;
13
+ } | {
14
+ readonly kind: "enforcer-missing";
15
+ readonly enforcer: string;
16
+ } | {
17
+ readonly kind: "entry-point-missing";
18
+ readonly file: string;
19
+ } | {
20
+ readonly kind: "example-missing";
21
+ readonly file: string;
22
+ } | {
23
+ readonly kind: "unknown-spec";
24
+ readonly cite: string;
25
+ } | {
26
+ readonly kind: "unknown-requirement";
27
+ readonly cite: string;
28
+ } | {
29
+ readonly kind: "unknown-link";
30
+ readonly name: string;
31
+ } | {
32
+ readonly kind: "undescribed";
33
+ readonly entity: string;
34
+ } | {
35
+ readonly kind: "import-failed";
36
+ readonly error: string;
37
+ } | {
38
+ readonly kind: "broken-link";
39
+ readonly href: string;
40
+ } | {
41
+ readonly kind: "duplicate-spec";
42
+ readonly id: string;
43
+ } | {
44
+ readonly kind: "diagram-undrawable";
45
+ readonly first: string;
46
+ } | {
47
+ readonly kind: "retired-name";
48
+ readonly name: string;
49
+ } | {
50
+ readonly kind: "forbidden-word";
51
+ readonly word: string;
52
+ };
53
+ /** A problem and where it is. */
54
+ export interface Finding {
55
+ /** The file, page or export it is found in. */
56
+ readonly where: string;
57
+ /** What is wrong there. */
58
+ readonly problem: Problem;
59
+ }
60
+ /** The sentence a finding is printed with. */
61
+ export declare function message(p: Problem): string;
62
+ /** The findings as the lines `check` prints, sorted and each once. */
63
+ export declare function report(found: readonly Finding[]): string[];
package/dist/check.js ADDED
@@ -0,0 +1,54 @@
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
+ /** The sentence a finding is printed with. */
11
+ export function message(p) {
12
+ switch (p.kind) {
13
+ case "undocumented":
14
+ return `${p.name} is exported with no TSDoc`;
15
+ case "no-about":
16
+ return "the package has no about.ts that exports about";
17
+ case "folder-missing":
18
+ return `about names the folder ${p.folder}, which does not exist`;
19
+ case "command-missing":
20
+ return `about names the command '${p.command}', which is not a script of package.json`;
21
+ case "enforcer-missing":
22
+ return `about says a rule is enforced by ${p.enforcer}, which does not exist`;
23
+ case "entry-point-missing":
24
+ return `about names the entry point ${p.file}, which does not exist`;
25
+ case "example-missing":
26
+ return `about names the example ${p.file}, which does not exist`;
27
+ case "unknown-spec":
28
+ return `cites ${p.cite}, which is not a specification of the spec kit`;
29
+ case "unknown-requirement":
30
+ return `cites ${p.cite}, which its specification does not have`;
31
+ case "unknown-link":
32
+ return `{@link ${p.name}} names nothing exported`;
33
+ case "undescribed":
34
+ return `${p.entity} has no description`;
35
+ case "import-failed":
36
+ return `the module could not be imported: ${p.error}`;
37
+ case "broken-link":
38
+ return `links to ${p.href}, which is not a page or an anchor of the site`;
39
+ case "duplicate-spec":
40
+ return `holds ${p.id}, which a spec kit before it holds too`;
41
+ case "diagram-undrawable":
42
+ 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}`;
43
+ case "retired-name":
44
+ return `names ${p.name}, which is retired`;
45
+ case "forbidden-word":
46
+ return `has the word "${p.word}", which a page people write does not use`;
47
+ default:
48
+ return absurd(p);
49
+ }
50
+ }
51
+ /** The findings as the lines `check` prints, sorted and each once. */
52
+ export function report(found) {
53
+ return [...new Set(found.map((f) => `${f.where}: ${message(f.problem)}`))].sort();
54
+ }
package/dist/cli.d.ts ADDED
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The parts of the command line of the documentation generator, `ifc-docs` (commons 0011-documentation FR-003, FR-023): `ifc-docs build [--out DIR]`
3
+ * writes the site into DIR (the configuration's `out` by default, `_site` at the repository's root unless it says otherwise);
4
+ * `ifc-docs check` builds it into a temporary folder, prints every finding as `where: message` on standard error, writes nothing in the
5
+ * repository, and exits 1 where there is one. Both read the configuration given by `--config FILE`, or else the first `docs.config.ts`
6
+ * 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
7
+ * 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
8
+ * `commons/docs/` run it from the source.
9
+ *
10
+ * @module
11
+ */
12
+ import { type Result } from "@intellectual-frontiers/core";
13
+ import { type Config } from "./config.js";
14
+ /** What the command line asks for. */
15
+ export type Command = {
16
+ readonly kind: "build";
17
+ readonly out: string | undefined;
18
+ readonly config: string | undefined;
19
+ } | {
20
+ readonly kind: "check";
21
+ readonly config: string | undefined;
22
+ } | {
23
+ readonly kind: "help";
24
+ };
25
+ /** The usage, printed by `--help` and with a refusal. */
26
+ export declare const USAGE = "usage: ifc-docs build [--out DIR] [--config FILE]\n ifc-docs check [--config FILE]\n\nbuild writes the site into DIR (the configuration's out, else _site at the repository's root)\ncheck builds the site into a temporary folder, prints every finding, and exits 1 where there is one\n--config FILE the configuration (default: the first docs.config.ts from here up to the repository's root)";
27
+ /**
28
+ * The command a command line asks for, or why it is not one.
29
+ *
30
+ * @param args - its arguments
31
+ */
32
+ export declare function parseArgs(args: readonly string[]): Result<Command, string>;
33
+ /**
34
+ * The configuration's file: the first `docs.config.ts` from a folder up to the repository's root (the first folder that holds `.git`).
35
+ *
36
+ * @param from - the folder to start from
37
+ */
38
+ export declare function findConfig(from: string): string | undefined;
39
+ /**
40
+ * A configuration's module loaded and checked: its default export, or its export `config`.
41
+ *
42
+ * @param file - the configuration's file
43
+ */
44
+ export declare function loadConfig(file: string): Promise<Result<Config, string[]>>;
45
+ /**
46
+ * The generator run: the site built, written or checked; the exit status (0, 1 where `check` finds something, 2 where it is refused).
47
+ *
48
+ * @param args - the command line's arguments
49
+ * @param cwd - the working folder, where the search for the configuration starts
50
+ */
51
+ export declare function main(args: readonly string[], cwd?: string): Promise<number>;
package/dist/cli.js ADDED
@@ -0,0 +1,165 @@
1
+ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx, extraExtensions, ignoreCase) {
2
+ if (typeof path === "string" && /^\.\.?\//.test(path)) {
3
+ if (extraExtensions) {
4
+ for (var extension in extraExtensions) {
5
+ var suffix = path.slice(-extension.length);
6
+ if (suffix === extension || ignoreCase && suffix.toLowerCase() === extension.toLowerCase()) {
7
+ var output = extraExtensions[extension];
8
+ return output === extension ? path : path.slice(0, -extension.length) + output;
9
+ }
10
+ }
11
+ }
12
+ return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
13
+ return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
14
+ });
15
+ }
16
+ return path;
17
+ };
18
+ // Spec: 0001-docs FR-003
19
+ /**
20
+ * The parts of the command line of the documentation generator, `ifc-docs` (commons 0011-documentation FR-003, FR-023): `ifc-docs build [--out DIR]`
21
+ * writes the site into DIR (the configuration's `out` by default, `_site` at the repository's root unless it says otherwise);
22
+ * `ifc-docs check` builds it into a temporary folder, prints every finding as `where: message` on standard error, writes nothing in the
23
+ * repository, and exits 1 where there is one. Both read the configuration given by `--config FILE`, or else the first `docs.config.ts`
24
+ * 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
25
+ * 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
26
+ * `commons/docs/` run it from the source.
27
+ *
28
+ * @module
29
+ */
30
+ import { err, ok } from "@intellectual-frontiers/core";
31
+ import { fs, path, proc } from "@intellectual-frontiers/system";
32
+ import { report } from "./check.js";
33
+ import { resolveConfig } from "./config.js";
34
+ import { buildSite, writeSite } from "./site.js";
35
+ /** The usage, printed by `--help` and with a refusal. */
36
+ export const USAGE = `usage: ifc-docs build [--out DIR] [--config FILE]
37
+ ifc-docs check [--config FILE]
38
+
39
+ build writes the site into DIR (the configuration's out, else _site at the repository's root)
40
+ check builds the site into a temporary folder, prints every finding, and exits 1 where there is one
41
+ --config FILE the configuration (default: the first docs.config.ts from here up to the repository's root)`;
42
+ /**
43
+ * The command a command line asks for, or why it is not one.
44
+ *
45
+ * @param args - its arguments
46
+ */
47
+ export function parseArgs(args) {
48
+ const [verb, ...rest] = args;
49
+ if (verb === undefined || verb === "--help" || verb === "-h" || verb === "help")
50
+ return ok({ kind: "help" });
51
+ let out;
52
+ let config;
53
+ for (let i = 0; i < rest.length; i++) {
54
+ const a = rest[i];
55
+ const value = rest[i + 1];
56
+ if (a === "--out" || a === "--config") {
57
+ if (value === undefined || value.startsWith("--"))
58
+ return err(`${a} needs a value`);
59
+ if (a === "--out")
60
+ out = value;
61
+ else
62
+ config = value;
63
+ i++;
64
+ }
65
+ else
66
+ return err(`unknown argument ${JSON.stringify(a)}`);
67
+ }
68
+ switch (verb) {
69
+ case "build":
70
+ return ok({ kind: "build", out, config });
71
+ case "check":
72
+ if (out !== undefined)
73
+ return err("check writes nothing: --out is for build");
74
+ return ok({ kind: "check", config });
75
+ default:
76
+ return err(`unknown command ${JSON.stringify(verb)}: build or check`);
77
+ }
78
+ }
79
+ /**
80
+ * The configuration's file: the first `docs.config.ts` from a folder up to the repository's root (the first folder that holds `.git`).
81
+ *
82
+ * @param from - the folder to start from
83
+ */
84
+ export function findConfig(from) {
85
+ let dir = path.resolve(from);
86
+ for (;;) {
87
+ const file = path.join(dir, "docs.config.ts");
88
+ if (fs.existsSync(file))
89
+ return file;
90
+ const parent = path.dirname(dir);
91
+ if (fs.existsSync(path.join(dir, ".git")) || parent === dir)
92
+ return undefined;
93
+ dir = parent;
94
+ }
95
+ }
96
+ /**
97
+ * A configuration's module loaded and checked: its default export, or its export `config`.
98
+ *
99
+ * @param file - the configuration's file
100
+ */
101
+ export async function loadConfig(file) {
102
+ const abs = path.resolve(file);
103
+ if (!fs.existsSync(abs))
104
+ return err([`${abs} does not exist`]);
105
+ let mod;
106
+ try {
107
+ mod = await import(__rewriteRelativeImportExtension(path.toFileUrl(abs).href));
108
+ }
109
+ catch (e) {
110
+ return err([`${abs} could not be imported: ${e instanceof Error ? e.message : String(e)}`]);
111
+ }
112
+ const value = typeof mod === "object" && mod !== null ? ("default" in mod && mod.default !== undefined ? mod.default : "config" in mod ? mod.config : undefined) : undefined;
113
+ return resolveConfig(value, abs);
114
+ }
115
+ /**
116
+ * The generator run: the site built, written or checked; the exit status (0, 1 where `check` finds something, 2 where it is refused).
117
+ *
118
+ * @param args - the command line's arguments
119
+ * @param cwd - the working folder, where the search for the configuration starts
120
+ */
121
+ export async function main(args, cwd = proc.cwd()) {
122
+ const parsed = parseArgs(args);
123
+ if (parsed.kind === "err") {
124
+ console.error(`ifc-docs: ${parsed.error}\n${USAGE}`);
125
+ return 2;
126
+ }
127
+ const c = parsed.value;
128
+ if (c.kind === "help") {
129
+ console.log(USAGE);
130
+ return 0;
131
+ }
132
+ const file = c.config === undefined ? findConfig(cwd) : path.resolve(cwd, c.config);
133
+ if (file === undefined) {
134
+ console.error(`ifc-docs: no docs.config.ts from ${cwd} up to the repository's root; give one with --config`);
135
+ return 2;
136
+ }
137
+ const loaded = await loadConfig(file);
138
+ if (loaded.kind === "err") {
139
+ for (const p of loaded.error)
140
+ console.error(`${file}: ${p}`);
141
+ return 2;
142
+ }
143
+ const config = loaded.value;
144
+ const built = await buildSite(config);
145
+ const lines = report(built.found);
146
+ if (c.kind === "check") {
147
+ const tmp = await fs.makeTempDir({ prefix: "ifc-docs-" });
148
+ try {
149
+ await writeSite(config, built, tmp);
150
+ }
151
+ finally {
152
+ await fs.remove(tmp, { recursive: true });
153
+ }
154
+ for (const l of lines)
155
+ console.error(l);
156
+ console.error(`${built.pages.length} pages, ${lines.length} findings`);
157
+ return lines.length > 0 ? 1 : 0;
158
+ }
159
+ const out = c.out === undefined ? config.out : path.resolve(cwd, c.out);
160
+ await writeSite(config, built, out);
161
+ for (const l of lines)
162
+ console.error(l);
163
+ console.error(`${built.pages.length} pages written to ${out}; ${lines.length} findings`);
164
+ return 0;
165
+ }