@orkestrel/scaffold 0.0.114 → 0.0.116
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/dist/bin/main.js +137 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +5 -7
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/claude/rules/tests.md +7 -4
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- package/dist/host/guides/abort.md +17 -17
- package/dist/host/guides/agent.md +445 -445
- package/dist/host/guides/brief.md +143 -143
- package/dist/host/guides/browser.md +731 -731
- package/dist/host/guides/budget.md +39 -39
- package/dist/host/guides/capture.md +298 -298
- package/dist/host/guides/console.md +109 -109
- package/dist/host/guides/contract.md +335 -335
- package/dist/host/guides/csv.md +30 -30
- package/dist/host/guides/database.md +163 -163
- package/dist/host/guides/emitter.md +17 -17
- package/dist/host/guides/form.md +99 -99
- package/dist/host/guides/guide.md +361 -183
- package/dist/host/guides/html.md +49 -49
- package/dist/host/guides/indexeddb.md +40 -40
- package/dist/host/guides/interpret.md +139 -139
- package/dist/host/guides/lsp.md +114 -114
- package/dist/host/guides/markdown.md +68 -68
- package/dist/host/guides/mcp.md +3745 -3745
- package/dist/host/guides/middleware.md +170 -170
- package/dist/host/guides/msg.md +95 -95
- package/dist/host/guides/ndjson.md +8 -8
- package/dist/host/guides/ollama.md +56 -56
- package/dist/host/guides/pool.md +21 -21
- package/dist/host/guides/probe.md +82 -82
- package/dist/host/guides/process.md +99 -99
- package/dist/host/guides/program.md +98 -96
- package/dist/host/guides/qualifier.md +70 -70
- package/dist/host/guides/queue.md +37 -37
- package/dist/host/guides/rater.md +38 -38
- package/dist/host/guides/reason.md +308 -308
- package/dist/host/guides/relation.md +50 -50
- package/dist/host/guides/router.md +58 -58
- package/dist/host/guides/scaffold.md +554 -419
- package/dist/host/guides/sea.md +128 -128
- package/dist/host/guides/server.md +100 -100
- package/dist/host/guides/sqlite.md +28 -28
- package/dist/host/guides/sse.md +20 -20
- package/dist/host/guides/study.md +444 -444
- package/dist/host/guides/table.md +82 -82
- package/dist/host/guides/template.md +41 -41
- package/dist/host/guides/terminal.md +121 -121
- package/dist/host/guides/test.md +273 -273
- package/dist/host/guides/timeout.md +18 -18
- package/dist/host/guides/tool.md +27 -27
- package/dist/host/guides/toolbox.md +166 -166
- package/dist/host/guides/websocket.md +54 -54
- package/dist/host/guides/worker.md +24 -24
- package/dist/host/guides/workflow.md +187 -187
- package/dist/host/guides/workspace.md +55 -55
- package/dist/host/manifest.json +93 -93
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +89 -3
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +229 -144
- package/dist/src/core/index.d.ts +229 -144
- package/dist/src/core/index.js +87 -4
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +292 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +188 -6
- package/dist/src/server/index.d.ts +188 -6
- package/dist/src/server/index.js +287 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +4 -3
|
@@ -14,27 +14,52 @@ consumer's own import specifiers onto those views, one shared `Source` per modul
|
|
|
14
14
|
that meets an import decides from the specifier alone which face of the package it names. A
|
|
15
15
|
guides-parity test asserts direct declarations equal the barrel surface and the barrel surface
|
|
16
16
|
equals the documented surface, in both directions, and `findDrift` reports where a `Summary`
|
|
17
|
-
cell, a documented method, or a titled fence disagrees with the source it
|
|
17
|
+
cell, a `Signature` cell, a documented method, or a titled fence disagrees with the source it
|
|
18
|
+
documents.
|
|
18
19
|
`parseManifest` reads a `guides/README.md`'s `## By concept` table into the list of
|
|
19
20
|
`{ concept, spec, source, tests }` entries a suite iterates to run this check once per documented
|
|
20
21
|
concept. [`GuideCommand`](../src/server/GuideCommand.ts) supplies the Node shell shared by package
|
|
21
22
|
guide scripts. It keeps package assertions in a worker callback while it owns native argument
|
|
22
23
|
selection, fresh inventory reads, explicit writes, the guides-project run, reporting, and exit
|
|
23
|
-
precedence.
|
|
24
|
+
precedence. [`GuideCompiler`](../src/server/GuideCompiler.ts) emits each documented module's
|
|
25
|
+
declarations through the workspace's own TypeScript compiler, the projection every `Signature`
|
|
26
|
+
cell is computed from. This package publishes core through `@orkestrel/guide` and the command through
|
|
24
27
|
`@orkestrel/guide/server`; its source is [`src/core`](../src/core) and
|
|
25
28
|
[`src/server`](../src/server).
|
|
26
29
|
|
|
27
30
|
## Surface
|
|
28
31
|
|
|
32
|
+
Every table uses `Name | Kind | Signature | Summary`, in that order. Each `Signature` cell is the
|
|
33
|
+
compiler's projection of the declaration, not a style an author writes: `GuideCompiler` emits the
|
|
34
|
+
module's declarations under the workspace's pinned TypeScript compiler, `extractSignatures` prints
|
|
35
|
+
each one from the emitted `.d.ts` text, and `npm run test:guides -- --to guide` writes the result
|
|
36
|
+
as one code span, with every `|` written `\|` and a longer backtick fence where the type holds a
|
|
37
|
+
backtick. The printed forms:
|
|
38
|
+
|
|
39
|
+
- `function`: `<T>(params) => RET` from the emitted head; an overload set is its emitted heads in
|
|
40
|
+
order, each parenthesized, joined with `&`.
|
|
41
|
+
- `class`: `new <T>(params) => YIELD` per emitted constructor, several as an intersection, none as
|
|
42
|
+
`new () => YIELD`; `YIELD` is the first `implements` type, else the class's own name with its type
|
|
43
|
+
parameters. Fields, methods, and `#private` are not read.
|
|
44
|
+
- `interface`: its own members in emitted order — `name`, `name?`, `name()` (an overloaded method
|
|
45
|
+
once), and a call, construct, or index signature as its collapsed text; the `extends` clause is
|
|
46
|
+
not printed.
|
|
47
|
+
- `type`: the aliased type, type parameters omitted, a multi-line body joined with single spaces.
|
|
48
|
+
- `const`: the declared type as the compiler emitted it, quote style included; an unannotated
|
|
49
|
+
literal prints the literal the compiler emitted as its type.
|
|
50
|
+
|
|
51
|
+
Guide construction refuses an empty cell, and `GuideCompiler` refuses a module whose project emits
|
|
52
|
+
no declaration under it rather than computing no signature; `findDrift` reports a present cell that differs from
|
|
53
|
+
the computed signature as `signature` drift.
|
|
54
|
+
|
|
29
55
|
### Types
|
|
30
56
|
|
|
31
57
|
The manifest/extraction shapes every check is built from, from [`types.ts`](../src/core/types.ts).
|
|
32
|
-
A `Shape` cell lists an interface's property names alone, and a type alias's value.
|
|
33
58
|
|
|
34
|
-
| Name | Kind |
|
|
59
|
+
| Name | Kind | Signature | Summary |
|
|
35
60
|
| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
36
|
-
| `ExportKeyword` | type | `
|
|
37
|
-
| `SurfaceSymbol` | interface | `{ name, keyword, summary? }`
|
|
61
|
+
| `ExportKeyword` | type | `(typeof EXPORT_KEYWORDS)[number]` | Represents the declaration keyword a documented / exported symbol carries — the reflected `type`, `interface`, `const`, `function`, and `class` heads, derived from `EXPORT_KEYWORDS` so the type, the guard, and the shape name one population. Comment/template payload is excluded before reflection. `enum` is outside this population, not forbidden by general package policy. |
|
|
62
|
+
| `SurfaceSymbol` | interface | `{ name, keyword, signature?, summary? }` | Represents one documented / exported symbol — its identifier, its declaration keyword, its optional guide signature, and the description paragraph the guide and the doc block are compared on. |
|
|
38
63
|
| `GuideModule` | type | `string \| readonly string[]` | Represents the source scope a guide's manifest entry covers — one module directory, or several when a layer guide spans multiple source directories (a core module plus its backend implementations). `'.'` is the canonical workspace-root directory; empty, trailing-slash, and dot-segment spellings canonicalize to the same value before reflection. |
|
|
39
64
|
| `SourceLine` | interface | `{ source, code, jsdoc }` | Represents one terminator-free physical source line and its aligned reflection projections. Every projection has the same length as `source`, and every genuine JSDoc span retains its physical opener column; the final physical line is present even when it is empty. |
|
|
40
65
|
| `SourceParenthesis` | interface | `{ role, phase, binding, previous }` | Represents one parenthesis frame in the source projector's lexical stack. |
|
|
@@ -43,11 +68,11 @@ A `Shape` cell lists an interface's property names alone, and a type alias's val
|
|
|
43
68
|
| `SourceComment` | interface | `{ text, line }` | Represents one eligible genuine JSDoc block paired with the physical record it documents — the block's unwrapped body and the `SourceLine` that follows its chain. |
|
|
44
69
|
| `MethodEntry` | interface | `{ name, summary? }` | Represents one documented method — its identifier plus the description paragraph the guide's `Summary` cell and the member's doc block are compared on. |
|
|
45
70
|
| `SourceExample` | interface | `{ name, title?, code, language? }` | Represents one `@example` block read from a doc comment — the declaration it documents, its pairing title, its code, and its fence language. |
|
|
46
|
-
| `DriftCategory` | type | `
|
|
47
|
-
| `Drift` | interface | `{
|
|
71
|
+
| `DriftCategory` | type | `(typeof DRIFT_CATEGORIES)[number]` | Represents the compared site one disagreement came from. |
|
|
72
|
+
| `Drift` | interface | `{ category, key, guide?, source? }` | Represents one disagreement between a guide and the source it documents — the compared key with the text each side carries there, the side carrying no text omitted. |
|
|
48
73
|
| `ManifestEntry` | interface | `{ concept, spec, source, tests }` | Represents one `## By concept` manifest row — a single guides-parity check target, paths normalized to workspace root. |
|
|
49
74
|
| `ParityPitch` | interface | `{ readme, spec }` | Names the inventory keys paired for README pitch parity. |
|
|
50
|
-
| `ParityOptions` | interface | `{ files, entries, modules, languages, language, pitch? }`
|
|
75
|
+
| `ParityOptions` | interface | `{ files, entries, modules, languages, language, pitch?, declarations? }` | Represents the pure inputs that configure a guides-parity composition. |
|
|
51
76
|
| `ParityRow` | interface | `{ entry, guide, source }` | Represents a manifest row joined to its parsed guide and reflected source. |
|
|
52
77
|
| `ParityFinding` | interface | `{ spec?, text }` | Represents a preformatted guides-parity finding. |
|
|
53
78
|
| `ParityExampleResult` | interface | `{ fences, functions, methods, titles }` | Groups executable-example findings by their independent evidence populations. |
|
|
@@ -55,14 +80,14 @@ A `Shape` cell lists an interface's property names alone, and a type alias's val
|
|
|
55
80
|
| `ParityDirection` | type | `'guide' \| 'source'` | Represents the destination an explicit parity rewrite updates. |
|
|
56
81
|
| `ParityChange` | interface | `{ path, content }` | Represents a changed inventory text returned by a parity rewrite. |
|
|
57
82
|
| `ParityRewriteResult` | interface | `{ changes, findings }` | Represents the changed texts and unresolved findings from an explicit rewrite. |
|
|
58
|
-
| `ParityInterface` | interface | `{ rows, inspect, document, annotate }`
|
|
83
|
+
| `ParityInterface` | interface | `{ rows(), inspect(), document(), annotate() }` | Represents a pure guides-parity composition over caller-supplied inventory. |
|
|
59
84
|
| `MethodGroup` | interface | `{ interface, methods }` | Represents one behavioral interface a guide's `## Methods` section documents — the H4 heading naming that interface as a code span, and the member entries its table lists. |
|
|
60
85
|
| `FenceImport` | interface | `{ specifier, names }` | Represents one brace `import` statement projected from a guide fence — its specifier paired with the exported names it binds. |
|
|
61
86
|
| `GuideFence` | interface | `{ language, code, title? }` | Represents one fenced code block projected from a guide document — its `language` is the fence's info-string tag and is absent when the fence is untagged, and its `title` is the flattened text of its nearest preceding heading. |
|
|
62
|
-
| `GuideInterface` | interface | `{ sections, tagline, surface, methods, unnamed, links, tests, fences }`
|
|
63
|
-
| `SourceInterface` | interface | `{ exports, surface, methods, exists, hidden, examples }`
|
|
64
|
-
| `SourceManagerInterface` | interface | `{ source, sources }`
|
|
65
|
-
| `SourceOptions` | interface | `{ files, module }`
|
|
87
|
+
| `GuideInterface` | interface | `{ sections(), tagline(), surface(), methods(), unnamed(), links(), tests(), fences() }` | Represents the structured, pure view of one parsed guide — every projection extracted and cached once at construction (see `createGuide`). |
|
|
88
|
+
| `SourceInterface` | interface | `{ exports(), surface(), methods(), exists(), hidden(), examples() }` | Represents the reflected source truth a guide's documented surface is checked against — a pure view over a consumer-supplied file inventory (see `Source`). |
|
|
89
|
+
| `SourceManagerInterface` | interface | `{ source(), sources() }` | Represents a specifier resolver that shares one `SourceInterface` per module and enumerates those views. |
|
|
90
|
+
| `SourceOptions` | interface | `{ files, module, declarations? }` | Represents the construction input for a `Source` — a consumer-supplied file inventory (root-relative path → file text) plus the module scope to reflect. The consumer gathers `files` however their environment allows (`node:fs` in a Node script, `import.meta.glob` in a browser/vitest run) — `Source` itself never touches disk. |
|
|
66
91
|
| `SourceManagerOptions` | interface | `{ files, modules }` | Represents the construction input for a `SourceManager`: one shared file inventory plus the consumer's specifier-to-module policy. |
|
|
67
92
|
| `DeclarationHead` | interface | `{ text, end }` | Pairs a declaration head joined into a single line with the index of the line carrying its opening `{` — how a head that oxfmt wrapped across lines (printWidth 100) is matched as if it were written on one. |
|
|
68
93
|
| `Declaration` | interface | `{ body, bases }` | Represents one located `export class` / `export interface` declaration — the body lines and the base identifiers read from the same head, so a consumer never pairs one declaration's body with another declaration's heritage (see `collectDeclarations`). |
|
|
@@ -70,15 +95,17 @@ A `Shape` cell lists an interface's property names alone, and a type alias's val
|
|
|
70
95
|
|
|
71
96
|
The server command contracts come from [`types.ts`](../src/server/types.ts).
|
|
72
97
|
|
|
73
|
-
| Name
|
|
74
|
-
|
|
|
75
|
-
| `GuideReadFunction`
|
|
76
|
-
| `GuideRunnerOptions`
|
|
77
|
-
| `GuideRunnerFunction`
|
|
78
|
-
| `GuideCommandContext`
|
|
79
|
-
| `GuideCommandHandler`
|
|
80
|
-
| `GuideCommandOptions`
|
|
81
|
-
| `GuideCommandInterface`
|
|
98
|
+
| Name | Kind | Signature | Summary |
|
|
99
|
+
| ------------------------ | --------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
100
|
+
| `GuideReadFunction` | type | `(root: URL \| string, targets: readonly string[]) => Readonly<Record<string, string>>` | Reads a workspace inventory through the consumer's host reader. |
|
|
101
|
+
| `GuideRunnerOptions` | interface | `{ root, config, project, reporters, cache, watch }` | Defines the fixed guides-project runner invocation. |
|
|
102
|
+
| `GuideRunnerFunction` | type | `(mode: 'test', options: GuideRunnerOptions) => Promise<unknown>` | Creates a foreign guides-project runner whose consumed members Guide validates before use. |
|
|
103
|
+
| `GuideCommandContext` | interface | `{ root, files, rows, report }` | Supplies fresh owned inventory, joined rows, and its generic parity result to package assertion setup. |
|
|
104
|
+
| `GuideCommandHandler` | type | `(context: GuideCommandContext) => Promise<void>` | Registers package assertions against the fresh worker context. |
|
|
105
|
+
| `GuideCommandOptions` | interface | `{ root, patterns, modules, languages, language, reader, runner }` | Configures workspace policy and direct host ports for the reusable command. |
|
|
106
|
+
| `GuideCommandInterface` | interface | `{ execute() }` | Represents the server command's native and worker behavior. |
|
|
107
|
+
| `GuideCompilerOptions` | interface | `{ root, timeout?, limit?, temporary? }` | Configures the workspace whose own TypeScript compiler emits a module's declarations. |
|
|
108
|
+
| `GuideCompilerInterface` | interface | `{ compile() }` | Represents the compiler projection that emits one module's declarations under the workspace's own TypeScript compiler. |
|
|
82
109
|
|
|
83
110
|
### Constants
|
|
84
111
|
|
|
@@ -86,27 +113,34 @@ The declaration-keyword population, the section-heading keys, and the external-l
|
|
|
86
113
|
extractor and link check is keyed on, from [`constants.ts`](../src/core/constants.ts). The server
|
|
87
114
|
workflow paths and usage text come from [`constants.ts`](../src/server/constants.ts).
|
|
88
115
|
|
|
89
|
-
| Name | Kind |
|
|
90
|
-
| ------------------ | ----- |
|
|
91
|
-
| `EXPORT_KEYWORDS` | const | `
|
|
92
|
-
| `DRIFT_CATEGORIES` | const | `
|
|
93
|
-
| `SURFACE` | const | `
|
|
94
|
-
| `METHODS` | const | `
|
|
95
|
-
| `TESTS` | const | `
|
|
96
|
-
| `MANIFEST` | const | `
|
|
97
|
-
| `KIND` | const | `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
116
|
+
| Name | Kind | Signature | Summary |
|
|
117
|
+
| ------------------ | ----- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `EXPORT_KEYWORDS` | const | `readonly ("class" \| "const" \| "function" \| "interface" \| "type")[]` | Lists the declaration keywords a documented or exported symbol carries, in the order the reflection grammar names them — the frozen population `ExportKeyword`, `isExportKeyword`, and `surfaceSymbolShape` all derive from. |
|
|
119
|
+
| `DRIFT_CATEGORIES` | const | `readonly ("example" \| "signature" \| "summary")[]` | Lists the compared sites a `Drift` can describe. |
|
|
120
|
+
| `SURFACE` | const | `string` | Names the `## Surface` heading text a guide's documented exports section is keyed on. |
|
|
121
|
+
| `METHODS` | const | `string` | Names the `## Methods` heading text a guide's documented interface-methods section is keyed on. |
|
|
122
|
+
| `TESTS` | const | `string` | Names the `## Tests` heading text a guide's documented test-link section is keyed on. |
|
|
123
|
+
| `MANIFEST` | const | `string` | Names the `## By concept` heading text the manifest's run-map table is keyed on. |
|
|
124
|
+
| `KIND` | const | `string` | Names the header text of the column a `## Surface` table's declaration keyword is read from. |
|
|
125
|
+
| `SIGNATURE` | const | `string` | Names the header text of the column a `## Surface` table's TypeScript signature is read from. |
|
|
126
|
+
| `SUMMARY` | const | `string` | Names the header text of the column a `## Surface` or `## Methods` table's compared description paragraph is read from. |
|
|
127
|
+
| `NAME` | const | `string` | Names the header text of a `## Surface` or `## Methods` table's first column, the symbol name. |
|
|
128
|
+
| `SURFACE_HEADER` | const | `readonly string[]` | Lists the uniform `## Surface` table header, column by column, that guide construction requires. |
|
|
129
|
+
| `EXTERNAL_SCHEMES` | const | `readonly string[]` | Lists the link `href` schemes a guides-parity link check skips as external — a link with one of these prefixes (or a bare `#` anchor, handled separately in `isExternalLink`) is never resolved against the filesystem. |
|
|
130
|
+
| `WRAP_WIDTH` | const | `number` | Holds the default character budget a rewritten doc block's description paragraph wraps inside — the greatest number of characters a re-wrapped line may carry, counted from the line's first character with a tab counting as one, so a wrapped line reads `${indent} * ${text}` and never passes that count. |
|
|
101
131
|
|
|
102
132
|
### Server constants
|
|
103
133
|
|
|
104
|
-
| Name
|
|
105
|
-
|
|
|
106
|
-
| `GUIDE_INDEX`
|
|
107
|
-
| `GUIDE_MANIFEST`
|
|
108
|
-
| `GUIDE_README`
|
|
109
|
-
| `GUIDE_USAGE`
|
|
134
|
+
| Name | Kind | Signature | Summary |
|
|
135
|
+
| ------------------------ | ----- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
|
136
|
+
| `GUIDE_INDEX` | const | `"guides/README.md"` | Names the workspace-relative guide concept index. |
|
|
137
|
+
| `GUIDE_MANIFEST` | const | `"package.json"` | Names the package manifest read for native pitch selection. |
|
|
138
|
+
| `GUIDE_README` | const | `"README.md"` | Names the package README paired with its indexed guide pitch. |
|
|
139
|
+
| `GUIDE_USAGE` | const | `"usage: npm run test:guides [-- --to guide\|--to source]"` | Holds the native command usage text written for unsupported arguments. |
|
|
140
|
+
| `GUIDE_SCRATCH_PREFIX` | const | `"orkestrel-guide-"` | Names the host temporary directory prefix of a declaration emit's scratch output. |
|
|
141
|
+
| `GUIDE_SCRATCH_RETRIES` | const | `3` | Holds the removal retries a declaration emit's scratch output takes on a busy host. |
|
|
142
|
+
| `GUIDE_COMPILER_TIMEOUT` | const | `300000` | Holds the default milliseconds one compiler run may take before it is stopped. |
|
|
143
|
+
| `GUIDE_COMPILER_LIMIT` | const | `number` | Holds the default bytes of output one compiler run may write to each stream, room for the diagnostics of a large failing project. |
|
|
110
144
|
|
|
111
145
|
### Helpers
|
|
112
146
|
|
|
@@ -115,90 +149,99 @@ the declaration, member, JSDoc, and guide-document grammars built on it, and the
|
|
|
115
149
|
path primitives `Guide`, `Source`, `parsers.ts`, and a consumer's parity test all reach for
|
|
116
150
|
directly.
|
|
117
151
|
|
|
118
|
-
| Name | Kind | Signature
|
|
119
|
-
| ----------------------- | -------- |
|
|
120
|
-
| `compareMembership` | function | `(spec: string, name: string, documented: readonly string[], declared: readonly string[]) => ParityFinding \| undefined`
|
|
121
|
-
| `identifyDrift` | function | `(spec: string, drift: Drift) => string`
|
|
122
|
-
| `formatSide` | function | `(value: string \| undefined) => string`
|
|
123
|
-
| `formatDrift` | function | `(drift: Drift) => string`
|
|
124
|
-
| `normalizeDirectories` | function | `(module: GuideModule) => readonly string[]`
|
|
125
|
-
| `computeModuleKey` | function | `(module: GuideModule) => string`
|
|
126
|
-
| `selectModuleKeys` | function | `(files: Readonly<Record<string, string>>, module: GuideModule) => readonly string[]`
|
|
127
|
-
| `hasCanonicalSegments` | function | `(key: string) => boolean`
|
|
128
|
-
| `computeSymbolKey` | function | `(symbol: SurfaceSymbol) => string`
|
|
129
|
-
| `findMissing` | function | `(names: readonly string[], source: readonly string[]) => readonly string[]`
|
|
130
|
-
| `findMissingSymbols` | function | `(symbols: readonly SurfaceSymbol[], source: readonly SurfaceSymbol[]) => readonly string[]`
|
|
131
|
-
| `hasBehaviouralSurface` | function | `(source: SourceInterface) => boolean`
|
|
132
|
-
| `extractSourceLines` | function | `(source: string) => readonly SourceLine[]`
|
|
133
|
-
| `extractExports` | function | `(source: string) => readonly SurfaceSymbol[]`
|
|
134
|
-
| `extractHidden` | function | `(source: string) => readonly SurfaceSymbol[]`
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `
|
|
171
|
-
| `
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
152
|
+
| Name | Kind | Signature | Summary |
|
|
153
|
+
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
154
|
+
| `compareMembership` | function | `(spec: string, name: string, documented: readonly string[], declared: readonly string[]) => ParityFinding \| undefined` | Compares documented and declared membership exactly after sorting copies, preserving duplicates. |
|
|
155
|
+
| `identifyDrift` | function | `(spec: string, drift: Drift) => string` | Computes a category-separated identity for a guide finding. |
|
|
156
|
+
| `formatSide` | function | `(value: string \| undefined) => string` | Formats present parity text as a JSON string and absent text as `absent`. |
|
|
157
|
+
| `formatDrift` | function | `(drift: Drift) => string` | Formats a categorized drift with its guide and source sides. |
|
|
158
|
+
| `normalizeDirectories` | function | `(module: GuideModule) => readonly string[]` | Normalizes a module scope to its canonical directory list. `'.'` represents workspace root; empty, trailing, and dot-segment spellings reduce through `resolvePath`, and duplicates are removed in first-seen order. |
|
|
159
|
+
| `computeModuleKey` | function | `(module: GuideModule) => string` | Computes the stable cache key for a `GuideModule`. Directories normalize before joining, so equivalent module spellings share one key. The NUL separator cannot occur in filesystem-backed canonical-segment inventory keys, so no directory boundary can collide with directory text. |
|
|
160
|
+
| `selectModuleKeys` | function | `(files: Readonly<Record<string, string>>, module: GuideModule) => readonly string[]` | Selects the exact opaque file-inventory keys belonging under any canonical `GuideModule` directory, sorted. `'.'` selects canonical root-relative keys without accepting `/`, `./`, or `../` aliases. Every selected exact `index.ts` and every `.test.ts` key is excluded independent of scope order. |
|
|
161
|
+
| `hasCanonicalSegments` | function | `(key: string) => boolean` | Checks whether an opaque inventory key contains only canonical slash-separated segments. Empty, `.` and `..` segments are rejected without rewriting the key; ordinary dotfile segments remain valid. |
|
|
162
|
+
| `computeSymbolKey` | function | `(symbol: SurfaceSymbol) => string` | Computes the bijection key for a surface symbol — `${keyword} ${name}` — so a symbol-set comparison diffs (name, keyword) pairs rather than names alone. |
|
|
163
|
+
| `findMissing` | function | `(names: readonly string[], source: readonly string[]) => readonly string[]` | Finds the names present in `names` but absent from `source` — the set-difference behind a both-directions bijection assertion. |
|
|
164
|
+
| `findMissingSymbols` | function | `(symbols: readonly SurfaceSymbol[], source: readonly SurfaceSymbol[]) => readonly string[]` | Finds the symbol-key set-difference between two symbol lists — `symbols` present but absent from `source`, compared by `computeSymbolKey` so a symbol can drift in neither name nor keyword. |
|
|
165
|
+
| `hasBehaviouralSurface` | function | `(source: SourceInterface) => boolean` | Checks whether a source declares at least one behavioural member — a `class` or `interface` in its surface that carries a call-signature member — so a guide owes a `## Methods` group only where the source has one to document. |
|
|
166
|
+
| `extractSourceLines` | function | `(source: string) => readonly SourceLine[]` | Extracts aligned physical source-line records in one character traversal. Real line and block comments and complete template tokens become spaces in `SourceLine.code`, while ordinary code, quoted strings, and recognized regex literals retain their columns. Genuine JSDoc opened from reflection code is retained span by span at its exact physical column in `SourceLine.jsdoc`; faux openers in comments and templates are excluded. Membership remains each consumer's separate anchored grammar. |
|
|
167
|
+
| `extractExports` | function | `(source: string) => readonly SurfaceSymbol[]` | Extracts the module-scope exports declared in one file's source text — the declaration keys `collectKeys` reports, each split back into the keyword and name that built it, deduped by (keyword, name). |
|
|
168
|
+
| `extractHidden` | function | `(source: string) => readonly SurfaceSymbol[]` | Extracts the module-scope declarations lacking the `export` keyword in one file's source text — the mirror image of `extractExports`'s grammar, anchored the same way (column 0, so an indented inner declaration never matches). |
|
|
169
|
+
| `computeDepths` | function | `(code: string) => readonly number[]` | Computes the bracket depth of every character of projected declaration code: an opening `(`, `[`, `{`, or `<` and its closing partner carry the depth outside the pair, the characters between them one more, and every character of a quoted string, its quotes included, `-1`. |
|
|
170
|
+
| `findClosing` | function | `(depths: readonly number[], start: number) => number \| undefined` | Finds the index of the bracket closing the opener at `start`: the first later character whose `computeDepths` depth equals the opener's. |
|
|
171
|
+
| `findSeparators` | function | `(code: string, depths: readonly number[], separator: string, depth: number) => readonly number[]` | Finds every index at which `separator` sits at `depth` outside quoted text, in code order. |
|
|
172
|
+
| `renderMember` | function | `(code: string, source: string) => string \| undefined` | Renders one emitted interface member as its signature entry: a property as its name, an optional one with `?`, a method as `name()` or `name?()`, an accessor as its name, and a call, construct, or index signature as its own text with whitespace collapsed. |
|
|
173
|
+
| `extractSignature` | function | `(code: string, source: string) => SurfaceSymbol \| undefined` | Extracts one emitted declaration's signature: the symbol its column-zero `export` head names, carrying the type text the compiler emitted for it. |
|
|
174
|
+
| `extractSignatures` | function | `(declaration: string) => readonly SurfaceSymbol[]` | Extracts every signature one compiler-emitted declaration file declares: each column-zero `export` head read through `extractSignature`, an overload set's emitted heads joined in order as an intersection of parenthesized signatures. |
|
|
175
|
+
| `joinHead` | function | `(lines: readonly string[], start: number) => DeclarationHead \| undefined` | Joins the declaration head starting at `start` into one space-separated line, consuming lines until the first that opens a body: one that ends with `{`, or one that closes an empty body with `{}` or `{ }`. |
|
|
176
|
+
| `escapeRegExp` | function | `(value: string) => string` | Escapes every regex metacharacter in a literal string so it reads as text inside a larger `RegExp` source rather than as syntax. |
|
|
177
|
+
| `collectDeclarations` | function | `(source: string) => ReadonlyMap<string, Declaration>` | Collects every `export class` / `export interface` declaration one file's source text declares, each keyed `${keyword} ${name}` and carrying the body lines and the base identifiers read from its own head, so a body and a heritage clause always come from the same declaration. |
|
|
178
|
+
| `extractDeclaration` | function | `(source: string, keyword: DeclarationKeyword, name: string) => Declaration \| undefined` | Locates the named `export class` / `export interface` declaration in one file's source text and returns its body lines and its base identifiers read from that one head, so a body and a heritage clause always come from the same declaration, or `undefined` when the file declares no such head. |
|
|
179
|
+
| `extractMemberMethods` | function | `(lines: readonly string[]) => readonly MethodEntry[]` | Selects the member lines declaring a callable member: plain, `async`, generator (`*`), and optional (`records?(`) methods all count; getters, setters, `static` members, and `#` privates never do (their keyword or `#` breaks the `name(` shape). The grammar is `collectKeys`'s, read once over `extractBodyLines`'s projection of the body, so commented method-like payload never becomes eligible and each member keys to the owner head that projection supplies. Each member carries its own doc block's description paragraph, read through `collectSummaries`; the first declaration of a name answers for it. |
|
|
180
|
+
| `extractSourceComments` | function | `(lines: readonly SourceLine[]) => readonly SourceComment[]` | Extracts every eligible genuine JSDoc block paired with the physical record it documents. |
|
|
181
|
+
| `normalizeComment` | function | `(comment: string) => string` | Returns the canonical body of one genuine JSDoc span — the `/**` opener, the closing marker, each line's continuation marker, and the block's leading indentation removed, with per-line trailing whitespace trimmed and the surrounding blank lines dropped. A line's own indentation beyond the marker is kept, so an `@example` fence body keeps the shape it was written in. |
|
|
182
|
+
| `unwrapComment` | function | `(comment: string) => readonly string[]` | Unwraps one genuine JSDoc span into one content line per physical line — the `/**` opener, the closing marker, each line's continuation marker, and per-line trailing whitespace removed, with a line's own indentation past the marker kept. The result is aligned with `comment.split('\n')`, so an index found in it addresses the same physical line of the span it was built from, which is what lets a rewrite keep every line it does not replace. `normalizeComment` is this projection joined and trimmed at its ends. |
|
|
183
|
+
| `buildComment` | function | `(lines: readonly string[], indent: string) => string` | Builds one genuine JSDoc span from its content lines — the inverse of `unwrapComment`. Each line is emitted at `indent` behind a continuation marker, an empty line as the bare marker so no line carries trailing whitespace, and the leading and trailing empty lines are dropped because the opener and the closer take those physical lines. |
|
|
184
|
+
| `wrapText` | function | `(text: string, width: number) => readonly string[]` | Wraps one paragraph into greedy lines no longer than `width` characters. Every run of whitespace separates words, and a word longer than `width` takes its own line rather than being split, so a long code token or URL survives the wrap intact. |
|
|
185
|
+
| `normalizeSummary` | function | `(text: string) => string` | Returns the canonical compared form of a description paragraph. `{@link Target}` and `{@link Target \| label}` become the code token of the target text, or of the label where one is written; a target's module part — the inline import form `import('./module.js').` and TSDoc's package-qualified form `@scope/pkg#` — is dropped first. Every run of whitespace, including a collapsed continuation marker and a line break, becomes one space, the ends trim, and a code span keeps its delimiters while its own boundary whitespace goes. The guide's side and the source's side read through this one form. |
|
|
186
|
+
| `maskFences` | function | `(text: string) => string` | Returns one doc block's unwrapped text with every fenced body replaced by aligned spaces, so a tag search reads the block's structure and never its example code. A line opening with three or more backticks or tildes opens a body, the first line opening with a run of the same character at least as long closes it, an unclosed body runs to the end, and the marker lines themselves stay. The projection preserves every line and every column, so an index found in it addresses the same character of the text it was built from. |
|
|
187
|
+
| `collectSummaries` | function | `(lines: readonly SourceLine[]) => ReadonlyMap<SourceLine, string>` | Collects the description paragraph of every documented physical record — a doc block's text before its first block tag, in `normalizeSummary`'s compared form — keyed by the record it documents. A record whose block carries no description contributes no entry, so an absent summary stays absent rather than becoming an empty string. |
|
|
188
|
+
| `extractBodyLines` | function | `(lines: readonly string[]) => readonly SourceLine[]` | Extracts the aligned physical records of a declaration's body, read inside an owner head this function supplies, so a callable member in the body carries the `Owner.member` key `collectKeys` reports for it, and that head's own record opens the projection. A body read on its own carries no head, and the member grammar attaches a member to the head enclosing it. |
|
|
189
|
+
| `collectKeys` | function | `(lines: readonly SourceLine[]) => ReadonlyMap<SourceLine, string>` | Collects the compared key of every physical record a key names — a `computeSymbolKey` symbol key for a column-zero `export` declaration head, an `Owner.member` key for a one-tab callable member inside one — keyed by the record itself. The owner closes at the first column-zero `}` or at a column-zero `export` declaration carrying another keyword, and a record no key names contributes no entry. |
|
|
190
|
+
| `collectExamples` | function | `(comment: string, name: string) => readonly SourceExample[]` | Collects the `@example` blocks one doc block's unwrapped text carries, each named for the declaration or member the block documents. The text after the tag becomes the block's `title`; a body opening with a fence contributes that fence's language and its verbatim body, and a body with no fence contributes its own trimmed text as the code. |
|
|
191
|
+
| `extractExampleLines` | function | `(lines: readonly SourceLine[]) => readonly SourceLine[]` | Selects the next physical record after an eligible genuine JSDoc whose final authoritative span carries an `@example` tag opening a line at its first non-blank column — the `extractSourceComments` walk filtered to the blocks that carry one. Title text is allowed, and `maskFences` keeps a fenced body's own lines out of the search. |
|
|
192
|
+
| `extractExamples` | function | `(source: string) => readonly SourceExample[]` | Extracts the `@example` blocks carried by the exported declaration heads in one file's source text, each named for the declaration its block documents. Shared adjacency comes from `extractSourceComments` and each block is read by `collectExamples`; head membership is the `collectKeys` key of the documented record under every keyword that grammar admits at column zero, so comment and template payload cannot qualify and the head grammar stays the one every reader here shares. A member key carries a dot and a head key does not, so a member's block belongs to `extractExampleMethods` instead. A head carrying several blocks contributes each. |
|
|
193
|
+
| `extractExampleMethods` | function | `(lines: readonly string[]) => readonly SourceExample[]` | Extracts the `@example` blocks carried by the callable members of a declaration body (per `collectKeys`' grammar, the same one `extractMemberMethods` reads), each named for the member its block documents. Shared adjacency comes from `extractSourceComments` and each block is read by `collectExamples`; member membership is the key `extractBodyLines`'s projection gives the documented record. |
|
|
194
|
+
| `selectSectionBlocks` | function | `(document: MarkdownDocument, heading: string) => readonly BlockNode[]` | Selects the block nodes under the named `##` heading, up to the next `##`-or-higher heading (or the document's end) — the section-scoping window `extractSurface` / `extractMethods` walk over. |
|
|
195
|
+
| `extractTagline` | function | `(document: MarkdownDocument) => string \| undefined` | Extracts the guide's tagline — the text of the blockquote following the document's H1, with every code span kept as a code span and whitespace collapsed. A heading before the blockquote ends the window, so a blockquote elsewhere in the document is not the tagline. |
|
|
196
|
+
| `extractSurface` | function | `(document: MarkdownDocument) => readonly SurfaceSymbol[]` | Extracts every `## Surface` identifier the guide documents — each table row's column 0 code span (the name) paired with its `Kind` column (located by header text), unioned with every H3 entity heading whose trimmed compared inline content is exactly its backticked code-span name, deduped by `computeSymbolKey`. A row with no code-span name has no name to key a symbol on, so this reader skips it and `extractUnnamed` reports it; a row with an unrecognized `Kind` text is skipped. A row also carries its `SUMMARY` column's compared text when the table has that column; a table without it leaves every row's summary absent, which `findDrift` reports. The exact `Signature` column contributes normalized signature text, including code spans, when present and non-empty; no other header supplies it. |
|
|
197
|
+
| `extractMethods` | function | `(document: MarkdownDocument) => readonly MethodGroup[]` | Extracts one `MethodGroup` per documented behavioral interface in `## Methods` — an H4 with a code span sets the current interface, and the table immediately following becomes its documented methods. A row with no code-span name has no name to key a member on, so this reader skips it and `extractUnnamed` reports it. Each row carries its `SUMMARY` column's compared text when the table has that column. |
|
|
198
|
+
| `collectGroups` | function | `(document: MarkdownDocument) => ReadonlyMap<TableNode, string>` | Collects each `## Methods` table keyed to the interface its `####` heading names — an H4 carrying a code span sets the current interface and the table immediately following claims it, so a heading with no table and a table with no heading before it contribute nothing. The map iterates in document order and a node keys itself, so a repeated identical table keeps its own entry. |
|
|
199
|
+
| `extractUnnamed` | function | `(document: MarkdownDocument) => readonly string[]` | Extracts every `## Surface` or `## Methods` table row whose first cell carries no code span. `extractSurface` and `extractMethods` skip such a row, because a row with no name gives them nothing to key a symbol or a member on, and this projection is what reports the skip. Each entry is the row's cells read through `extractCellText` and joined by `\|`, so a reader can locate the row in the guide; the `## Surface` rows come first, then the `## Methods` rows, each in document order. `GuideInterface.unnamed` caches it. |
|
|
200
|
+
| `extractLinks` | function | `(document: MarkdownDocument) => readonly string[]` | Extracts every link href in the guide document, including table cells — a full, depth-first walk of the whole AST. |
|
|
201
|
+
| `extractTests` | function | `(document: MarkdownDocument) => readonly string[]` | Extracts the relative test links declared under `## Tests` — every link href found within that section only. |
|
|
202
|
+
| `extractFences` | function | `(document: MarkdownDocument) => readonly GuideFence[]` | Extracts every fenced code block anywhere in the guide document. A full AST walk includes fences nested inside blockquotes and lists, and the same walk carries each fence's nearest preceding heading as its `title` — the key an `@example` block pairs on. A heading's text is flattened, so a title written with a code span pairs with a plain `@example` title. |
|
|
203
|
+
| `collectFences` | function | `(document: MarkdownDocument) => ReadonlyMap<CodeBlockNode, GuideFence>` | Collects each fenced code block keyed by its own node, paired with the `GuideFence` `extractFences` reports for it — the node-addressed form a rewrite needs, so a caller that located a fence by title can read that node's source region back from the parser. The map iterates in document order and a node keys itself, so a repeated identical fence keeps its own entry. |
|
|
204
|
+
| `isExternalLink` | function | `(href: string) => boolean` | Checks whether a guides-parity link check skips a link `href` — an external scheme (`EXTERNAL_SCHEMES`) or a bare in-document `#` anchor. |
|
|
205
|
+
| `resolveLink` | function | `(file: string, target: string) => string` | Resolves a relative `target` from the directory containing a root-relative declaring `file`. A slashless file belongs to the workspace root; path reduction is delegated to `resolvePath`. |
|
|
206
|
+
| `resolvePath` | function | `(directory: string, target: string) => string` | Resolves a relative `target` from a root-relative `directory`, normalizing forward-slash dot segments without filesystem or extension inference. A parent pops only a retained real component; every excess leading parent is preserved. |
|
|
207
|
+
| `findFirstCode` | function | `(nodes: readonly InlineNode[]) => string \| undefined` | Finds the first code-span value by descending an inline node list, following into `emphasis` / `link` / `image` children — the extraction rule behind a Surface or Methods table row's first-column identifier. |
|
|
208
|
+
| `normalizeIdentifier` | function | `(code: string) => string` | Returns the identifier prefix of a code-span text — everything before its first `<`, trimmed. Guide cells and headings may annotate a generic-parameterized name (`MarkdownHandler<TNode, T>`) for readability, but the bijection key is the bare identifier the source scanner captures, so both sides must normalize the same way. |
|
|
209
|
+
| `findColumnIndex` | function | `(table: TableNode, header: string) => number \| undefined` | Finds the index of the column whose header text is `header` so a table's columns survive reordering. The match is exact and case-sensitive — a table without that exact header contributes nothing to the projection reading it, so a `## Surface` table with no `SUMMARY` column leaves every row's summary absent and `findDrift` reports each of those rows, never agreement. |
|
|
210
|
+
| `extractRowSymbol` | function | `(table: TableNode, row: number) => SurfaceSymbol \| undefined` | Extracts one `## Surface` table row's symbol — its column 0 code span as the name, its `KIND` column as the keyword, and its exact `Signature` and `SUMMARY` columns as normalized text when those columns exist. Empty cells remain absent. A row with no code-span name and a row whose `Kind` text is no `ExportKeyword` have no symbol to key, so each returns `undefined`. |
|
|
211
|
+
| `validateSurface` | function | `(document: MarkdownDocument) => void` | Validates every `## Surface` table a guide carries: each header must be exactly `SURFACE_HEADER`, and each row that keys a symbol must carry a non-empty `Signature` cell. |
|
|
212
|
+
| `validateModules` | function | `(files: Readonly<Record<string, string>>, module: GuideModule) => void` | Validates that the modules one manifest entry spans declare disjoint exports: one name exported from two modules, whatever its keyword, is one capability split across environments. |
|
|
213
|
+
| `extractRowEntry` | function | `(table: TableNode, row: number) => MethodEntry \| undefined` | Extracts one `## Methods` table row's entry — its column 0 code span as the name and its `SUMMARY` column as the compared summary when the table has that column. A row with no code-span name has no member to key, so it returns `undefined`. |
|
|
214
|
+
| `extractRowSummary` | function | `(table: TableNode, row: number) => string \| undefined` | Extracts one row's compared summary — its `SUMMARY` column read through `extractCellText` and `normalizeSummary`. A table with no such column and a row whose cell is empty each carry no summary and return `undefined` rather than an empty string, so `findDrift` reports the absence. |
|
|
215
|
+
| `extractCellText` | function | `(cell: readonly InlineNode[]) => string` | Extracts compared inline content — the text of a table cell or candidate entity heading flattened with every code span kept as a code span, so \`\` \`Widget\` \`\` reads the same wherever the parity reader compares it. Emphasis drops to its text, a link drops to its text, an image drops to its alternative text, and the markdown parser has already unescaped \`\\\|\`. |
|
|
216
|
+
| `buildCell` | function | `(text: string) => readonly InlineNode[]` | Builds one table cell's inline content from its compared text — the inverse of `extractCellText`. A single-backtick run whose text carries no inner backtick and neither a leading nor a trailing space becomes a code span; every other character, a backtick included, becomes literal text, which `renderMarkdown` escapes so the rendered cell parses back to the text this function was given. |
|
|
217
|
+
| `extractCellLinks` | function | `(cell: readonly InlineNode[]) => readonly string[]` | Extracts the link hrefs within one table cell's inline content, in walk order. |
|
|
218
|
+
| `findUnexampled` | function | `(names: readonly string[], fences: readonly string[], examples: readonly string[]) => readonly string[]` | Finds the names in `names` that have no example — a fence containing the name at a word boundary in `fences`, or a membership in `examples`, both count as "has an example"; presence-only, fence and JSDoc content are never checked. |
|
|
219
|
+
| `findUnlisted` | function | `(fences: readonly GuideFence[], languages: readonly string[]) => readonly GuideFence[]` | Finds the fences whose language is absent from the caller's listed languages. Untagged fences are always returned because they have no language to list. |
|
|
220
|
+
| `extractFenceImports` | function | `(fence: string) => readonly FenceImport[]` | Parses a fence's brace `import` statements into per-specifier imported identifier names — `import type`, mixed multiline braces, and `x as y` aliases all count, each alias resolved to the exported name `x` because that is the name the checked barrel surface must hold. Brace bindings only: a default, namespace, side-effect, or mixed `import Default, { named }` statement is not surfaced. |
|
|
221
|
+
| `collectTitles` | function | `(guide: GuideInterface, source: SourceInterface) => ReadonlyMap<string, SourceExample>` | Collects the titled `@example` blocks a guide's documented surface reaches — the module's exported declaration heads, plus the own members of every documented `class` and `interface` — keyed by title, the first block of a title answering for it. |
|
|
222
|
+
| `computeDrift` | function | `(key: string, category: Drift['category'], guide: string \| undefined, source: string \| undefined) => Drift \| undefined` | Computes the drift between one compared key's guide text and source text. A pair agrees only when both sides carry the same text, and every other state is a drift: guide text alone reports the guide's side, source text alone reports the source's, and neither side carrying text reports the key by itself. A side carrying no text is absent from the result, so a documented symbol with no doc block reports as a drift naming the guide's text alone, and a row a table has no `Summary` column for against a declaration with no doc block reports as `{ key }`. |
|
|
223
|
+
| `findDrift` | function | `(guide: GuideInterface, source: SourceInterface) => readonly Drift[]` | Finds every disagreement between a guide and the source it documents, naming both sites: each `## Surface` row against its declaration's description paragraph, each present `Signature` cell against the declaration's computed signature written as a code span, each `## Methods` row against its member's, and the first titled guide fence of a heading against the `@example` block of the same title. An example's compared text is its language on the first line and its body beneath, so a fence that names another language drifts on its own. |
|
|
224
|
+
| `renderSurface` | function | `(symbols: readonly SurfaceSymbol[]) => string` | Renders a uniform `Name \| Kind \| Signature \| Summary` table with one row per symbol, the name as a code span, the keyword as text, and the signature and summary through `buildCell`. An absent signature or summary renders an empty cell, which `extractSurface` reads back as absent. Guide construction refuses an empty signature cell. |
|
|
225
|
+
| `renderMethods` | function | `(group: MethodGroup) => string` | Renders one `## Methods` group — the `####` heading naming the interface as a code span, then a `Name` and `SUMMARY` table with one row per documented member. A member carrying no summary renders an empty cell, which `extractMethods` reads back as an absent summary. |
|
|
226
|
+
| `renderExample` | function | `(example: SourceExample) => string` | Renders one `@example` block as the guide fence it pairs with — an H3 heading carrying the block's title, then a fence carrying its language and its code. An untitled block renders the fence alone, because a fence pairs on its nearest preceding heading and an untitled block claims none. |
|
|
227
|
+
| `buildTable` | function | `(table: TableNode, row: number, column: number, cell: readonly InlineNode[]) => TableNode` | Builds a copy of `table` with one cell's inline content replaced by `cell`. Every other cell keeps its own nodes, so a rewrite touches the one cell it names and the header and the alignment row travel unchanged. |
|
|
228
|
+
| `buildFence` | function | `(example: SourceExample) => CodeBlockNode` | Builds the fenced code block one `@example` block renders as — its code inside a fence carrying its language, and an untagged fence when the block names none. |
|
|
229
|
+
| `spliceSpan` | function | `(source: string, span: MarkdownSpan, replacement: string) => string` | Splices `replacement` into `source` over the region `span` addresses, and returns the result. The text before the region and the text after it travel byte for byte, so a rewrite that addresses one node's region changes nothing else in the document. |
|
|
230
|
+
| `replaceCell` | function | `(guide: string, key: string, column: string, cell: readonly InlineNode[]) => string \| undefined` | Replaces one compared cell in a guide's text and returns the whole guide back. `key` names the row the way `findDrift` names it — a `computeSymbolKey` key for a `## Surface` row, an `Owner.member` key for a `## Methods` row — and the row's cell under the `column` header becomes `cell`. Only the table's own source region is rewritten, so every byte outside it travels unchanged; a key reaching no cell returns `undefined`, and a row already carrying that cell returns the guide byte for byte. |
|
|
231
|
+
| `replaceFence` | function | `(guide: string, title: string, example: SourceExample) => string \| undefined` | Replaces one titled fence in a guide's text and returns the whole guide back. The first fence carrying `title` — the pairing `findDrift` compares on — takes `example`'s language and code. Only the fence's own source region is rewritten, so every byte outside it travels unchanged; a title no fence carries returns `undefined`, and a fence already carrying that body returns the guide byte for byte. |
|
|
232
|
+
| `replaceSummary` | function | `(comment: string, summary: string, width?: number) => string \| undefined` | Replaces one doc block's description paragraph with `summary` and returns the whole block back. The paragraph is the block's text before its first block tag, and it re-wraps inside `width`; the blank line before the first tag, every tag line, the block's indentation, and its continuation markers all survive. A block already carrying the summary returns byte for byte, and a text that is no doc block and a summary carrying no word each return `undefined`. |
|
|
233
|
+
| `replaceExample` | function | `(comment: string, example: SourceExample) => string \| undefined` | Replaces the body of one titled `@example` tag in a doc block's raw text and returns the whole block back. The tag carrying `example`'s title takes a fence of its language and its code; every other tag, the description paragraph, the block's indentation, and its continuation markers all survive. A text that is no doc block, a title no tag carries, and a language or code the emitted three-backtick fence cannot enclose or the doc block cannot hold each return `undefined`. |
|
|
234
|
+
| `locateComment` | function | `(text: string, key: string) => MarkdownSpan \| undefined` | Locates the doc block a compared key attaches to inside one file's text and returns the block's own character region, so a caller can `slice` the block, rewrite it through `replaceSummary` or `replaceExample`, and write the result back through `spliceSpan`. `key` names the pair the way `findDrift` names it — a `computeSymbolKey` key for a declaration, an `Owner.member` key for an interface or class member; the region covers the block's own indentation, and no block carrying the key returns `undefined`. |
|
|
193
235
|
|
|
194
236
|
The server command leaves come from [`helpers.ts`](../src/server/helpers.ts).
|
|
195
237
|
|
|
196
|
-
| Name
|
|
197
|
-
|
|
|
198
|
-
| `formatGuideFinding`
|
|
199
|
-
| `matchesGuideResult`
|
|
200
|
-
| `resolveGuideRoot`
|
|
201
|
-
| `selectGuidePitch`
|
|
238
|
+
| Name | Kind | Signature | Summary |
|
|
239
|
+
| --------------------- | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
240
|
+
| `formatGuideFinding` | function | `(finding: ParityFinding) => string` | Formats one finding with its guide prefix when needed. |
|
|
241
|
+
| `matchesGuideResult` | function | `(result: unknown) => boolean` | Reads an owned foreign result view and accepts passed modules without unhandled errors. |
|
|
242
|
+
| `resolveGuideRoot` | function | `(root: URL \| string) => string` | Resolves a command root to a native absolute path. |
|
|
243
|
+
| `selectGuidePitch` | function | `(entries: readonly ManifestEntry[], name: string \| undefined) => string \| undefined` | Selects the indexed guide matching a package's bare name. |
|
|
244
|
+
| `computeGuideProject` | function | `(module: string) => string \| undefined` | Computes the scoped project a guide module's declarations are emitted through. |
|
|
202
245
|
|
|
203
246
|
### Parsers
|
|
204
247
|
|
|
@@ -216,37 +259,38 @@ The server argument and package-manifest parsers come from
|
|
|
216
259
|
| --------------------- | -------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
217
260
|
| `parseGuideDirection` | function | `(args: readonly string[]) => ParityDirection \| undefined` | Maps the supported `--to guide` and `--to source` arguments to an explicit rewrite destination. |
|
|
218
261
|
| `parsePackageName` | function | `(manifest: string) => string \| undefined` | Reads the bare package name from package manifest JSON. |
|
|
262
|
+
| `parseCompilerRoot` | function | `(text: string) => string \| undefined` | Reads the `rootDir` a `tsc --showConfig` reading resolves. |
|
|
219
263
|
|
|
220
264
|
### Shapers
|
|
221
265
|
|
|
222
266
|
Declarative `ContractShape` values (from `@orkestrel/contract`) from
|
|
223
267
|
[`shapers.ts`](../src/core/shapers.ts) — every documented data type here is non-recursive, so
|
|
224
|
-
each shapes directly.
|
|
268
|
+
each shapes directly. Their signatures name the declared shape types.
|
|
225
269
|
|
|
226
|
-
| Name | Kind |
|
|
227
|
-
| -------------------- | ----- |
|
|
228
|
-
| `surfaceSymbolShape` | const | `{ name:
|
|
229
|
-
| `methodGroupShape` | const | `{ interface:
|
|
230
|
-
| `methodEntryShape` | const | `{ name:
|
|
231
|
-
| `sourceExampleShape` | const | `{ name:
|
|
232
|
-
| `driftShape` | const | `{ key:
|
|
233
|
-
| `manifestEntryShape` | const | `{ concept:
|
|
270
|
+
| Name | Kind | Signature | Summary |
|
|
271
|
+
| -------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
272
|
+
| `surfaceSymbolShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; keyword: import("@orkestrel/contract").LiteralShape<readonly ("class" \| "const" \| "function" \| "interface" \| "type")[]>; signature: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; summary: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Shapes a `SurfaceSymbol` — a documented / exported symbol's `name` paired with its `ExportKeyword`, optional `signature`, and optional compared `summary`. |
|
|
273
|
+
| `methodGroupShape` | const | `import("@orkestrel/contract").ObjectShape<{ interface: import("@orkestrel/contract").StringShape; methods: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; summary: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>>; }, false>` | Shapes a `MethodGroup` — a backticked `interface` name paired with its documented `methods`. |
|
|
274
|
+
| `methodEntryShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; summary: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Shapes a `MethodEntry` — one documented method's `name` paired with its optional compared `summary`. |
|
|
275
|
+
| `sourceExampleShape` | const | `import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; title: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; code: import("@orkestrel/contract").StringShape; language: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Shapes a `SourceExample` — one `@example` block's `name`, its optional pairing `title`, its `code`, and its optional fence `language`. |
|
|
276
|
+
| `driftShape` | const | `import("@orkestrel/contract").ObjectShape<{ key: import("@orkestrel/contract").StringShape; category: import("@orkestrel/contract").LiteralShape<readonly ("example" \| "signature" \| "summary")[]>; guide: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; source: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; }, false>` | Shapes a `Drift` — one disagreement's compared `key` with the optional text each side carries there. |
|
|
277
|
+
| `manifestEntryShape` | const | `import("@orkestrel/contract").ObjectShape<{ concept: import("@orkestrel/contract").StringShape; spec: import("@orkestrel/contract").StringShape; source: import("@orkestrel/contract").UnionShape<readonly [import("@orkestrel/contract").StringShape, import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>]>; tests: import("@orkestrel/contract").StringShape; }, false>` | Shapes a `ManifestEntry` — one `## By concept` manifest row, `source` accepting either a single directory or several. |
|
|
234
278
|
|
|
235
279
|
### Validators
|
|
236
280
|
|
|
237
281
|
Total from-unknown guards composed from `@orkestrel/contract` combinators, from
|
|
238
282
|
[`validators.ts`](../src/core/validators.ts).
|
|
239
283
|
|
|
240
|
-
| Name | Kind | Summary
|
|
241
|
-
| ----------------- | ----- |
|
|
242
|
-
| `isExportKeyword` | const | Checks whether `value` is one of the documented `ExportKeyword` literals — the guard behind extracting a Surface table's `Kind` cell into a typed symbol.
|
|
243
|
-
| `isDriftCategory` | const | Checks whether `value` names a supported drift category.
|
|
244
|
-
| `isSurfaceSymbol` | const | Checks whether `value` is a well-formed `SurfaceSymbol` — a `name` string paired with a valid `ExportKeyword`, and
|
|
245
|
-
| `isMethodGroup` | const | Checks whether `value` is a well-formed `MethodGroup` — a backticked `interface` name paired with its documented `MethodEntry` rows.
|
|
246
|
-
| `isMethodEntry` | const | Checks whether `value` is a well-formed `MethodEntry` — a `name` string with an optional `summary`.
|
|
247
|
-
| `isSourceExample` | const | Checks whether `value` is a well-formed `SourceExample` — a `name` and `code` string with an optional `title` and `language`.
|
|
248
|
-
| `isDrift` | const | Checks whether `value` is a well-formed `Drift` — a compared `key` with an optional `guide` and `source` text.
|
|
249
|
-
| `isManifestEntry` | const | Checks whether `value` is a well-formed `ManifestEntry` — a `## By concept` manifest row, its `source` accepting either a single directory or several.
|
|
284
|
+
| Name | Kind | Signature | Summary |
|
|
285
|
+
| ----------------- | ----- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
286
|
+
| `isExportKeyword` | const | `Guard<ExportKeyword>` | Checks whether `value` is one of the documented `ExportKeyword` literals — the guard behind extracting a Surface table's `Kind` cell into a typed symbol. |
|
|
287
|
+
| `isDriftCategory` | const | `Guard<DriftCategory>` | Checks whether `value` names a supported drift category. |
|
|
288
|
+
| `isSurfaceSymbol` | const | `Guard<SurfaceSymbol>` | Checks whether `value` is a well-formed `SurfaceSymbol` — a `name` string paired with a valid `ExportKeyword`, and optional `signature` and `summary` strings. |
|
|
289
|
+
| `isMethodGroup` | const | `Guard<MethodGroup>` | Checks whether `value` is a well-formed `MethodGroup` — a backticked `interface` name paired with its documented `MethodEntry` rows. |
|
|
290
|
+
| `isMethodEntry` | const | `Guard<MethodEntry>` | Checks whether `value` is a well-formed `MethodEntry` — a `name` string with an optional `summary`. |
|
|
291
|
+
| `isSourceExample` | const | `Guard<SourceExample>` | Checks whether `value` is a well-formed `SourceExample` — a `name` and `code` string with an optional `title` and `language`. |
|
|
292
|
+
| `isDrift` | const | `Guard<Drift>` | Checks whether `value` is a well-formed `Drift` — a compared `key` with an optional `guide` and `source` text. |
|
|
293
|
+
| `isManifestEntry` | const | `Guard<ManifestEntry>` | Checks whether `value` is a well-formed `ManifestEntry` — a `## By concept` manifest row, its `source` accepting either a single directory or several. |
|
|
250
294
|
|
|
251
295
|
### Factories
|
|
252
296
|
|
|
@@ -268,17 +312,18 @@ From [`factories.ts`](../src/core/factories.ts).
|
|
|
268
312
|
|
|
269
313
|
The implementing classes, from [`Guide.ts`](../src/core/Guide.ts),
|
|
270
314
|
[`Parity.ts`](../src/core/Parity.ts), [`GuideCommand.ts`](../src/server/GuideCommand.ts),
|
|
271
|
-
[`Source.ts`](../src/core/sources/Source.ts), and
|
|
315
|
+
[`GuideCompiler.ts`](../src/server/GuideCompiler.ts), [`Source.ts`](../src/core/sources/Source.ts), and
|
|
272
316
|
[`SourceManager.ts`](../src/core/sources/SourceManager.ts) — each documented in full under its own
|
|
273
317
|
heading following this table.
|
|
274
318
|
|
|
275
|
-
| Name | Kind | Summary |
|
|
276
|
-
| --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
277
|
-
| `Guide` | class | Presents a pure, structured view over one parsed guide — the documented projections (`sections` / `tagline` / `surface` / `methods` / `unnamed` / `links` / `tests` / `fences`) are extracted once at construction and cached. |
|
|
278
|
-
| `Parity` | class | Composes generic guide-parity inspection and explicit in-memory rewrites over a caller inventory. |
|
|
279
|
-
| `GuideCommand` | class | Drives native checking and explicit rewrites or registers package assertions in the guides worker. |
|
|
280
|
-
| `
|
|
281
|
-
| `
|
|
319
|
+
| Name | Kind | Signature | Summary |
|
|
320
|
+
| --------------- | ----- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
321
|
+
| `Guide` | class | `new (source: string) => GuideInterface` | Presents a pure, structured view over one parsed guide — the documented projections (`sections` / `tagline` / `surface` / `methods` / `unnamed` / `links` / `tests` / `fences`) are extracted once at construction and cached. |
|
|
322
|
+
| `Parity` | class | `new (options: ParityOptions) => ParityInterface` | Composes generic guide-parity inspection and explicit in-memory rewrites over a caller inventory. |
|
|
323
|
+
| `GuideCommand` | class | `new (options: GuideCommandOptions) => GuideCommandInterface` | Drives native checking and explicit rewrites or registers package assertions in the guides worker. |
|
|
324
|
+
| `GuideCompiler` | class | `new (options: GuideCompilerOptions) => GuideCompilerInterface` | Emits a guide module's declarations through the workspace's own TypeScript compiler, the projection every computed `Signature` cell is read from. |
|
|
325
|
+
| `Source` | class | `new (options: SourceOptions) => SourceInterface` | Reflects, as a pure `SourceInterface`, a module scope's intentional direct declarations, conventional barrel-reachable surface, and member methods over a consumer-supplied file inventory, using text-only line scanners rather than the TypeScript compiler API or the filesystem. `Source` never touches disk: the consumer gathers the inventory however their environment allows (`node:fs` in a Node script, `import.meta.glob` in a browser/vitest run) and passes it in as `files`. |
|
|
326
|
+
| `SourceManager` | class | `new (options: SourceManagerOptions) => SourceManagerInterface` | Resolves a consumer-owned import-specifier policy into pure source views and caches those views by module, so aliases for one module share one entity. Unmapped specifiers remain foreign to the consumer and return `undefined`. `sources()` enumerates the same shared views, one per distinct module the policy maps. |
|
|
282
327
|
|
|
283
328
|
### `Guide`
|
|
284
329
|
|
|
@@ -303,10 +348,22 @@ The implementing class of `GuideCommandInterface`, from
|
|
|
303
348
|
[`GuideCommand.ts`](../src/server/GuideCommand.ts). In a guides worker, `execute` reads fresh
|
|
304
349
|
workspace bytes and supplies the resolved root, owned file inventory, joined parity rows, and
|
|
305
350
|
generic parity result to the package callback. Outside a guides worker, it accepts no arguments
|
|
306
|
-
for a no-write check, `--to guide` to update guide summaries and examples
|
|
307
|
-
`--to source` to update source doc blocks from the guide. A
|
|
308
|
-
|
|
309
|
-
|
|
351
|
+
for a no-write check, `--to guide` to update guide summaries, `Signature` cells, and examples
|
|
352
|
+
from source, or `--to source` to update source doc blocks from the guide. A signature is computed
|
|
353
|
+
from the source declaration, so `--to source` reports a differing `Signature` cell as unresolved
|
|
354
|
+
and leaves the source unchanged. A rewrite rereads the workspace before checking unresolved
|
|
355
|
+
findings and then runs the real guides Vitest project. Unsupported arguments print `GUIDE_USAGE`;
|
|
356
|
+
no-write and rewrite failures preserve a higher existing process exit code.
|
|
357
|
+
|
|
358
|
+
Every inventory read first constructs `Parity` without declarations, so every manifest guide
|
|
359
|
+
parses, and every name two modules of one entry declare refuses, before any module compiles. It
|
|
360
|
+
then compiles each distinct directory the parsed rows' sources name through `GuideCompiler` and
|
|
361
|
+
passes the emitted declarations to `Parity` as `declarations`. A module compiles once per `execute`
|
|
362
|
+
call: a `--to` run's second inventory read reuses the first read's declarations, which a
|
|
363
|
+
`--to source` rewrite cannot change, because it rewrites doc blocks and the emit removes comments.
|
|
364
|
+
A refusal names the guide or the module; a compile refusal carries the compiler's output in its
|
|
365
|
+
message and in `context.output`. The native command writes the message to stderr and raises the
|
|
366
|
+
exit status to at least 1, and the worker rejects `execute`.
|
|
310
367
|
|
|
311
368
|
The `reader` port may throw while gathering the initial or fresh inventory. The `runner` port may
|
|
312
369
|
throw while creating the foreign runner or starting its guides project. Guide validates the
|
|
@@ -317,6 +374,38 @@ and cleanup exceptions are written to stderr, raise the process exit status, and
|
|
|
317
374
|
fulfilled after native handling. A failed or malformed runner result raises the exit status.
|
|
318
375
|
Worker inventory and registration failures escape and reject `execute`.
|
|
319
376
|
|
|
377
|
+
### `GuideCompiler`
|
|
378
|
+
|
|
379
|
+
The implementing class of `GuideCompilerInterface`, from
|
|
380
|
+
[`GuideCompiler.ts`](../src/server/GuideCompiler.ts). `compile(module)` accepts a module
|
|
381
|
+
`src/<env>` or `app/<env>` and refuses any other module with a message naming the expected
|
|
382
|
+
`configs/<layer>/tsconfig.<env>.json` project path. It runs `process.execPath` with the `bin.tsc`
|
|
383
|
+
entry that the workspace root's `node_modules/typescript/package.json` names, with no shell, and
|
|
384
|
+
declares no TypeScript dependency of its own, so the signature follows the workspace's pinned
|
|
385
|
+
toolchain. Each run takes the `timeout` option, `GUIDE_COMPILER_TIMEOUT` by default, and the
|
|
386
|
+
`limit` option on each output stream, `GUIDE_COMPILER_LIMIT` by default. It reads the project's
|
|
387
|
+
`rootDir` through `tsc --showConfig`, then emits through
|
|
388
|
+
`tsc -p <project> --declaration --emitDeclarationOnly --noEmit false --declarationMap false --removeComments --newLine lf --outDir <scratch>`
|
|
389
|
+
into a fresh directory under the `temporary` option, the host temporary directory by default. It
|
|
390
|
+
returns the emitted text keyed by workspace-relative `.d.ts` path, the source key with `.ts`
|
|
391
|
+
replaced by `.d.ts`, for the files under the module alone, sorted and frozen. The scratch path
|
|
392
|
+
never enters the result, so two compiles of one tree under one compiler return the same text.
|
|
393
|
+
|
|
394
|
+
Every refusal is a `GuideError` whose `context` names the module and project, except that a module
|
|
395
|
+
outside `src/<env>` and `app/<env>` names the module alone and a workspace that installs no compiler
|
|
396
|
+
names its `root`. The codes:
|
|
397
|
+
|
|
398
|
+
- `compile` for a module outside `src/<env>` and `app/<env>`, a workspace that installs no
|
|
399
|
+
compiler, a project that declares no `rootDir`, and a non-zero exit, which carries the
|
|
400
|
+
compiler's own output, so no partial emit is projected;
|
|
401
|
+
- `empty` for a project that emits no declaration under the module, such as one whose
|
|
402
|
+
`declarationDir` sends the emit elsewhere or whose `include` misses the module;
|
|
403
|
+
- `timeout` for a run that passes the timeout, and `overflow` for a run that writes more than the
|
|
404
|
+
output bound to one stream.
|
|
405
|
+
|
|
406
|
+
The scratch directory is removed before `compile` returns or throws. When a removal fails after a
|
|
407
|
+
refusal, the refusal is the error thrown.
|
|
408
|
+
|
|
320
409
|
### `Source`
|
|
321
410
|
|
|
322
411
|
The implementing class of `SourceInterface`, from [`Source.ts`](../src/core/sources/Source.ts). A
|
|
@@ -332,9 +421,12 @@ within the same module scope, reading the first file that declares the name. Eve
|
|
|
332
421
|
once per instance from the immutable inventory and is reused — the `exports` and `surface`
|
|
333
422
|
projections on first access, the scope's declaration map on the first `methods` or `examples`
|
|
334
423
|
lookup, then each name's members and each example collection under the name it was asked for — so a
|
|
335
|
-
whole-guide comparison reads each file once rather than once per compared row.
|
|
336
|
-
|
|
337
|
-
|
|
424
|
+
whole-guide comparison reads each file once rather than once per compared row. When the options
|
|
425
|
+
carry `declarations`, each `exports()` and `surface()` symbol carries the signature
|
|
426
|
+
`extractSignatures` prints from the emitted text under its file's `.d.ts` key; a symbol the emitted
|
|
427
|
+
text does not declare carries none. `Source` never uses the TypeScript compiler API or filesystem;
|
|
428
|
+
the consumer gathers `files` and `declarations` however its environment allows. See
|
|
429
|
+
[`## Methods`](#methods) for the public call-signature surface.
|
|
338
430
|
|
|
339
431
|
### `SourceManager`
|
|
340
432
|
|
|
@@ -350,6 +442,20 @@ check that must sweep every face of the package reads them without repeating the
|
|
|
350
442
|
`Source` is cached per module, so two specifiers naming one module share one entity and the
|
|
351
443
|
inventory is scanned once. See [`## Methods`](#methods) for its public call-signature surface.
|
|
352
444
|
|
|
445
|
+
### Coded refusals
|
|
446
|
+
|
|
447
|
+
The coded error and its cross-copy guard come from [`errors.ts`](../src/core/errors.ts), and its
|
|
448
|
+
codes from [`constants.ts`](../src/core/constants.ts).
|
|
449
|
+
|
|
450
|
+
| Name | Kind | Signature | Summary |
|
|
451
|
+
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
452
|
+
| `GuideCode` | type | `(typeof GUIDE_CODES)[number]` | Identifies a refused guide, manifest entry, or module compile, derived from `GUIDE_CODES`. |
|
|
453
|
+
| `GUIDE_CODES` | const | `readonly ("collision" \| "compile" \| "empty" \| "header" \| "overflow" \| "signature" \| "timeout")[]` | Lists the codes a `GuideError` carries: a refused Surface `header` or empty `signature` cell, a name two modules of one manifest entry declare (`collision`), and the compiler faults — a failed `compile`, an `empty` emit, a `timeout`, and an output `overflow`. |
|
|
454
|
+
| `GuideErrorOptions` | interface | `{ context? }` | Configures a `GuideError`: the standard `cause` and the machine-readable `context` its refusal carries. |
|
|
455
|
+
| `GUIDE_ERROR_BRAND` | const | `unique symbol` | Names the cross-copy identity marker of a Guide error. |
|
|
456
|
+
| `GuideError` | class | `new (message: string, code: GuideCode, options?: GuideErrorOptions) => GuideError` | Carries a coded refusal of a guide, a manifest entry, or a module compile. |
|
|
457
|
+
| `isGuideError` | function | `(value: unknown) => value is GuideError` | Checks whether a value carries the Guide error brand and declared members across package copies. |
|
|
458
|
+
|
|
353
459
|
## Methods
|
|
354
460
|
|
|
355
461
|
The public methods of each behavioral interface — one table per type, keyed by its
|
|
@@ -361,7 +467,7 @@ backticked name (`.claude/rules/documentation.md` § Parity).
|
|
|
361
467
|
| ---------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
362
468
|
| `sections` | `readonly string[]` | Lists the `##` heading names, in document order — the non-vacuousness guard for section presence. |
|
|
363
469
|
| `tagline` | `string \| undefined` | Returns the text of the blockquote following the document's H1 — the guide's tagline, or `undefined` when a heading intervenes first. |
|
|
364
|
-
| `surface` | `readonly SurfaceSymbol[]` | Lists every `## Surface` identifier + keyword — table rows union H3 entity headings whose trimmed compared inline content is exactly their backticked code-span name. Each row carries its `Summary`
|
|
470
|
+
| `surface` | `readonly SurfaceSymbol[]` | Lists every `## Surface` identifier + keyword — table rows union H3 entity headings whose trimmed compared inline content is exactly their backticked code-span name. Each row carries its non-empty `Signature` and `Summary` cells, located by exact header text and normalized through the same text reader, when the table has those columns. |
|
|
365
471
|
| `methods` | `readonly MethodGroup[]` | Returns one `MethodGroup` per documented behavioral interface in `## Methods`, each row carrying its `Summary` cell. |
|
|
366
472
|
| `unnamed` | `readonly string[]` | Lists every `## Surface` or `## Methods` row whose first cell carries no code span — the rows `surface` and `methods` skip for want of a name, each entry being the row's cells joined by `\|`. Such a row reaches neither projection, so no bijection check can report it and this one names it instead. The `## Surface` rows come first, then the `## Methods` rows, each in document order. |
|
|
367
473
|
| `links` | `readonly string[]` | Lists every link href in the guide, including table cells. |
|
|
@@ -383,6 +489,12 @@ backticked name (`.claude/rules/documentation.md` § Parity).
|
|
|
383
489
|
| --------- | --------------- | ----------------------------------------------------------------------------------------------- |
|
|
384
490
|
| `execute` | `Promise<void>` | Runs the native command or registers package assertions with fresh worker inventory and parity. |
|
|
385
491
|
|
|
492
|
+
#### `GuideCompilerInterface`
|
|
493
|
+
|
|
494
|
+
| Method | Returns | Summary |
|
|
495
|
+
| --------- | ---------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
496
|
+
| `compile` | `Readonly<Record<string, string>>` | Emits the declarations of one `src/<env>` or `app/<env>` module through its scoped project. |
|
|
497
|
+
|
|
386
498
|
#### `SourceInterface`
|
|
387
499
|
|
|
388
500
|
| Method | Returns | Summary |
|
|
@@ -424,18 +536,39 @@ internal implementation classes a denylist would enumerate by hand, so a fence-i
|
|
|
424
536
|
|
|
425
537
|
## The extraction model
|
|
426
538
|
|
|
539
|
+
The `Guide` constructor and `createGuide` refuse through `validateSurface` at the first
|
|
540
|
+
offending Surface table, before returning a guide. Every `## Surface` section is checked, a
|
|
541
|
+
repeated one included. A nonuniform header throws `GuideError` with code `header`; a keyed row
|
|
542
|
+
with an empty Signature cell throws it with code `signature`. The message identifies the table and
|
|
543
|
+
found header or row, then states `SURFACE_HEADER`, `Name | Kind | Signature | Summary`. Untrusted
|
|
544
|
+
diagnostic text is JSON-encoded after a 200-character cap. No option disables this check. Parity
|
|
545
|
+
adds the guide's spec path and rethrows the same code and `context` with the original refusal as
|
|
546
|
+
its cause, both for a manifest guide and for the README and the guide a pitch comparison parses;
|
|
547
|
+
`GuideCommand` propagates worker failure and reports native failure with a failing exit status.
|
|
548
|
+
The guard `isGuideError` recognizes the package's branded errors across copies.
|
|
549
|
+
|
|
550
|
+
Parity also refuses a manifest entry whose source spans several modules when one name, whatever its
|
|
551
|
+
kind, is exported from two of them: `validateModules` throws `GuideError` with code `collision`, naming
|
|
552
|
+
every colliding name and each module that declares it in one message, with the same list in
|
|
553
|
+
`context.collisions`. It reads the population `exports()` reads: direct `type`, `interface`,
|
|
554
|
+
`const`, `function`, and `class` declarations in each module's files, outside its root barrel.
|
|
555
|
+
Each source file answers for the most specific listed module that contains it. The message tells
|
|
556
|
+
you to declare logic both environments can share once in the layer's `core` directory, such as
|
|
557
|
+
`src/core` or `app/core`, and to give each environment's own logic a distinct name.
|
|
558
|
+
|
|
427
559
|
`Guide` parses a guide's markdown once (through `@orkestrel/markdown`'s `createMarkdown`) and
|
|
428
560
|
caches its projections at construction — `sections`, `tagline`, `surface`, `methods`, `unnamed`,
|
|
429
561
|
`links`, `tests`, `fences` — so every accessor is a cheap array return, not a re-parse.
|
|
430
562
|
`extractSurface` scopes to the `## Surface` section (`selectSectionBlocks`) and unions its sources
|
|
431
563
|
of identifiers: every table's column-0 code span (keyword read from the column whose header text
|
|
432
|
-
is `Kind`, located
|
|
564
|
+
is `Kind`, located by that header text; `validateSurface` has already refused every table whose
|
|
565
|
+
columns are not `SURFACE_HEADER` in order) and every H3 entity heading whose
|
|
433
566
|
trimmed compared inline content is exactly its backticked code-span name (a class documented
|
|
434
567
|
outside a table, keyword fixed to `'class'`). Surrounding spaces, emphasis, and links preserve
|
|
435
568
|
that identity. `extractSurface` refuses a heading carrying any other visible text or an additional
|
|
436
569
|
code span. Surface entries retain encounter order and deduplicate by name + keyword: the
|
|
437
570
|
first-seen entry wins, so a genuine entity heading before its matching class row keeps the
|
|
438
|
-
|
|
571
|
+
heading entry without signature or summary, while a preceding table row keeps both cells; the same
|
|
439
572
|
name under another keyword remains distinct. `extractMethods` scopes to
|
|
440
573
|
`## Methods`: an H4 whose first code span sets the current interface name, and the very next
|
|
441
574
|
table becomes that interface's `MethodGroup`. Both extractors normalize every identifier
|
|
@@ -461,6 +594,20 @@ the directory before the final slash, treats a slashless file as workspace-root,
|
|
|
461
594
|
Neither helper consults the filesystem, infers extensions, or guesses whether a dotted component
|
|
462
595
|
is a file.
|
|
463
596
|
|
|
597
|
+
The row reader locates the exact `Signature` header and carries non-empty cell text into
|
|
598
|
+
`SurfaceSymbol.signature`, through `extractCellText` and `normalizeSummary`. A low-level row read
|
|
599
|
+
without that column carries no signature. Headers named `Shape`, `Export`, or `Symbol` never supply
|
|
600
|
+
one; guide construction refuses their nonuniform table. `computeSymbolKey` reads only name and
|
|
601
|
+
keyword. A signature change cannot change bijection identity or summary drift.
|
|
602
|
+
|
|
603
|
+
The source side's signature comes from the emitted declarations. `extractSignatures` reads one
|
|
604
|
+
`.d.ts` text through `extractSourceLines`, trims each physical line, joins each column-zero
|
|
605
|
+
`export` declaration's lines with single spaces, and prints each through `extractSignature`.
|
|
606
|
+
`computeDepths` gives every character its bracket depth outside quoted text, `findClosing` and
|
|
607
|
+
`findSeparators` locate the brackets and the `;`, `,`, and `{` separators at a depth, and
|
|
608
|
+
`renderMember` prints one interface member. An `enum`, a namespace, and a re-export print no
|
|
609
|
+
signature.
|
|
610
|
+
|
|
464
611
|
The guide's side and the source's side read into one form. `extractSurface` and `extractMethods` locate
|
|
465
612
|
the compared column by its header text, `Summary`, exactly as they locate `Kind`, and read that cell
|
|
466
613
|
through `extractCellText` and `normalizeSummary`. `extractSourceComments` walks the aligned
|
|
@@ -517,7 +664,11 @@ every tag search reads the block.
|
|
|
517
664
|
`@param`, `@returns` and the `Returns` column, `@remarks` and narrative, and the H1 tagline are
|
|
518
665
|
outside the comparison — `tagline()` reads the tagline for a package that compares it against its own
|
|
519
666
|
README, and it gains a partner to compare against when a source declares `@packageDocumentation`.
|
|
520
|
-
|
|
667
|
+
The `Signature` cell is preserved on `SurfaceSymbol.signature` and stays outside summary drift
|
|
668
|
+
and symbol identity. `findDrift` compares it, as `signature` drift, against the computed signature
|
|
669
|
+
written as a code span and read through `normalizeSummary`, and only when both sides carry one: an
|
|
670
|
+
H3 entity heading carries no cell, and a source reflected without `declarations` computes none.
|
|
671
|
+
The `Returns` column in a Methods table stays outside the comparison.
|
|
521
672
|
|
|
522
673
|
Examples pair by title. A `GuideFence` carries the flattened text of its nearest preceding heading as
|
|
523
674
|
`title`, a `SourceExample` carries the text after its `@example` tag, and a block claims the fence of
|
|
@@ -645,6 +796,10 @@ same readonly array instance is returned thereafter.
|
|
|
645
796
|
|
|
646
797
|
## The check catalog
|
|
647
798
|
|
|
799
|
+
Parsing precedes parity findings. A nonuniform Surface header, an empty keyed Signature cell, or
|
|
800
|
+
a name two modules of one entry export throws the coded refusal described in the extraction model. Parity neither duplicates those refusals as
|
|
801
|
+
findings nor converts an old table. The guide author must revise the table before inspection.
|
|
802
|
+
|
|
648
803
|
Every guides-parity check reduces to `expect([]).toEqual([])`, paired with a non-vacuousness
|
|
649
804
|
guard so a renamed heading fails loudly instead of passing on an empty extraction:
|
|
650
805
|
|
|
@@ -695,6 +850,13 @@ guard so a renamed heading fails loudly instead of passing on an empty extractio
|
|
|
695
850
|
agreement. A table with no `Summary` column therefore reports every row it documents, and a package
|
|
696
851
|
adopting SQ cannot pass it vacuously. `findDrift` is the comparison. Guard: the SB extractions
|
|
697
852
|
this check reuses already prove non-vacuous.
|
|
853
|
+
- **GQ — Surface signature equality.** For every symbol both `guide.surface()` and
|
|
854
|
+
`source.surface()` carry a signature for, the guide row's `Signature` cell equals the computed
|
|
855
|
+
signature written as a code span. A cell that differs reports `signature` drift; a row the
|
|
856
|
+
source computes no signature for, and an H3 entity heading, stay outside the comparison.
|
|
857
|
+
`findDrift` is the comparison. Guard: `GuideCommand` supplies `declarations` on every inventory
|
|
858
|
+
read, and a module that fails to compile, or whose project emits no declaration under it, refuses
|
|
859
|
+
rather than computing no signature.
|
|
698
860
|
- **MQ — Methods summary equality.** The same comparison per `MethodGroup`, over the members
|
|
699
861
|
`group.methods` and `source.methods(group.interface)` both carry, keyed `Owner.member`.
|
|
700
862
|
- **EQ — Example equality.** Every titled guide fence against the `@example` block of the same title,
|
|
@@ -717,7 +879,7 @@ guard so a renamed heading fails loudly instead of passing on an empty extractio
|
|
|
717
879
|
statement; `findMissing` diffs the imported names against the public/barrel surface's names.
|
|
718
880
|
Guard: the comparison runs against at least one resolved import.
|
|
719
881
|
|
|
720
|
-
SQ, MQ, and EQ share one function: `findDrift(guide, source)` returns every disagreement with both
|
|
882
|
+
SQ, GQ, MQ, and EQ share one function: `findDrift(guide, source)` returns every disagreement with both
|
|
721
883
|
sites, so a package's whole equality gate is `expect(findDrift(guide, source)).toEqual([])`. It
|
|
722
884
|
compares only the pairs both sides carry, so a symbol, a member, or a title one side lacks is left to
|
|
723
885
|
the bijection check that owns it and is never reported twice.
|
|
@@ -737,7 +899,7 @@ a change across. These core leaves return text and write nothing, so the worker
|
|
|
737
899
|
explicit `npm run test:guides -- --to guide` or `--to source` request.
|
|
738
900
|
|
|
739
901
|
`renderSurface`, `renderMethods`, and `renderExample` produce fresh guide text from source
|
|
740
|
-
entries — a `Name` / `Kind` / `Summary` table, a `####` group and its `Name` / `Summary` table,
|
|
902
|
+
entries — a `Name` / `Kind` / `Signature` / `Summary` table, a `####` group and its `Name` / `Summary` table,
|
|
741
903
|
and a titled fence. Each builds a markdown node and renders it through the parser's own
|
|
742
904
|
`renderMarkdown`, so the text it returns is the text the package parses back. Each renders the
|
|
743
905
|
block a guide section contains rather than the section itself, because a guide documents its
|
|
@@ -753,7 +915,10 @@ own formatter re-aligns it and the comparison stays on parsed entries rather tha
|
|
|
753
915
|
its node through the readers — `extractRowSymbol` and `collectGroups` for a row, `collectFences`
|
|
754
916
|
for a fence — reads that node's source region from the parser's provenance, rebuilds the node, and
|
|
755
917
|
splices the render over the region through `spliceSpan`. Only the located node's own region is
|
|
756
|
-
rewritten, so every byte of the guide outside it travels unchanged.
|
|
918
|
+
rewritten, so every byte of the guide outside it travels unchanged. `replaceCell` takes the header
|
|
919
|
+
of the column it writes and the cell's inline content: `--to guide` passes `SUMMARY` with
|
|
920
|
+
`buildCell(summary)` for a summary, and `SIGNATURE` with one code span carrying the computed
|
|
921
|
+
signature, which the render writes with `|` as `\|` and a longer fence around a backtick.
|
|
757
922
|
|
|
758
923
|
`replaceSummary` and `replaceExample` rewrite one doc block's raw text — its description paragraph,
|
|
759
924
|
or the body of the `@example` tag carrying a given title. `locateComment` is how a caller finds
|
|
@@ -765,7 +930,7 @@ and its continuation markers. A replaced description re-wraps inside the caller'
|
|
|
765
930
|
to `WRAP_WIDTH`, because a doc block's own wrapping is not recoverable from its text.
|
|
766
931
|
|
|
767
932
|
Every replacer reports a miss the same way. `undefined` means "not replaced", and it covers a key
|
|
768
|
-
that reaches no row, a table carrying no
|
|
933
|
+
that reaches no row, a table carrying no column of the header written, a title no fence or tag carries, a text
|
|
769
934
|
that is no doc block, a summary carrying no word, and a language or code the emitted three-backtick
|
|
770
935
|
fence cannot enclose or the doc block cannot hold — a body carrying `*/`. A caller reports the key
|
|
771
936
|
it could not place instead of writing a file it could not read back.
|
|
@@ -800,8 +965,10 @@ reachable exact `.ts` target for `surface()` to observe them; absent keys remain
|
|
|
800
965
|
```ts
|
|
801
966
|
import { createGuide } from '@orkestrel/guide'
|
|
802
967
|
|
|
803
|
-
const guide = createGuide(
|
|
804
|
-
|
|
968
|
+
const guide = createGuide(
|
|
969
|
+
'## Surface\n\n| Name | Kind | Signature | Summary |\n| --- | --- | --- | --- |\n| `X` | class | `new () => X` | |',
|
|
970
|
+
)
|
|
971
|
+
guide.surface() // [{ name: 'X', keyword: 'class', signature: '`new () => X`' }]
|
|
805
972
|
guide.sections() // ['Surface']
|
|
806
973
|
```
|
|
807
974
|
|
|
@@ -860,7 +1027,9 @@ sources.sources() // [the one shared view both specifiers name]
|
|
|
860
1027
|
```ts
|
|
861
1028
|
import { createGuide, createSource, findMissingSymbols } from '@orkestrel/guide'
|
|
862
1029
|
|
|
863
|
-
const guide = createGuide(
|
|
1030
|
+
const guide = createGuide(
|
|
1031
|
+
'## Surface\n\n| Name | Kind | Signature | Summary |\n| --- | --- | --- | --- |\n| `Guide` | class | `new () => Guide` | |',
|
|
1032
|
+
)
|
|
864
1033
|
const source = createSource({
|
|
865
1034
|
files: {
|
|
866
1035
|
'src/core/index.ts': "export * from './Guide.js'\n",
|
|
@@ -882,7 +1051,7 @@ findMissingSymbols(guide.surface(), source.surface()) // []
|
|
|
882
1051
|
import { createGuide, createSource, findDrift } from '@orkestrel/guide'
|
|
883
1052
|
|
|
884
1053
|
const guide = createGuide(
|
|
885
|
-
'## Surface\n\n| Name | Kind | Summary |\n| --- | --- | --- |\n| `walk` | function | Walks the tree. |',
|
|
1054
|
+
'## Surface\n\n| Name | Kind | Signature | Summary |\n| --- | --- | --- | --- |\n| `walk` | function | `() => void` | Walks the tree. |',
|
|
886
1055
|
)
|
|
887
1056
|
const source = createSource({
|
|
888
1057
|
files: {
|
|
@@ -979,16 +1148,16 @@ await new GuideCommand({
|
|
|
979
1148
|
### Carry a summary across into the guide
|
|
980
1149
|
|
|
981
1150
|
```ts
|
|
982
|
-
import { replaceCell, replaceSummary } from '@orkestrel/guide'
|
|
1151
|
+
import { buildCell, replaceCell, replaceSummary, SUMMARY } from '@orkestrel/guide'
|
|
983
1152
|
|
|
984
1153
|
const guide =
|
|
985
|
-
'## Surface\n\n| Name | Kind | Summary |\n| --- | --- | --- |\n| `walk` | function | Walks the tree. |'
|
|
1154
|
+
'## Surface\n\n| Name | Kind | Signature | Summary |\n| --- | --- | --- | --- |\n| `walk` | function | `() => void` | Walks the tree. |'
|
|
986
1155
|
|
|
987
1156
|
// The guide's text back, with that one cell replaced and every byte outside the table unchanged.
|
|
988
|
-
replaceCell(guide, 'function walk', 'Walks a tree.')
|
|
989
|
-
// '## Surface\n\n| Name | Kind | Summary |\n| --- | --- | --- |\n| `walk` | function | Walks a tree. |'
|
|
990
|
-
replaceCell(guide, 'function phantom', 'Absent.') // undefined — no row carries that key
|
|
991
|
-
replaceCell(guide, 'function walk', 'Walks the tree.') === guide // true — the row already carries it
|
|
1157
|
+
replaceCell(guide, 'function walk', SUMMARY, buildCell('Walks a tree.'))
|
|
1158
|
+
// '## Surface\n\n| Name | Kind | Signature | Summary |\n| --- | --- | --- | --- |\n| `walk` | function | `() => void` | Walks a tree. |'
|
|
1159
|
+
replaceCell(guide, 'function phantom', SUMMARY, buildCell('Absent.')) // undefined — no row carries that key
|
|
1160
|
+
replaceCell(guide, 'function walk', SUMMARY, buildCell('Walks the tree.')) === guide // true — the row already carries it
|
|
992
1161
|
|
|
993
1162
|
// The other direction: one doc block's raw text, its description paragraph replaced.
|
|
994
1163
|
replaceSummary('/** Walks the tree. */', 'Walks a tree.') // '/** Walks a tree. */'
|
|
@@ -1025,10 +1194,14 @@ resolveLink('index.ts', './root.ts') // 'root.ts'
|
|
|
1025
1194
|
## Tests
|
|
1026
1195
|
|
|
1027
1196
|
This repository runs the catalog against itself. Its `tests/guides.test.ts` wires RN, SB, MB, LI,
|
|
1028
|
-
TE, NV, FL, EX, FI, SQ, MQ, EQ, and RQ. Every `## Surface` and `## Methods` table here heads its
|
|
1197
|
+
TE, NV, FL, EX, FI, SQ, GQ, MQ, EQ, and RQ. Every `## Surface` and `## Methods` table here heads its
|
|
1029
1198
|
compared column `Summary`, so `findDrift` reads every row this guide documents and the equality
|
|
1030
|
-
case asserts the whole worklist empty
|
|
1031
|
-
|
|
1199
|
+
case asserts the whole worklist empty. The `Kind` column supplies the symbol keyword, and every
|
|
1200
|
+
`Signature` cell here is the engine's output, written by `npm run test:guides -- --to guide` and
|
|
1201
|
+
compared against `src/core` and `src/server` as this checkout's compiler emits them. Guide
|
|
1202
|
+
construction refuses a nonuniform Surface header and every keyed row with an empty Signature cell,
|
|
1203
|
+
and parity refuses a name this checkout's `src/core` and `src/server` both export.
|
|
1204
|
+
The Methods `Returns` column stays outside drift. EQ compares a `## Patterns` fence only where an `@example`
|
|
1032
1205
|
block carries the same title, so a fence composing several symbols, a fence whose body a
|
|
1033
1206
|
three-backtick doc-block fence cannot enclose, a fence whose body carries the doc-comment
|
|
1034
1207
|
terminator `*/`, and a class's constructor-door block stay outside it; a case beside the equality
|
|
@@ -1036,17 +1209,22 @@ one pins that at least one title pairs, so retiring the example half reddens the
|
|
|
1036
1209
|
source authority into guides with `npm run test:guides -- --to guide`, or guide authority into
|
|
1037
1210
|
source with `npm run test:guides -- --to source`; never weaken the case.
|
|
1038
1211
|
|
|
1039
|
-
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — direct `SourceLine`, lexical, and JSDoc-alignment invariants; projected declaration-keyword direct/hidden reflection; genuine JSDoc example adjacency and faux JSDoc exclusion; every guide-document extractor; the compared form clause by clause on both sides; the `Summary`
|
|
1212
|
+
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — direct `SourceLine`, lexical, and JSDoc-alignment invariants; projected declaration-keyword direct/hidden reflection; genuine JSDoc example adjacency and faux JSDoc exclusion; every guide-document extractor; the compared form clause by clause on both sides; the exact `Signature` and `Summary` locators over reordered headers, absent columns, and empty cells; signature-independent symbol keys; uniform renderer output with escaped unions; the nameless-row finding against a name the reader reads through emphasis; a block tag written past one space after the continuation marker, and a tag-shaped line inside a fenced body left to the example code; the fenced-body projection `maskFences` returns; fence titles and the tagline; `findDrift` with a negative control drawn from the symbols the bijection legs already report, a planted disagreement of each kind, and a later fence under one heading left outside the comparison; the doc-block reader against `parseSync`'s own reading, which names the shape the reader misses; the compared cell built back from its text, over every doc-block summary this package ships; the compared form's code-span clause converging a padded, a one-sided, and an all-whitespace span from either side, leaving a link token inside a span literal, and leaving a multi-backtick span untouched; the corpus this package ships carrying a floor of blocks, read at its raw spans through the aligned JSDoc projection and checked against the blocks `extractSourceComments` attaches; the renderers round-tripping through the readers that own them and the render read the same as the column-aligned committed form; each replacer's located node rewritten with every byte outside it unchanged, its miss returning `undefined`, and its identity case byte-stable over every described doc block this package ships and a fixed point on the second run, with a control from outside each replacer's membership; the one key grammar `collectKeys` reports over the control fixtures and a member fixture, its owner closing at a column-zero brace, and the keyword and member name each reader splits back out of it; `locateComment` over an overload set, a member key, an owner closed at its brace, a CRLF file, and the shapes the attaching reader misses, then a rewrite spliced back and read through `collectSummaries`, and every `Owner.member` key this package's own source declares located back to the block carrying that member's summary; canonical-key, runtime-name, `resolvePath`, and `resolveLink` invariants; all remaining helper leaves; bracket depths, separators, member rendering, and every emitted-declaration signature form; signature drift and the `Signature` cell rewrite; `validateSurface` over a repeated section and a keyed empty cell; `validateModules` reporting every collision in one refusal, refusing one name declared as two kinds and one name a parent module and its nested module both export, naming the entry's layer core, with distinct-name, single-module, and nested-module controls
|
|
1040
1213
|
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseManifest` row parsing, malformed-row skipping, one-versus-many Source canonicalization, and nested manifest directories.
|
|
1041
1214
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — `isExportKeyword` / `isSurfaceSymbol` / `isMethodEntry` / `isSourceExample` / `isDrift` / `isMethodGroup` / `isManifestEntry`.
|
|
1042
1215
|
- [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — per-shape guard exactness, JSON Schema essentials, seeded generate round-trips, parse rebuilds.
|
|
1043
1216
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createGuide` / `createSource` + the compiled symbol, entry, example, drift, group, and manifest contracts.
|
|
1044
|
-
- [`tests/src/core/Guide.test.ts`](../tests/src/core/Guide.test.ts) —
|
|
1045
|
-
- [`tests/src/core/
|
|
1217
|
+
- [`tests/src/core/Guide.test.ts`](../tests/src/core/Guide.test.ts) — uniform table parsing; exact coded refusals for old headers and empty signatures; encounter order, repeated Surface sections, and bounded JSON diagnostics; cached projections, tagline, nameless rows, fence titles, and production barrel/Guide phantom and keyword-drift controls.
|
|
1218
|
+
- [`tests/src/core/errors.test.ts`](../tests/src/core/errors.test.ts) — error code, message, cause, identity descriptor, subclass recognition, and rejection of lookalikes and proxies; a JSON `context` under every declared code, and refusal of a context of another shape.
|
|
1219
|
+
- [`tests/src/core/Parity.test.ts`](../tests/src/core/Parity.test.ts) — parity findings, rewrite boundaries, and propagation of parse refusals with the guide path and cause. The `Signature` cell rewrite under guide authority and its report under source authority; the README named in a refused pitch parse; a name two modules of one entry export, refused with the guide, the name, and both modules, beside a distinct-name control.
|
|
1220
|
+
- [`tests/src/core/sources/Source.test.ts`](../tests/src/core/sources/Source.test.ts) — direct/barrel projections, lexical and JSDoc regressions, canonical-key populations, root and nested indexes, exact row grammar, graph invariants, and correlated population controls; signatures carried from supplied emitted declarations
|
|
1046
1221
|
- [`tests/src/core/sources/SourceManager.test.ts`](../tests/src/core/sources/SourceManager.test.ts) — `computeModuleKey` boundary collision, specifier resolution, the `undefined` skip for an unmapped specifier, array-valued module scopes, `sources()` enumeration, and per-module entity sharing with a differently-scoped identity control.
|
|
1047
|
-
- [`tests/src/server/GuideCommand.test.ts`](../tests/src/server/GuideCommand.test.ts) — direct installed reader and runner ports, fresh worker context, registration rejection, real runner cleanup after start failure, cleanup failure reporting, and higher native exit preservation
|
|
1048
|
-
- [`tests/src/server/
|
|
1049
|
-
- [`tests/src/server/
|
|
1222
|
+
- [`tests/src/server/GuideCommand.test.ts`](../tests/src/server/GuideCommand.test.ts) — malformed guide rejection with its path, code, and required header; direct installed reader and runner ports, fresh worker context, registration rejection, real runner cleanup after start failure, cleanup failure reporting, and higher native exit preservation; compile refusal naming the module; native `--to guide` signature rewrite and `--to source` report with exit codes; a malformed guide refused before any compile; one compile per module across a `--to guide` run, counted through a recording compiler; native exit 1 for a header refusal and for a compile refusal; a name `src/core` and `src/server` both export, refused, beside a distinct-name control that resolves
|
|
1223
|
+
- [`tests/src/server/GuideCompiler.test.ts`](../tests/src/server/GuideCompiler.test.ts) — every signature form computed from a fixture workspace compiler; byte-equal repeated compiles; refusal of a failing compile, a missing project, a module outside `src/<env>` and `app/<env>`, and a workspace with no compiler; coded `compile` refusals with the compiler output in `context`; `empty` refusals for a `declarationDir` and for an `include` that misses the module; `timeout` and `overflow` refusals; the scratch directory gone after a success and after a failure; sorted keys.
|
|
1224
|
+
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — finding formatting, native and file-URL root resolution, pitch selection, and owned foreign-result reading with live receivers. Module-to-project mapping.
|
|
1225
|
+
- [`tests/src/server/parsers.test.ts`](../tests/src/server/parsers.test.ts) — native direction arguments and package-name parsing. `rootDir` reading from `--showConfig` output.
|
|
1226
|
+
- [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the native carrier and `readGuideBuild`, which returns the built server entry the native-command cases load and refuses a missing build or one older than a source.
|
|
1227
|
+
- [`tests/distribution.test.ts`](../tests/distribution.test.ts) — the packed package through the `tests/setupDistribution.ts` harness, and `isGuideError` across the packed `import` and `require` entries and a copy at a second path: pairwise-distinct constructors, a hidden brand, subclass recognition, and refusal of a look-alike, a proxy, and a brand-only object.
|
|
1050
1228
|
- [`tests/fixtures/broken/stranded-export`](../tests/fixtures/broken/stranded-export) — permanent negative control: its guide and direct declarations agree while its conventional barrel omits `strandedExport`.
|
|
1051
1229
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the drop-in guides-parity suite, run against **this** repository's own `guides/README.md` manifest — the self-dogfooding acceptance criterion.
|
|
1052
1230
|
|