(
opts: { check?: boolean } = {}
)
| 346 | * refreshes the doc automatically after it finalizes the artifact. |
| 347 | */ |
| 348 | export function generateReferenceDoc( |
| 349 | opts: { check?: boolean } = {} |
| 350 | ): { |
| 351 | identities: number; |
| 352 | areas: number; |
| 353 | files: number; |
| 354 | bytes: number; |
| 355 | changed: boolean; |
| 356 | } { |
| 357 | const check = opts.check ?? false; |
| 358 | |
| 359 | const { usage, manifest } = loadUsage(); |
| 360 | const corpus = loadCorpus(CORPUS_DIR); |
| 361 | const topicTitles = loadTopicTitles(); |
| 362 | const headDesc = loadHeadDescriptions(corpus.declarations); |
| 363 | const injected = loadInjected(); |
| 364 | const ce = createEngine(corpus.declarations); |
| 365 | const byId = new Map(corpus.entries.map((e) => [e.id, e])); |
| 366 | |
| 367 | // Resolve every used id to a source entry (corpus or curated injection). |
| 368 | const resolved: Resolved[] = []; |
| 369 | let unresolved = 0; |
| 370 | for (const id of usage.keys()) { |
| 371 | const e = byId.get(id) ?? injected.get(id); |
| 372 | if (!e) { |
| 373 | unresolved++; |
| 374 | continue; |
| 375 | } |
| 376 | resolved.push({ e, u: usage.get(id) }); |
| 377 | } |
| 378 | |
| 379 | // Group by topic. |
| 380 | const byTopic = new Map<string, Resolved[]>(); |
| 381 | for (const r of resolved) { |
| 382 | const topic = r.e.topic ?? r.e.topics?.[0] ?? 'misc'; |
| 383 | if (!byTopic.has(topic)) byTopic.set(topic, []); |
| 384 | byTopic.get(topic)!.push(r); |
| 385 | } |
| 386 | for (const list of byTopic.values()) list.sort((a, b) => a.e.id.localeCompare(b.e.id)); |
| 387 | |
| 388 | // Map topics -> areas; collect any unmapped covered topic into "Other". |
| 389 | const topicArea = new Map<string, string>(); |
| 390 | for (const a of AREAS) for (const t of a.topics) topicArea.set(t, a.slug); |
| 391 | const areas = AREAS.map((a) => ({ ...a })); |
| 392 | const orphanTopics: string[] = []; |
| 393 | for (const topic of byTopic.keys()) |
| 394 | if (!topicArea.has(topic)) orphanTopics.push(topic); |
| 395 | if (orphanTopics.length) { |
| 396 | areas.push({ |
| 397 | letter: 'z', |
| 398 | slug: 'other', |
| 399 | title: 'Other special functions', |
| 400 | topics: orphanTopics.sort(), |
| 401 | }); |
| 402 | } |
| 403 | |
| 404 | const short = manifest?.upstream?.snapshotSha256 |
| 405 | ? String(manifest.upstream.snapshotSha256).slice(0, 12) |
no test coverage detected