@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/src/tsdoc.ts ADDED
@@ -0,0 +1,131 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * TSDoc read into its parts (commons 0011-documentation FR-006): the summary, `@remarks`, `@limits` (this repository's own block tag: what
4
+ * a module does not do, or does only in part), `@example`, `@see`, `@param`, `@returns` and `@deprecated`, from a comment's text or from
5
+ * the tags the TypeScript checker gives. The text of each part stays Markdown, for `markdown.ts` to read.
6
+ *
7
+ * @example
8
+ * ```ts
9
+ * import { moduleComment } from "./tsdoc.ts";
10
+ * moduleComment("/**\n * What it is.\n *\n * @limits\n * What it is not.\n *\n * @module\n *\/\n")?.limits; // "What it is not."
11
+ * ```
12
+ *
13
+ * @module
14
+ */
15
+
16
+ /** A parameter's name and what the comment says of it. */
17
+ export interface DocParam {
18
+ /** Its name. */
19
+ readonly name: string;
20
+ /** What it is. */
21
+ readonly text: string;
22
+ }
23
+
24
+ /** The parts of a TSDoc comment. */
25
+ export interface DocComment {
26
+ /** What comes before the first block tag. */
27
+ readonly summary: string;
28
+ /** `@remarks`: the longer account. */
29
+ readonly remarks?: string;
30
+ /** `@limits`: what it does not do, or does only in part. */
31
+ readonly limits?: string;
32
+ /** Each `@example`. */
33
+ readonly examples: readonly string[];
34
+ /** Each `@see`. */
35
+ readonly see: readonly string[];
36
+ /** Each `@param`. */
37
+ readonly params: readonly DocParam[];
38
+ /** `@returns`. */
39
+ readonly returns?: string;
40
+ /** `@deprecated`, with why. */
41
+ readonly deprecated?: string;
42
+ /** Whether it says `@module`. */
43
+ readonly isModule: boolean;
44
+ }
45
+
46
+ /** A block tag and its text, as the checker gives it or as a comment's text holds it. */
47
+ export interface DocTag {
48
+ /** The tag's name, without `@`. */
49
+ readonly name: string;
50
+ /** Its text. */
51
+ readonly text: string;
52
+ }
53
+
54
+ const dedent = (s: string): string => {
55
+ const lines = s.replace(/^\n+|\s+$/g, "").split("\n");
56
+ const ind = Math.min(...lines.filter((l) => l.trim() !== "").map((l) => l.length - l.trimStart().length));
57
+ return lines.map((l) => l.slice(Number.isFinite(ind) ? ind : 0)).join("\n");
58
+ };
59
+
60
+ /** A `@param` tag's text, as `name - what` or `name what`. */
61
+ function param(text: string): DocParam {
62
+ const m = /^\s*([\w$.[\]]+)\s*(?:-\s*)?([\s\S]*)$/.exec(text);
63
+ return { name: m?.[1] ?? "", text: (m?.[2] ?? "").trim() };
64
+ }
65
+
66
+ /**
67
+ * The parts of a comment, from its summary and its block tags.
68
+ *
69
+ * @param summary - the text before the first block tag
70
+ * @param tags - the block tags, in order
71
+ */
72
+ export function docOf(summary: string, tags: readonly DocTag[]): DocComment {
73
+ const all = (n: string): string[] => tags.filter((t) => t.name === n).map((t) => dedent(t.text));
74
+ const one = (n: string): string | undefined => {
75
+ const v = all(n);
76
+ return v.length === 0 ? undefined : v.join("\n\n");
77
+ };
78
+ const remarks = one("remarks");
79
+ const limits = one("limits");
80
+ const returns = one("returns");
81
+ const deprecated = one("deprecated");
82
+ return {
83
+ summary: dedent(summary),
84
+ ...(remarks === undefined ? {} : { remarks }),
85
+ ...(limits === undefined ? {} : { limits }),
86
+ examples: all("example"),
87
+ see: all("see"),
88
+ params: tags.filter((t) => t.name === "param").map((t) => param(t.text)),
89
+ ...(returns === undefined ? {} : { returns }),
90
+ ...(deprecated === undefined ? {} : { deprecated }),
91
+ isModule: tags.some((t) => t.name === "module"),
92
+ };
93
+ }
94
+
95
+ /**
96
+ * The parts of a comment's text: the inside of `/** ... *\/`, its leading asterisks taken off.
97
+ *
98
+ * @param inside - the comment's text between its delimiters
99
+ */
100
+ export function parseComment(inside: string): DocComment {
101
+ const lines = inside.split("\n").map((l) => l.replace(/^\s*\* ?/, ""));
102
+ const tags: DocTag[] = [];
103
+ const summary: string[] = [];
104
+ let current: { name: string; lines: string[] } | undefined;
105
+ let fenced = false;
106
+ for (const l of lines) {
107
+ if (/^\s*(```|~~~)/.test(l)) fenced = !fenced;
108
+ const tag = fenced ? null : /^@(\w+)\s?(.*)$/.exec(l.trim());
109
+ if (tag !== null) {
110
+ if (current !== undefined) tags.push({ name: current.name, text: current.lines.join("\n") });
111
+ current = { name: tag[1] ?? "", lines: tag[2] === undefined || tag[2] === "" ? [] : [tag[2]] };
112
+ continue;
113
+ }
114
+ if (current === undefined) summary.push(l);
115
+ else current.lines.push(l);
116
+ }
117
+ if (current !== undefined) tags.push({ name: current.name, text: current.lines.join("\n") });
118
+ return docOf(summary.join("\n"), tags);
119
+ }
120
+
121
+ /**
122
+ * The module comment of a source file: its first `/** ... *\/` comment (after any `//` lines, such as a `// Spec:` header), where that comment says `@module`.
123
+ *
124
+ * @param source - the file's text
125
+ */
126
+ export function moduleComment(source: string): DocComment | undefined {
127
+ const m = /^\s*(?:#![^\n]*\n\s*)?(?:\/\/[^\n]*\n\s*)*\/\*\*([\s\S]*?)\*\//.exec(source);
128
+ if (m === null) return undefined;
129
+ const doc = parseComment(m[1] ?? "");
130
+ return doc.isModule ? doc : undefined;
131
+ }