sdocs 0.0.40 → 0.0.42

package/dist/language/parser.js

@@ -0,0 +1,293 @@
+/**
+ * Semantic layer over the syntactic scanner: validates attributes against
+ * the sdoc language rules and produces typed entities ready for the Vite
+ * plugin, the CLI app-gen, and the editor tooling.
+ */
+import { scanSdoc, } from './scanner.js';
+/**
+ * Normalize a raw block body for consumption: strip the common leading
+ * indentation (bodies sit one level deep inside their block), drop a
+ * trailing carriage return per line, and unescape lines that start with
+ * `\[` (the escape for body lines that would otherwise read as tags).
+ * The scanner keeps the raw text and spans; this is the display/runtime form.
+ */
+export function normalizeBody(raw) {
+    const lines = raw.split('\n').map((line) => line.replace(/\r$/, ''));
+    let common = null;
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        const indent = line.match(/^[ \t]*/)[0];
+        if (common === null) {
+            common = indent;
+        }
+        else {
+            let k = 0;
+            while (k < common.length && k < indent.length && common[k] === indent[k])
+                k++;
+            common = common.slice(0, k);
+        }
+    }
+    const cut = common?.length ?? 0;
+    return lines
+        .map((line) => (line.trim() === '' ? '' : line.slice(cut)))
+        .map((line) => (line.startsWith('\\[') ? line.slice(1) : line))
+        .join('\n')
+        .replace(/^\n+|\n+$/g, '');
+}
+/** Slug used for entity addressing: relPath + '#' + slug. */
+export function slugifyTitle(title) {
+    return (title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'untitled');
+}
+const IDENTIFIER_RE = /^[A-Z][A-Za-z0-9_]*$/;
+const ENTITY_ATTR_RULES = {
+    DOCS: {
+        title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
+        description: { required: false, kind: 'string', hint: 'description="…"' },
+    },
+    PAGE: {
+        title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
+    },
+    LAYOUT: {
+        title: { required: true, kind: 'string', hint: 'title="Group / Name"' },
+        padding: { required: false, kind: 'string', hint: 'padding="48px"' },
+    },
+};
+const SUB_BLOCK_ATTR_RULES = {
+    preview: {
+        component: { required: true, kind: 'expression', hint: 'component={Button}' },
+        args: { required: false, kind: 'expression', hint: 'args={{ label: "Hi" }}' },
+        title: { required: false, kind: 'string', hint: 'title="…"' },
+    },
+    example: {
+        title: { required: true, kind: 'string', hint: 'title="…"' },
+    },
+};
+function checkAttrs(owner, attrs, rules, ownerSpan, diagnostics) {
+    for (const [name, value] of Object.entries(attrs)) {
+        const rule = rules[name];
+        if (!rule) {
+            diagnostics.push({
+                code: 'unknown-attr',
+                message: `Unknown attribute "${name}" on ${owner}. Allowed: ${Object.keys(rules).join(', ')}.`,
+                span: value.span,
+            });
+            continue;
+        }
+        if (value.kind !== rule.kind) {
+            diagnostics.push({
+                code: 'attr-value-kind',
+                message: `Attribute "${name}" on ${owner} must be written ${rule.hint}.`,
+                span: value.span,
+            });
+        }
+    }
+    for (const [name, rule] of Object.entries(rules)) {
+        if (rule.required && !attrs[name]) {
+            diagnostics.push({
+                code: 'missing-attr',
+                message: `${owner} requires ${rule.hint}.`,
+                span: ownerSpan,
+            });
+        }
+    }
+}
+function stringAttr(attrs, name) {
+    const v = attrs[name];
+    return v && v.kind === 'string' ? v.raw : null;
+}
+/**
+ * Parse a preview args expression: a flat object literal whose values are
+ * plain literals (strings, numbers, booleans). Anything richer belongs in
+ * the block body, so it is rejected here.
+ */
+export function parseArgsLiteral(raw, span, diagnostics) {
+    const fail = (message) => {
+        diagnostics.push({ code: 'args-literal', message, span });
+        return null;
+    };
+    let i = 0;
+    const ws = () => {
+        while (i < raw.length && /\s/.test(raw[i]))
+            i++;
+    };
+    ws();
+    if (raw[i] !== '{')
+        return fail('args must be an object literal: args={{ name: value }}.');
+    i++;
+    const values = {};
+    ws();
+    while (i < raw.length && raw[i] !== '}') {
+        const keyMatch = raw.slice(i).match(/^([A-Za-z_$][A-Za-z0-9_$]*|'[^']*'|"[^"]*")\s*:/);
+        if (!keyMatch)
+            return fail('args keys must be plain names, like args={{ label: "Hi" }}.');
+        const key = keyMatch[1].replace(/^['"]|['"]$/g, '');
+        i += keyMatch[0].length;
+        ws();
+        const rest = raw.slice(i);
+        let m;
+        if ((m = rest.match(/^'((?:[^'\\]|\\.)*)'/)) || (m = rest.match(/^"((?:[^"\\]|\\.)*)"/))) {
+            values[key] = m[1].replace(/\\(.)/g, '$1');
+            i += m[0].length;
+        }
+        else if ((m = rest.match(/^-?\d+(\.\d+)?/))) {
+            values[key] = Number(m[0]);
+            i += m[0].length;
+        }
+        else if ((m = rest.match(/^(true|false)\b/))) {
+            values[key] = m[0] === 'true';
+            i += m[0].length;
+        }
+        else {
+            return fail(`args value for "${key}" must be a plain literal (string, number, or boolean); richer values go in the block body.`);
+        }
+        ws();
+        if (raw[i] === ',') {
+            i++;
+            ws();
+        }
+        else if (raw[i] !== '}') {
+            return fail('args entries must be separated by commas.');
+        }
+    }
+    if (raw[i] !== '}')
+        return fail('args object literal is missing its closing "}".');
+    i++;
+    ws();
+    if (i !== raw.length)
+        return fail('Unexpected text after the args object literal.');
+    return values;
+}
+function parsePreview(block, diagnostics) {
+    checkAttrs('[preview]', block.attrs, SUB_BLOCK_ATTR_RULES.preview, block.openerSpan, diagnostics);
+    let componentName = null;
+    const component = block.attrs.component;
+    if (component && component.kind === 'expression') {
+        const name = component.raw.trim();
+        if (IDENTIFIER_RE.test(name)) {
+            componentName = name;
+        }
+        else {
+            diagnostics.push({
+                code: 'component-identifier',
+                message: 'component must be a component identifier imported in the file\'s <script>, like component={Button}.',
+                span: component.valueSpan,
+            });
+        }
+    }
+    let args = null;
+    let argsRaw = null;
+    const argsAttr = block.attrs.args;
+    if (argsAttr && argsAttr.kind === 'expression') {
+        argsRaw = argsAttr.raw.trim();
+        args = parseArgsLiteral(argsAttr.raw, argsAttr.valueSpan, diagnostics);
+    }
+    const title = stringAttr(block.attrs, 'title');
+    return {
+        componentName,
+        args,
+        argsRaw,
+        title,
+        label: title ?? componentName ?? 'Preview',
+        body: normalizeBody(block.body),
+        bodySpan: block.bodySpan,
+        span: block.span,
+    };
+}
+function parseDocs(entity, diagnostics) {
+    checkAttrs('[DOCS]', entity.attrs, ENTITY_ATTR_RULES.DOCS, entity.openerSpan, diagnostics);
+    const previews = [];
+    const examples = [];
+    const exampleTitles = new Set();
+    const previewLabels = new Set();
+    for (const block of entity.blocks) {
+        if (block.kind === 'preview') {
+            const preview = parsePreview(block, diagnostics);
+            if (previewLabels.has(preview.label)) {
+                diagnostics.push({
+                    code: 'duplicate-preview-label',
+                    message: `Two previews are both labeled "${preview.label}" — give one a title="…".`,
+                    span: block.openerSpan,
+                });
+            }
+            previewLabels.add(preview.label);
+            previews.push(preview);
+        }
+        else {
+            checkAttrs('[example]', block.attrs, SUB_BLOCK_ATTR_RULES.example, block.openerSpan, diagnostics);
+            const title = stringAttr(block.attrs, 'title') ?? '';
+            if (title && exampleTitles.has(title)) {
+                diagnostics.push({
+                    code: 'duplicate-example-title',
+                    message: `Duplicate example title "${title}" — titles are unique within a [DOCS] block.`,
+                    span: block.openerSpan,
+                });
+            }
+            exampleTitles.add(title);
+            examples.push({
+                title,
+                body: normalizeBody(block.body),
+                bodySpan: block.bodySpan,
+                span: block.span,
+            });
+        }
+    }
+    const title = stringAttr(entity.attrs, 'title') ?? '';
+    return {
+        kind: 'DOCS',
+        title,
+        slug: slugifyTitle(title),
+        description: stringAttr(entity.attrs, 'description'),
+        previews,
+        examples,
+        openerSpan: entity.openerSpan,
+        span: entity.span,
+    };
+}
+export function parseSdoc(source) {
+    const scanned = scanSdoc(source);
+    const diagnostics = [...scanned.errors];
+    const entities = [];
+    const slugs = new Set();
+    for (const entity of scanned.entities) {
+        let typed;
+        if (entity.kind === 'DOCS') {
+            typed = parseDocs(entity, diagnostics);
+        }
+        else {
+            checkAttrs(`[${entity.kind}]`, entity.attrs, ENTITY_ATTR_RULES[entity.kind], entity.openerSpan, diagnostics);
+            const title = stringAttr(entity.attrs, 'title') ?? '';
+            const base = {
+                title,
+                slug: slugifyTitle(title),
+                body: normalizeBody(entity.body),
+                bodySpan: entity.bodySpan,
+                openerSpan: entity.openerSpan,
+                span: entity.span,
+            };
+            typed =
+                entity.kind === 'PAGE'
+                    ? { kind: 'PAGE', ...base }
+                    : { kind: 'LAYOUT', padding: stringAttr(entity.attrs, 'padding'), ...base };
+        }
+        if (slugs.has(typed.slug)) {
+            diagnostics.push({
+                code: 'duplicate-entity-title',
+                message: `Two entities in this file resolve to the same address ("${typed.slug}") — make their titles distinct.`,
+                span: typed.openerSpan,
+            });
+        }
+        slugs.add(typed.slug);
+        entities.push(typed);
+    }
+    return {
+        script: scanned.script,
+        style: scanned.style,
+        entities,
+        diagnostics,
+        source,
+    };
+}

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

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

package/dist/language/parser.test.js

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+import { parseSdoc, parseArgsLiteral, slugifyTitle, normalizeBody, } from './parser.js';
+function diagnosticCodes(source) {
+    return parseSdoc(source).diagnostics.map((d) => d.code);
+}
+describe('parseSdoc typed entities', () => {
+    const source = `<script>
+	import Tabs from './Tabs.svelte';
+	import Tab from './Tab.svelte';
+</script>
+
+[DOCS title="Navigation / Tabs" description="A tab bar."]
+
+	[preview component={Tabs} args={{ active: 0 }}]
+		<Tabs {...args}><Tab label="One">…</Tab></Tabs>
+	[/preview]
+
+	[preview component={Tab} args={{ label: 'One' }}]
+		<Tabs><Tab {...args}>…</Tab></Tabs>
+	[/preview]
+
+	[example title="Vertical"]
+		<Tabs vertical />
+	[/example]
+
+[/DOCS]
+`;
+    const doc = parseSdoc(source);
+    const docs = doc.entities[0];
+    it('parses without diagnostics', () => {
+        expect(doc.diagnostics).toEqual([]);
+    });
+    it('types the DOCS entity', () => {
+        expect(docs.kind).toBe('DOCS');
+        expect(docs.title).toBe('Navigation / Tabs');
+        expect(docs.slug).toBe('navigation-tabs');
+        expect(docs.description).toBe('A tab bar.');
+    });
+    it('collects previews with component names, own args, and labels', () => {
+        expect(docs.previews).toHaveLength(2);
+        expect(docs.previews[0]).toMatchObject({
+            componentName: 'Tabs',
+            args: { active: 0 },
+            label: 'Tabs',
+        });
+        expect(docs.previews[1]).toMatchObject({
+            componentName: 'Tab',
+            args: { label: 'One' },
+            label: 'Tab',
+        });
+    });
+    it('collects examples', () => {
+        expect(docs.examples).toHaveLength(1);
+        expect(docs.examples[0].title).toBe('Vertical');
+        expect(docs.examples[0].body).toContain('<Tabs vertical />');
+    });
+    it('uses title= as the tab label override', () => {
+        const overridden = parseSdoc(`[DOCS title="X"]
+[preview component={Button} title="As a link" args={{ a: 1 }}]
+x
+[/preview]
+[preview component={Button}]
+x
+[/preview]
+[/DOCS]
+`);
+        const entity = overridden.entities[0];
+        expect(entity.previews.map((p) => p.label)).toEqual(['As a link', 'Button']);
+        expect(overridden.diagnostics).toEqual([]);
+    });
+});
+describe('parseSdoc validation', () => {
+    it('requires entity titles', () => {
+        expect(diagnosticCodes('[DOCS]\n[/DOCS]\n')).toContain('missing-attr');
+        expect(diagnosticCodes('[PAGE]\nx\n[/PAGE]\n')).toContain('missing-attr');
+    });
+    it('requires component on previews and title on examples', () => {
+        expect(diagnosticCodes('[DOCS title="X"]\n[preview]\nx\n[/preview]\n[/DOCS]\n')).toContain('missing-attr');
+        expect(diagnosticCodes('[DOCS title="X"]\n[example]\nx\n[/example]\n[/DOCS]\n')).toContain('missing-attr');
+    });
+    it('rejects unknown attributes', () => {
+        expect(diagnosticCodes('[DOCS title="X" component={B}]\n[/DOCS]\n')).toContain('unknown-attr');
+        expect(diagnosticCodes('[PAGE title="X" padding="4px"]\nx\n[/PAGE]\n')).toContain('unknown-attr');
+    });
+    it('rejects wrong attribute value kinds', () => {
+        expect(diagnosticCodes('[DOCS title={x}]\n[/DOCS]\n')).toContain('attr-value-kind');
+        expect(diagnosticCodes('[DOCS title="X"]\n[preview component="Button"]\nx\n[/preview]\n[/DOCS]\n')).toContain('attr-value-kind');
+    });
+    it('rejects non-identifier component expressions', () => {
+        expect(diagnosticCodes('[DOCS title="X"]\n[preview component={Tabs.Tab}]\nx\n[/preview]\n[/DOCS]\n')).toContain('component-identifier');
+    });
+    it('rejects duplicate example titles and preview labels', () => {
+        expect(diagnosticCodes('[DOCS title="X"]\n[example title="A"]\nx\n[/example]\n[example title="A"]\ny\n[/example]\n[/DOCS]\n')).toContain('duplicate-example-title');
+        expect(diagnosticCodes('[DOCS title="X"]\n[preview component={B}]\nx\n[/preview]\n[preview component={B}]\ny\n[/preview]\n[/DOCS]\n')).toContain('duplicate-preview-label');
+    });
+    it('rejects colliding entity addresses in one file', () => {
+        expect(diagnosticCodes('[PAGE title="A B"]\nx\n[/PAGE]\n[PAGE title="A / B"]\ny\n[/PAGE]\n')).toContain('duplicate-entity-title');
+    });
+    it('accepts LAYOUT presentation attributes', () => {
+        const doc = parseSdoc('[LAYOUT title="Login" padding="48px"]\n<div />\n[/LAYOUT]\n');
+        expect(doc.diagnostics).toEqual([]);
+        expect(doc.entities[0]).toMatchObject({ kind: 'LAYOUT', padding: '48px' });
+    });
+});
+describe('parseArgsLiteral', () => {
+    function parse(raw) {
+        const diagnostics = [];
+        const values = parseArgsLiteral(raw, { start: 0, end: raw.length }, diagnostics);
+        return { values, messages: diagnostics.map((d) => d.message) };
+    }
+    it('parses flat literals of all three types', () => {
+        expect(parse(`{ label: 'Hi', size: 14, wide: true, off: false, neg: -0.5 }`).values).toEqual({
+            label: 'Hi',
+            size: 14,
+            wide: true,
+            off: false,
+            neg: -0.5,
+        });
+    });
+    it('parses empty objects, quoted keys, and escaped strings', () => {
+        expect(parse('{}').values).toEqual({});
+        expect(parse(`{ "data-x": 'a', b: "it\\'s" }`).values).toEqual({ 'data-x': 'a', b: "it's" });
+    });
+    it('rejects nested values and identifiers with a pointer to the body', () => {
+        expect(parse(`{ items: [1, 2] }`).values).toBeNull();
+        expect(parse(`{ obj: { a: 1 } }`).values).toBeNull();
+        const { values, messages } = parse(`{ icon: MyIcon }`);
+        expect(values).toBeNull();
+        expect(messages[0]).toContain('plain literal');
+    });
+    it('rejects malformed objects', () => {
+        expect(parse(`plain`).values).toBeNull();
+        expect(parse(`{ a: 1 b: 2 }`).values).toBeNull();
+        expect(parse(`{ a: 1 } extra`).values).toBeNull();
+    });
+});
+describe('normalizeBody', () => {
+    it('strips the common indentation but keeps relative indent', () => {
+        expect(normalizeBody('\n\t\t<div>\n\t\t\t<b>x</b>\n\t\t</div>\n')).toBe('<div>\n\t<b>x</b>\n</div>');
+    });
+    it('ignores blank lines when computing the indent and blanks them out', () => {
+        expect(normalizeBody('\t\ta\n\n\t\tb\n')).toBe('a\n\nb');
+    });
+    it('unescapes body lines that start with \\[', () => {
+        expect(normalizeBody('\t\\[example title="x"]\n\ttext\n')).toBe('[example title="x"]\ntext');
+    });
+    it('dedents PAGE bodies so markdown does not become code blocks', () => {
+        const doc = parseSdoc('[PAGE title="X"]\n\t## Heading\n\n\ttext\n[/PAGE]\n');
+        expect(doc.entities[0].body).toBe('## Heading\n\ntext');
+    });
+});
+describe('slugifyTitle', () => {
+    it('slugifies title paths', () => {
+        expect(slugifyTitle('Forms / Button')).toBe('forms-button');
+        expect(slugifyTitle('  Weird -- Title!! ')).toBe('weird-title');
+        expect(slugifyTitle('')).toBe('untitled');
+    });
+});

package/dist/language/scanner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 interface Span {
+    start: number;
+    end: number;
+}
+export type EntityKind = 'DOCS' | 'PAGE' | 'LAYOUT';
+export type SubBlockKind = 'preview' | 'example';
+export declare const ENTITY_KINDS: readonly EntityKind[];
+export declare const SUB_BLOCK_KINDS: readonly SubBlockKind[];
+export interface AttrValue {
+    /** 'string' for name="text", 'expression' for name={expr}, 'bare' for a lone name */
+    kind: 'string' | 'expression' | 'bare';
+    /** Exact source between the quotes/braces ('' for bare attributes) */
+    raw: string;
+    /** Span of the whole attribute (name through closing quote/brace) */
+    span: Span;
+    /** Span of `raw` inside the source */
+    valueSpan: Span;
+}
+export type Attrs = Record<string, AttrValue>;
+export interface SubBlock {
+    kind: SubBlockKind;
+    attrs: Attrs;
+    /** Raw body between the opener line and the closer line */
+    body: string;
+    bodySpan: Span;
+    openerSpan: Span;
+    span: Span;
+}
+export interface Entity {
+    kind: EntityKind;
+    attrs: Attrs;
+    /** DOCS: sub-blocks. PAGE/LAYOUT: always empty. */
+    blocks: SubBlock[];
+    /** PAGE/LAYOUT: the raw body. DOCS: '' (body text between blocks is an error). */
+    body: string;
+    bodySpan: Span;
+    openerSpan: Span;
+    span: Span;
+}
+/** A top-level <script> or <style> tag block. */
+export interface TagBlock {
+    /** Raw text between the tag name and '>', e.g. ' lang="ts"' */
+    attrsText: string;
+    content: string;
+    contentSpan: Span;
+    span: Span;
+}
+export interface ScanError {
+    code: string;
+    message: string;
+    span: Span;
+}
+export interface SdocFile {
+    script: TagBlock | null;
+    style: TagBlock | null;
+    entities: Entity[];
+    errors: ScanError[];
+    source: string;
+}
+export declare function scanSdoc(source: string): SdocFile;
+/** Convert an offset to a 0-based line/column pair (for editors/CLI output). */
+export declare function offsetToPosition(source: string, offset: number): {
+    line: number;
+    column: number;
+};