@markup-carve/carve-lsp 0.1.1 → 0.1.2

package/dist/include-directive.js

@@ -0,0 +1,158 @@
+/**
+ * Recognition of processor-level `{{ … }}` include directives (PART 6 grammar,
+ * PART 9 §19 rule I1).
+ *
+ * Kept separate from {@link ./includes.js} so consumers that only need to
+ * RECOGNIZE a directive do not pull in the expander's file-system imports.
+ *
+ * The regular expressions and `parseDirective` mirror `src/include-directive.ts`
+ * in the carve-js engine deliberately: one rule, one spelling. What is added
+ * here is source-level scanning. The engine recognizes directives on
+ * reassembled inline runs of a parsed AST; this server has no include-aware
+ * engine to parse with (the pinned `@markup-carve/carve` predates the pass), so
+ * it scans the raw document text and shields verbatim regions itself.
+ */
+export const DIRECTIVE_SCAN_RE = /\{\{\s+(?:"((?:\\.|[^"\\])*)"|\u201c([^\u201d]*)\u201d|([^#@}\s"\u201c]+))((?:\s+#[A-Za-z_][\w-]*)?)(.*?)\s+\}\}/g;
+export const DIRECTIVE_FULL_RE = /^\{\{\s+(?:"((?:\\.|[^"\\])*)"|\u201c([^\u201d]*)\u201d|([^#@}\s"\u201c]+))((?:\s+#[A-Za-z_][\w-]*)?)(.*?)\s+\}\}$/;
+const OPTION_RE = /^@([A-Za-z_][\w-]*):([^#@}\s]+)$/;
+function unescapeQuotedPath(value) {
+    return value.replace(/\\(["\\])/g, '$1');
+}
+/**
+ * Parse one candidate directive token. Returns null when the token is not a
+ * well-formed directive per I1 (a bad shape, or an unrecognized or malformed
+ * option), in which case it stays ordinary text and `onInvalidOption` fires so
+ * the caller can raise `include-unknown-option`.
+ */
+export function parseDirective(raw, onInvalidOption) {
+    const m = DIRECTIVE_FULL_RE.exec(raw);
+    if (!m)
+        return null;
+    const includePath = m[1] !== undefined ? unescapeQuotedPath(m[1]) : (m[2] ?? m[3]);
+    if (includePath === '')
+        return null;
+    const sectionPart = m[4]?.trim();
+    const section = sectionPart ? sectionPart.slice(1) : undefined;
+    let lines;
+    let shift = 0;
+    const rest = m[5]?.trim();
+    if (rest) {
+        for (const part of rest.split(/\s+/)) {
+            const opt = OPTION_RE.exec(part);
+            const invalid = () => {
+                // I1: an unrecognized (or malformed) option makes the directive
+                // unresolvable - warning plus literal text, never a silent drop.
+                if (part.startsWith('@'))
+                    onInvalidOption?.(part);
+                return null;
+            };
+            if (!opt)
+                return invalid();
+            const [, key, value] = opt;
+            if (key === 'lines') {
+                const lm = /^([1-9]\d*)-([1-9]\d*)$/.exec(value);
+                if (!lm)
+                    return invalid();
+                lines = { start: Number(lm[1]), end: Number(lm[2]) };
+                if (lines.end < lines.start)
+                    return invalid();
+            }
+            else if (key === 'shift') {
+                // I8: a signed integer or the literal "auto", never both forms.
+                if (value === 'auto')
+                    shift = 'auto';
+                else if (!/^[+-]?\d+$/.test(value))
+                    return invalid();
+                else
+                    shift = Number(value);
+            }
+            else {
+                return invalid();
+            }
+        }
+    }
+    const directive = { raw, path: includePath, shift };
+    if (section !== undefined)
+        directive.section = section;
+    if (lines !== undefined)
+        directive.lines = lines;
+    return directive;
+}
+/**
+ * Regions of `source` whose content is verbatim and therefore shielded from
+ * include recognition (I9): fenced blocks of every flavour, raw blocks
+ * (```` ```=html ````) included, and inline code spans.
+ *
+ * Approximate by design, and deliberately so: it is a line-and-backtick scan
+ * rather than a parse, because the pinned engine cannot tell us where a
+ * directive sits relative to a fence. It errs toward shielding - an ambiguous
+ * region is treated as verbatim and the directive stays literal, which is the
+ * safe direction for a file-read capability.
+ */
+export function verbatimSpans(source) {
+    const spans = [];
+    let offset = 0;
+    let fence = null;
+    for (const line of source.split('\n')) {
+        const lineStart = offset;
+        const lineEnd = offset + line.length;
+        offset = lineEnd + 1;
+        if (fence) {
+            const close = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+            if (close && close[1][0] === fence.char && close[1].length >= fence.length) {
+                spans.push({ start: fence.start, end: lineEnd });
+                fence = null;
+            }
+            continue;
+        }
+        const open = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        // A backtick fence's info string may not itself contain a backtick; a
+        // tilde fence's may. Same rule the engines apply.
+        if (open && !(open[1][0] === '`' && open[2].includes('`'))) {
+            fence = { char: open[1][0], length: open[1].length, start: lineStart };
+            continue;
+        }
+        // Inline code spans, matched run-for-run within the line.
+        const runs = /`+/g;
+        let openRun = null;
+        for (let m = runs.exec(line); m; m = runs.exec(line)) {
+            if (!openRun) {
+                openRun = { index: m.index, length: m[0].length };
+                continue;
+            }
+            if (m[0].length === openRun.length) {
+                spans.push({ start: lineStart + openRun.index, end: lineStart + m.index + m[0].length });
+                openRun = null;
+            }
+        }
+    }
+    // An unterminated fence shields everything to the end of the document.
+    if (fence)
+        spans.push({ start: fence.start, end: source.length });
+    return spans;
+}
+/**
+ * Locate the well-formed directives in `source`, in source order, skipping any
+ * that begin inside a verbatim region (I9).
+ *
+ * `onInvalidOption` fires for a token of directive shape whose options do not
+ * parse, so the caller can raise `include-unknown-option` on it.
+ */
+export function findDirectives(source, onInvalidOption) {
+    const shielded = verbatimSpans(source);
+    const inVerbatim = (index) => shielded.some((span) => index >= span.start && index < span.end);
+    const re = new RegExp(DIRECTIVE_SCAN_RE.source, 'g');
+    const found = [];
+    for (let m = re.exec(source); m; m = re.exec(source)) {
+        const start = m.index;
+        const end = start + m[0].length;
+        if (inVerbatim(start))
+            continue;
+        const parsed = parseDirective(m[0], (part) => onInvalidOption?.(part, start, end));
+        if (!parsed)
+            continue;
+        found.push({ ...parsed, start, end });
+    }
+    return found;
+}
+//# sourceMappingURL=include-directive.js.map

package/dist/include-directive.js.map

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

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

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

package/dist/include-directive.test.js

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { findDirectives, parseDirective, verbatimSpans } from './include-directive.js';
+// Expectations here follow the cross-engine include-conformance vectors named
+// in each test (markup-carve/carve tests/include-conformance/vectors). Those
+// vectors currently live only on the unmerged spec branch for
+// markup-carve/carve#291, so they are cited rather than vendored.
+test('a bare directive is recognized with its path', () => {
+    const [d] = findDirectives('{{ child.crv }}');
+    assert.ok(d);
+    assert.equal(d.path, 'child.crv');
+    assert.equal(d.start, 0);
+    assert.equal(d.end, 15);
+});
+test('a quoted path carrying a space is recognized (i01-quoted-path-roundtrip)', () => {
+    const [d] = findDirectives('{{ "my chapter.crv" }}');
+    assert.ok(d);
+    assert.equal(d.path, 'my chapter.crv');
+});
+test('a section selector is separated from the path', () => {
+    const [d] = findDirectives('{{ c.crv #Intro }}');
+    assert.ok(d);
+    assert.equal(d.path, 'c.crv');
+    assert.equal(d.section, 'Intro');
+});
+test('empty and pathless brace pairs stay literal (i01-*-literal)', () => {
+    // Each of these is ordinary text under the PART 6 production: the path token
+    // is mandatory and may not begin with `#` or `@`.
+    for (const source of ['{{}}', '{{   }}', '{{ #sec }}', '{{ @shift:1 }}']) {
+        assert.deepEqual(findDirectives(source), [], source);
+    }
+});
+test('an unknown option makes the directive literal and reports the option (i01-unknown-option-literal)', () => {
+    const seen = [];
+    const found = findDirectives('{{ child @nope:1 }}', (part) => seen.push(part));
+    assert.deepEqual(found, []);
+    assert.deepEqual(seen, ['@nope:1']);
+});
+test('a malformed shift value is an unknown option (i01-shift-malformed-value)', () => {
+    const seen = [];
+    assert.deepEqual(findDirectives('{{ child @shift:x }}', (part) => seen.push(part)), []);
+    assert.deepEqual(seen, ['@shift:x']);
+});
+test('several directives in one run are all found (i09a-multi-directive-one-run)', () => {
+    const found = findDirectives('start {{ a.crv }} mid {{ b.crv }} end');
+    assert.deepEqual(found.map((d) => d.path), ['a.crv', 'b.crv']);
+});
+test('adjacent directives are both found', () => {
+    const found = findDirectives('{{ a.crv }}{{ d.crv }}');
+    assert.deepEqual(found.map((d) => d.path), ['a.crv', 'd.crv']);
+});
+// ---------------------------------------------------------------------------
+// Verbatim shielding (I9)
+// ---------------------------------------------------------------------------
+test('a directive inside a fence or a code span is shielded (i09-verbatim-fence-and-code-span)', () => {
+    const source = '```txt\n{{ child }}\n```\n\nUse `{{ child }}`.';
+    assert.deepEqual(findDirectives(source), []);
+});
+test('a raw block shields its directive (i09-verbatim-raw-block)', () => {
+    assert.deepEqual(findDirectives('```=html\n{{ child }}\n```'), []);
+});
+test('a fence shields only itself; a directive after it still resolves (i09-fence-info-shields-plain-expands)', () => {
+    const source = '```js\n{{ child }}\n```\n\n{{ child }}';
+    const found = findDirectives(source);
+    assert.equal(found.length, 1);
+    // The surviving one is the directive AFTER the closing fence.
+    assert.equal(found[0].start, source.lastIndexOf('{{ child }}'));
+});
+test('a tilde fence shields too', () => {
+    assert.deepEqual(findDirectives('~~~\n{{ child }}\n~~~'), []);
+});
+test('an unterminated fence shields to the end of the document', () => {
+    assert.deepEqual(findDirectives('```\n{{ child }}\n'), []);
+});
+test('verbatimSpans covers the whole fence including its markers', () => {
+    const source = '```\nx\n```\n';
+    assert.deepEqual(verbatimSpans(source), [{ start: 0, end: 9 }]);
+});
+test('parseDirective rejects a token that is not a directive', () => {
+    assert.equal(parseDirective('{{ oops'), null);
+    assert.equal(parseDirective('{{ }}'), null);
+});
+//# sourceMappingURL=include-directive.test.js.map

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

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

package/dist/include-path.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Why a resolver refused a target. Reported on {@link IncludeWarning.detail},
+ * never folded into the diagnostic message: §19 I7 requires a
+ * processor-generated message naming the failure class, and the
+ * include-conformance goldens (`i10-fs-*`) spell every containment denial as
+ * the single rule `include-unresolved` so that a denial cannot be used to probe
+ * host layout. The class is kept available for tooling and tests.
+ */
+export type IncludeDenial = 'remote-not-allowed' | 'absolute-denied' | 'outside-root' | 'not-found' | 'not-a-file';
+export interface IncludeContext {
+    /** Identity of the including document, supplied by the host when known. */
+    sourcePath?: string;
+    /**
+     * Include chain, root first: the canonical id of each ancestor. Used for
+     * relative resolution (a nested include resolves against its actual parent
+     * directory) and for the cycle guard.
+     */
+    stack: string[];
+    /** Zero-based include depth of the directive being resolved. */
+    depth: number;
+}
+export type IncludeResolved = {
+    ok: true;
+    id: string;
+    source: string;
+    bytes: number;
+} | {
+    ok: false;
+    id: string;
+    denial: IncludeDenial;
+};
+export type IncludeResolver = (includePath: string, ctx: IncludeContext) => IncludeResolved;
+export interface FileSystemResolverOptions {
+    /** Allow absolute include paths, still subject to root containment. Default false. */
+    allowAbsolute?: boolean;
+    /**
+     * Hosts a remote include may name. Empty (the default) means no remote
+     * include is permitted at all.
+     *
+     * Note that this server never fetches over the network under any setting:
+     * an allowlisted host is still refused, because there is no fetcher. The
+     * option exists so that "allowlist explicitly configured" is a real,
+     * inspectable condition rather than an implicit one, and so a host that
+     * later gains a fetcher has the gate already in place.
+     */
+    allowedRemoteHosts?: string[];
+}
+/**
+ * Filesystem resolver with canonical root containment, for a workspace the
+ * client reports as trusted.
+ *
+ * Canonicalize-then-contain: the candidate is resolved to its real path
+ * (symlinks followed) and only then compared against the real root.
+ *
+ * Deliberately NOT a lexical ban on `..`, which is both too strict and too
+ * weak. Too strict: `../shared/glossary.crv` from `chapters/ch1.crv` is a
+ * normal book layout whose canonical target is inside the root, and the
+ * conformance vector `i10-fs-dotdot-inside-root-allowed` requires it to
+ * resolve. Too weak: a symlink inside the root pointing out of it, or an
+ * absolute path, escapes without containing `..` at all
+ * (`i10-fs-symlink-dir-escape-denied`). Canonical containment subsumes both.
+ */
+export declare function fileSystemResolver(includeRoot: string, opts?: FileSystemResolverOptions): IncludeResolver;

package/dist/include-path.js

@@ -0,0 +1,135 @@
+/**
+ * The single place an include path becomes a file read.
+ *
+ * PART 9 §19 puts four MUSTs on this function, and they are here rather than
+ * spread over the callers on purpose: a guard applied on one path and missed on
+ * another is the defect this repository's siblings keep hitting. Nothing else
+ * in this package joins, canonicalizes or opens an include target.
+ *
+ * - MUST resolve include paths only to files under the configured project root
+ *   AFTER symlink resolution (rejecting `..`-traversal and absolute paths that
+ *   escape the root)
+ * - MUST NOT fetch remote URLs unless an allowlist is explicitly configured
+ *
+ * The remaining two MUSTs (recursion depth, total expanded byte size) are
+ * properties of the include GRAPH rather than of one path, so they live in
+ * {@link ./includes.js} where the walk is.
+ */
+import { closeSync, fstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+/** A scheme with an authority (`https://…`), or a protocol-relative `//host/…`. */
+const REMOTE_RE = /^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\//;
+function remoteHost(spec) {
+    const withScheme = spec.startsWith('//') ? `https:${spec}` : spec;
+    try {
+        return new URL(withScheme).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Filesystem resolver with canonical root containment, for a workspace the
+ * client reports as trusted.
+ *
+ * Canonicalize-then-contain: the candidate is resolved to its real path
+ * (symlinks followed) and only then compared against the real root.
+ *
+ * Deliberately NOT a lexical ban on `..`, which is both too strict and too
+ * weak. Too strict: `../shared/glossary.crv` from `chapters/ch1.crv` is a
+ * normal book layout whose canonical target is inside the root, and the
+ * conformance vector `i10-fs-dotdot-inside-root-allowed` requires it to
+ * resolve. Too weak: a symlink inside the root pointing out of it, or an
+ * absolute path, escapes without containing `..` at all
+ * (`i10-fs-symlink-dir-escape-denied`). Canonical containment subsumes both.
+ */
+export function fileSystemResolver(includeRoot, opts = {}) {
+    const rootReal = realpathSync(includeRoot);
+    const allowedRemoteHosts = opts.allowedRemoteHosts ?? [];
+    const contains = (candidate) => {
+        const rel = path.relative(rootReal, candidate);
+        if (rel === '')
+            return true;
+        if (!rel || path.isAbsolute(rel))
+            return false;
+        // Segment-wise, so a directory legitimately named "..foo" is not read as
+        // an escape the way a startsWith('..') prefix test would.
+        return rel.split(path.sep)[0] !== '..';
+    };
+    return (includePath, ctx) => {
+        // GUARD 1 (§19: MUST NOT fetch remote URLs unless an allowlist is
+        // explicitly configured). Checked before any path join, so a URL can never
+        // be mistaken for a relative path and read off disk as `<root>/https:/…`.
+        if (REMOTE_RE.test(includePath)) {
+            const host = remoteHost(includePath);
+            if (!allowedRemoteHosts.includes(host)) {
+                return { ok: false, id: includePath, denial: 'remote-not-allowed' };
+            }
+            // Allowlisted, and still refused: this server has no fetcher. Reported
+            // as a denial rather than silently, so the author sees why.
+            return { ok: false, id: includePath, denial: 'remote-not-allowed' };
+        }
+        // GUARD 2 (§19: absolute paths). Denied outright by default; when the host
+        // opts in, an absolute path still has to survive GUARD 3.
+        if (!opts.allowAbsolute && path.isAbsolute(includePath)) {
+            return { ok: false, id: includePath, denial: 'absolute-denied' };
+        }
+        // The stack carries the canonical path of each ancestor, so a nested
+        // relative include resolves against its actual parent directory, not the
+        // root.
+        const parent = ctx.stack[ctx.stack.length - 1];
+        const base = parent ? path.dirname(path.resolve(rootReal, parent)) : rootReal;
+        const joined = path.isAbsolute(includePath)
+            ? includePath
+            : path.resolve(base, includePath);
+        let real;
+        try {
+            // Symlink resolution happens HERE, before containment, which is what
+            // makes a symlinked escape visible to GUARD 3 at all.
+            real = realpathSync(joined);
+        }
+        catch {
+            return { ok: false, id: includePath, denial: 'not-found' };
+        }
+        // GUARD 3 (§19: only files under the configured project root AFTER symlink
+        // resolution). Catches `..` that leaves the root, a symlink that points out
+        // of it, and an absolute path outside it.
+        if (!contains(real)) {
+            return { ok: false, id: includePath, denial: 'outside-root' };
+        }
+        let fd;
+        try {
+            fd = openSync(real, 'r');
+        }
+        catch {
+            return { ok: false, id: includePath, denial: 'not-found' };
+        }
+        try {
+            const stat = fstatSync(fd);
+            // Regular files only. A FIFO or a character device would block the read
+            // or stream without end, and neither is a document.
+            if (!stat.isFile())
+                return { ok: false, id: real, denial: 'not-a-file' };
+            const buffer = Buffer.allocUnsafe(stat.size);
+            let read = 0;
+            while (read < stat.size) {
+                const n = readSync(fd, buffer, read, stat.size - read, read);
+                if (n <= 0)
+                    break;
+                read += n;
+            }
+            return {
+                ok: true,
+                id: real,
+                source: buffer.subarray(0, read).toString('utf8'),
+                // Encoded bytes, not JavaScript characters, so the budget counts what
+                // the include-bomb actually costs.
+                bytes: read,
+            };
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+}
+//# sourceMappingURL=include-path.js.map

package/dist/include-path.js.map

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

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

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