@markup-carve/carve-lsp 0.1.2 → 0.1.3

package/dist/hover.js

@@ -1,6 +1,7 @@
 import { MarkupKind } from 'vscode-languageserver/node.js';
 import { parse, resolve, } from '@markup-carve/carve';
 import { astColumnToCharacter, characterToAstColumn, sourceLines } from './position.js';
+import { captionTargetById } from './captions.js';
 const rules = [
     {
         pattern: /#{1,6}/g,
@@ -82,8 +83,12 @@ function astHoverAt(doc, position, lines) {
         character: characterToAstColumn(lines[position.line] ?? '', position.character) - 1,
     };
     const matches = [];
+    // A crossref's help depends on what the id NAMES, so the whole document is in
+    // scope for it while every other rule reads one node. It is looked up through
+    // this resolver rather than from inside the inline walk.
+    const resolveRef = (id) => captionTargetById(doc, id);
     for (const node of doc.children)
-        collectBlock(matches, node, cursor);
+        collectBlock(matches, node, cursor, resolveRef);
     matches.sort((a, b) => spanSize(a.pos) - spanSize(b.pos));
     const match = matches[0];
     if (!match)
@@ -96,53 +101,58 @@ function astHoverAt(doc, position, lines) {
         range: toRange(match.pos, lines),
     };
 }
-function collectBlock(matches, node, position) {
+function collectBlock(matches, node, position, resolveRef) {
     addMatch(matches, node.pos, position, blockContents(node));
     switch (node.type) {
         case 'heading':
-            collectInline(matches, node.children, position);
+            collectInline(matches, node.children, position, resolveRef);
             break;
         case 'paragraph':
-            collectInline(matches, node.children, position);
+            collectInline(matches, node.children, position, resolveRef);
             break;
         case 'block_quote':
-            node.children.forEach((child) => collectBlock(matches, child, position));
+            node.children.forEach((child) => collectBlock(matches, child, position, resolveRef));
             break;
         case 'list':
-            node.items.forEach((item) => item.children.forEach((child) => collectBlock(matches, child, position)));
+            node.items.forEach((item) => item.children.forEach((child) => collectBlock(matches, child, position, resolveRef)));
             break;
         case 'admonition':
         case 'div':
-            node.children.forEach((child) => collectBlock(matches, child, position));
+            node.children.forEach((child) => collectBlock(matches, child, position, resolveRef));
             if (node.type === 'admonition' && node.title)
-                collectInline(matches, node.title, position);
+                collectInline(matches, node.title, position, resolveRef);
             break;
         case 'definition_list':
             node.items.forEach((item) => {
-                item.terms.forEach((term) => collectInline(matches, term, position));
-                item.definitions.forEach((definition) => definition.forEach((child) => collectBlock(matches, child, position)));
+                item.terms.forEach((term) => collectInline(matches, term, position, resolveRef));
+                item.definitions.forEach((definition) => definition.forEach((child) => collectBlock(matches, child, position, resolveRef)));
             });
             break;
         case 'figure':
-            collectBlock(matches, node.target, position);
-            collectInline(matches, node.caption, position);
+            collectBlock(matches, node.target, position, resolveRef);
+            collectInline(matches, node.caption, position, resolveRef);
+            break;
+        case 'figure_group':
+            node.children.forEach((child) => collectBlock(matches, child, position, resolveRef));
+            if (node.caption)
+                collectInline(matches, node.caption, position, resolveRef);
             break;
         case 'table':
             if (node.caption)
-                collectInline(matches, node.caption, position);
-            node.rows.forEach((row) => row.cells.forEach((cell) => collectInline(matches, cell.children, position)));
+                collectInline(matches, node.caption, position, resolveRef);
+            node.rows.forEach((row) => row.cells.forEach((cell) => collectInline(matches, cell.children, position, resolveRef)));
             break;
     }
 }
-function collectInline(matches, nodes, position) {
+function collectInline(matches, nodes, position, resolveRef) {
     for (const node of nodes) {
-        addMatch(matches, node.pos, position, inlineContents(node));
+        addMatch(matches, node.pos, position, inlineContents(node, resolveRef));
         const children = node.children;
         if (Array.isArray(children))
-            collectInline(matches, children, position);
+            collectInline(matches, children, position, resolveRef);
         const content = node.content;
         if (Array.isArray(content))
-            collectInline(matches, content, position);
+            collectInline(matches, content, position, resolveRef);
     }
 }
 function addMatch(matches, pos, position, contents) {
@@ -168,11 +178,15 @@ function blockContents(node) {
             return '**Admonition**\n\nTyped `:::` fences create admonition blocks.';
         case 'div':
             return '**Div**\n\nBare `:::` fences create generic container blocks.';
+        case 'figure_group':
+            return ('**Composite Figure**\n\nA bare `::: figure` fence is one figure of ordered panels. ' +
+                'The `^ ` line after the closing fence captions the whole group. ' +
+                'An opener carrying a title or a `[label]` stays a generic container instead.');
         default:
             return null;
     }
 }
-function inlineContents(node) {
+function inlineContents(node, resolveRef) {
     switch (node.type) {
         case 'strong':
             return '**Bold**\n\nCarve uses single asterisks for bold text: `*bold*`.';
@@ -202,10 +216,35 @@ function inlineContents(node) {
             return '**Tag**\n\nTags use `#name`.';
         case 'span':
             return '**Span**\n\nInline spans use `[text]{attrs}`.';
+        case 'heading_ref':
+            return crossrefContents(node, resolveRef);
         default:
             return null;
     }
 }
+/**
+ * A `</#id>` used to fall through this switch entirely, so the LEXICAL rules
+ * above took it and reported the `#` inside the reference as a heading marker.
+ * It now says what the reference resolves to, which for a composite figure's
+ * panel is the group's number plus its letter (PART 9 §4c).
+ *
+ * A heading target keeps the generic wording: the heading's own text is what
+ * the reference renders, and it is already on screen.
+ */
+function crossrefContents(node, resolveRef) {
+    const generic = '**Cross-reference**\n\nA `</#id>` reference links to the heading or captioned host carrying that id.';
+    const id = node.target;
+    if (typeof id !== 'string')
+        return generic;
+    const target = resolveRef(id);
+    if (!target)
+        return generic;
+    if (target.text === null) {
+        return ('**Cross-reference**\n\nAn unnumbered ' + target.kind + '. It is an anchor, but it drew no ' +
+            'number, so this reference has no caption text to render.');
+    }
+    return '**Cross-reference**\n\nResolves to **' + target.text + '** (' + target.kind + ').';
+}
 function contains(pos, position) {
     if (pos.startColumn === undefined ||
         pos.endColumn === undefined ||

package/dist/hover.js.map

@@ -1 +1 @@
-{"version":3,"file":"hover.js","sourceRoot":"","sources":["../src/hover.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hover.js","sourceRoot":"","sources":["../src/hover.ts"],"names":[],"mappings":"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"}

package/dist/include-cache.d.ts

@@ -0,0 +1,26 @@
+export interface CachedInclude {
+    source: string;
+    bytes: number;
+}
+/** Bounded LRU cache for include source, validated by file metadata. */
+export declare class IncludeSourceCache {
+    #private;
+    readonly maxEntries: number;
+    constructor(maxEntries?: number);
+    get(id: string, mtimeMs: number, size: number): CachedInclude | undefined;
+    set(id: string, mtimeMs: number, size: number, value: CachedInclude): void;
+    invalidate(id: string): void;
+    clear(): void;
+    get size(): number;
+}
+/** Bounded LRU cache for parsed child documents. */
+export declare class IncludeParseCache {
+    #private;
+    readonly maxEntries: number;
+    constructor(maxEntries?: number);
+    get(id: string, version: string): Document | undefined;
+    set(id: string, version: string, document: Document): void;
+    invalidate(id: string): void;
+    clear(): void;
+}
+import type { Document } from '@markup-carve/carve';

package/dist/include-cache.js

@@ -0,0 +1,74 @@
+/** Bounded LRU cache for include source, validated by file metadata. */
+export class IncludeSourceCache {
+    maxEntries;
+    #entries = new Map();
+    constructor(maxEntries = 128) {
+        this.maxEntries = maxEntries;
+    }
+    get(id, mtimeMs, size) {
+        const entry = this.#entries.get(id);
+        if (!entry || entry.mtimeMs !== mtimeMs || entry.size !== size) {
+            if (entry)
+                this.#entries.delete(id);
+            return undefined;
+        }
+        this.#entries.delete(id);
+        this.#entries.set(id, entry);
+        return { source: entry.source, bytes: entry.bytes };
+    }
+    set(id, mtimeMs, size, value) {
+        this.#entries.delete(id);
+        this.#entries.set(id, { ...value, mtimeMs, size });
+        while (this.#entries.size > this.maxEntries) {
+            const oldest = this.#entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#entries.delete(oldest);
+        }
+    }
+    invalidate(id) {
+        this.#entries.delete(id);
+    }
+    clear() {
+        this.#entries.clear();
+    }
+    get size() {
+        return this.#entries.size;
+    }
+}
+/** Bounded LRU cache for parsed child documents. */
+export class IncludeParseCache {
+    maxEntries;
+    #entries = new Map();
+    constructor(maxEntries = 128) {
+        this.maxEntries = maxEntries;
+    }
+    get(id, version) {
+        const entry = this.#entries.get(id);
+        if (!entry || entry.version !== version) {
+            if (entry)
+                this.#entries.delete(id);
+            return undefined;
+        }
+        this.#entries.delete(id);
+        this.#entries.set(id, entry);
+        return entry.document;
+    }
+    set(id, version, document) {
+        this.#entries.delete(id);
+        this.#entries.set(id, { version, document });
+        while (this.#entries.size > this.maxEntries) {
+            const oldest = this.#entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#entries.delete(oldest);
+        }
+    }
+    invalidate(id) {
+        this.#entries.delete(id);
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}
+//# sourceMappingURL=include-cache.js.map

package/dist/include-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-cache.js","sourceRoot":"","sources":["../src/include-cache.ts"],"names":[],"mappings":"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"}

package/dist/include-definition-denial.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/include-definition-denial.test.js

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdtempSync, writeFileSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { definitionAt } from './definition.js';
+import { includeDefinitionAt } from './include-definition.js';
+import { fileSystemResolver } from './include-path.js';
+/*
+ * THE DENIAL HALF of include go-to-definition.
+ *
+ * `include-features.test.ts` covers the resolvable case - a directive whose
+ * target exists inside the root navigates to it. What no test covered is the
+ * other branch: a target the resolver REFUSES must not navigate at all.
+ *
+ * That branch is the whole security value of routing navigation through
+ * `include-path.ts` rather than joining the path locally. Without it,
+ * go-to-definition is a way around the containment PART 9 section 19 puts on
+ * include resolution: the editor opens a file the include pass would not read.
+ *
+ * It was verified to be uncovered before these were written. Replacing
+ * `if (!resolved.ok) return null` in include-definition.ts with a best-effort
+ * location left the whole suite green at 224 of 224 - a guard that cannot fail.
+ * Each test below fails under that mutation.
+ */
+function workspace() {
+    const root = mkdtempSync(path.join(tmpdir(), 'carve-lsp-incdef-'));
+    const child = path.join(root, 'chapter-1.crv');
+    writeFileSync(child, '# Chapter One\n');
+    return { root, doc: path.join(root, 'book.crv'), child };
+}
+const optionsFor = (root, sourcePath) => ({
+    resolver: fileSystemResolver(root, {}),
+    includeRoot: root,
+    sourcePath,
+});
+test('a target outside the root does not navigate', () => {
+    const { root, doc } = workspace();
+    writeFileSync(path.join(path.dirname(root), 'outside.crv'), 'secret\n');
+    const at = includeDefinitionAt('{{ ../outside.crv }}\n', { line: 0, character: 4 }, optionsFor(root, doc));
+    assert.equal(at, null);
+});
+test('a symlink escaping the root does not navigate', () => {
+    const { root, doc } = workspace();
+    const outsideDir = mkdtempSync(path.join(tmpdir(), 'carve-lsp-outside-'));
+    const secret = path.join(outsideDir, 'secret.crv');
+    writeFileSync(secret, 'secret\n');
+    symlinkSync(secret, path.join(root, 'link.crv'));
+    const at = includeDefinitionAt('{{ link.crv }}\n', { line: 0, character: 4 }, optionsFor(root, doc));
+    assert.equal(at, null);
+});
+test('an absolute path does not navigate while absolutes are denied', () => {
+    const { root, doc, child } = workspace();
+    const at = includeDefinitionAt(`{{ ${child} }}\n`, { line: 0, character: 4 }, optionsFor(root, doc));
+    assert.equal(at, null);
+});
+test('a missing target does not navigate', () => {
+    const { root, doc } = workspace();
+    const at = includeDefinitionAt('{{ nope.crv }}\n', { line: 0, character: 4 }, optionsFor(root, doc));
+    assert.equal(at, null);
+});
+/*
+ * Three properties around the branch rather than inside it. The first two are
+ * NOT killed by the denial mutation above - they are controls for different
+ * mistakes, and are labelled as such rather than presented as proof of the
+ * guard.
+ */
+test('with no resolver the include branch is inert (control)', () => {
+    const { root, doc } = workspace();
+    const uri = pathToFileURL(doc).toString();
+    assert.equal(includeDefinitionAt('{{ chapter-1.crv }}\n', { line: 0, character: 4 }, {}), null);
+    assert.equal(definitionAt(uri, '{{ chapter-1.crv }}\n', { line: 0, character: 4 }), null);
+    assert.ok(root);
+});
+test('a directive inside verbatim content is not a directive (control)', () => {
+    const { root, doc } = workspace();
+    const at = includeDefinitionAt('`{{ chapter-1.crv }}`\n', { line: 0, character: 6 }, optionsFor(root, doc));
+    assert.equal(at, null);
+});
+test('a CRLF document resolves the same offsets as LF', () => {
+    const { root, doc, child } = workspace();
+    const at = includeDefinitionAt('a\r\nb\r\n{{ chapter-1.crv }}\r\n', { line: 2, character: 5 }, optionsFor(root, doc));
+    assert.equal(at?.uri, pathToFileURL(child).toString());
+});
+//# sourceMappingURL=include-definition-denial.test.js.map

package/dist/include-definition-denial.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-definition-denial.test.js","sourceRoot":"","sources":["../src/include-definition-denial.test.ts"],"names":[],"mappings":"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"}

package/dist/include-definition.d.ts

@@ -0,0 +1,3 @@
+import { type Location, type Position } from 'vscode-languageserver/node.js';
+import type { IncludeOptions } from './includes.js';
+export declare function includeDefinitionAt(source: string, position: Position, options: IncludeOptions | undefined): Location | null;

package/dist/include-definition.js

@@ -0,0 +1,37 @@
+import { pathToFileURL } from 'node:url';
+import { findDirectives } from './include-directive.js';
+export function includeDefinitionAt(source, position, options) {
+    if (!options?.resolver)
+        return null;
+    const normalized = source.replace(/\r\n?/g, '\n');
+    const offset = offsetAt(normalized, position);
+    const directive = findDirectives(normalized).find((candidate) => offset >= candidate.start && offset < candidate.end);
+    if (!directive)
+        return null;
+    const stack = options.sourcePath === undefined ? [] : [options.sourcePath];
+    const resolved = options.resolver(directive.path, {
+        stack,
+        depth: 0,
+        ...(options.sourcePath === undefined ? {} : { sourcePath: options.sourcePath }),
+    });
+    if (!resolved.ok)
+        return null;
+    return {
+        uri: pathToFileURL(resolved.id).toString(),
+        range: {
+            start: { line: 0, character: 0 },
+            end: { line: 0, character: 0 },
+        },
+    };
+}
+function offsetAt(source, position) {
+    let offset = 0;
+    for (let line = 0; line < position.line; line += 1) {
+        const newline = source.indexOf('\n', offset);
+        if (newline < 0)
+            return source.length;
+        offset = newline + 1;
+    }
+    return Math.min(source.length, offset + position.character);
+}
+//# sourceMappingURL=include-definition.js.map

package/dist/include-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-definition.js","sourceRoot":"","sources":["../src/include-definition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAGvD,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,QAAkB,EAClB,OAAmC;IAEnC,IAAI,CAAC,OAAO,EAAE,QAAQ;QAAE,OAAO,IAAI,CAAA;IACnC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;IACjD,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IAC7C,MAAM,SAAS,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC,IAAI,CAC/C,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,IAAI,SAAS,CAAC,KAAK,IAAI,MAAM,GAAG,SAAS,CAAC,GAAG,CACnE,CAAA;IACD,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAA;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IAC1E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE;QAChD,KAAK;QACL,KAAK,EAAE,CAAC;QACR,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAChF,CAAC,CAAA;IACF,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IAC7B,OAAO;QACL,GAAG,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;QAC1C,KAAK,EAAE;YACL,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;YAChC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;SAC/B;KACF,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CAAC,MAAc,EAAE,QAAkB;IAClD,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QAC5C,IAAI,OAAO,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC,MAAM,CAAA;QACrC,MAAM,GAAG,OAAO,GAAG,CAAC,CAAA;IACtB,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAA;AAC7D,CAAC"}

package/dist/include-features.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/include-features.test.js

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { analyzeCarve } from './analyze.js';
+import { DependencyIndex, watcherFor } from './dependencies.js';
+import { definitionAt } from './definition.js';
+import { IncludeSourceCache } from './include-cache.js';
+import { fileSystemResolver } from './include-path.js';
+import { parse, resolve } from '@markup-carve/carve';
+import { IncludeParseCache } from './include-cache.js';
+function fixture() {
+    const dir = realpathSync(mkdtempSync(path.join(tmpdir(), 'carve-lsp-features-')));
+    test.after(() => rmSync(dir, { recursive: true, force: true }));
+    return dir;
+}
+test('include cache is metadata-validated and LRU-bounded', () => {
+    const cache = new IncludeSourceCache(2);
+    cache.set('/a', 1, 1, { source: 'a', bytes: 1 });
+    cache.set('/b', 1, 1, { source: 'b', bytes: 1 });
+    assert.equal(cache.get('/a', 1, 1)?.source, 'a');
+    cache.set('/c', 1, 1, { source: 'c', bytes: 1 });
+    assert.equal(cache.get('/b', 1, 1), undefined);
+    assert.equal(cache.get('/a', 2, 1), undefined);
+    assert.equal(cache.size, 1);
+});
+test('parsed-child cache is version-validated', () => {
+    const cache = new IncludeParseCache();
+    const document = resolve(parse('# Cached\n'));
+    cache.set('/child', '1:9', document);
+    assert.equal(cache.get('/child', '1:9'), document);
+    assert.equal(cache.get('/child', '2:9'), undefined);
+});
+test('filesystem cache invalidates after an included file changes', () => {
+    const dir = fixture();
+    const child = path.join(dir, 'child.crv');
+    writeFileSync(child, '# Before\n');
+    const cache = new IncludeSourceCache();
+    const resolver = fileSystemResolver(dir, { cache });
+    const context = { stack: [path.join(dir, 'main.crv')], depth: 0 };
+    const first = resolver('child.crv', context);
+    assert.match(first.ok ? first.source : '', /Before/);
+    const prior = statSync(child).mtimeMs;
+    writeFileSync(child, '# After!\n');
+    utimesSync(child, new Date(), new Date(prior + 1000));
+    const next = resolver('child.crv', context);
+    assert.equal(next.ok && next.source, '# After!\n');
+});
+test('missing contained targets expose an absolute watch candidate', () => {
+    const dir = fixture();
+    const result = fileSystemResolver(dir)('later.crv', {
+        stack: [path.join(dir, 'main.crv')],
+        depth: 0,
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.ok ? undefined : result.watch, path.join(dir, 'later.crv'));
+});
+test('same missing spelling in different child directories produces two watchers', () => {
+    const dir = fixture();
+    mkdirSync(path.join(dir, 'a'));
+    mkdirSync(path.join(dir, 'b'));
+    writeFileSync(path.join(dir, 'a', 'chapter.crv'), '{{ missing.crv }}\n');
+    writeFileSync(path.join(dir, 'b', 'chapter.crv'), '{{ missing.crv }}\n');
+    const analysis = analyzeCarve('{{ a/chapter.crv }}\n{{ b/chapter.crv }}\n', {
+        includes: {
+            resolver: fileSystemResolver(dir),
+            sourcePath: path.join(dir, 'main.crv'),
+            includeRoot: dir,
+        },
+    });
+    const missing = analysis.dependencies.filter((dependency) => !dependency.resolved);
+    assert.deepEqual(missing.map((dependency) => dependency.watch).sort(), [path.join(dir, 'a', 'missing.crv'), path.join(dir, 'b', 'missing.crv')]);
+});
+test('a missing target below an escaping symlink is never watched', () => {
+    const dir = fixture();
+    const outside = fixture();
+    mkdirSync(path.join(dir, 'inside'));
+    symlinkSync(outside, path.join(dir, 'inside', 'escape'));
+    const result = fileSystemResolver(dir)('inside/escape/later.crv', {
+        stack: [path.join(dir, 'main.crv')],
+        depth: 0,
+    });
+    assert.equal(result.ok, false);
+    assert.equal(result.ok ? undefined : result.denial, 'outside-root');
+    assert.equal(result.ok ? undefined : result.watch, undefined);
+});
+test('dependency index tracks reverse edges and meaningful watch-set changes', () => {
+    const index = new DependencyIndex();
+    assert.equal(index.update('file:///a', ['/child', '/missing']), true);
+    assert.equal(index.update('file:///a', ['/missing', '/child']), false);
+    index.update('file:///b', ['/child']);
+    assert.deepEqual(index.documentsFor('/child').sort(), ['file:///a', 'file:///b']);
+    assert.equal(index.remove('file:///a'), true);
+    assert.deepEqual(index.watchedPaths(), ['/child']);
+});
+test('watchers for missing directory trees root at an existing ancestor', () => {
+    const dir = fixture();
+    const watcher = watcherFor(path.join(dir, 'future', 'chapter.crv'));
+    assert.equal(watcher.globPattern.baseUri, pathToFileURL(dir).toString());
+    assert.equal(watcher.globPattern.pattern, 'future/chapter.crv');
+});
+test('go-to-definition on an include uses the guarded resolver', () => {
+    const dir = fixture();
+    const main = path.join(dir, 'main.crv');
+    const child = path.join(dir, 'child.crv');
+    writeFileSync(main, '{{ child.crv }}\n');
+    writeFileSync(child, '# Child\n');
+    const source = readFileSync(main, 'utf8');
+    const location = definitionAt(pathToFileURL(main).toString(), source, { line: 0, character: 5 }, {
+        resolver: fileSystemResolver(dir),
+        sourcePath: main,
+        includeRoot: dir,
+    });
+    assert.equal(location?.uri, pathToFileURL(child).toString());
+});
+test('included headings contribute symbols attributed to the child file', () => {
+    const dir = fixture();
+    const main = path.join(dir, 'main.crv');
+    const child = path.join(dir, 'child.crv');
+    writeFileSync(child, '# Child heading\n');
+    const analysis = analyzeCarve('{{ child.crv }}\n', {
+        includes: {
+            resolver: fileSystemResolver(dir),
+            sourcePath: main,
+            includeRoot: dir,
+        },
+    });
+    assert.equal(analysis.includedSymbols[0]?.name, 'Child heading');
+    assert.equal(analysis.includedSymbols[0]?.location.uri, pathToFileURL(child).toString());
+});
+//# sourceMappingURL=include-features.test.js.map

package/dist/include-features.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-features.test.js","sourceRoot":"","sources":["../src/include-features.test.ts"],"names":[],"mappings":"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"}

package/dist/include-path.d.ts

@@ -1,3 +1,4 @@
+import type { IncludeSourceCache } from './include-cache.js';
 /**
  * Why a resolver refused a target. Reported on {@link IncludeWarning.detail},
  * never folded into the diagnostic message: §19 I7 requires a
@@ -24,10 +25,13 @@ export type IncludeResolved = {
     id: string;
     source: string;
     bytes: number;
+    watch?: string;
+    version?: string;
 } | {
     ok: false;
     id: string;
     denial: IncludeDenial;
+    watch?: string;
 };
 export type IncludeResolver = (includePath: string, ctx: IncludeContext) => IncludeResolved;
 export interface FileSystemResolverOptions {
@@ -44,6 +48,8 @@ export interface FileSystemResolverOptions {
      * later gains a fetcher has the gate already in place.
      */
     allowedRemoteHosts?: string[];
+    /** Process-level child-source cache, consulted only after containment. */
+    cache?: IncludeSourceCache;
 }
 /**
  * Filesystem resolver with canonical root containment, for a workspace the