@blueprint-chart/mcp 0.1.1 → 0.1.4

package/dist/dsl/parseErrorHints.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Translates raw PEG parser messages from @blueprint-chart/lib into plain,
+ * actionable guidance. The raw token-class messages (e.g.
+ * `Expected "\t" or [^\t\n\r{}=] but "\n" found`) were the worst-rated error
+ * in the authoring usability test — newcomers averaged 6.3 attempts-to-valid,
+ * largely stuck on data syntax. Unknown messages pass through unchanged.
+ */
+export interface HumanizedError {
+    message: string;
+    suggestion?: string;
+}
+export declare function humanizeParseError(raw: string): HumanizedError;

package/dist/dsl/parseErrorHints.js

@@ -0,0 +1,32 @@
+const RULES = [
+    {
+        // The PEG message contains the literal two-char sequence backslash-t (e.g.
+        // `Expected "\t" or [^\t\n\r{}=] ...`); \\t in this literal matches that
+        // backslash-t, not an actual tab.
+        match: /Expected .*\\t.* but .* found/,
+        message: 'A data row must be written as `"Label" = value` (a quoted label, `=`, then the value). Multiple values per row are comma-separated.',
+        suggestion: 'Single series: `"Asia" = 59.4`. Multi-series: add `_series = "Gold","Silver"` then `"USA" = 40,44`.',
+    },
+    {
+        match: /Expected whitespace but ":" found/,
+        message: 'The chart declaration uses a block, not a colon. Write `chart <type> { … }`.',
+        suggestion: 'chart donut {\n  data { "A" = 1 }\n}',
+    },
+    {
+        match: /Expected (?:"chart"|end of input)[^"]*but "d" found/,
+        message: 'The `data { … }` block must be nested inside the chart block, not at the top level.',
+        suggestion: 'chart bar-vertical {\n  data { "A" = 1 }\n}',
+    },
+    {
+        match: /Expected "=" .* but ":" found/,
+        message: 'Properties use `=`, not `:`. Write `title = "…"`.',
+    },
+];
+export function humanizeParseError(raw) {
+    for (const rule of RULES) {
+        if (rule.match.test(raw)) {
+            return { message: rule.message, suggestion: rule.suggestion };
+        }
+    }
+    return { message: raw };
+}

package/dist/dsl/parseErrorHints.test.d.ts

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

package/dist/dsl/parseErrorHints.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { humanizeParseError } from './parseErrorHints';
+describe('humanizeParseError', () => {
+    // Real lib message (with trailing period): 'Expected "\t" or [^\t\n\r{}=] but "\n" found.'
+    it('explains the tab/delimiter error for data rows', () => {
+        const h = humanizeParseError('Expected "\\t" or [^\\t\\n\\r{}=] but "\\n" found.');
+        expect(h.message).toMatch(/data row/i);
+        expect(h.suggestion).toMatch(/_series|comma/i);
+    });
+    // Real lib message (with trailing period): 'Expected whitespace but ":" found.'
+    it('explains a YAML-style chart declaration', () => {
+        const h = humanizeParseError('Expected whitespace but ":" found.');
+        expect(h.message).toMatch(/chart <type> \{/i);
+    });
+    // Real lib message: 'Expected "chart" or optional whitespace but "d" found.'
+    // (data block written at the top level, not inside a chart block)
+    it('explains data at the top level', () => {
+        const h = humanizeParseError('Expected "chart" or optional whitespace but "d" found.');
+        expect(h.message).toMatch(/inside the chart block/i);
+    });
+    it('passes unknown messages through unchanged', () => {
+        const h = humanizeParseError('something totally different');
+        expect(h.message).toBe('something totally different');
+        expect(h.suggestion).toBeUndefined();
+    });
+});

package/dist/dsl/semanticWarnings.d.ts

@@ -0,0 +1,7 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+import type { ValidationIssue } from './validate';
+/** Like ValidationIssue but with a widened string `code` for the new W_* advisory codes. */
+export type WarningIssue = Omit<ValidationIssue, 'code'> & {
+    code: string;
+};
+export declare function collectWarnings(ast: ChartNode): WarningIssue[];

package/dist/dsl/semanticWarnings.js

@@ -0,0 +1,66 @@
+import { canonicalChartType } from './chartTypes';
+import { lookupCapability, statusOf } from './capabilityMatrix';
+// Chart types that REQUIRE multiple series to be meaningful.
+const MULTI_SERIES_TYPES = new Set([
+    'bar-multi',
+    'bar-grouped',
+    'bar-stacked',
+    'bar-split',
+    'column-stacked',
+    'line-multi',
+    'area-stacked',
+]);
+function checkKey(type, key, path) {
+    const cell = lookupCapability(type, key);
+    const status = statusOf(cell);
+    if (status === 'inapplicable') {
+        return {
+            code: 'W_NO_EFFECT',
+            path,
+            message: `"${key}" has no effect on a ${type} chart.${cell.note ? ' ' + cell.note : ''}`,
+        };
+    }
+    if (status === 'not-implemented') {
+        return {
+            code: 'W_NOT_IMPLEMENTED',
+            path,
+            message: `"${key}" is not yet honored by the ${type} renderer.${cell.note ? ' ' + cell.note : ''}`,
+        };
+    }
+    return undefined;
+}
+export function collectWarnings(ast) {
+    const issues = [];
+    const type = canonicalChartType(ast.chartType) ?? ast.chartType;
+    for (const prop of ast.properties ?? []) {
+        const issue = checkKey(type, prop.key, `chart.${prop.key}`);
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if ((ast.colorizes ?? []).some(c => c.fromHighlight !== true)) {
+        const issue = checkKey(type, 'colorize', 'chart.colorize');
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if ((ast.highlights?.length ?? 0) > 0 || (ast.colorizes ?? []).some(c => c.fromHighlight === true)) {
+        const issue = checkKey(type, 'highlight', 'chart.highlight');
+        if (issue) {
+            issues.push(issue);
+        }
+    }
+    if (MULTI_SERIES_TYPES.has(type)) {
+        const entries = ast.data?.entries ?? [];
+        const hasSeriesHeader = entries.some(e => e.key === '_series');
+        const hasMultiValueRow = entries.some(e => (e.values?.length ?? 0) > 1);
+        if (!hasSeriesHeader && !hasMultiValueRow && entries.length > 0) {
+            issues.push({
+                code: 'W_MULTISERIES_SHAPE',
+                path: 'data',
+                message: `A ${type} chart needs multiple series, but the data parsed as single-value rows with no \`_series\` header. Add a \`_series = "A","B",…\` row and comma-separated values per row (e.g. \`"USA" = 40,44,42\`).`,
+            });
+        }
+    }
+    return issues;
+}

package/dist/dsl/semanticWarnings.test.d.ts

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

package/dist/dsl/semanticWarnings.test.js

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { parseDsl } from '../parse';
+import { collectWarnings } from './semanticWarnings';
+function warn(src) {
+    const r = parseDsl(src);
+    if (!r.ok) {
+        throw new Error('parse failed: ' + JSON.stringify(r.errors));
+    }
+    return collectWarnings(r.data.ast);
+}
+describe('collectWarnings', () => {
+    it('warns W_NO_EFFECT for sort on donut', () => {
+        const w = warn('chart donut {\n  sort = descending\n  data {\n    "A" = 1\n    "B" = 2\n  }\n}');
+        expect(w.some(i => i.code === 'W_NO_EFFECT' && i.path === 'chart.sort')).toBe(true);
+    });
+    it('does not warn for colorize on donut (now supported since W1c)', () => {
+        const w = warn('chart donut {\n  data { "A" = 1 }\n  colorize "A" { color = "#f00" }\n}');
+        expect(w.some(i => i.path.includes('colorize'))).toBe(false);
+    });
+    it('warns W_MULTISERIES_SHAPE when a multi-series type parsed zero series', () => {
+        const w = warn('chart bar-multi {\n  data {\n    "A" = 1\n    "B" = 2\n  }\n}');
+        expect(w.some(i => i.code === 'W_MULTISERIES_SHAPE')).toBe(true);
+    });
+    it('is silent for a well-formed multi-series chart', () => {
+        const w = warn('chart bar-multi {\n  data {\n    _series = "X","Y"\n    "A" = 1,2\n    "B" = 3,4\n  }\n}');
+        expect(w.filter(i => i.code === 'W_MULTISERIES_SHAPE')).toEqual([]);
+    });
+    it('is silent for a clean single-series bar chart', () => {
+        const w = warn('chart bar-vertical {\n  title = "t"\n  data { "A" = 1 }\n}');
+        expect(w).toEqual([]);
+    });
+});

package/dist/dsl/suggest.d.ts

@@ -0,0 +1 @@
+export declare function nearestSuggestion(input: string, candidates: readonly string[], maxDistance?: number): string | undefined;

package/dist/dsl/suggest.js

@@ -0,0 +1,66 @@
+function distance(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++) {
+        dp[i][0] = i;
+    }
+    for (let j = 0; j <= n; j++) {
+        dp[0][j] = j;
+    }
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const deletion = dp[i - 1][j] + 1;
+            const insertion = dp[i][j - 1] + 1;
+            const substitution = dp[i - 1][j - 1] + cost;
+            dp[i][j] = Math.min(deletion, insertion, substitution);
+        }
+    }
+    return dp[m][n];
+}
+const DEFAULT_MAX_DISTANCE = 10;
+/**
+ * Hand-curated synonyms for property keys authors commonly guess wrong but that
+ * are too edit-distant for the Levenshtein scan to catch. `subtitle` is the
+ * canonical example: authors reach for it constantly, but the real key is
+ * `description` (distance 7), so the distance scan wrongly suggests `title`.
+ */
+const SYNONYMS = {
+    subtitle: 'description',
+    subhead: 'description',
+    subheading: 'description',
+    author: 'byline',
+    credit: 'byline',
+    caption: 'note',
+    footnote: 'note',
+};
+export function nearestSuggestion(input, candidates, maxDistance = DEFAULT_MAX_DISTANCE) {
+    const synonym = SYNONYMS[input];
+    if (synonym && candidates.includes(synonym)) {
+        return synonym;
+    }
+    let best;
+    for (const cand of candidates) {
+        const d = distance(input, cand);
+        if (d > maxDistance) {
+            continue;
+        }
+        // Prefer candidates that start with the input (prefix match bonus)
+        const prefixBonus = cand.startsWith(input) ? -1000 : 0;
+        const score = d + prefixBonus;
+        if (!best || score < best.score || (score === best.score && cand < best.name)) {
+            best = { name: cand, dist: d, score };
+        }
+    }
+    return best?.name;
+}

package/dist/dsl/suggest.test.d.ts

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

package/dist/dsl/suggest.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { nearestSuggestion } from './suggest';
+describe('nearestSuggestion', () => {
+    it('returns the closest match within edit distance', () => {
+        expect(nearestSuggestion('bar', ['bar-vertical', 'bar-horizontal', 'line']))
+            .toBe('bar-vertical');
+    });
+    it('returns the alphabetically-first on tie', () => {
+        expect(nearestSuggestion('xx', ['ab', 'ba'])).toBe('ab');
+    });
+    it('returns undefined when no candidate is within max distance', () => {
+        expect(nearestSuggestion('zz', ['absolutely-unrelated'], 3)).toBeUndefined();
+    });
+    it('returns undefined when candidates is empty', () => {
+        expect(nearestSuggestion('any', [])).toBeUndefined();
+    });
+    it('handles exact match', () => {
+        expect(nearestSuggestion('line', ['line', 'pie'])).toBe('line');
+    });
+    it('suggests description for the common subtitle mistake', () => {
+        const keys = ['title', 'description', 'byline', 'source', 'sourceUrl', 'note'];
+        expect(nearestSuggestion('subtitle', keys)).toBe('description');
+    });
+    it('still does edit-distance matching for other typos', () => {
+        const keys = ['title', 'description', 'colorPalette'];
+        expect(nearestSuggestion('titel', keys)).toBe('title');
+    });
+    it('falls back to edit-distance when the synonym target is absent from candidates', () => {
+        const keys = ['title', 'byline', 'note']; // no 'description'
+        // subtitle's synonym (description) isn't a candidate, so the scan runs;
+        // nearest by distance among these is 'title'
+        expect(nearestSuggestion('subtitle', keys)).toBe('title');
+    });
+});

package/dist/dsl/universalProperties.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Metadata for a universal chart property (type, description, and optional
+ * choice list). Consumed by `describeChartType` to build the properties list.
+ */
+export interface UniversalPropertyMeta {
+    type: string;
+    description?: string;
+    choices?: string[];
+}
+/**
+ * Static metadata for universal properties that are consumed by astToDefinition
+ * directly rather than registered per chart type via getChartOptions. These
+ * appear in chart DSL across all chart types (e.g. sort, title, colors).
+ *
+ * This is the single source of truth for both the metadata and the membership
+ * of the universal-properties set. `UNIVERSAL_PROPERTIES` is derived from the
+ * keys of this object so the two cannot drift apart.
+ */
+export declare const UNIVERSAL_PROPERTY_META: Readonly<Record<string, UniversalPropertyMeta>>;
+/**
+ * Property keys recognized at the chart top level regardless of chart type.
+ *
+ * Derived from the keys of UNIVERSAL_PROPERTY_META to keep membership and
+ * metadata in lockstep. If a new universal property is added to the lib,
+ * add it to UNIVERSAL_PROPERTY_META above. The sample-roundtrip test (added
+ * in Task 6) catches drift: if a sample uses a key we don't know about, the
+ * validator will error on it and that test will fail.
+ */
+export declare const UNIVERSAL_PROPERTIES: ReadonlySet<string>;
+export declare function isUniversalProperty(key: string): boolean;

package/dist/dsl/universalProperties.js

@@ -0,0 +1,52 @@
+/**
+ * Static metadata for universal properties that are consumed by astToDefinition
+ * directly rather than registered per chart type via getChartOptions. These
+ * appear in chart DSL across all chart types (e.g. sort, title, colors).
+ *
+ * This is the single source of truth for both the metadata and the membership
+ * of the universal-properties set. `UNIVERSAL_PROPERTIES` is derived from the
+ * keys of this object so the two cannot drift apart.
+ */
+export const UNIVERSAL_PROPERTY_META = {
+    // Attribution metadata
+    title: { type: 'text', description: 'Chart title' },
+    description: { type: 'text', description: 'Chart description / subtitle' },
+    byline: { type: 'text', description: 'Byline / author credit' },
+    source: { type: 'text', description: 'Data source label' },
+    sourceUrl: { type: 'text', description: 'Data source URL' },
+    note: { type: 'text', description: 'Footer note' },
+    // Sort directives
+    sort: { type: 'select', description: 'Sort direction for categories', choices: ['ascending', 'descending', 'none'] },
+    sortMode: { type: 'select', description: 'Sort mode for grouped/stacked charts', choices: ['total', 'within-groups', 'none'] },
+    // Theme + palette (apply to every chart type)
+    theme: { type: 'text', description: 'Visual theme name' },
+    colorPalette: { type: 'text', description: 'Named color palette' },
+    colors: { type: 'colors', description: 'Custom color list' },
+    // Frame / layout
+    padding: { type: 'text', description: 'Frame padding (CSS shorthand)' },
+    background: { type: 'text', description: 'Background color' },
+    frameSizing: { type: 'select', description: 'Frame sizing mode', choices: ['auto', 'standard', 'aspect-ratio'] },
+    aspectRatio: { type: 'text', description: 'Aspect ratio (width / height)' },
+    // Value-label toggles (shared across bar/column variants but used universally
+    // in samples; per-type registry overrides when stricter)
+    valueLabels: { type: 'boolean', description: 'Show value labels on bars/segments' },
+    verticalLabelPosition: { type: 'select', description: 'Vertical axis label position', choices: ['auto', 'inside', 'outside', 'off'] },
+    horizontalLabelPosition: { type: 'select', description: 'Horizontal axis label position', choices: ['auto', 'inside', 'outside', 'off'] },
+    verticalGridStyle: { type: 'select', description: 'Vertical grid line style', choices: ['solid', 'dashed', 'dotted', 'none'] },
+    horizontalGridStyle: { type: 'select', description: 'Horizontal grid line style', choices: ['solid', 'dashed', 'dotted', 'none'] },
+    // TODO(lib): expose heightMode on area-stacked via getChartOptions
+    heightMode: { type: 'text', description: 'Height mode for stacked area charts' },
+};
+/**
+ * Property keys recognized at the chart top level regardless of chart type.
+ *
+ * Derived from the keys of UNIVERSAL_PROPERTY_META to keep membership and
+ * metadata in lockstep. If a new universal property is added to the lib,
+ * add it to UNIVERSAL_PROPERTY_META above. The sample-roundtrip test (added
+ * in Task 6) catches drift: if a sample uses a key we don't know about, the
+ * validator will error on it and that test will fail.
+ */
+export const UNIVERSAL_PROPERTIES = new Set(Object.keys(UNIVERSAL_PROPERTY_META));
+export function isUniversalProperty(key) {
+    return UNIVERSAL_PROPERTIES.has(key);
+}

package/dist/dsl/universalProperties.test.d.ts

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

package/dist/dsl/universalProperties.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { UNIVERSAL_PROPERTIES, UNIVERSAL_PROPERTY_META, isUniversalProperty } from './universalProperties';
+describe('universalProperties', () => {
+    it('includes attribution metadata', () => {
+        expect(UNIVERSAL_PROPERTIES.has('title')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('description')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('byline')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('source')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('sourceUrl')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('note')).toBe(true);
+    });
+    it('includes universal sort directives', () => {
+        expect(UNIVERSAL_PROPERTIES.has('sort')).toBe(true);
+        expect(UNIVERSAL_PROPERTIES.has('sortMode')).toBe(true);
+    });
+    it('isUniversalProperty matches', () => {
+        expect(isUniversalProperty('title')).toBe(true);
+        expect(isUniversalProperty('madeUpKey')).toBe(false);
+    });
+    it('UNIVERSAL_PROPERTY_META has schema entries matching the set', () => {
+        expect(UNIVERSAL_PROPERTY_META['title']?.type).toBe('text');
+        expect(UNIVERSAL_PROPERTY_META['sort']?.choices).toContain('ascending');
+        // Membership and metadata are in lockstep
+        expect(new Set(Object.keys(UNIVERSAL_PROPERTY_META))).toEqual(UNIVERSAL_PROPERTIES);
+    });
+});

package/dist/dsl/validate.d.ts

@@ -0,0 +1,10 @@
+import type { ChartNode } from '@blueprint-chart/lib';
+export type ValidationCode = 'E_UNKNOWN_CHART_TYPE' | 'E_UNKNOWN_PROPERTY' | 'E_INVALID_PROPERTY_VALUE' | 'E_DUPLICATE_BLOCK' | 'E_EMPTY_DATA' | 'E_UNKNOWN_DATA_KEY';
+export interface ValidationIssue {
+    code: ValidationCode;
+    path: string;
+    message: string;
+    suggestion?: string;
+    context?: Record<string, unknown>;
+}
+export declare function validateAst(ast: ChartNode): ValidationIssue[];

package/dist/dsl/validate.js

@@ -0,0 +1,68 @@
+import { getChartOptions } from '@blueprint-chart/lib';
+import { canonicalChartType, isKnownChartType, listCanonicalChartTypes } from './chartTypes';
+import { UNIVERSAL_PROPERTIES } from './universalProperties';
+import { nearestSuggestion } from './suggest';
+import { looksLikeUnquotedKey } from './dataKey';
+function chartLevelKnownKeys(chartType) {
+    const canonical = canonicalChartType(chartType) ?? chartType;
+    const perType = getChartOptions(canonical).map(o => o.key);
+    return [...UNIVERSAL_PROPERTIES, ...perType];
+}
+export function validateAst(ast) {
+    const issues = [];
+    const chartType = ast.chartType;
+    const chartTypeKnown = isKnownChartType(chartType);
+    if (!chartTypeKnown) {
+        const known = listCanonicalChartTypes();
+        issues.push({
+            code: 'E_UNKNOWN_CHART_TYPE',
+            path: 'chart',
+            message: `Unknown chart type "${chartType}". Known types: ${known.join(', ')}.`,
+            suggestion: nearestSuggestion(chartType, known),
+            context: { got: chartType, known },
+        });
+    }
+    // Chart-level property keys (only meaningful when the chart type is known)
+    if (chartTypeKnown) {
+        const known = chartLevelKnownKeys(chartType);
+        const knownSet = new Set(known);
+        for (const prop of ast.properties ?? []) {
+            if (!knownSet.has(prop.key)) {
+                issues.push({
+                    code: 'E_UNKNOWN_PROPERTY',
+                    path: `chart.${prop.key}`,
+                    message: `Unknown property "${prop.key}" on chart ${chartType}.`,
+                    suggestion: nearestSuggestion(prop.key, known),
+                    context: { got: prop.key, chartType },
+                });
+            }
+        }
+    }
+    // Data block
+    const dataEntries = ast.data?.entries ?? [];
+    if (dataEntries.length === 0) {
+        issues.push({
+            code: 'E_EMPTY_DATA',
+            path: 'data',
+            message: 'Chart has no data. Add a `data { … }` block with at least one entry.',
+        });
+    }
+    else {
+        for (const entry of dataEntries) {
+            // The `_series` pseudo-key is a multi-series header, not a row label.
+            if (entry.key === '_series') {
+                continue;
+            }
+            if (looksLikeUnquotedKey(entry)) {
+                issues.push({
+                    code: 'E_UNKNOWN_DATA_KEY',
+                    path: `data.${entry.key}`,
+                    message: `Data key "${entry.key}" looks like an identifier, but data rows expect quoted string labels (e.g. \`"${entry.key}" = …\`).`,
+                    context: { got: entry.key },
+                    suggestion: `"${entry.key}"`,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/dist/dsl/validate.test.d.ts

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

package/dist/dsl/validate.test.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { parse, samples } from '@blueprint-chart/lib';
+import { validateAst } from './validate';
+function ast(src) {
+    return parse(src);
+}
+describe('validateAst', () => {
+    it('returns empty issues for a known chart type with data', () => {
+        const a = ast('chart bar-vertical { data { "E" = 1 } }');
+        expect(validateAst(a)).toEqual([]);
+    });
+    it('reports E_UNKNOWN_CHART_TYPE with suggestion', () => {
+        const a = ast('chart bar { data { "E" = 1 } }');
+        const issues = validateAst(a);
+        expect(issues.length).toBeGreaterThanOrEqual(1);
+        const chartIssue = issues.find(i => i.code === 'E_UNKNOWN_CHART_TYPE');
+        expect(chartIssue).toBeDefined();
+        expect(chartIssue.path).toBe('chart');
+        expect(chartIssue.suggestion).toMatch(/^bar-/);
+        expect(chartIssue.context?.got).toBe('bar');
+        expect(Array.isArray(chartIssue.context?.known)).toBe(true);
+    });
+    it('reports E_EMPTY_DATA when data block is missing', () => {
+        const a = ast('chart bar-vertical { title = "x" }');
+        const issues = validateAst(a);
+        expect(issues.some(i => i.code === 'E_EMPTY_DATA')).toBe(true);
+    });
+    it('reports E_EMPTY_DATA when data block has zero entries', () => {
+        const a = ast('chart bar-vertical { data {} }');
+        const issues = validateAst(a);
+        expect(issues.some(i => i.code === 'E_EMPTY_DATA')).toBe(true);
+    });
+    it('does not double-report when chart type is unknown but data is fine', () => {
+        const a = ast('chart bar { data { "E" = 1 } }');
+        const issues = validateAst(a);
+        expect(issues.find(i => i.code === 'E_EMPTY_DATA')).toBeUndefined();
+    });
+});
+describe('validateAst — properties and data keys', () => {
+    it('reports E_UNKNOWN_PROPERTY for an unknown chart-level key', () => {
+        const a = ast('chart bar-vertical { totallyMadeUp = 1  data { "E" = 1 } }');
+        const issues = validateAst(a);
+        const unk = issues.find(i => i.code === 'E_UNKNOWN_PROPERTY');
+        expect(unk).toBeDefined();
+        expect(unk.context?.got).toBe('totallyMadeUp');
+    });
+    it('does not report a known per-chart-type property as unknown', () => {
+        const a = ast('chart bar-vertical { barGap = 0.2  data { "E" = 1 } }');
+        expect(validateAst(a).filter(i => i.code === 'E_UNKNOWN_PROPERTY')).toEqual([]);
+    });
+    it('does not report a known universal property as unknown', () => {
+        const a = ast('chart bar-vertical { title = "x"  data { "E" = 1 } }');
+        expect(validateAst(a).filter(i => i.code === 'E_UNKNOWN_PROPERTY')).toEqual([]);
+    });
+    it('suggests a near-miss universal property', () => {
+        const a = ast('chart bar-vertical { titl = "x"  data { "E" = 1 } }');
+        const issues = validateAst(a);
+        const unk = issues.find(i => i.code === 'E_UNKNOWN_PROPERTY');
+        expect(unk?.suggestion).toBe('title');
+    });
+    it('reports E_UNKNOWN_DATA_KEY for unquoted-identifier data keys when chart expects labels', () => {
+        const a = ast('chart bar-vertical { data { unquotedKey = 1 } }');
+        const issues = validateAst(a);
+        expect(issues.some(i => i.code === 'E_UNKNOWN_DATA_KEY')).toBe(true);
+    });
+    it('roundtrips every shipped sample with no errors', () => {
+        for (const sample of samples) {
+            const a = ast(sample.dsl);
+            const issues = validateAst(a);
+            expect(issues, `sample ${sample.id}: ${JSON.stringify(issues)}`).toEqual([]);
+        }
+    });
+});

package/dist/errors.d.ts

@@ -3,15 +3,32 @@ export declare const ErrorCode: {
     readonly E_PARSE: "E_PARSE";
     readonly E_SEMANTIC: "E_SEMANTIC";
     readonly E_RENDER: "E_RENDER";
+    readonly E_CONFIG: "E_CONFIG";
     readonly E_INTERNAL: "E_INTERNAL";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export interface ToolErrorEntry {
+    /**
+     * Item-level error code in `E_XXX` shape.
+     *
+     * Intentionally typed as `string` rather than the `ErrorCode` enum.
+     * Item-level codes are driven by the context that produced the error:
+     * - validation errors use `ValidationCode` values (e.g. `'E_UNKNOWN_PROPERTY'`)
+     * - render pre-flight uses `RenderDiagnosticCode` values (e.g. `'E_NO_DATA'`)
+     * - individual tools may define their own codes (e.g. `'E_UNKNOWN_SAMPLE'`)
+     *
+     * These codes differ from the top-level `ToolResult.code` field, which always
+     * uses the `ErrorCode` enum and categorises the failure class (parse, input,
+     * render, etc.). Item-level codes do not need to be enumerated here.
+     */
+    code?: string;
     path?: string;
     line?: number;
     column?: number;
     message: string;
     snippet?: string;
+    context?: Record<string, unknown>;
+    suggestion?: string;
 }
 export type ToolResult<T> = {
     ok: true;
@@ -22,7 +39,9 @@ export type ToolResult<T> = {
     errors: ToolErrorEntry[];
 };
 export declare function toolOk<T>(data: T): ToolResult<T>;
-export declare function toolError<T = never>(code: ErrorCode, errors: ToolErrorEntry[]): ToolResult<T>;
+export declare function toolError<T = never>(code: ErrorCode, errors: ToolErrorEntry[]): Extract<ToolResult<T>, {
+    ok: false;
+}>;
 export declare function isToolError<T>(r: ToolResult<T>): r is Extract<ToolResult<T>, {
     ok: false;
 }>;

package/dist/errors.js

@@ -3,6 +3,7 @@ export const ErrorCode = {
     E_PARSE: 'E_PARSE',
     E_SEMANTIC: 'E_SEMANTIC',
     E_RENDER: 'E_RENDER',
+    E_CONFIG: 'E_CONFIG',
     E_INTERNAL: 'E_INTERNAL',
 };
 export function toolOk(data) {

package/dist/errors.test.js

@@ -20,4 +20,25 @@ describe('errors', () => {
         const r = toolError(ErrorCode.E_INTERNAL, [{ message: 'x' }]);
         expect(isToolError(r)).toBe(true);
     });
+    it('includes E_CONFIG for missing server configuration', () => {
+        expect(ErrorCode.E_CONFIG).toBe('E_CONFIG');
+    });
+});
+describe('ToolErrorEntry structured fields', () => {
+    it('accepts code, context, and suggestion on a tool-error entry', () => {
+        const entry = {
+            code: 'E_UNKNOWN_CHART_TYPE',
+            path: 'chart',
+            message: 'Unknown chart type "bar"',
+            context: { got: 'bar', knownTypes: ['bar-vertical'] },
+            suggestion: 'bar-vertical',
+        };
+        const r = toolError(ErrorCode.E_SEMANTIC, [entry]);
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.errors[0].code).toBe('E_UNKNOWN_CHART_TYPE');
+            expect(r.errors[0].context).toEqual({ got: 'bar', knownTypes: ['bar-vertical'] });
+            expect(r.errors[0].suggestion).toBe('bar-vertical');
+        }
+    });
 });