sdocs 0.0.40 → 0.0.41

package/dist/language/scanner.js

@@ -0,0 +1,529 @@
+/**
+ * Syntactic scanner for v2 .sdoc files.
+ *
+ * A .sdoc file is: optional <script> at the top, entity blocks in the
+ * middle ([DOCS] / [PAGE] / [LAYOUT], with lowercase sub-blocks [preview] /
+ * [example] inside [DOCS]), optional <style> at the bottom.
+ *
+ * The scanner is line-anchored and non-balancing: tags are recognized only
+ * at the start of a line and only where the current state allows them, so
+ * block bodies may contain any text — including square brackets — without
+ * escaping. Inside a body, only the matching closer line terminates it.
+ *
+ * This layer is purely syntactic: it reports structure, attribute values
+ * and precise spans, and recovers from errors so an editor can keep
+ * getting diagnostics for the rest of the file. Semantic validation
+ * (required attributes, uniqueness, literal-only args) lives in parser.ts.
+ */
+export const ENTITY_KINDS = ['DOCS', 'PAGE', 'LAYOUT'];
+export const SUB_BLOCK_KINDS = ['preview', 'example'];
+function splitLines(source) {
+    const lines = [];
+    let start = 0;
+    for (let i = 0; i <= source.length; i++) {
+        if (i === source.length || source[i] === '\n') {
+            lines.push({ start, end: i, text: source.slice(start, i) });
+            start = i + 1;
+        }
+    }
+    return lines;
+}
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]*/;
+/** Scan an opener's attributes starting right after `[KIND`. Handles
+ * multi-line openers and quote/brace nesting. Returns the offset just past
+ * the closing ']' or reports an error and returns -1. */
+function scanOpenerAttrs(source, from, attrs, errors) {
+    let i = from;
+    while (i < source.length) {
+        const ch = source[i];
+        if (ch === ']')
+            return i + 1;
+        if (/\s/.test(ch)) {
+            i++;
+            continue;
+        }
+        const nameMatch = source.slice(i).match(NAME_RE);
+        if (!nameMatch) {
+            errors.push({
+                code: 'attr-syntax',
+                message: `Unexpected character '${ch}' in block opener.`,
+                span: { start: i, end: i + 1 },
+            });
+            return -1;
+        }
+        const name = nameMatch[0];
+        const nameStart = i;
+        i += name.length;
+        if (source[i] !== '=') {
+            addAttr(attrs, errors, name, {
+                kind: 'bare',
+                raw: '',
+                span: { start: nameStart, end: i },
+                valueSpan: { start: i, end: i },
+            });
+            continue;
+        }
+        i++; // '='
+        if (source[i] === '"') {
+            const valueStart = i + 1;
+            const close = source.indexOf('"', valueStart);
+            if (close === -1) {
+                errors.push({
+                    code: 'attr-syntax',
+                    message: `Unterminated string value for attribute "${name}".`,
+                    span: { start: nameStart, end: source.length },
+                });
+                return -1;
+            }
+            addAttr(attrs, errors, name, {
+                kind: 'string',
+                raw: source.slice(valueStart, close),
+                span: { start: nameStart, end: close + 1 },
+                valueSpan: { start: valueStart, end: close },
+            });
+            i = close + 1;
+        }
+        else if (source[i] === '{') {
+            const valueStart = i + 1;
+            const close = scanBalancedBraces(source, i);
+            if (close === -1) {
+                errors.push({
+                    code: 'attr-syntax',
+                    message: `Unterminated expression value for attribute "${name}".`,
+                    span: { start: nameStart, end: source.length },
+                });
+                return -1;
+            }
+            addAttr(attrs, errors, name, {
+                kind: 'expression',
+                raw: source.slice(valueStart, close),
+                span: { start: nameStart, end: close + 1 },
+                valueSpan: { start: valueStart, end: close },
+            });
+            i = close + 1;
+        }
+        else {
+            errors.push({
+                code: 'attr-syntax',
+                message: `Attribute "${name}" must have a "string" or {expression} value.`,
+                span: { start: nameStart, end: i },
+            });
+            return -1;
+        }
+    }
+    errors.push({
+        code: 'attr-syntax',
+        message: 'Block opener is missing its closing "]".',
+        span: { start: from, end: source.length },
+    });
+    return -1;
+}
+function addAttr(attrs, errors, name, value) {
+    if (attrs[name]) {
+        errors.push({
+            code: 'duplicate-attr',
+            message: `Duplicate attribute "${name}".`,
+            span: value.span,
+        });
+        return;
+    }
+    attrs[name] = value;
+}
+/** Given source[open] === '{', return the offset of the matching '}',
+ * skipping strings and nested braces. -1 when unterminated. */
+function scanBalancedBraces(source, open) {
+    let depth = 0;
+    for (let i = open; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "'" || ch === '"' || ch === '`') {
+            i = skipString(source, i);
+            if (i === -1)
+                return -1;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** Given source[at] is a quote, return the offset of the closing quote. */
+function skipString(source, at) {
+    const quote = source[at];
+    for (let i = at + 1; i < source.length; i++) {
+        if (source[i] === '\\') {
+            i++;
+            continue;
+        }
+        if (source[i] === quote)
+            return i;
+    }
+    return -1;
+}
+/** Parse a `[name` / `[/name` token at the start of a trimmed line. */
+function tagToken(trimmed) {
+    const m = trimmed.match(/^\[(\/?)([A-Za-z][A-Za-z0-9_-]*)/);
+    if (!m)
+        return null;
+    return { name: m[2], closer: m[1] === '/' };
+}
+function isEntityKind(name) {
+    return ENTITY_KINDS.includes(name);
+}
+function isSubBlockKind(name) {
+    return SUB_BLOCK_KINDS.includes(name);
+}
+export function scanSdoc(source) {
+    const lines = splitLines(source);
+    const errors = [];
+    const entities = [];
+    let script = null;
+    let style = null;
+    let li = 0;
+    /** Skip an HTML comment starting on line `li` at trimmed position; returns the next line index. */
+    function skipComment(startLi) {
+        const startOffset = lines[startLi].start + lines[startLi].text.indexOf('<!--');
+        const close = source.indexOf('-->', startOffset + 4);
+        if (close === -1) {
+            errors.push({
+                code: 'unclosed-comment',
+                message: 'Unclosed HTML comment.',
+                span: { start: startOffset, end: source.length },
+            });
+            return lines.length;
+        }
+        let i = startLi;
+        while (i < lines.length && lines[i].end < close + 3)
+            i++;
+        const rest = source.slice(close + 3, lines[i].end);
+        if (rest.trim() !== '') {
+            errors.push({
+                code: 'text-outside-blocks',
+                message: 'Unexpected text after comment.',
+                span: { start: close + 3, end: lines[i].end },
+            });
+        }
+        return i + 1;
+    }
+    /** Capture a <script>/<style> tag block whose opener starts line `li`. */
+    function captureTag(tag, startLi) {
+        const openLine = lines[startLi];
+        const openStart = openLine.start + openLine.text.indexOf(`<${tag}`);
+        const openEnd = source.indexOf('>', openStart);
+        if (openEnd === -1) {
+            errors.push({
+                code: 'tag-syntax',
+                message: `Malformed <${tag}> tag.`,
+                span: { start: openStart, end: openLine.end },
+            });
+            return null;
+        }
+        const closeIdx = source.indexOf(`</${tag}>`, openEnd + 1);
+        if (closeIdx === -1) {
+            errors.push({
+                code: 'unclosed-tag',
+                message: `Missing </${tag}>.`,
+                span: { start: openStart, end: source.length },
+            });
+            return null;
+        }
+        const closeEnd = closeIdx + `</${tag}>`.length;
+        let i = startLi;
+        while (i < lines.length && lines[i].end < closeEnd)
+            i++;
+        const rest = source.slice(closeEnd, lines[i].end);
+        if (rest.trim() !== '') {
+            errors.push({
+                code: 'text-outside-blocks',
+                message: `Unexpected text after </${tag}>.`,
+                span: { start: closeEnd, end: lines[i].end },
+            });
+        }
+        return {
+            block: {
+                attrsText: source.slice(openStart + tag.length + 1, openEnd),
+                content: source.slice(openEnd + 1, closeIdx),
+                contentSpan: { start: openEnd + 1, end: closeIdx },
+                span: { start: openStart, end: closeEnd },
+            },
+            nextLi: i + 1,
+        };
+    }
+    /** Scan an entity or sub-block opener starting at line `li`. Returns the
+     * attrs, the opener span, and the line index after the opener. */
+    function scanOpener(startLi, kindLen) {
+        const line = lines[startLi];
+        const bracketStart = line.start + line.text.indexOf('[');
+        const attrs = {};
+        const end = scanOpenerAttrs(source, bracketStart + 1 + kindLen, attrs, errors);
+        if (end === -1)
+            return null;
+        let i = startLi;
+        while (i < lines.length && lines[i].end < end)
+            i++;
+        const rest = source.slice(end, lines[i].end);
+        if (rest.trim() !== '') {
+            errors.push({
+                code: 'tag-not-alone',
+                message: 'A block opener must be alone on its line.',
+                span: { start: end, end: lines[i].end },
+            });
+        }
+        return { attrs, openerSpan: { start: bracketStart, end }, nextLi: i + 1 };
+    }
+    /** Collect raw body lines until the exact closer line `[/kind]`. */
+    function captureBody(startLi, closer) {
+        const bodyStart = startLi < lines.length ? lines[startLi].start : source.length;
+        for (let i = startLi; i < lines.length; i++) {
+            if (lines[i].text.trim() === closer) {
+                const bodyEnd = i > 0 ? lines[i - 1].end : bodyStart;
+                const tagStart = lines[i].start + lines[i].text.indexOf(closer);
+                return {
+                    body: source.slice(bodyStart, Math.max(bodyStart, bodyEnd)),
+                    bodySpan: { start: bodyStart, end: Math.max(bodyStart, bodyEnd) },
+                    closerSpan: { start: tagStart, end: tagStart + closer.length },
+                    nextLi: i + 1,
+                };
+            }
+        }
+        return null;
+    }
+    /** Scan the inside of a [DOCS] entity until its closer. */
+    function scanDocsBody(startLi, entity) {
+        let i = startLi;
+        while (i < lines.length) {
+            const line = lines[i];
+            const trimmed = line.text.trim();
+            if (trimmed === '') {
+                i++;
+                continue;
+            }
+            if (trimmed.startsWith('<!--')) {
+                i = skipComment(i);
+                continue;
+            }
+            const token = tagToken(trimmed);
+            if (token && token.closer && token.name === 'DOCS' && trimmed === '[/DOCS]') {
+                const tagStart = line.start + line.text.indexOf('[/DOCS]');
+                entity.span.end = tagStart + '[/DOCS]'.length;
+                return i + 1;
+            }
+            if (token && !token.closer && isSubBlockKind(token.name)) {
+                const opener = scanOpener(i, token.name.length);
+                if (!opener)
+                    return lines.length;
+                const captured = captureBody(opener.nextLi, `[/${token.name}]`);
+                if (!captured) {
+                    errors.push({
+                        code: 'unclosed-block',
+                        message: `Missing [/${token.name}].`,
+                        span: opener.openerSpan,
+                    });
+                    return lines.length;
+                }
+                entity.blocks.push({
+                    kind: token.name,
+                    attrs: opener.attrs,
+                    body: captured.body,
+                    bodySpan: captured.bodySpan,
+                    openerSpan: opener.openerSpan,
+                    span: { start: opener.openerSpan.start, end: captured.closerSpan.end },
+                });
+                i = captured.nextLi;
+                continue;
+            }
+            const span = { start: line.start + line.text.indexOf(trimmed[0]), end: line.end };
+            if (token && isSubBlockKind(token.name.toLowerCase()) && !token.closer) {
+                errors.push({
+                    code: 'casing',
+                    message: `Sub-block tags are lowercase: [${token.name.toLowerCase()}].`,
+                    span,
+                });
+                i++;
+                continue;
+            }
+            if (token && !token.closer && isEntityKind(token.name)) {
+                errors.push({
+                    code: 'unclosed-block',
+                    message: `Missing [/DOCS] before the next entity.`,
+                    span,
+                });
+                entity.span.end = line.start;
+                return i; // recover: let the outer loop re-read this line
+            }
+            if (token) {
+                errors.push({
+                    code: token.closer ? 'stray-closer' : 'unknown-tag',
+                    message: token.closer
+                        ? `Unexpected closer [/${token.name}] inside [DOCS].`
+                        : `Unknown block [${token.name}] inside [DOCS] — expected [preview] or [example].`,
+                    span,
+                });
+                i++;
+                continue;
+            }
+            errors.push({
+                code: 'text-outside-blocks',
+                message: 'Text inside [DOCS] must be inside a [preview] or [example] block.',
+                span,
+            });
+            i++;
+        }
+        errors.push({
+            code: 'unclosed-block',
+            message: 'Missing [/DOCS].',
+            span: entity.openerSpan,
+        });
+        entity.span.end = source.length;
+        return lines.length;
+    }
+    // ---- main loop over top-level lines ----
+    while (li < lines.length) {
+        const line = lines[li];
+        const trimmed = line.text.trim();
+        if (trimmed === '') {
+            li++;
+            continue;
+        }
+        if (trimmed.startsWith('<!--')) {
+            li = skipComment(li);
+            continue;
+        }
+        if (trimmed.startsWith('<script')) {
+            const captured = captureTag('script', li);
+            if (!captured)
+                return { script, style, entities, errors, source };
+            if (script) {
+                errors.push({
+                    code: 'duplicate-script',
+                    message: 'Only one <script> block is allowed.',
+                    span: captured.block.span,
+                });
+            }
+            else if (entities.length > 0 || style) {
+                errors.push({
+                    code: 'script-position',
+                    message: '<script> must be at the top of the file, before any entity.',
+                    span: captured.block.span,
+                });
+            }
+            else {
+                script = captured.block;
+            }
+            li = captured.nextLi;
+            continue;
+        }
+        if (trimmed.startsWith('<style')) {
+            const captured = captureTag('style', li);
+            if (!captured)
+                return { script, style, entities, errors, source };
+            if (style) {
+                errors.push({
+                    code: 'duplicate-style',
+                    message: 'Only one <style> block is allowed.',
+                    span: captured.block.span,
+                });
+            }
+            else {
+                style = captured.block;
+            }
+            li = captured.nextLi;
+            continue;
+        }
+        const token = tagToken(trimmed);
+        if (token && !token.closer && isEntityKind(token.name)) {
+            if (style) {
+                errors.push({
+                    code: 'style-position',
+                    message: '<style> must be at the bottom of the file, after all entities.',
+                    span: { start: line.start, end: line.end },
+                });
+            }
+            const opener = scanOpener(li, token.name.length);
+            if (!opener)
+                return { script, style, entities, errors, source };
+            const entity = {
+                kind: token.name,
+                attrs: opener.attrs,
+                blocks: [],
+                body: '',
+                bodySpan: { start: opener.openerSpan.end, end: opener.openerSpan.end },
+                openerSpan: opener.openerSpan,
+                span: { start: opener.openerSpan.start, end: opener.openerSpan.end },
+            };
+            entities.push(entity);
+            if (token.name === 'DOCS') {
+                li = scanDocsBody(opener.nextLi, entity);
+            }
+            else {
+                const captured = captureBody(opener.nextLi, `[/${token.name}]`);
+                if (!captured) {
+                    errors.push({
+                        code: 'unclosed-block',
+                        message: `Missing [/${token.name}].`,
+                        span: opener.openerSpan,
+                    });
+                    entity.body = source.slice(opener.nextLi < lines.length ? lines[opener.nextLi].start : source.length);
+                    entity.span.end = source.length;
+                    return { script, style, entities, errors, source };
+                }
+                entity.body = captured.body;
+                entity.bodySpan = captured.bodySpan;
+                entity.span.end = captured.closerSpan.end;
+                li = captured.nextLi;
+            }
+            continue;
+        }
+        const span = { start: line.start + line.text.indexOf(trimmed[0]), end: line.end };
+        if (token && !token.closer && isEntityKind(token.name.toUpperCase())) {
+            errors.push({
+                code: 'casing',
+                message: `Entity tags are uppercase: [${token.name.toUpperCase()}].`,
+                span,
+            });
+            li++;
+            continue;
+        }
+        if (token && !token.closer && isSubBlockKind(token.name)) {
+            errors.push({
+                code: 'block-outside-entity',
+                message: `[${token.name}] is only valid inside a [DOCS] entity.`,
+                span,
+            });
+            li++;
+            continue;
+        }
+        if (token && token.closer) {
+            errors.push({
+                code: 'stray-closer',
+                message: `Unexpected closer [/${token.name}].`,
+                span,
+            });
+            li++;
+            continue;
+        }
+        errors.push({
+            code: 'text-outside-blocks',
+            message: 'Text must be inside an entity block.',
+            span,
+        });
+        li++;
+    }
+    return { script, style, entities, errors, source };
+}
+/** Convert an offset to a 0-based line/column pair (for editors/CLI output). */
+export function offsetToPosition(source, offset) {
+    let line = 0;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if (source[i] === '\n') {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: offset - lineStart };
+}

package/dist/language/scanner.test.d.ts

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

package/dist/language/scanner.test.js

@@ -0,0 +1,146 @@
+import { describe, expect, it } from 'vitest';
+import { scanSdoc } from './scanner.js';
+const FULL = `<script lang="ts">
+	import Button from './Button.svelte';
+</script>
+
+[DOCS title="Forms / Button" description="A flexible button."]
+
+	[preview component={Button} args={{ label: 'Hi', count: 2 }}]
+		<Button {...args} />
+	[/preview]
+
+	[example title="Disabled"]
+		<Button label="Nope" disabled />
+	[/example]
+
+[/DOCS]
+
+[PAGE title="Guides / Usage"]
+
+	## When to use
+
+	A [reference link][DOCS] and a fence:
+
+	\`\`\`svelte
+	[preview looks like a tag but is content]
+	\`\`\`
+
+[/PAGE]
+
+[LAYOUT title="Patterns / Login" padding="48px"]
+	<Button label="Sign in" />
+[/LAYOUT]
+
+<style>
+	.row { display: flex; }
+</style>
+`;
+describe('scanSdoc structure', () => {
+    const file = scanSdoc(FULL);
+    it('scans a full file without errors', () => {
+        expect(file.errors).toEqual([]);
+    });
+    it('captures script and style', () => {
+        expect(file.script?.attrsText).toContain('lang="ts"');
+        expect(file.script?.content).toContain("import Button from './Button.svelte';");
+        expect(file.style?.content).toContain('.row { display: flex; }');
+    });
+    it('finds all three entities in order', () => {
+        expect(file.entities.map((e) => e.kind)).toEqual(['DOCS', 'PAGE', 'LAYOUT']);
+    });
+    it('parses entity attributes with kinds', () => {
+        const docs = file.entities[0];
+        expect(docs.attrs.title).toMatchObject({ kind: 'string', raw: 'Forms / Button' });
+        expect(docs.attrs.description).toMatchObject({ kind: 'string', raw: 'A flexible button.' });
+        const layout = file.entities[2];
+        expect(layout.attrs.padding).toMatchObject({ kind: 'string', raw: '48px' });
+    });
+    it('parses sub-blocks with attributes and bodies', () => {
+        const [preview, example] = file.entities[0].blocks;
+        expect(preview.kind).toBe('preview');
+        expect(preview.attrs.component).toMatchObject({ kind: 'expression', raw: 'Button' });
+        expect(preview.attrs.args.raw).toBe("{ label: 'Hi', count: 2 }");
+        expect(preview.body).toContain('<Button {...args} />');
+        expect(example.kind).toBe('example');
+        expect(example.body).toContain('<Button label="Nope" disabled />');
+    });
+    it('keeps bracket-looking lines inside bodies as content', () => {
+        const page = file.entities[1];
+        expect(page.body).toContain('[reference link][DOCS]');
+        expect(page.body).toContain('[preview looks like a tag but is content]');
+        expect(file.entities).toHaveLength(3);
+    });
+    it('tracks spans that slice back to the source', () => {
+        const docs = file.entities[0];
+        expect(FULL.slice(docs.openerSpan.start, docs.openerSpan.end)).toBe('[DOCS title="Forms / Button" description="A flexible button."]');
+        expect(FULL.slice(docs.span.start, docs.span.end).endsWith('[/DOCS]')).toBe(true);
+        const preview = docs.blocks[0];
+        expect(FULL.slice(preview.bodySpan.start, preview.bodySpan.end)).toBe(preview.body);
+    });
+});
+describe('scanSdoc details', () => {
+    it('supports multi-line openers', () => {
+        const file = scanSdoc('[DOCS\n\ttitle="Forms / Button"\n\tdescription="Long."\n]\n[/DOCS]\n');
+        expect(file.errors).toEqual([]);
+        expect(file.entities[0].attrs.title.raw).toBe('Forms / Button');
+    });
+    it('supports bare attributes', () => {
+        const file = scanSdoc('[DOCS title="X" draft]\n[/DOCS]\n');
+        expect(file.entities[0].attrs.draft).toMatchObject({ kind: 'bare', raw: '' });
+    });
+    it('allows comments between blocks', () => {
+        const file = scanSdoc('<!-- a note\nspanning lines -->\n[PAGE title="X"]\nhi\n[/PAGE]\n');
+        expect(file.errors).toEqual([]);
+        expect(file.entities).toHaveLength(1);
+    });
+    it('tolerates CRLF line endings and a BOM', () => {
+        const file = scanSdoc('[DOCS title="X"]\r\n[preview component={B}]\r\n<B />\r\n[/preview]\r\n[/DOCS]\r\n');
+        expect(file.errors).toEqual([]);
+        expect(file.entities[0].blocks[0].body).toContain('<B />');
+    });
+    it('handles nested braces and strings in expression attributes', () => {
+        const file = scanSdoc(`[DOCS title="X"]\n[preview component={Button} args={{ a: '}', b: { }, c: "]" }}]\nx\n[/preview]\n[/DOCS]\n`);
+        expect(file.errors).toEqual([]);
+        expect(file.entities[0].blocks[0].attrs.args.raw).toBe(`{ a: '}', b: { }, c: "]" }`);
+    });
+});
+function codes(source) {
+    return scanSdoc(source).errors.map((e) => e.code);
+}
+describe('scanSdoc errors', () => {
+    it('rejects text outside blocks', () => {
+        expect(codes('hello\n')).toContain('text-outside-blocks');
+        expect(codes('[DOCS title="X"]\nstray text\n[/DOCS]\n')).toContain('text-outside-blocks');
+    });
+    it('rejects wrong casing with a targeted message', () => {
+        expect(codes('[docs title="X"]\n[/docs]\n')).toContain('casing');
+        expect(codes('[DOCS title="X"]\n[PREVIEW component={B}]\nx\n[/PREVIEW]\n[/DOCS]\n')).toContain('casing');
+    });
+    it('rejects sub-blocks outside DOCS and unknown blocks inside', () => {
+        expect(codes('[preview component={B}]\nx\n[/preview]\n')).toContain('block-outside-entity');
+        expect(codes('[DOCS title="X"]\n[stuff]\nx\n[/stuff]\n[/DOCS]\n')).toContain('unknown-tag');
+    });
+    it('requires openers to be alone on their line', () => {
+        expect(codes('[DOCS title="X"] trailing\n[/DOCS]\n')).toContain('tag-not-alone');
+    });
+    it('reports unclosed blocks', () => {
+        expect(codes('[DOCS title="X"]\n')).toContain('unclosed-block');
+        expect(codes('[DOCS title="X"]\n[preview component={B}]\nx\n[/DOCS]\n')).toContain('unclosed-block');
+        expect(codes('[PAGE title="X"]\ntext\n')).toContain('unclosed-block');
+    });
+    it('reports stray closers and duplicate attributes', () => {
+        expect(codes('[/DOCS]\n')).toContain('stray-closer');
+        expect(codes('[DOCS title="A" title="B"]\n[/DOCS]\n')).toContain('duplicate-attr');
+    });
+    it('enforces file anatomy: script top, style bottom', () => {
+        expect(codes('[PAGE title="X"]\nx\n[/PAGE]\n<script>\nlet a;\n</script>\n')).toContain('script-position');
+        expect(codes('<style>\n.a {}\n</style>\n[PAGE title="X"]\nx\n[/PAGE]\n')).toContain('style-position');
+    });
+    it('recovers when an entity opener appears inside an unclosed [DOCS]', () => {
+        const file = scanSdoc('[DOCS title="A"]\n[PAGE title="B"]\nx\n[/PAGE]\n');
+        expect(file.errors.map((e) => e.code)).toContain('unclosed-block');
+        expect(file.entities.map((e) => e.kind)).toEqual(['DOCS', 'PAGE']);
+        expect(file.entities[1].body.trim()).toBe('x');
+    });
+});