@mnemonik/shared 7.97.1 → 7.98.0

package/scripts/vendor-grammars.ts

@@ -5,8 +5,8 @@
  * packages to this workspace's devDependencies and npm refused the tree:
  * tree-sitter-groovy declares a `peerOptional` on the NATIVE tree-sitter
  * (^0.21.1), which this design deliberately never installs. Rather than force
- * the resolution, note that these packages have no business in the dependency
- * graph at all — we want two files out of each of them, at build time, on our
+ * the resolution. These packages have no business in the dependency graph at
+ * all: we want two files out of each of them, at build time, on our
  * machine. `npm pack` fetches a tarball and performs NO dependency resolution,
  * so there is no peer graph to satisfy, `npm ci` stays fast for every developer
  * and every CI run, and nobody downloads ~283 MB of grammars to build the repo.
@@ -14,7 +14,7 @@
  * What ships to a user: the extracted `.wasm` and `.tags.scm` files, committed
  * here and published inside @mnemonik/shared. A user's install therefore pulls
  * no grammar package, runs no postinstall, needs no compiler, and fetches
- * nothing at runtime — which is the whole reason this plan chose WebAssembly
+ * nothing at runtime - which is the whole reason this plan chose WebAssembly
  * over the native bindings.
  *
  * Run: npx tsx packages/shared/scripts/vendor-grammars.ts [--check]
