@orkestrel/scaffold 0.0.112 → 0.0.114
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/agents/skills/orkestrel-harden/scripts/titles.js +3 -3
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +120 -21
- package/dist/bin/main.js +71 -23
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/platforms/windows.md +1 -1
- package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +3 -3
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +25 -8
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +187 -54
- package/dist/host/claude/agents/orkestrel.md +53 -53
- package/dist/host/claude/rules/architecture.md +4 -3
- package/dist/host/claude/rules/tests.md +24 -7
- package/dist/host/claude/rules/typescript.md +11 -2
- package/dist/host/claude/rules/workspace.md +32 -28
- package/dist/host/configs/policy.ts +49 -0
- package/dist/host/dotfiles/gitignore +1 -0
- package/dist/host/dotfiles/oxlintrc.json +6 -0
- package/dist/host/guides/agent.md +13 -13
- package/dist/host/guides/brief.md +4 -0
- package/dist/host/guides/browser.md +162 -44
- package/dist/host/guides/budget.md +1 -1
- package/dist/host/guides/capture.md +4 -0
- package/dist/host/guides/console.md +13 -0
- package/dist/host/guides/contract.md +38 -3
- package/dist/host/guides/csv.md +5 -0
- package/dist/host/guides/database.md +58 -8
- package/dist/host/guides/form.md +17 -0
- package/dist/host/guides/guide.md +36 -33
- package/dist/host/guides/html.md +72 -44
- package/dist/host/guides/indexeddb.md +4 -0
- package/dist/host/guides/lsp.md +49 -8
- package/dist/host/guides/markdown.md +146 -1
- package/dist/host/guides/mcp.md +117 -22
- package/dist/host/guides/middleware.md +194 -26
- package/dist/host/guides/msg.md +9 -5
- package/dist/host/guides/pool.md +8 -1
- package/dist/host/guides/probe.md +13 -1
- package/dist/host/guides/process.md +102 -90
- package/dist/host/guides/program.md +4 -0
- package/dist/host/guides/qualifier.md +4 -0
- package/dist/host/guides/rater.md +4 -0
- package/dist/host/guides/reason.md +6 -4
- package/dist/host/guides/relation.md +4 -0
- package/dist/host/guides/scaffold.md +32 -14
- package/dist/host/guides/server.md +29 -13
- package/dist/host/guides/sqlite.md +6 -0
- package/dist/host/guides/sse.md +6 -0
- package/dist/host/guides/study.md +473 -473
- package/dist/host/guides/table.md +3 -0
- package/dist/host/guides/template.md +3 -0
- package/dist/host/guides/test.md +38 -20
- package/dist/host/guides/tool.md +3 -0
- package/dist/host/guides/toolbox.md +21 -0
- package/dist/host/guides/websocket.md +3 -1
- package/dist/host/guides/workflow.md +103 -11
- package/dist/host/guides/workspace.md +4 -0
- package/dist/host/manifest.json +56 -56
- package/dist/host/tests/config.test.ts +72 -16
- package/dist/host/tests/policy.test.ts +21 -7
- package/dist/host/tests/setupPolicy.ts +147 -12
- package/dist/src/core/index.cjs +22 -28
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +8 -8
- package/dist/src/core/index.d.ts +8 -8
- package/dist/src/core/index.js +22 -28
- package/dist/src/core/index.js.map +1 -1
- package/package.json +12 -12
package/dist/host/guides/html.md
CHANGED
|
@@ -18,8 +18,10 @@ The full node shape and handle contract, from [`types.ts`](../src/core/types.ts)
|
|
|
18
18
|
| Name | Kind | Shape | Summary |
|
|
19
19
|
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
20
20
|
| `HTMLAttribute` | interface | `{ name, value? }` | Represents one attribute of an `ElementNode` - its `name` and, when the source wrote one, its `value`. |
|
|
21
|
+
| `HTMLAttributeValue` | type | `readonly [value: string, next: number]` | Carries one decoded attribute value and its exclusive source boundary. |
|
|
22
|
+
| `HTMLOrigin` | type | `readonly [node: HTMLNode, source: HTMLNode \| undefined]` | Carries one derived node and its recorded source identity. |
|
|
21
23
|
| `HTMLStartTag` | interface | `{ name, attributes, slashed, next }` | Represents one unambiguous start tag parsed directly from source without recovery. |
|
|
22
|
-
| `HTMLTag` | interface | `{ name, attributes,
|
|
24
|
+
| `HTMLTag` | interface | `{ name, attributes, final, next }` | Represents one start or close tag returned by the total, recovering `scanTag` scanner. |
|
|
23
25
|
| `ElementNode` | interface | `{ category, name, attributes, children }` | Represents an element - `<p>`, `<table>`, `<my-widget>`, or any other tag, known or custom. |
|
|
24
26
|
| `TextNode` | interface | `{ category, value }` | Represents a run of character data - the leaf node, whose `value` is already-decoded text. |
|
|
25
27
|
| `CommentNode` | interface | `{ category, value }` | Represents a comment - `<!-- … -->` - whose `value` is verbatim inner text, never decoded and never parsed as markup. |
|
|
@@ -95,45 +97,67 @@ The document coercers, from [`parsers.ts`](../src/core/parsers.ts). `parseProven
|
|
|
95
97
|
|
|
96
98
|
### Helpers
|
|
97
99
|
|
|
98
|
-
Pure leaves from [`helpers.ts`](../src/core/helpers.ts) — the lexical scanners the document walk composes, the name, element, and URL predicates every engine consults, and the functional core `HTML`'s engines compose and callers reach for directly on a bare node. Every one of them is independently testable, and a hostile value degrades to `''`, to an empty list, or to the input unchanged, contained by `attempt` from `@orkestrel/contract` rather than by a second boundary of this package's own (§ [Relationship with `@orkestrel/contract`](#relationship-with-orkestrelcontract)). `
|
|
99
|
-
|
|
100
|
-
| Name
|
|
101
|
-
|
|
|
102
|
-
| `normalizeSource`
|
|
103
|
-
| `projectSpan`
|
|
104
|
-
| `findOpenPosition`
|
|
105
|
-
| `projectDepth`
|
|
106
|
-
| `lowercaseASCII`
|
|
107
|
-
| `isVoidElement`
|
|
108
|
-
| `isRawElement`
|
|
109
|
-
| `isLiteralElement`
|
|
110
|
-
| `isBlockElement`
|
|
111
|
-
| `isEmptyElement`
|
|
112
|
-
| `decodeEntities`
|
|
113
|
-
| `scanAttributes`
|
|
114
|
-
| `parseStartTag`
|
|
115
|
-
| `scanTag`
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
100
|
+
Pure leaves from [`helpers.ts`](../src/core/helpers.ts) — the lexical scanners the document walk composes, the name, element, and URL predicates every engine consults, and the functional core `HTML`'s engines compose and callers reach for directly on a bare node. Every one of them is independently testable, and a hostile value degrades to `''`, to an empty list, or to the input unchanged, contained by `attempt` from `@orkestrel/contract` rather than by a second boundary of this package's own (§ [Relationship with `@orkestrel/contract`](#relationship-with-orkestrelcontract)). `renderHTMLPart` and `scanHTMLIndex` are composition leaves: the former propagates unreadable-node errors to `renderHTML`'s containment, and the latter propagates predicate errors to its caller. `scanHTMLIndex` accepts safe integer bounds. `foldNode` also propagates errors: it runs the handler table you supply and lets a handler's error propagate, exactly as `fold` does (§ [The sanitize floor](#the-sanitize-floor)). The canonical form the renderers write and the constructs they refuse are § [Roundtrip laws](#roundtrip-laws), and what the text projection drops is § [Text is the lossy projection](#text-is-the-lossy-projection).
|
|
101
|
+
|
|
102
|
+
| Name | Kind | Signature | Summary |
|
|
103
|
+
| ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
104
|
+
| `normalizeSource` | function | `(html: string) => HTMLSource` | Normalizes an HTML input - CRLF and a lone carriage return to one newline, `U+0000` to `U+FFFD` - and maps each normalized boundary to its original UTF-16 offset. |
|
|
105
|
+
| `projectSpan` | function | `(offsets: readonly number[], start: number, end: number) => HTMLSpan \| undefined` | Projects a normalized half-open region through an original-input boundary map. |
|
|
106
|
+
| `findOpenPosition` | function | `(represented: ReadonlyMap<string, readonly number[]>, overflow: ReadonlyMap<string, readonly number[]>, name: string) => HTMLOpenPosition \| undefined` | Finds the deepest open occurrence of an element name across the parser's represented and depth-overflow stacks. |
|
|
107
|
+
| `projectDepth` | function | `(overflow: boolean, position: number, height: number) => number` | Projects one stack position onto the single depth scale the represented and depth-overflow stacks compare on, so an overflow position ranks below every represented one. |
|
|
108
|
+
| `lowercaseASCII` | function | `(value: string) => string` | Lowercases only ASCII uppercase characters, preserving every other code point exactly. |
|
|
109
|
+
| `isVoidElement` | function | `(name: string) => boolean` | Determines whether an element name is void, matching `VOID_ELEMENTS` without case sensitivity. |
|
|
110
|
+
| `isRawElement` | function | `(name: string) => boolean` | Determines whether an element name contains verbatim raw text - `script` or `style`, the parser's no-scanning boundary and the renderer's refusal boundary. |
|
|
111
|
+
| `isLiteralElement` | function | `(name: string) => boolean` | Determines whether an element name contains decoded literal text - `title` or `textarea`, whose body is one text node with character references resolved. |
|
|
112
|
+
| `isBlockElement` | function | `(name: string) => boolean` | Determines whether an element name is a block boundary, matching `BLOCK_ELEMENTS`. |
|
|
113
|
+
| `isEmptyElement` | function | `(element: ElementNode) => boolean` | Checks whether an element has no child nodes - the predicate the distill pass consults before dropping an empty non-void element. |
|
|
114
|
+
| `decodeEntities` | function | `(value: string) => string` | Decodes numeric and semicolon-terminated WHATWG named character references in a string. |
|
|
115
|
+
| `scanAttributes` | function | `(source: string) => readonly HTMLAttribute[]` | Scans an attribute source segment into ordered, ASCII-lowercased, first-wins attributes with decoded values. |
|
|
116
|
+
| `parseStartTag` | function | `(html: string, offset: number) => HTMLStartTag \| undefined` | Parses one unambiguous start tag without recovery under the package's ASCII tag-name grammar. |
|
|
117
|
+
| `scanTag` | function | `(html: string, offset: number) => HTMLTag \| undefined` | Scans one complete start or close tag. |
|
|
118
|
+
| `scanHTMLIndex` | function | `(start: number, end: number, accept: (index: number) => boolean) => number` | Finds the first refused index in a numeric span with logarithmically bounded recursion. |
|
|
119
|
+
| `scanHTMLAttributeValue` | function | `(html: string, start: number) => HTMLAttributeValue \| undefined` | Scans one complete quoted or unquoted attribute value under the strict token grammar. |
|
|
120
|
+
| `scanComment` | function | `(html: string, offset: number) => HTMLScan<CommentNode> \| undefined` | Scans a standard or bogus HTML comment. |
|
|
121
|
+
| `scanDoctype` | function | `(html: string, offset: number) => HTMLScan<DoctypeNode> \| undefined` | Scans an HTML doctype with optional public and system identifiers. |
|
|
122
|
+
| `scanRawText` | function | `(html: string, offset: number, name: string, entities?: boolean) => HTMLRawText` | Scans text through the case-insensitive matching close tag of a raw or literal element. |
|
|
123
|
+
| `encodeText` | function | `(value: string) => string` | Encodes the characters that have markup meaning in HTML text - `&`, `<`, and `>`, and nothing else. |
|
|
124
|
+
| `encodeAttribute` | function | `(value: string) => string` | Encodes the characters that have markup meaning in a double-quoted HTML attribute - `&` and `"`, and nothing else. |
|
|
125
|
+
| `sanitizeURL` | function | `(value: string, schemes: ReadonlySet<string> \| readonly string[]) => string` | Decodes and inspects a URL against an explicit scheme allowlist and a fixed dangerous floor. |
|
|
126
|
+
| `isSafeURL` | function | `(value: string, schemes?: ReadonlySet<string> \| readonly string[]) => boolean` | Determines whether a URL is relative or uses an allowed non-dangerous scheme. |
|
|
127
|
+
| `resolveURL` | function | `(value: string, base: string) => string` | Resolves a URL through the platform WHATWG URL implementation. |
|
|
128
|
+
| `attributeOf` | function | `(node: ElementNode, name: string) => string \| undefined` | Finds an element attribute without case sensitivity. |
|
|
129
|
+
| `sanitizeAttributes` | function | `(node: ElementNode, attributes: ReadonlySet<string> \| readonly string[], schemes: ReadonlySet<string> \| readonly string[]) => readonly HTMLAttribute[]` | Filters an element's attributes down to the ones a sanitized document may carry. |
|
|
130
|
+
| `resolveAttributes` | function | `(node: ElementNode, base: string) => readonly HTMLAttribute[]` | Resolves an element's URL attributes against a base URL. |
|
|
131
|
+
| `resolveDerivations` | function | `(origins: Iterable<HTMLOrigin>) => ReadonlyMap<HTMLNode, HTMLNode \| undefined>` | Resolves recorded source identities, refusing a node with conflicting origins. |
|
|
132
|
+
| `collapseSpace` | function | `(value: string) => string` | Collapses a run of whitespace to one inter-word space and removes edge whitespace. |
|
|
133
|
+
| `renderHTML` | function | `(node: HTMLNode) => string` | Serializes an HTML node to canonical, safety-bounded HTML. |
|
|
134
|
+
| `renderHTMLPart` | function | `(node: HTMLNode, children: readonly string[]) => string` | Renders one HTML node from its already-rendered children. |
|
|
135
|
+
| `renderText` | function | `(node: HTMLNode) => string` | Projects an HTML node to structural plain text. |
|
|
136
|
+
| `walkNodes` | function | `(node: HTMLNode) => Generator<HTMLNode>` | Walks an HTML node depth-first in pre-order, lazily and depth-bounded, including the supplied root. |
|
|
137
|
+
| `foldNode` | function | `<T>(node: HTMLNode, handlers: HTMLHandlerMap<T>) => T` | Folds an HTML node bottom-up through a total handler table - each node's children fold first, then its own handler runs with those already-folded results. |
|
|
138
|
+
| `rewriteDocument` | function | `(document: HTMLDocument, rewrite: HTMLRewriteHandler) => HTMLDerivation<HTMLDocument>` | Rewrites a document bottom-up with copy-on-write identity preservation. |
|
|
139
|
+
| `mergeText` | function | `(children: readonly HTMLNode[]) => readonly HTMLNode[]` | Restores the no-adjacent-text invariant in a rebuilt list of siblings. |
|
|
140
|
+
| `collapseText` | function | `(children: readonly HTMLNode[]) => HTMLDerivation<readonly HTMLNode[]>` | Collapses the whitespace runs inside each direct text child of a sibling list. |
|
|
141
|
+
| `extractRegion` | function | `(document: HTMLDocument, names: readonly string[]) => HTMLDerivation<HTMLDocument>` | Re-roots a document at the sole occurrence of one of the named region elements. |
|
|
142
|
+
| `pruneDocument` | function | `(document: HTMLDocument, prune: HTMLPruneHandler) => HTMLDerivation<HTMLDocument>` | Rebuilds a document bottom-up, letting each node become any number of nodes - the one-to-many spine the sanitize and distill engines share. |
|
|
143
|
+
|
|
144
|
+
The scanner and renderer composition leaves can also be called directly:
|
|
145
|
+
|
|
146
|
+
```ts
|
|
147
|
+
import type { HTMLNode } from '@orkestrel/html'
|
|
148
|
+
import {
|
|
149
|
+
renderHTMLPart,
|
|
150
|
+
resolveDerivations,
|
|
151
|
+
scanHTMLAttributeValue,
|
|
152
|
+
scanHTMLIndex,
|
|
153
|
+
} from '@orkestrel/html'
|
|
154
|
+
|
|
155
|
+
scanHTMLIndex(0, 4, (index) => index < 2) // 2
|
|
156
|
+
scanHTMLAttributeValue('"a&b">', 0) // ['a&b', 9]
|
|
157
|
+
renderHTMLPart({ category: 'text', value: '<' }, []) // '<'
|
|
158
|
+
const node: HTMLNode = { category: 'text', value: 'x' }
|
|
159
|
+
resolveDerivations([[node, node]]).get(node) // node
|
|
160
|
+
```
|
|
137
161
|
|
|
138
162
|
### Shapers
|
|
139
163
|
|
|
@@ -367,8 +391,10 @@ page.span(page.document) // { start: 0, end: 40 } - half-open offsets in the ori
|
|
|
367
391
|
page.find(isElementNode)?.name // 'h1' - narrowed to ElementNode by the guard overload
|
|
368
392
|
page.filter(isElementNode).map((element) => element.name) // ['h1', 'p', 'b']
|
|
369
393
|
|
|
370
|
-
const categories
|
|
371
|
-
|
|
394
|
+
const categories = page
|
|
395
|
+
.walk()
|
|
396
|
+
.map((node) => node.category)
|
|
397
|
+
.toArray()
|
|
372
398
|
// ['document', 'element', 'text', 'element', 'text', 'element', 'text', 'text']
|
|
373
399
|
```
|
|
374
400
|
|
|
@@ -428,7 +454,9 @@ const page = createHTML('<h1>Title</h1><p>First.</p><p>Second.</p>')
|
|
|
428
454
|
|
|
429
455
|
// universal - a reader loop works in every ReadableStream-supporting environment
|
|
430
456
|
const reader = page.stream().getReader()
|
|
431
|
-
for (
|
|
457
|
+
for (;;) {
|
|
458
|
+
const result = await reader.read()
|
|
459
|
+
if (result.done) break
|
|
432
460
|
result.value.category // 'element' - the root's direct children only
|
|
433
461
|
}
|
|
434
462
|
|
|
@@ -595,7 +623,7 @@ parseStartTag('<html lang="en" data-bs-theme="light">', 0)
|
|
|
595
623
|
parseStartTag('<html data-note="unterminated>', 0) // undefined — no recovery
|
|
596
624
|
|
|
597
625
|
scanTag('<IMG SRC="x.png" alt=hi />', 0)
|
|
598
|
-
// { name: 'img', attributes: [{ name: 'src', value: 'x.png' }, { name: 'alt', value: 'hi' }],
|
|
626
|
+
// { name: 'img', attributes: [{ name: 'src', value: 'x.png' }, { name: 'alt', value: 'hi' }], final: false, next: 26 }
|
|
599
627
|
|
|
600
628
|
scanAttributes(' HREF="/a" disabled href="/b"')
|
|
601
629
|
// [{ name: 'href', value: '/a' }, { name: 'disabled' }] - lowercased, first wins, valueless stays valueless
|
|
@@ -55,6 +55,10 @@ await users.index('byAge').records(rangeFromKey(18)) // adults, index-backed (O(
|
|
|
55
55
|
|
|
56
56
|
### Helpers and errors
|
|
57
57
|
|
|
58
|
+
`isIndexedDBError` recognizes the error's own identity brand, declared code, and
|
|
59
|
+
context across package copies. Subclass instances pass without an exact name;
|
|
60
|
+
transparent proxies, unbranded look-alikes, and plain branded objects fail.
|
|
61
|
+
|
|
58
62
|
| API | Kind | Summary |
|
|
59
63
|
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
60
64
|
| `supportsIndexedDB` | function | Checks whether IndexedDB is available in this environment. |
|
package/dist/host/guides/lsp.md
CHANGED
|
@@ -189,8 +189,9 @@ later continuation. The parser accepts unknown header fields and refuses malform
|
|
|
189
189
|
known `Content-Type` field. Use `encodeLSPMessage()` to produce a byte-accurate frame.
|
|
190
190
|
|
|
191
191
|
The core package publishes the operations over a retained state beside the codec.
|
|
192
|
-
`
|
|
193
|
-
|
|
192
|
+
`LSPChain` walks retained segments newest first. Its `join()` method flattens the chain into one
|
|
193
|
+
owned buffer, and `tail()` takes its last bytes into an owned scan window. Each instance owns one
|
|
194
|
+
traversal; construct a fresh instance for each operation.
|
|
194
195
|
`scanLSPBoundary()` reports the first `\r\n\r\n` index in a flat buffer, and that index addresses
|
|
195
196
|
the buffer you passed, so a caller scanning a window adds the window's own offset to it.
|
|
196
197
|
`scanLSPBoundary()` returns the boundary's index, so `bytes.subarray(0, boundary)` is the block
|
|
@@ -200,15 +201,27 @@ Flatten a retained state, scan that buffer for the header boundary, and take the
|
|
|
200
201
|
|
|
201
202
|
```ts
|
|
202
203
|
import type { LSPDecodeState } from '@orkestrel/lsp'
|
|
203
|
-
import {
|
|
204
|
+
import { LSPChain, scanLSPBoundary } from '@orkestrel/lsp'
|
|
204
205
|
|
|
205
206
|
declare const state: LSPDecodeState
|
|
206
207
|
|
|
207
|
-
const bytes =
|
|
208
|
+
const bytes = new LSPChain(state).join()
|
|
208
209
|
const boundary = scanLSPBoundary(bytes)
|
|
209
|
-
const overlap =
|
|
210
|
+
const overlap = new LSPChain(state).tail(3)
|
|
210
211
|
```
|
|
211
212
|
|
|
213
|
+
Build a retained segment without decoding it when assembling a continuation:
|
|
214
|
+
|
|
215
|
+
```ts
|
|
216
|
+
import { buildLSPSegment } from '@orkestrel/lsp'
|
|
217
|
+
|
|
218
|
+
const state = buildLSPSegment(undefined, new TextEncoder().encode('Content-'))
|
|
219
|
+
const continued = buildLSPSegment(state, new TextEncoder().encode('Length: 40'))
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
An empty chunk preserves the preceding state by identity. Non-empty chunks are copied and retain
|
|
223
|
+
any resolved header boundary and content length.
|
|
224
|
+
|
|
212
225
|
When you frame the bytes yourself, reach the header and body grammars directly. `readLSPHeader()`
|
|
213
226
|
reads one header block and returns the `Content-Length` it declares. `readLSPBody()` reads the
|
|
214
227
|
content bytes that length measures and returns the validated JSON-RPC message. Each refuses with an
|
|
@@ -336,6 +349,27 @@ The transport interface exposes these behavioral methods:
|
|
|
336
349
|
| `send` | `send(bytes: Uint8Array): Promise<boolean>` | Sends bytes and reports whether the transport accepted them. |
|
|
337
350
|
| `close` | `close(): Promise<void>` | Closes the active transport generation. |
|
|
338
351
|
|
|
352
|
+
#### `LSPChain`
|
|
353
|
+
|
|
354
|
+
The chain exposes its iterator step and owned byte projections:
|
|
355
|
+
|
|
356
|
+
| Method | Signature | Summary |
|
|
357
|
+
| ------ | --------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
358
|
+
| `next` | `next(): IteratorResult<LSPDecodeState, undefined>` | Yields the next segment, newest first, or reports exhaustion. |
|
|
359
|
+
| `join` | `join(): Uint8Array` | Flattens the remaining segments into an owned buffer at their original offsets. |
|
|
360
|
+
| `tail` | `tail(count: number): Uint8Array` | Takes at most the requested final bytes, refusing a negative allocation length. |
|
|
361
|
+
|
|
362
|
+
Consume one traversal through its iterator protocol:
|
|
363
|
+
|
|
364
|
+
```ts
|
|
365
|
+
import type { LSPDecodeState } from '@orkestrel/lsp'
|
|
366
|
+
import { LSPChain } from '@orkestrel/lsp'
|
|
367
|
+
|
|
368
|
+
declare const state: LSPDecodeState
|
|
369
|
+
const chain = new LSPChain(state)
|
|
370
|
+
const first = chain.next()
|
|
371
|
+
```
|
|
372
|
+
|
|
339
373
|
## Surface
|
|
340
374
|
|
|
341
375
|
### Stdio client transport
|
|
@@ -375,6 +409,11 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
375
409
|
|
|
376
410
|
The framing, timing, and error surface provides these exports.
|
|
377
411
|
|
|
412
|
+
`isLSPError` recognizes an own identity brand across package copies and accepts subclasses whose
|
|
413
|
+
`name` differs. It refuses transparent proxies, unbranded lookalikes, and plain branded objects.
|
|
414
|
+
It checks the declared code and context members; context objects and callable contexts are accepted
|
|
415
|
+
when their members conform, and message arrays are checked by index without running their iterator.
|
|
416
|
+
|
|
378
417
|
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none.
|
|
379
418
|
|
|
380
419
|
| Export | Kind | Shape | Summary |
|
|
@@ -382,8 +421,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
382
421
|
| `encodeLSPMessage` | function | `(message: JSONRPCMessage) => Uint8Array` | Encodes a JSON-RPC message as one byte-accurate LSP base-protocol frame. |
|
|
383
422
|
| `parseLSPMessages` | function | `(chunk: Uint8Array, state?: LSPDecodeState) => readonly [messages: readonly JSONRPCMessage[], state: LSPDecodeState \| undefined]` | Parses a byte chunk into complete LSP base-protocol messages and retained decode state. |
|
|
384
423
|
| `LSPDecodeState` | type | `{ bytes, previous?, size } \| { bytes, previous?, size, boundary, length }` | Retains incremental base-protocol bytes and resolved framing metadata between decode calls. |
|
|
385
|
-
| `
|
|
386
|
-
| `
|
|
424
|
+
| `buildLSPSegment` | function | `(state: LSPDecodeState \| undefined, chunk: Uint8Array) => LSPDecodeState \| undefined` | Appends an owned byte segment while retaining the preceding framing metadata. |
|
|
425
|
+
| `LSPChain` | class | `IterableIterator<LSPDecodeState>` | Walks retained decode segments newest first and copies their bytes in arrival order. |
|
|
387
426
|
| `scanLSPBoundary` | function | `(bytes: Uint8Array) => number \| undefined` | Finds the first base-protocol header boundary in a flat buffer. |
|
|
388
427
|
| `readLSPHeader` | function | `(header: Uint8Array, messages?: readonly JSONRPCMessage[]) => number` | Reads one base-protocol header block and returns the content length it declares. |
|
|
389
428
|
| `readLSPBody` | function | `(body: Uint8Array, messages?: readonly JSONRPCMessage[]) => JSONRPCMessage` | Reads one base-protocol content body as a validated JSON-RPC message. |
|
|
@@ -506,7 +545,9 @@ A `Shape` cell holds the constant's declared type.
|
|
|
506
545
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` and `src/server` bijection, the `LSPClientInterface` ↔ `LSPClient` and `LSPTransportInterface` method bijections, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Create a client and inspect a document` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
|
|
507
546
|
- [`tests/src/core/LSPClient.test.ts`](../tests/src/core/LSPClient.test.ts) — the handshake, the ready and dead generations, document ownership, the pull and push diagnostics paths, the abort and timeout bounds, and bounded teardown.
|
|
508
547
|
- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createLSPClient` returns a working `LSPClientInterface` over the options it is handed.
|
|
509
|
-
- [`tests/src/core/
|
|
548
|
+
- [`tests/src/core/LSPFraming.test.ts`](../tests/src/core/LSPFraming.test.ts) — frame transitions, retained incomplete state, refusal contexts, and coalesced-frame depth.
|
|
549
|
+
- [`tests/src/core/LSPChain.test.ts`](../tests/src/core/LSPChain.test.ts) — segment order, owned joins and tails, iterator exhaustion, and a deep single-byte chain.
|
|
550
|
+
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — `encodeLSPMessage`, the `scanLSPBoundary` index, the `readLSPHeader` and `readLSPBody` grammars with their coded refusals, and `waitForDeadline`.
|
|
510
551
|
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `parseLSPMessages` over split, coalesced, and malformed frames, and the state it retains between calls.
|
|
511
552
|
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — every guard accepts its own shape, refuses a near miss, and stays total for a hostile value.
|
|
512
553
|
- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) — `createStdioClientTransport` returns a working `StdioClientTransportInterface` over the options it is handed.
|
|
@@ -60,6 +60,10 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
60
60
|
| `MarkdownDerivation<T>` | type | `readonly [value: T, derivations: ReadonlyMap<MarkdownNode, MarkdownNode \| undefined>]` | Pairs a rewritten value with the input node each rewritten node was produced from — what `rewriteDocument` returns, so provenance survives a rewrite instead of ending at it. `T` is the rewritten value: the document for a whole-document rewrite. |
|
|
61
61
|
| `MarkdownInterface` | interface | `{ document } plus walk, find, filter, span, map, reduce, fold, stream` | Represents a stateful, parsed markdown document: the typed `MarkdownDocument` AST plus the query, rewrite, and fold operations over it. |
|
|
62
62
|
|
|
63
|
+
| Type | Kind | Shape | Summary |
|
|
64
|
+
| -------------------- | --------- | --------------- | ---------------------------------------------------------------------------- |
|
|
65
|
+
| `MarkdownInlineScan` | interface | `{ node, end }` | Represents an inline construct and the source offset where scanning resumes. |
|
|
66
|
+
|
|
63
67
|
### Constants
|
|
64
68
|
|
|
65
69
|
From [`constants.ts`](../src/core/constants.ts).
|
|
@@ -138,6 +142,29 @@ Pure, total leaves from [`helpers.ts`](../src/core/helpers.ts) — the line and
|
|
|
138
142
|
| `rewriteDocument` | function | `(document: MarkdownDocument, rewrite: MarkdownRewriteHandler) => MarkdownDerivation<MarkdownDocument>` | Rewrites a `MarkdownDocument` bottom-up (copy-on-write) — each node's children are rewritten first (post-order), then `rewrite` is applied to the node itself; the document root is never passed to `rewrite` (the `element: 'document'` invariant always holds). A table's inline cells and a list's items are rewritten too. |
|
|
139
143
|
| `flattenText` | function | `(node: MarkdownNode) => string` | Concatenates the `value` / `code` content of every descendant text / code-span / code-block node under `node`, including image alternative content, in walk order — the plain-text projection of an AST (search indexing, word counts, a text-only preview). |
|
|
140
144
|
|
|
145
|
+
The iterative engines compose these node and scan operations. Child results are supplied in traversal order; span recorders and cell-pair logs belong to the operation that calls them.
|
|
146
|
+
|
|
147
|
+
| Helper | Kind | Signature | Summary |
|
|
148
|
+
| ------------------------- | -------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
149
|
+
| `projectMarkdownNode` | function | `(current, children) => HTMLNode \| undefined` | Projects one markdown node from its already projected children. |
|
|
150
|
+
| `renderMarkdownNode` | function | `(current, children, literal, emphasis) => string` | Renders one markdown node from its rendered children and escaped literal text. |
|
|
151
|
+
| `foldMarkdownNode` | function | `<T>(node, handlers, children) => T` | Dispatches one markdown node and its folded children to the matching handler. |
|
|
152
|
+
| `rebuildMarkdownNode` | function | `(current, children) => MarkdownNode` | Rebuilds one markdown node when accepted child replacements change its identity. |
|
|
153
|
+
| `rebuildMarkdownCell` | function | `(cell, outputs, pairs) => readonly InlineNode[]` | Rebuilds a table cell and records each input and accepted output pair. |
|
|
154
|
+
| `acceptMarkdownNode` | function | `(current, rebuilt, result) => MarkdownNode` | Accepts a rewritten node only when it fits the original node slot. |
|
|
155
|
+
| `walkMarkdownCharacters` | function | `(source, from, to) => Generator<readonly [number, string], void, unknown>` | Yields UTF-16 offsets and characters within a markdown scan window. |
|
|
156
|
+
| `countMarkdownRun` | function | `(source, start, to) => number` | Counts consecutive copies of the character at the start of a scan window. |
|
|
157
|
+
| `findFollowingNode` | function | `(nodes, start) => MarkdownNode \| undefined` | Finds the next defined markdown node at or after an array offset. |
|
|
158
|
+
| `escapeMarkdownText` | function | `(value, bang) => string` | Escapes literal text so markdown syntax remains literal when rendered. |
|
|
159
|
+
| `locateMarkdownDelimiter` | function | `(source, start, to, open, close) => number \| undefined` | Locates a balanced closing delimiter while skipping backslash escapes. |
|
|
160
|
+
| `recordMarkdownText` | function | `(source, value, start, end, spans, nodes) => void` | Appends a nonempty text node and records its original source span. |
|
|
161
|
+
| `scanMarkdownInline` | function | `(source, index, to, spans, depth) => MarkdownInlineScan \| undefined` | Scans one inline construct and records the spans of its nested children. |
|
|
162
|
+
| `walkMarkdownLines` | function | `(lines, start) => Generator<number, void, unknown>` | Yields line offsets through a closable markdown scan iterator. |
|
|
163
|
+
| `splitTextRuns` | function | `(nodes) => ReadonlyArray<readonly InlineNode[]>` | Splits inline nodes into adjacent text runs and singleton non-text runs. |
|
|
164
|
+
| `listChildren` | function | `(node) => readonly MarkdownNode[]` | Lists the direct children of a markdown node in traversal order. |
|
|
165
|
+
| `trimLeading` | function | `(nodes) => readonly InlineNode[]` | Trims leading whitespace when an inline run starts with a text node. |
|
|
166
|
+
| `trimTrailing` | function | `(nodes) => readonly InlineNode[]` | Trims trailing whitespace when an inline run ends with a text node. |
|
|
167
|
+
|
|
141
168
|
### Compilers
|
|
142
169
|
|
|
143
170
|
From [`compilers.ts`](../src/core/compilers.ts) — the class-driving half of the outbound direction. `helpers.ts` owns the pure `markdownToHTML` projection and imports no implementation class; the compiler below constructs `@orkestrel/html`'s `HTML` class, so it sits above the leaves and consumes them.
|
|
@@ -761,7 +788,9 @@ const markdown = new Markdown('# Title\n\nFirst.\n\nSecond.')
|
|
|
761
788
|
// universal — a reader loop works in every ReadableStream-supporting environment
|
|
762
789
|
const reader = markdown.stream().getReader()
|
|
763
790
|
const tops: string[] = []
|
|
764
|
-
for (
|
|
791
|
+
for (;;) {
|
|
792
|
+
const result = await reader.read()
|
|
793
|
+
if (result.done) break
|
|
765
794
|
tops.push(result.value.element) // shallow — top-level blocks only
|
|
766
795
|
}
|
|
767
796
|
// tops: ['heading', 'paragraph', 'paragraph']
|
|
@@ -962,3 +991,119 @@ text.is(fixture) // true — guard / generator stay in lockstep
|
|
|
962
991
|
|
|
963
992
|
- [`AGENTS.md`](../AGENTS.md) — the repository rules, including the documentation contract every guide here is held to.
|
|
964
993
|
- [`README.md`](README.md) — the guides index.
|
|
994
|
+
|
|
995
|
+
## Node and scan operations
|
|
996
|
+
|
|
997
|
+
These operations also accept the child results and recorders supplied by their callers. The handler example uses `countHandlers` from the traversal example above.
|
|
998
|
+
|
|
999
|
+
### `projectMarkdownNode`
|
|
1000
|
+
|
|
1001
|
+
```ts
|
|
1002
|
+
projectMarkdownNode({ element: 'text', value: 'hi' }, []) // { category: 'text', value: 'hi' }
|
|
1003
|
+
```
|
|
1004
|
+
|
|
1005
|
+
### `renderMarkdownNode`
|
|
1006
|
+
|
|
1007
|
+
```ts
|
|
1008
|
+
renderMarkdownNode({ element: 'thematicBreak' }, [], '', 0) // '---'
|
|
1009
|
+
```
|
|
1010
|
+
|
|
1011
|
+
### `foldMarkdownNode`
|
|
1012
|
+
|
|
1013
|
+
```ts
|
|
1014
|
+
foldMarkdownNode({ element: 'text', value: 'hi' }, countHandlers, []) // 1
|
|
1015
|
+
```
|
|
1016
|
+
|
|
1017
|
+
### `rebuildMarkdownNode`
|
|
1018
|
+
|
|
1019
|
+
```ts
|
|
1020
|
+
const original: ParagraphNode = { element: 'paragraph', children: [] }
|
|
1021
|
+
rebuildMarkdownNode(original, []) === original // true
|
|
1022
|
+
```
|
|
1023
|
+
|
|
1024
|
+
### `rebuildMarkdownCell`
|
|
1025
|
+
|
|
1026
|
+
```ts
|
|
1027
|
+
rebuildMarkdownCell([], [].values(), []) // []
|
|
1028
|
+
```
|
|
1029
|
+
|
|
1030
|
+
### `acceptMarkdownNode`
|
|
1031
|
+
|
|
1032
|
+
```ts
|
|
1033
|
+
const original: TextNode = { element: 'text', value: 'hi' }
|
|
1034
|
+
acceptMarkdownNode(original, original, { element: 'thematicBreak' }) === original // true
|
|
1035
|
+
```
|
|
1036
|
+
|
|
1037
|
+
### `walkMarkdownCharacters`
|
|
1038
|
+
|
|
1039
|
+
```ts
|
|
1040
|
+
Array.from(walkMarkdownCharacters('ab', 0, 2)) // [[0, 'a'], [1, 'b']]
|
|
1041
|
+
```
|
|
1042
|
+
|
|
1043
|
+
### `countMarkdownRun`
|
|
1044
|
+
|
|
1045
|
+
```ts
|
|
1046
|
+
countMarkdownRun('***x', 0, 4) // 3
|
|
1047
|
+
```
|
|
1048
|
+
|
|
1049
|
+
### `findFollowingNode`
|
|
1050
|
+
|
|
1051
|
+
```ts
|
|
1052
|
+
findFollowingNode([], 0) // undefined
|
|
1053
|
+
```
|
|
1054
|
+
|
|
1055
|
+
### `escapeMarkdownText`
|
|
1056
|
+
|
|
1057
|
+
```ts
|
|
1058
|
+
escapeMarkdownText('*hi*', false) // '\\*hi\\*'
|
|
1059
|
+
```
|
|
1060
|
+
|
|
1061
|
+
### `locateMarkdownDelimiter`
|
|
1062
|
+
|
|
1063
|
+
```ts
|
|
1064
|
+
locateMarkdownDelimiter('[a]', 0, 3, '[', ']') // 2
|
|
1065
|
+
```
|
|
1066
|
+
|
|
1067
|
+
### `recordMarkdownText`
|
|
1068
|
+
|
|
1069
|
+
```ts
|
|
1070
|
+
const nodes: InlineNode[] = []
|
|
1071
|
+
recordMarkdownText({ text: 'a', segments: [] }, 'a', 0, 1, new Map(), nodes)
|
|
1072
|
+
nodes // [{ element: 'text', value: 'a' }]
|
|
1073
|
+
```
|
|
1074
|
+
|
|
1075
|
+
### `scanMarkdownInline`
|
|
1076
|
+
|
|
1077
|
+
```ts
|
|
1078
|
+
scanMarkdownInline({ text: '`x`', segments: [] }, 0, 3, new Map(), 0)?.end // 3
|
|
1079
|
+
```
|
|
1080
|
+
|
|
1081
|
+
### `walkMarkdownLines`
|
|
1082
|
+
|
|
1083
|
+
```ts
|
|
1084
|
+
Array.from(walkMarkdownLines(splitLines('a\nb'), 1)) // [1]
|
|
1085
|
+
```
|
|
1086
|
+
|
|
1087
|
+
### `splitTextRuns`
|
|
1088
|
+
|
|
1089
|
+
```ts
|
|
1090
|
+
splitTextRuns([{ element: 'text', value: 'a' }]).length // 1
|
|
1091
|
+
```
|
|
1092
|
+
|
|
1093
|
+
### `listChildren`
|
|
1094
|
+
|
|
1095
|
+
```ts
|
|
1096
|
+
listChildren({ element: 'document', children: [] }) // []
|
|
1097
|
+
```
|
|
1098
|
+
|
|
1099
|
+
### `trimLeading`
|
|
1100
|
+
|
|
1101
|
+
```ts
|
|
1102
|
+
trimLeading([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: 'a ' }]
|
|
1103
|
+
```
|
|
1104
|
+
|
|
1105
|
+
### `trimTrailing`
|
|
1106
|
+
|
|
1107
|
+
```ts
|
|
1108
|
+
trimTrailing([{ element: 'text', value: ' a ' }]) // [{ element: 'text', value: ' a' }]
|
|
1109
|
+
```
|