@abelxiaoxing/cadence 2.1.0 → 2.1.2
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/README.de.md +72 -76
- package/README.es.md +71 -75
- package/README.fr.md +72 -76
- package/README.ja.md +83 -101
- package/README.ko.md +81 -97
- package/README.md +71 -86
- package/README.pt-BR.md +72 -76
- package/README.ru.md +72 -77
- package/README.zh-CN.md +74 -84
- package/docs/reuse-and-distribution.md +1 -0
- package/package.json +5 -2
- package/src/native-build.ts +1 -1
- package/src/service/contracts/workbench.ts +82 -0
- package/src/service/knowledge-store.ts +496 -0
- package/src/service/project-knowledge.ts +539 -0
- package/src/service/workflow-git.ts +773 -0
- package/src/service-host.mjs +172 -83
- package/web/dist/assets/cadence.css +1 -1
- package/web/dist/assets/cadence.js +28 -28
- package/web/dist/manifest.json +7 -7
|
@@ -0,0 +1,496 @@
|
|
|
1
|
+
/** The managed project knowledge store: one route table and topic cards under a
|
|
2
|
+
* fixed budget. This module reads, measures and lints; it never writes. The
|
|
3
|
+
* store is a bounded cache of what cannot be cheaply re-derived from the code:
|
|
4
|
+
* new knowledge has to displace or compress old knowledge, and a delivery
|
|
5
|
+
* whose store is over budget does not pass. */
|
|
6
|
+
import { lstatSync, opendirSync, readFileSync } from "node:fs";
|
|
7
|
+
import { dirname, posix } from "node:path";
|
|
8
|
+
import { workflowCovers } from "./contracts/workflow.ts";
|
|
9
|
+
import { readKnowledgeFile } from "./project-knowledge.ts";
|
|
10
|
+
import { safeWorkflowFile } from "./workflow-git.ts";
|
|
11
|
+
|
|
12
|
+
export const KNOWLEDGE_STORE = {
|
|
13
|
+
/** Routes code areas to the documents and sections that own them. Every
|
|
14
|
+
* worker and the coordinator receive it whole. */
|
|
15
|
+
index: ".cadence/project.md",
|
|
16
|
+
topics: ".cadence/knowledge",
|
|
17
|
+
indexBytes: 4 * 1024,
|
|
18
|
+
topicBytes: 8 * 1024,
|
|
19
|
+
entryBytes: 1024,
|
|
20
|
+
totalBytes: 200 * 1024,
|
|
21
|
+
topicFiles: 64,
|
|
22
|
+
/** Curated deliveries without any worker being routed to a route's target
|
|
23
|
+
* before the curator is told it is a candidate for removal. */
|
|
24
|
+
idleDeliveries: 8,
|
|
25
|
+
} as const;
|
|
26
|
+
/** Paths a delivery may always maintain: the store itself. */
|
|
27
|
+
export const KNOWLEDGE_SCOPE: readonly string[] = [
|
|
28
|
+
KNOWLEDGE_STORE.index,
|
|
29
|
+
KNOWLEDGE_STORE.topics,
|
|
30
|
+
];
|
|
31
|
+
|
|
32
|
+
export interface KnowledgeRoute {
|
|
33
|
+
/** Code paths this route is for; a path covers itself and what is under it. */
|
|
34
|
+
patterns: string[];
|
|
35
|
+
/** The document to read first, and one of its headings when named. */
|
|
36
|
+
target: string;
|
|
37
|
+
section: string | null;
|
|
38
|
+
summary: string;
|
|
39
|
+
}
|
|
40
|
+
export interface KnowledgeAnchor {
|
|
41
|
+
path: string;
|
|
42
|
+
/** Text that must occur in the file: a symbol or a test name. */
|
|
43
|
+
symbol: string | null;
|
|
44
|
+
}
|
|
45
|
+
export interface KnowledgeEntry {
|
|
46
|
+
topic: string;
|
|
47
|
+
section: string | null;
|
|
48
|
+
title: string;
|
|
49
|
+
bytes: number;
|
|
50
|
+
anchors: KnowledgeAnchor[];
|
|
51
|
+
}
|
|
52
|
+
export interface KnowledgeTopic {
|
|
53
|
+
path: string;
|
|
54
|
+
bytes: number;
|
|
55
|
+
entries: KnowledgeEntry[];
|
|
56
|
+
}
|
|
57
|
+
export interface KnowledgeStore {
|
|
58
|
+
index: { bytes: number; routes: KnowledgeRoute[]; unparsed: string[] } | null;
|
|
59
|
+
topics: KnowledgeTopic[];
|
|
60
|
+
totalBytes: number;
|
|
61
|
+
/** More topic files exist than one observation reads. */
|
|
62
|
+
limited: boolean;
|
|
63
|
+
}
|
|
64
|
+
export interface KnowledgeFinding {
|
|
65
|
+
kind:
|
|
66
|
+
| "over-budget"
|
|
67
|
+
| "dead-route"
|
|
68
|
+
| "dead-anchor"
|
|
69
|
+
| "unanchored"
|
|
70
|
+
| "duplicate"
|
|
71
|
+
| "unparsed-route";
|
|
72
|
+
path: string;
|
|
73
|
+
detail: string;
|
|
74
|
+
/** Whether it fails the delivery, or is only handed to the curator and review. */
|
|
75
|
+
blocking: boolean;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/u;
|
|
79
|
+
const quoted = (text: string) =>
|
|
80
|
+
[...text.matchAll(/`([^`]+)`/gu)].map((match) => match[1].trim());
|
|
81
|
+
const slug = (text: string) =>
|
|
82
|
+
text
|
|
83
|
+
.toLowerCase()
|
|
84
|
+
.replace(/[^\p{L}\p{N}]+/gu, "-")
|
|
85
|
+
.replace(/^-|-$/gu, "");
|
|
86
|
+
const fenced = (line: string) => /^\s*(?:```|~~~)/u.test(line);
|
|
87
|
+
|
|
88
|
+
/** One section of a Markdown body: from the heading named `heading` (by its
|
|
89
|
+
* text or its slug) to the next heading of the same or a higher level. */
|
|
90
|
+
export function knowledgeSection(body: string, heading: string): string | null {
|
|
91
|
+
const lines = body.split("\n"),
|
|
92
|
+
wanted = slug(heading);
|
|
93
|
+
let start = -1,
|
|
94
|
+
level = 0,
|
|
95
|
+
code = false;
|
|
96
|
+
for (let i = 0; i < lines.length; i++) {
|
|
97
|
+
if (fenced(lines[i])) code = !code;
|
|
98
|
+
if (code) continue;
|
|
99
|
+
const match = HEADING.exec(lines[i]);
|
|
100
|
+
if (!match) continue;
|
|
101
|
+
if (start < 0) {
|
|
102
|
+
if (slug(match[2]) === wanted) {
|
|
103
|
+
start = i;
|
|
104
|
+
level = match[1].length;
|
|
105
|
+
}
|
|
106
|
+
} else if (match[1].length <= level)
|
|
107
|
+
return lines.slice(start, i).join("\n").trimEnd();
|
|
108
|
+
}
|
|
109
|
+
return start < 0 ? null : lines.slice(start).join("\n").trimEnd();
|
|
110
|
+
}
|
|
111
|
+
/** Route lines of the table's `## Routes` section:
|
|
112
|
+
* ``- `src/area`, `test/area` -> `docs/topic.md#Heading` — what it settles``. */
|
|
113
|
+
export function knowledgeRoutes(body: string): {
|
|
114
|
+
routes: KnowledgeRoute[];
|
|
115
|
+
unparsed: string[];
|
|
116
|
+
} {
|
|
117
|
+
const section = knowledgeSection(body, "Routes");
|
|
118
|
+
const routes: KnowledgeRoute[] = [],
|
|
119
|
+
unparsed: string[] = [];
|
|
120
|
+
for (const line of (section ?? "").split("\n").slice(1)) {
|
|
121
|
+
if (!/^\s*[-*]\s+/u.test(line)) continue;
|
|
122
|
+
const arrow =
|
|
123
|
+
/^\s*[-*]\s+(.+?)\s*(?:->|→)\s*`([^`#\s]+)(?:#([^`]+))?`\s*(?:(?:—|–|:|-)\s*(.*))?$/u.exec(
|
|
124
|
+
line,
|
|
125
|
+
);
|
|
126
|
+
const patterns = arrow ? quoted(arrow[1]) : [];
|
|
127
|
+
if (!arrow || !patterns.length) {
|
|
128
|
+
unparsed.push(line.trim().slice(0, 160));
|
|
129
|
+
continue;
|
|
130
|
+
}
|
|
131
|
+
routes.push({
|
|
132
|
+
patterns: patterns.map((p) => p.replace(/\/\*{1,2}$/u, "")),
|
|
133
|
+
target: posix.normalize(arrow[2]),
|
|
134
|
+
section: arrow[3]?.trim() || null,
|
|
135
|
+
summary: (arrow[4] ?? "").trim(),
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
return { routes, unparsed };
|
|
139
|
+
}
|
|
140
|
+
/** Routes whose code area an assignment's write paths touch, in table order. */
|
|
141
|
+
export function matchKnowledgeRoutes(
|
|
142
|
+
routes: readonly KnowledgeRoute[],
|
|
143
|
+
writes: readonly string[],
|
|
144
|
+
): KnowledgeRoute[] {
|
|
145
|
+
return routes.filter((route) =>
|
|
146
|
+
route.patterns.some(
|
|
147
|
+
(pattern) =>
|
|
148
|
+
workflowCovers([pattern], pattern) &&
|
|
149
|
+
writes.some(
|
|
150
|
+
(path) =>
|
|
151
|
+
workflowCovers([pattern], path) || workflowCovers([path], pattern),
|
|
152
|
+
),
|
|
153
|
+
),
|
|
154
|
+
);
|
|
155
|
+
}
|
|
156
|
+
/** A topic's entries: each `###` heading with its lines, and the anchors its
|
|
157
|
+
* `Anchors:` line names (`` `path` `` or `` `path#symbol` ``). */
|
|
158
|
+
export function knowledgeEntries(
|
|
159
|
+
topic: string,
|
|
160
|
+
body: string,
|
|
161
|
+
): KnowledgeEntry[] {
|
|
162
|
+
const lines = body.split("\n");
|
|
163
|
+
const entries: KnowledgeEntry[] = [];
|
|
164
|
+
let section: string | null = null,
|
|
165
|
+
current: { title: string; start: number } | undefined,
|
|
166
|
+
code = false;
|
|
167
|
+
const close = (end: number) => {
|
|
168
|
+
if (!current) return;
|
|
169
|
+
const text = lines.slice(current.start, end).join("\n");
|
|
170
|
+
const anchors = text
|
|
171
|
+
.split("\n")
|
|
172
|
+
.filter((line) => /^\s*Anchors?\s*:/iu.test(line))
|
|
173
|
+
.flatMap(quoted)
|
|
174
|
+
.map((value): KnowledgeAnchor => {
|
|
175
|
+
const at = value.indexOf("#");
|
|
176
|
+
return at < 0
|
|
177
|
+
? { path: posix.normalize(value), symbol: null }
|
|
178
|
+
: {
|
|
179
|
+
path: posix.normalize(value.slice(0, at)),
|
|
180
|
+
symbol: value.slice(at + 1).trim() || null,
|
|
181
|
+
};
|
|
182
|
+
});
|
|
183
|
+
entries.push({
|
|
184
|
+
topic,
|
|
185
|
+
section,
|
|
186
|
+
title: current.title,
|
|
187
|
+
bytes: Buffer.byteLength(text),
|
|
188
|
+
anchors,
|
|
189
|
+
});
|
|
190
|
+
current = undefined;
|
|
191
|
+
};
|
|
192
|
+
for (let i = 0; i < lines.length; i++) {
|
|
193
|
+
if (fenced(lines[i])) code = !code;
|
|
194
|
+
if (code) continue;
|
|
195
|
+
const match = HEADING.exec(lines[i]);
|
|
196
|
+
if (!match) continue;
|
|
197
|
+
if (match[1].length <= 3) close(i);
|
|
198
|
+
if (match[1].length === 2) section = match[2];
|
|
199
|
+
if (match[1].length === 3) current = { title: match[2], start: i };
|
|
200
|
+
}
|
|
201
|
+
close(lines.length);
|
|
202
|
+
return entries;
|
|
203
|
+
}
|
|
204
|
+
/** A fresh observation of the store. Unreadable or unsafe files are absent. */
|
|
205
|
+
export function readKnowledgeStore(root: string): KnowledgeStore {
|
|
206
|
+
const table = readKnowledgeFile(root, KNOWLEDGE_STORE.index);
|
|
207
|
+
const topics: KnowledgeTopic[] = [];
|
|
208
|
+
let limited = false;
|
|
209
|
+
let names: string[] = [];
|
|
210
|
+
try {
|
|
211
|
+
// Validates every ancestor; the probe names a file inside the directory.
|
|
212
|
+
const directory = dirname(
|
|
213
|
+
safeWorkflowFile(root, `${KNOWLEDGE_STORE.topics}/index.md`),
|
|
214
|
+
);
|
|
215
|
+
if (lstatSync(directory).isDirectory()) {
|
|
216
|
+
const dir = opendirSync(directory);
|
|
217
|
+
try {
|
|
218
|
+
for (let e = dir.readSync(); e; e = dir.readSync()) {
|
|
219
|
+
if (!e.isFile() || !/\.md$/iu.test(e.name)) continue;
|
|
220
|
+
if (names.length >= KNOWLEDGE_STORE.topicFiles) {
|
|
221
|
+
limited = true;
|
|
222
|
+
break;
|
|
223
|
+
}
|
|
224
|
+
names.push(e.name);
|
|
225
|
+
}
|
|
226
|
+
} finally {
|
|
227
|
+
dir.closeSync();
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
} catch {
|
|
231
|
+
names = [];
|
|
232
|
+
}
|
|
233
|
+
for (const name of names.sort()) {
|
|
234
|
+
const path = `${KNOWLEDGE_STORE.topics}/${name}`;
|
|
235
|
+
const file = readKnowledgeFile(root, path);
|
|
236
|
+
if (!file) continue;
|
|
237
|
+
topics.push({
|
|
238
|
+
path,
|
|
239
|
+
// A file longer than one read is measured by what was read: already over.
|
|
240
|
+
bytes: file.truncated
|
|
241
|
+
? Number.MAX_SAFE_INTEGER
|
|
242
|
+
: Buffer.byteLength(file.body),
|
|
243
|
+
entries: knowledgeEntries(path, file.body),
|
|
244
|
+
});
|
|
245
|
+
}
|
|
246
|
+
const index = table
|
|
247
|
+
? {
|
|
248
|
+
bytes: table.truncated
|
|
249
|
+
? Number.MAX_SAFE_INTEGER
|
|
250
|
+
: Buffer.byteLength(table.body),
|
|
251
|
+
...knowledgeRoutes(table.body),
|
|
252
|
+
}
|
|
253
|
+
: null;
|
|
254
|
+
return {
|
|
255
|
+
index,
|
|
256
|
+
topics,
|
|
257
|
+
limited,
|
|
258
|
+
totalBytes:
|
|
259
|
+
(index?.bytes ?? 0) + topics.reduce((sum, topic) => sum + topic.bytes, 0),
|
|
260
|
+
};
|
|
261
|
+
}
|
|
262
|
+
function fileHas(root: string, path: string, symbol: string | null): boolean {
|
|
263
|
+
if (/\.md$/iu.test(path)) {
|
|
264
|
+
const file = readKnowledgeFile(root, path);
|
|
265
|
+
return !!file && (symbol === null || file.body.includes(symbol));
|
|
266
|
+
}
|
|
267
|
+
try {
|
|
268
|
+
const stat = lstatSync(safeWorkflowFile(root, path));
|
|
269
|
+
if (!stat.isFile() && !stat.isDirectory()) return false;
|
|
270
|
+
if (symbol === null) return true;
|
|
271
|
+
if (!stat.isFile() || stat.size > 4 * 1024 * 1024) return false;
|
|
272
|
+
return readSource(root, path).includes(symbol);
|
|
273
|
+
} catch {
|
|
274
|
+
return false;
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
function readSource(root: string, path: string): string {
|
|
278
|
+
return readFileSync(safeWorkflowFile(root, path), "utf8");
|
|
279
|
+
}
|
|
280
|
+
const size = (bytes: number) =>
|
|
281
|
+
bytes === Number.MAX_SAFE_INTEGER ? "more than one read" : `${bytes} bytes`;
|
|
282
|
+
|
|
283
|
+
/** What a route leads to, as readers and the usage record name it. */
|
|
284
|
+
export const routeLabel = (
|
|
285
|
+
route: Pick<KnowledgeRoute, "target" | "section">,
|
|
286
|
+
) => (route.section ? `${route.target}#${route.section}` : route.target);
|
|
287
|
+
/** How the store has been used, counted in curated deliveries. The owner
|
|
288
|
+
* keeps it in its private state: it decides which topic is looked over next
|
|
289
|
+
* and which routes nothing has needed for a long time. Nothing is pinned and
|
|
290
|
+
* nothing here is knowledge; losing it only restarts the counting. */
|
|
291
|
+
export interface KnowledgeUse {
|
|
292
|
+
deliveries: number;
|
|
293
|
+
/** By route label: the delivery it was first seen at and last routed in. */
|
|
294
|
+
routes: Record<string, { first: number; used?: number }>;
|
|
295
|
+
/** By topic path: the delivery that last looked it over. */
|
|
296
|
+
topics: Record<string, { reviewed: number }>;
|
|
297
|
+
}
|
|
298
|
+
export function decodeKnowledgeUse(value: unknown): KnowledgeUse {
|
|
299
|
+
const count = (v: unknown) => {
|
|
300
|
+
if (!Number.isSafeInteger(v) || (v as number) < 0)
|
|
301
|
+
throw new Error("Invalid knowledge use");
|
|
302
|
+
return v as number;
|
|
303
|
+
};
|
|
304
|
+
const record = (v: unknown) => {
|
|
305
|
+
if (!v || typeof v !== "object" || Array.isArray(v))
|
|
306
|
+
throw new Error("Invalid knowledge use");
|
|
307
|
+
return Object.entries(v as Record<string, unknown>);
|
|
308
|
+
};
|
|
309
|
+
const o = Object.fromEntries(record(value));
|
|
310
|
+
return {
|
|
311
|
+
deliveries: count(o.deliveries),
|
|
312
|
+
routes: Object.fromEntries(
|
|
313
|
+
record(o.routes).map(([label, entry]) => {
|
|
314
|
+
const e = Object.fromEntries(record(entry));
|
|
315
|
+
return [
|
|
316
|
+
label,
|
|
317
|
+
{
|
|
318
|
+
first: count(e.first),
|
|
319
|
+
...(e.used === undefined ? {} : { used: count(e.used) }),
|
|
320
|
+
},
|
|
321
|
+
];
|
|
322
|
+
}),
|
|
323
|
+
),
|
|
324
|
+
topics: Object.fromEntries(
|
|
325
|
+
record(o.topics).map(([path, entry]) => [
|
|
326
|
+
path,
|
|
327
|
+
{ reviewed: count(Object.fromEntries(record(entry)).reviewed) },
|
|
328
|
+
]),
|
|
329
|
+
),
|
|
330
|
+
};
|
|
331
|
+
}
|
|
332
|
+
/** One more curated delivery: `routed` are the routes its workers were given.
|
|
333
|
+
* Returns the record to keep, the topic that has gone longest without a look
|
|
334
|
+
* (now marked as looked over) and the routes idle for `idleDeliveries`.
|
|
335
|
+
* Routes and topics no longer in the store are forgotten. */
|
|
336
|
+
export function advanceKnowledgeUse(
|
|
337
|
+
previous: KnowledgeUse | null,
|
|
338
|
+
store: { routes: readonly string[]; topics: readonly string[] },
|
|
339
|
+
routed: Iterable<string>,
|
|
340
|
+
): { use: KnowledgeUse; rotation: string | null; idle: string[] } {
|
|
341
|
+
const deliveries = (previous?.deliveries ?? 0) + 1;
|
|
342
|
+
const given = new Set(routed);
|
|
343
|
+
const routes: KnowledgeUse["routes"] = {};
|
|
344
|
+
for (const label of store.routes) {
|
|
345
|
+
const known = previous?.routes[label];
|
|
346
|
+
routes[label] = {
|
|
347
|
+
first: known?.first ?? deliveries,
|
|
348
|
+
...(given.has(label)
|
|
349
|
+
? { used: deliveries }
|
|
350
|
+
: known?.used === undefined
|
|
351
|
+
? {}
|
|
352
|
+
: { used: known.used }),
|
|
353
|
+
};
|
|
354
|
+
}
|
|
355
|
+
const topics: KnowledgeUse["topics"] = {};
|
|
356
|
+
let rotation: string | null = null;
|
|
357
|
+
for (const path of store.topics) {
|
|
358
|
+
const reviewed = previous?.topics[path]?.reviewed ?? 0;
|
|
359
|
+
if (reviewed) topics[path] = { reviewed };
|
|
360
|
+
if (rotation === null || reviewed < (topics[rotation]?.reviewed ?? 0))
|
|
361
|
+
rotation = path;
|
|
362
|
+
}
|
|
363
|
+
if (rotation !== null) topics[rotation] = { reviewed: deliveries };
|
|
364
|
+
return {
|
|
365
|
+
use: { deliveries, routes, topics },
|
|
366
|
+
rotation,
|
|
367
|
+
idle: Object.entries(routes)
|
|
368
|
+
.filter(
|
|
369
|
+
([, entry]) =>
|
|
370
|
+
deliveries - (entry.used ?? entry.first) >=
|
|
371
|
+
KNOWLEDGE_STORE.idleDeliveries,
|
|
372
|
+
)
|
|
373
|
+
.map(([label]) => label),
|
|
374
|
+
};
|
|
375
|
+
}
|
|
376
|
+
export interface KnowledgeLint {
|
|
377
|
+
findings: KnowledgeFinding[];
|
|
378
|
+
/** What the route table leads to, by label. */
|
|
379
|
+
routes: string[];
|
|
380
|
+
/** Entries about code this delivery changed: the curator checks them again. */
|
|
381
|
+
revalidate: KnowledgeEntry[];
|
|
382
|
+
usage: {
|
|
383
|
+
indexBytes: number;
|
|
384
|
+
totalBytes: number;
|
|
385
|
+
topics: { path: string; bytes: number; entries: number }[];
|
|
386
|
+
};
|
|
387
|
+
}
|
|
388
|
+
/** Deterministic checks of the store against the tree at `root`. `changed` is
|
|
389
|
+
* what this delivery changed: a budget violation always fails it; a broken
|
|
390
|
+
* reference fails it only where this delivery wrote the entry or moved its
|
|
391
|
+
* target, and is otherwise a note for the curator and the review. */
|
|
392
|
+
export function lintKnowledge(
|
|
393
|
+
root: string,
|
|
394
|
+
changed: readonly string[],
|
|
395
|
+
): KnowledgeLint {
|
|
396
|
+
const store = readKnowledgeStore(root);
|
|
397
|
+
const touched = (path: string) => workflowCovers(changed, path);
|
|
398
|
+
const findings: KnowledgeFinding[] = [];
|
|
399
|
+
const over = (path: string, detail: string) =>
|
|
400
|
+
findings.push({ kind: "over-budget", path, detail, blocking: true });
|
|
401
|
+
if (store.index && store.index.bytes > KNOWLEDGE_STORE.indexBytes)
|
|
402
|
+
over(
|
|
403
|
+
KNOWLEDGE_STORE.index,
|
|
404
|
+
`the route table is ${size(store.index.bytes)}; its budget is ${KNOWLEDGE_STORE.indexBytes}`,
|
|
405
|
+
);
|
|
406
|
+
if (store.limited)
|
|
407
|
+
over(
|
|
408
|
+
KNOWLEDGE_STORE.topics,
|
|
409
|
+
`more than ${KNOWLEDGE_STORE.topicFiles} topic files`,
|
|
410
|
+
);
|
|
411
|
+
if (store.totalBytes > KNOWLEDGE_STORE.totalBytes)
|
|
412
|
+
over(
|
|
413
|
+
KNOWLEDGE_STORE.topics,
|
|
414
|
+
`the store is ${size(store.totalBytes)}; its budget is ${KNOWLEDGE_STORE.totalBytes}`,
|
|
415
|
+
);
|
|
416
|
+
for (const line of store.index?.unparsed ?? [])
|
|
417
|
+
findings.push({
|
|
418
|
+
kind: "unparsed-route",
|
|
419
|
+
path: KNOWLEDGE_STORE.index,
|
|
420
|
+
detail: line,
|
|
421
|
+
blocking: touched(KNOWLEDGE_STORE.index),
|
|
422
|
+
});
|
|
423
|
+
for (const route of store.index?.routes ?? []) {
|
|
424
|
+
const target = readKnowledgeFile(root, route.target);
|
|
425
|
+
if (
|
|
426
|
+
!target ||
|
|
427
|
+
(route.section !== null &&
|
|
428
|
+
knowledgeSection(target.body, route.section) === null)
|
|
429
|
+
)
|
|
430
|
+
findings.push({
|
|
431
|
+
kind: "dead-route",
|
|
432
|
+
path: KNOWLEDGE_STORE.index,
|
|
433
|
+
detail: `${route.target}${route.section ? `#${route.section}` : ""} does not resolve`,
|
|
434
|
+
blocking: touched(KNOWLEDGE_STORE.index) || touched(route.target),
|
|
435
|
+
});
|
|
436
|
+
}
|
|
437
|
+
const revalidate: KnowledgeEntry[] = [];
|
|
438
|
+
for (const topic of store.topics) {
|
|
439
|
+
const mine = touched(topic.path);
|
|
440
|
+
if (topic.bytes > KNOWLEDGE_STORE.topicBytes)
|
|
441
|
+
over(
|
|
442
|
+
topic.path,
|
|
443
|
+
`the topic is ${size(topic.bytes)}; its budget is ${KNOWLEDGE_STORE.topicBytes}`,
|
|
444
|
+
);
|
|
445
|
+
const seen = new Set<string>();
|
|
446
|
+
for (const entry of topic.entries) {
|
|
447
|
+
if (entry.bytes > KNOWLEDGE_STORE.entryBytes)
|
|
448
|
+
over(
|
|
449
|
+
topic.path,
|
|
450
|
+
`entry "${entry.title}" is ${entry.bytes} bytes; an entry's budget is ${KNOWLEDGE_STORE.entryBytes}`,
|
|
451
|
+
);
|
|
452
|
+
const key = slug(entry.title);
|
|
453
|
+
if (seen.has(key))
|
|
454
|
+
findings.push({
|
|
455
|
+
kind: "duplicate",
|
|
456
|
+
path: topic.path,
|
|
457
|
+
detail: `entry "${entry.title}" appears more than once`,
|
|
458
|
+
blocking: mine,
|
|
459
|
+
});
|
|
460
|
+
seen.add(key);
|
|
461
|
+
if (!entry.anchors.length)
|
|
462
|
+
findings.push({
|
|
463
|
+
kind: "unanchored",
|
|
464
|
+
path: topic.path,
|
|
465
|
+
detail: `entry "${entry.title}" names no anchor`,
|
|
466
|
+
blocking: mine,
|
|
467
|
+
});
|
|
468
|
+
for (const anchor of entry.anchors) {
|
|
469
|
+
const moved = touched(anchor.path);
|
|
470
|
+
if (!fileHas(root, anchor.path, anchor.symbol))
|
|
471
|
+
findings.push({
|
|
472
|
+
kind: "dead-anchor",
|
|
473
|
+
path: topic.path,
|
|
474
|
+
detail: `entry "${entry.title}": ${anchor.path}${anchor.symbol ? `#${anchor.symbol}` : ""} does not resolve`,
|
|
475
|
+
blocking: mine || moved,
|
|
476
|
+
});
|
|
477
|
+
}
|
|
478
|
+
if (entry.anchors.some((anchor) => touched(anchor.path)))
|
|
479
|
+
revalidate.push(entry);
|
|
480
|
+
}
|
|
481
|
+
}
|
|
482
|
+
return {
|
|
483
|
+
findings,
|
|
484
|
+
routes: [...new Set((store.index?.routes ?? []).map(routeLabel))],
|
|
485
|
+
revalidate,
|
|
486
|
+
usage: {
|
|
487
|
+
indexBytes: store.index?.bytes ?? 0,
|
|
488
|
+
totalBytes: store.totalBytes,
|
|
489
|
+
topics: store.topics.map((topic) => ({
|
|
490
|
+
path: topic.path,
|
|
491
|
+
bytes: topic.bytes,
|
|
492
|
+
entries: topic.entries.length,
|
|
493
|
+
})),
|
|
494
|
+
},
|
|
495
|
+
};
|
|
496
|
+
}
|