@@ -51,8 +51,8 @@ interface GrammarSpec {
   pkg: string;
   /**
    * `.wasm` basename inside the tarball when it differs from the package's own
-   * name — tree-sitter-typescript ships two, and tree-sitter-c-sharp names its
-   * file with an underscore.
+   * name - tree-sitter-typescript ships two, and tree-sitter-c-sharp names its
+   * file with an `_` separator.
    */
   wasmFile?: string;
   /**
@@ -70,19 +70,19 @@ interface GrammarSpec {
  * remove.
  *
  * Absent on purpose:
- *   julia, objc, haskell — the three largest grammars that ALSO ship no tag
+ *   julia, objc, haskell - the three largest grammars that ALSO ship no tag
  *     query, so each costs both its size (6.1/5.2/3.7 MB) and a hand-written
  *     query. Dropped to keep the payload under 40 MB; still indexed via the
  *     allowlist, still chunked heuristically.
- *   dart — its bundled .wasm (package v1.0.0, 2023) fails Language.load under
+ *   dart - its bundled .wasm (package v1.0.0, 2023) fails Language.load under
  *     web-tree-sitter 0.26.11 with a dylink-metadata error: the artifact
  *     predates the current wasm ABI. Presence is not loadability, which is why
  *     --check verifies both. Flutter matters, so this is worth revisiting by
  *     compiling from source with tree-sitter-cli.
- *   kotlin, swift, lua, perl, zig — bundle no .wasm, so they need a build step
+ *   kotlin, swift, lua, perl, zig - bundle no .wasm, so they need a build step
  *     with tree-sitter-cli. Deferred until the grammars above are proven; they
  *     keep the heuristic chunker meanwhile.
- *   markdown — keeps chunkMarkdown. Headers already are a document's semantic
+ *   markdown - keeps chunkMarkdown. Headers already are a document's semantic
  *     unit; an AST would not improve on them.
  */
 const GRAMMARS: GrammarSpec[] = [
@@ -124,7 +124,7 @@ const GRAMMARS: GrammarSpec[] = [
  * Derived, not declared: the chains themselves live in the runtime registry
  * (`src/ast/grammars.ts`), which is the module that has to compose them for real
  * work. A second hand-maintained copy here could drift from the one the scanner
- * uses, and a drifted chain does not fail — it silently under-matches, which is
+ * uses, and a drifted chain does not fail - it silently under-matches, which is
  * the exact failure this vendoring step exists to catch. See that module for why
  * tag queries are deltas and what composing them is worth (948 TypeScript
  * definitions against 6,471).
@@ -178,7 +178,7 @@ async function checkOnly(): Promise<Problem[]> {
     if (!chain) {
       problems.push({
         id: spec.id,
-        detail: `no QUERY_CHAIN entry in src/ast/grammars.ts — the grammar would load and match nothing`,
+        detail: `no QUERY_CHAIN entry in src/ast/grammars.ts - the grammar would load and match nothing`,
       });
       continue;
     }
@@ -201,7 +201,7 @@ async function checkOnly(): Promise<Problem[]> {
       if (!captures.some((c) => c.startsWith('definition.'))) {
         problems.push({
           id: spec.id,
-          detail: `composed query compiles but captures no definition.* — it would name nothing`,
+          detail: `composed query compiles but captures no definition.* - it would name nothing`,
         });
       }
     } catch (err) {
@@ -271,7 +271,7 @@ function vendor(): Problem[] {
         if (!existsSync(tagsSrc)) {
           problems.push({
             id: spec.id,
-            detail: `${spec.pkg} ships no queries/tags.scm — reclassify this entry as 'ours' and author one`,
+            detail: `${spec.pkg} ships no queries/tags.scm - reclassify this entry as 'ours' and author one`,
           });
         } else {
           copyFileSync(tagsSrc, join(WASM_DIR, `${spec.id}.tags.scm`));

package/src/ambientPointer.ts

@@ -5,7 +5,8 @@ const LEGACY_MEMORY_ID_SOURCE = `[0-9A-Za-z_-]{${AMBIENT_ID_PREFIX_LENGTH}}`;
 
 /** Current full UUID pointers plus cached eight-character pointers from older hooks. */
 export const AMBIENT_ITEM_POINTER_SOURCE =
-  `—\\s*memory_get\\s+(${MEMORY_UUID_SOURCE}|${LEGACY_MEMORY_ID_SOURCE})` + '(?![0-9A-Za-z_-])';
+  `\\u2014\\s*memory_get\\s+(${MEMORY_UUID_SOURCE}|${LEGACY_MEMORY_ID_SOURCE})` +
+  '(?![0-9A-Za-z_-])';
 
 export function ambientItemPointerRegex(flags = 'g'): RegExp {
   return new RegExp(AMBIENT_ITEM_POINTER_SOURCE, flags);

package/src/apiOrigin.ts

@@ -0,0 +1,4 @@
+/** The existing resource override selects the API origin for local staging rehearsals. */
+export function apiOrigin(env: NodeJS.ProcessEnv = process.env): string {
+  return new URL(env.MNEMONIK_API_RESOURCE || 'https://api.mnemonik.dev').origin;
+}

package/src/ast/astChunker.ts

@@ -3,7 +3,7 @@
  * logging of file contents, one pure entry point (`chunkWithAst`).
  *
  * WHY THIS EXISTS. The heuristic chunker matches a regex whose name pattern
- * requires a leading `function`/`class`/`const` keyword — a keyword a method's
+ * requires a leading `function`/`class`/`const` keyword - a keyword a method's
  * first line never has. So it produces method-shaped chunks with no
  * `symbolName`: 1,512 methods in this repo, unnameable and therefore unusable
  * as citation anchors. Measured over the same 1,037 TypeScript files, the
@@ -13,15 +13,15 @@
  * THE NESTING RULE. Emitting both a whole class and each of its methods would
  * duplicate every method body and double the embedding bill, so:
  *
- * - a STRUCTURAL definition — one whose body is a container of other definitions
- *   (class, interface, enum, struct, trait, object, module, namespace) — emits a
+ * - a STRUCTURAL definition - one whose body is a container of other definitions
+ *   (class, interface, enum, struct, trait, object, module, namespace) - emits a
  *   HEADER chunk from its own first line to the line before its first nested
  *   definition: the declaration plus the fields that precede the first method.
  *   Real contiguous source, never an elision;
  * - every other definition is a LEAF and becomes one chunk over its FULL line
  *   range, whatever it happens to contain. A local arrow function is part of
  *   what the enclosing function IS, not a sibling of it, so definitions nested
- *   inside a leaf are not emitted separately — the leaf's chunk already carries
+ *   inside a leaf are not emitted separately - the leaf's chunk already carries
  *   their source verbatim. See `STRUCTURAL_KINDS` for why that distinction is
  *   load-bearing rather than cosmetic;
  * - every remaining uncovered line span becomes a `raw` chunk.
@@ -70,11 +70,11 @@ export interface AstChunk {
   chunkType: 'function' | 'class' | 'module' | 'raw';
   /**
    * Bare symbol name, never qualified. Present on every chunk that came from a
-   * `definition.*` capture — INCLUDING the value-shaped kinds that map to
+   * `definition.*` capture - INCLUDING the value-shaped kinds that map to
    * `chunkType: 'raw'` (`variable`, `constant`, `field`, `property`), because the
    * wire enum has no value-shaped member but the identity is real and
    * `memory_file_index.symbol_name` indexes it either way. Absent only on the
-   * uncovered-span chunks, which have no capture behind them — those are exactly
+   * uncovered-span chunks, which have no capture behind them - those are exactly
    * the chunks with no `symbolKind` either.
    */
   symbolName?: string;
@@ -83,14 +83,14 @@ export interface AstChunk {
   /** The definition's first line, trimmed, capped at 500 chars. */
   signature?: string;
   /**
-   * Name of the immediate STRUCTURAL parent — whatever `STRUCTURAL_KINDS` admits
+   * Name of the immediate STRUCTURAL parent - whatever `STRUCTURAL_KINDS` admits
    * for the language. Absent at module scope, and absent inside a leaf (nothing
    * inside a leaf is emitted at all).
    *
    * In TS/JS that is `class`, `interface` and a module-scope `const`; NOT `enum`
    * and NOT `namespace`, despite both being structural kinds. Enum members are
    * never captured as definitions, and `namespace Outer {}` parses as
-   * `internal_module`, which typescript.tags.scm does not match — `Outer`
+   * `internal_module`, which typescript.tags.scm does not match - `Outer`
    * produces no definition, so it can never be anybody's container. Do not widen
    * this list from `STRUCTURAL_KINDS` alone; a kind is only reachable here if
    * some tag query also captures a definition INSIDE it.
@@ -108,8 +108,8 @@ export type AstChunkResult =
       /**
        * Definitions that reached no chunk. Two chunks over one line range would
        * collide on `filePath:startLine-endLine`, the staleness key ProjectManager
-       * compares, so a second definition sharing a range — `function a() {}
-       * function b() {}` on one line — cannot be emitted, and neither can a
+       * compares, so a second definition sharing a range - `function a() {}
+       * function b() {}` on one line - cannot be emitted, and neither can a
        * container whose first nested definition opens on the container's own
        * first line (`class A { m() {} }`). Two captures can also COLLAPSE onto one
        * range while widening: `int f(int), g(int);` binds two declarators to one
@@ -126,7 +126,7 @@ export type AstChunkResult =
  * Parse ceiling, derived from Task 4's measurement rather than guessed: the
  * largest source file in this repo is 415 KB (`src/agent/ContextAgent.ts`) and
  * the slowest per-file parse across 1,061 files was 108.6 ms. 2 MiB is ~5x that
- * largest real file, which bounds the worst case near half a second — while
+ * largest real file, which bounds the worst case near half a second - while
  * still refusing the multi-megabyte generated blobs that `MAX_SCANNED_FILE_BYTES`
  * (10 MB) otherwise lets through. Above the ceiling the caller degrades to the
  * heuristic chunker, which is line-bounded and cheap.
@@ -150,7 +150,7 @@ const MAX_SIGNATURE_CHARS = 500;
  * Kinds absent here (`constant`, `field`, `property`, `variable`) fall to
  * `'raw'`: the enum has no value-shaped member, and claiming a constant is a
  * `class` or a `module` would be false where `'raw'` only says "no coarse class
- * for this" — the identity is still carried by `symbolName` + `symbolKind`.
+ * for this" - the identity is still carried by `symbolName` + `symbolKind`.
  */
 const CHUNK_TYPE_BY_KIND: Readonly<Record<string, AstChunk['chunkType']>> = {
   function: 'function',
@@ -174,7 +174,7 @@ const CHUNK_TYPE_BY_KIND: Readonly<Record<string, AstChunk['chunkType']>> = {
  * The distinction is load-bearing, not cosmetic. When every `definition.*`
  * capture counted as a nested child, a function declaring one local arrow
  * function collapsed to its first two lines: `ContextAgent.registerDocsTools`
- * spans 513 lines and was recorded as 2. A wrong extent is worse than no extent —
+ * spans 513 lines and was recorded as 2. A wrong extent is worse than no extent -
  * it anchors citations confidently at the wrong place instead of failing to
  * anchor them.
  *
@@ -185,20 +185,20 @@ const CHUNK_TYPE_BY_KIND: Readonly<Record<string, AstChunk['chunkType']>> = {
  * double the embedding bill.
  *
  * `constant` IS IN, and only because the tag queries anchor it to module scope.
- * A module `const` is the ordinary home of a handler map or an evaluator table —
- * `export const EVALUATORS = { foo() {...}, bar: () => {...} }` — whose members
+ * A module `const` is the ordinary home of a handler map or an evaluator table -
+ * `export const EVALUATORS = { foo() {...}, bar: () => {...} }` - whose members
  * are separately named definitions a reader looks up by name. As a leaf it
  * suppressed all of them: 49 named symbols vanished from `src/` alone, with
  * `droppedDefinitions` at 0, which is the silent-loss class that counter exists
  * to prevent. A function-valued `const` is NOT affected: it binds
  * `definition.function` on the same range and KIND_SPECIFICITY keeps that kind,
  * so a closure and its local helpers stay one chunk. A `const` with no nested
- * definition never splits either — `headerEndRow` is only set when a child
- * exists — so the scalar case is byte-identical to the leaf behaviour.
+ * definition never splits either - `headerEndRow` is only set when a child
+ * exists - so the scalar case is byte-identical to the leaf behaviour.
  *
  * `type` stays out deliberately. C's `(type_definition declarator:
  * (type_identifier) @name) @definition.type` matches `typedef struct {...} Foo;`,
- * whose nested `struct_specifier` opens on the typedef's own first line — as a
+ * whose nested `struct_specifier` opens on the typedef's own first line - as a
  * container it would split to an empty header and be dropped entirely, so the
  * typedef is the leaf and keeps the whole range.
  */
@@ -249,7 +249,7 @@ interface Definition {
  *
  * Async only because `loadGrammar` is; the grammar is cached per process, so
  * after the first file of a given language there is no per-file async cost.
- * Never throws — every failure is a named `unsupported` reason with a detail the
+ * Never throws - every failure is a named `unsupported` reason with a detail the
  * caller can log before degrading.
  */
 export async function chunkWithAst(
@@ -299,9 +299,9 @@ export async function chunkWithAst(
   try {
     const lines = content.split('\n');
     // A trailing newline TERMINATES the last line, it does not open a new one,
-    // but `split` yields a phantom '' for it. Dropping it here — before
+    // but `split` yields a phantom '' for it. Dropping it here - before
     // `lines.length` is read by the coverage array, `uncoveredSpans` or
-    // `sliceLines` — is what keeps `endLine` equal to the file's last line
+    // `sliceLines` - is what keeps `endLine` equal to the file's last line
     // number. Left in, the final raw chunk of every newline-terminated file (109
     // of this repo's 268 `src/` TypeScript files) ran one line past the end, and
     // `memory_file_index.end_line` feeds citation anchoring and the golden eval's
@@ -313,8 +313,8 @@ export async function chunkWithAst(
       chunks: built.chunks,
       errorNodes: countErrorNodes(tree),
       parseMs,
-      // A definition can be lost at either stage — collapsed onto another
-      // definition's byte range here, or reaching no chunk in `buildChunks` — and
+      // A definition can be lost at either stage - collapsed onto another
+      // definition's byte range here, or reaching no chunk in `buildChunks` - and
       // the caller logs one number, so both have to be in it.
       droppedDefinitions: built.droppedDefinitions + collected.collapsedDefinitions,
     };
@@ -333,7 +333,7 @@ export async function chunkWithAst(
  * `STRUCTURAL_KINDS`, and a fourth table keyed on `definition.<kind>` drifts
  * from the other three the moment a grammar is vendored: listing the strong
  * kinds once already omitted `struct`, `object`, `trait` and `macro`, which
- * scored 0 and LOST to `constant` — inverting the whole point of the table and
+ * scored 0 and LOST to `constant` - inverting the whole point of the table and
  * able to demote a structural kind to a leaf. Deny-listing the four value-shaped
  * kinds cannot fail that way: a kind nobody has thought of yet outranks a
  * `constant` instead of losing to it, which is the safe direction.
@@ -353,7 +353,7 @@ interface CollectedDefinitions {
    * Definitions lost to the byte-range dedup below, counted only when the two
    * captures carried DIFFERENT names. Widening COLLAPSES: `int f(int), g(int);`
    * binds two `function_declarator` siblings to one `declaration`, so both widen
-   * onto the same node and the second is discarded here — upstream of
+   * onto the same node and the second is discarded here - upstream of
    * `buildChunks`, where every other drop is counted. Left uncounted, widening
    * turned a COUNTED drop into a silent one, which is the exact defect class
    * `droppedDefinitions` exists to eliminate.
@@ -370,7 +370,7 @@ interface CollectedDefinitions {
  *
  * `matches()` rather than `captures()`: a match is one pattern's captures, so
  * the `@name` belonging to a definition is unambiguous. `captures()` returns a
- * flat stream in which pairing is guesswork — and the composed QUERY_CHAIN
+ * flat stream in which pairing is guesswork - and the composed QUERY_CHAIN
  * concatenates several files' patterns, so guessing would mispair across
  * grammars.
  */
@@ -451,7 +451,7 @@ function collectDefinitions(query: Query, root: Node): CollectedDefinitions {
  *     (function_declarator declarator: (identifier) @name) @definition.function
  *
  * `function_declarator` ends at the closing paren of the parameter list, so
- * naming it alone reproduces — for two whole languages — the exact defect this
+ * naming it alone reproduces - for two whole languages - the exact defect this
  * module exists to fix: a named signature line plus an anonymous raw chunk
  * holding the body.
  *
@@ -464,10 +464,10 @@ function collectDefinitions(query: Query, root: Node): CollectedDefinitions {
  *    owns the body (`function_definition`, `declaration`, `field_declaration`,
  *    through any `pointer_declarator` or `array_declarator` in between).
  * 2. A DECLARATOR WRAPPER. `int &f()` parses as
- *    `(function_definition declarator: (reference_declarator (function_declarator …)))`
- *    and `int (*f(void))[4]` as `… (parenthesized_declarator (pointer_declarator …))`.
+ *    `(function_definition declarator: (reference_declarator (function_declarator ...)))`
+ *    and `int (*f(void))[4]` as `... (parenthesized_declarator (pointer_declarator ...))`.
  *    Neither `reference_declarator` nor `parenthesized_declarator` NAMES the
- *    declarator it wraps — the child sits in an unnamed field — so rule 1 alone
+ *    declarator it wraps - the child sits in an unnamed field - so rule 1 alone
  *    stopped dead at `function_declarator` and reproduced the very defect above
  *    for `T &operator[]`, `std::string &name()`, and every other
  *    reference-returning accessor in real C++. So also ascend when the parent is
@@ -476,7 +476,7 @@ function collectDefinitions(query: Query, root: Node): CollectedDefinitions {
  * Both forms keep the property that made rule 1 safe: neither can reach an
  * unrelated ancestor. Rule 1 follows a field the grammar defines only within a
  * declaration; rule 2 requires BOTH ends to be declarator nodes, and a
- * `field_declaration_list` is not one — a method inside a class body therefore
+ * `field_declaration_list` is not one - a method inside a class body therefore
  * still stops at its own `function_definition` and a class is never swallowed.
  * Grammars that already bind the whole definition (every JS/TS, Python, Go, Rust,
  * Ruby pattern) fail both conditions on the first iteration, which makes this a
@@ -491,7 +491,7 @@ function widenToDefinition(node: Node): Node {
     if (!parent) return current;
     // `childrenForFieldName`, not `childForFieldName`: `int a, f(int x);` binds
     // two declarators to one declaration, and the singular accessor answers only
-    // the first — which would refuse to widen every declarator but one.
+    // the first - which would refuse to widen every declarator but one.
     const boundToDeclaratorField = parent
       .childrenForFieldName('declarator')
       .some((child) => child.id === current.id);
@@ -507,7 +507,7 @@ function isDeclarator(node: Node): boolean {
 
 /**
  * True when `parent` is a declarator that wraps `child` without naming the field
- * — `reference_declarator` (`&` / `&&`) and `parenthesized_declarator` (`( … )`),
+ * - `reference_declarator` (`&` / `&&`) and `parenthesized_declarator` (`( ... )`),
  * whose grammar rules are a bare token sequence around the inner declarator.
  *
  * Both ends must be declarators, and the field must be UNNAMED: a declarator's
@@ -539,7 +539,7 @@ interface BuiltChunks {
 
 function buildChunks(definitions: Definition[], lines: string[]): BuiltChunks {
   // `headerEndRow[i]` is the 0-based row of definition `i`'s first nested
-  // definition — set only for STRUCTURAL definitions, since only they split.
+  // definition - set only for STRUCTURAL definitions, since only they split.
   // `suppressed[i]` marks a definition that lies inside a leaf and is therefore
   // already carried, verbatim, by that leaf's own chunk.
   const headerEndRow = new Map<number, number>();
@@ -598,7 +598,7 @@ function buildChunks(definitions: Definition[], lines: string[]): BuiltChunks {
     // starts on `headerEnd + 1`, so its header ends on the line before that:
     // `headerEnd`. When the child opens on the container's own first line
     // (`class A { m() {} }`) that range is empty, `emit` refuses it and the
-    // refusal is counted — emitting the line anyway would duplicate the child's
+    // refusal is counted - emitting the line anyway would duplicate the child's
     // source. Clamped to the last real line so a definition whose node runs to
     // end-of-file cannot name a line that does not exist.
     const headerEnd = headerEndRow.get(i);
@@ -620,7 +620,7 @@ function buildChunks(definitions: Definition[], lines: string[]): BuiltChunks {
     // A definition that reaches no chunk reaches no index either, and a citation
     // to it resolves as `unresolved_symbol`. It cannot be emitted without
     // colliding on the staleness key, so it is counted and reported instead of
-    // vanishing — a silent no-op is the defect class, not the collision.
+    // vanishing - a silent no-op is the defect class, not the collision.
     if (!emitted) droppedDefinitions++;
   }
 
@@ -664,13 +664,13 @@ function uncoveredSpans(covered: Uint8Array, lineCount: number): Array<[number,
 
 /**
  * Break an uncovered span on line boundaries so no chunk exceeds
- * `MAX_RAW_SPAN_CHARS`. No overlap — overlap would re-embed the same lines — and
+ * `MAX_RAW_SPAN_CHARS`. No overlap - overlap would re-embed the same lines - and
  * no mid-line splitting: two chunks over one line range would collide on the
  * `filePath:startLine-endLine` staleness key, so an over-long single line is
  * left whole and the embedding layer truncates it with a warning
  * (`EmbeddingService` caps each input at the 8191-token per-input limit).
  *
- * Whitespace-only spans yield nothing — `emit` drops them, and the blank lines
+ * Whitespace-only spans yield nothing - `emit` drops them, and the blank lines
  * between definitions are the one thing total coverage does not owe a chunk.
  */
 function splitSpan(
@@ -698,7 +698,7 @@ function splitSpan(
  * of inferring it from thin chunks.
  *
  * Short-circuits on a clean tree, and descends only into subtrees whose own
- * `hasError` is true — 97.6% of this repo's TypeScript files have no error at
+ * `hasError` is true - 97.6% of this repo's TypeScript files have no error at
  * all, and they must not pay for a full tree walk.
  */
 function countErrorNodes(tree: Tree): number {

package/src/ast/grammars.ts

@@ -5,7 +5,7 @@
  * Every failure mode is a named value (`wasm_missing`, `wasm_load_failed`,
  * `tags_query_missing`, `query_compile_failed`, `not_covered`) rather than a
  * null or a throw, because the consequence of a degraded install is not a crash
- * — it is quietly worse chunks, forever, with nothing in the logs. A caller that
+ * - it is quietly worse chunks, forever, with nothing in the logs. A caller that
  * gets `unavailable` can fall back to the heuristic chunker AND say why.
  *
  * Artifacts are vendored, not installed: `packages/shared/wasm/<id>.wasm` plus
@@ -67,7 +67,7 @@ export const AST_LANGUAGE_IDS: readonly AstLanguageId[] = AST_LANGUAGE_ID_LIST;
  * Ids whose vendored artifact basename differs from the id.
  *
  * `tree-sitter-c-sharp` names its file with a hyphen while every consumer of
- * this registry — `languageForExtension`, chunk metadata, the wire — spells the
+ * this registry - `languageForExtension`, chunk metadata, the wire - spells the
  * language `csharp`. Mapping the two explicitly is cheaper than renaming a
  * vendored artifact: the vendoring script, the committed files and the
  * `--check` verifier all agree on `c-sharp`, and a rename would make this
@@ -84,7 +84,7 @@ export function grammarArtifactBasename(id: AstLanguageId): string {
 
 /**
  * Ordered tag-query files composing each grammar's EFFECTIVE query. THE source
- * of truth — `scripts/vendor-grammars.ts` imports this rather than keeping its
+ * of truth - `scripts/vendor-grammars.ts` imports this rather than keeping its
  * own copy, because two chains that can drift is precisely the defect this
  * layer exists to remove.
  *
@@ -93,7 +93,7 @@ export function grammarArtifactBasename(id: AstLanguageId): string {
  * `interface_declaration`, `abstract_class_declaration`);
  * `function_declaration`, `class_declaration`, `method_definition` and arrow
  * functions all live in javascript's query and are meant to be inherited.
- * Nothing in the query engine resolves that — composing the chain is the
+ * Nothing in the query engine resolves that - composing the chain is the
  * consumer's job.
  *
  * Measured cost of not composing it: 948 definitions across 1,037 TypeScript
@@ -129,7 +129,7 @@ export const QUERY_CHAIN: Readonly<Record<AstLanguageId, readonly AstLanguageId[
  * Extensions whose grammar the language string alone gets WRONG.
  *
  * `.ts` and `.tsx` both report language `typescript` and need different
- * grammars out of the same npm package — a `.tsx` file parsed by the typescript
+ * grammars out of the same npm package - a `.tsx` file parsed by the typescript
  * grammar errors on the first JSX element. This is the entire reason
  * `resolveAstLanguage` takes an extension at all.
  */
@@ -196,7 +196,7 @@ const WASM_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'wasm
  * in parallel forks, so renaming `ruby.wasm` aside is visible to every other
  * file for as long as it lasts, and any file that cold-loads Ruby inside that
  * window caches a `wasm_missing` this checkout does not have. Copy from here
- * into a temp directory and break the copy — `loadGrammar` takes the directory.
+ * into a temp directory and break the copy - `loadGrammar` takes the directory.
  */
 export const VENDORED_ARTIFACT_DIR = WASM_DIR;
 
@@ -216,7 +216,7 @@ export function resolveAstLanguage(extension: string, language: string): AstLang
 
 /**
  * Accepts `.TSX`, `tsx`, or a whole path, and answers the lowercase dotted
- * extension. Mirrors `languageForExtension`'s ordering — `extname` first, so a
+ * extension. Mirrors `languageForExtension`'s ordering - `extname` first, so a
  * dotfile carrying a real extension ('.eslintrc.js') is not swallowed whole.
  */
 function normalizeExtension(raw: string): string {
@@ -251,7 +251,7 @@ const loads = new Map<string, Promise<GrammarLoad>>();
 /**
  * Ids whose `Language` has actually been instantiated, same keying as `loads`.
  *
- * A ledger rather than a cache index, because the entry can never be removed:
+ * This is a permanent record rather than a cache index because entries cannot be removed:
  * a loaded Language cannot be freed (see `attemptLoad`), so this set IS the
  * permanent wasm memory this process is holding. `loadedGrammarIds` reads it,
  * and the startup path is asserted against it.
@@ -283,7 +283,7 @@ export function loadGrammar(
 }
 
 /**
- * Which grammars this process has instantiated — what is resident in wasm
+ * Which grammars this process has instantiated - what is resident in wasm
  * memory right now, not what is vendored or what was asked for.
  *
  * Exists because the cost is permanent and therefore worth being able to state:
@@ -306,7 +306,7 @@ async function loadUncached(id: AstLanguageId, artifactDir: string): Promise<Gra
 
 /**
  * The on-disk half of a load: artifacts present, query chain composed. No wasm
- * is instantiated, so this is what the cheap report and the real load SHARE —
+ * is instantiated, so this is what the cheap report and the real load SHARE -
  * two separate presence checks that could disagree is how a report starts
  * claiming a grammar the loader rejects.
  */
@@ -373,7 +373,7 @@ async function attemptLoad(id: AstLanguageId, artifactDir: string): Promise<Gram
   // A loaded Language cannot be freed: web-tree-sitter 0.26.11 exposes
   // `delete()` on Tree and Query but NOT on Language. The failure results below
   // are cached, so a grammar whose query is broken leaks its Language exactly
-  // once per process rather than once per file — which is why the cache matters
+  // once per process rather than once per file - which is why the cache matters
   // for more than latency. Trees are a different story and must be deleted per
   // file by the chunker; the JS heap does not GC wasm memory.
   let query: Query;
@@ -392,7 +392,7 @@ async function attemptLoad(id: AstLanguageId, artifactDir: string): Promise<Gram
     query.delete();
     return {
       unavailable: 'query_compile_failed',
-      detail: `${id} tag query [${QUERY_CHAIN[id].join(', ')}] compiled but captures no definition.* — it would name nothing`,
+      detail: `${id} tag query [${QUERY_CHAIN[id].join(', ')}] compiled but captures no definition.* - it would name nothing`,
     };
   }
 
@@ -409,13 +409,13 @@ const describe = (err: unknown): string =>
  *
  * Every check is a `statSync` plus a few hundred bytes of `.scm`: the grammar's
  * `.wasm` is present and non-empty, and so is every tag-query file in its chain.
- * Microseconds, and zero permanent memory — which is what makes it the right
+ * Microseconds, and zero permanent memory - which is what makes it the right
  * answer for a startup line (see `logAstCapabilityOnce`).
  *
  * It shares `resolveArtifacts` with the real loader, so it cannot report a
  * grammar as vendored that `loadGrammar` would reject for a missing artifact.
  * What it deliberately cannot see is the two failure modes that require the
- * grammar in memory — `wasm_load_failed` and `query_compile_failed`. Those are
+ * grammar in memory - `wasm_load_failed` and `query_compile_failed`. Those are
  * reported by `astCapabilityReport` when a human asks, and warned once per
  * language by the scan path on the first file that needs them
  * (`grammar_unavailable` in codeScanner); paying ~75 MB up front to pre-answer
@@ -462,12 +462,12 @@ export function astArtifactReport(artifactDir: string = WASM_DIR): {
  * NOT free, and the cost is memory rather than only latency: measured on this
  * checkout, ~690 ms and ~75 MB of RSS that is never given back. web-tree-sitter
  * 0.26.11 exposes no `Language.delete` (see `attemptLoad`), so all 18 grammars
- * stay resident for the life of the process — including the fifteen a given repo
+ * stay resident for the life of the process - including the fifteen a given repo
  * has no files for. Caching makes the second call free; it does not make the
  * first one cheap.
  *
  * So: fine for a diagnostic a human asked for (`doctor`, a `--check` script,
- * this suite). Wrong for a daemon's startup line — that is `astArtifactReport`.
+ * this suite). Wrong for a daemon's startup line - that is `astArtifactReport`.
  */
 export async function astCapabilityReport(artifactDir: string = WASM_DIR): Promise<{
   available: AstLanguageId[];