feat(core): export chart validation from flint-chart

[Wei Tao (taoche)]

Closes #104

Summary

Moves the validate/assemble logic that lived only inside flint-chart-mcp (src/tools/validate.ts, src/render/assemble.ts) into the core package as a new flint-chart/validate subpath (also re-exported from the root flint-chart). Hosts that let an agent author ChartAssemblyInput outside MCP can now call validateChart(input, backend) and get the same per-problem feedback the validate_chart tool provides, instead of vendoring MCP sources.

import { validateChart } from 'flint-chart/validate';

const result = validateChart(input, 'vegalite');
// { backend, chartType, valid, warnings, errors, computedSize? }

Exported from flint-chart / flint-chart/validate

• validateChart(input, backend, options?) — never throws
• validateChartInput(input, backend?, options?) — shape checks, throws on first problem
• validateSemanticTypes(semantic_types) — labels not in the type registry; validateChart surfaces these as unknown_semantic_type warnings (not errors), so valid is unaffected
• assembleForBackend(backend, input, options?), stripPrivateKeys(spec)
• ValidationBackend (vegalite | echarts | chartjs | plotly), ValidateChartOptions (maxDataRows, maxCanvasDim), ValidateResult, AssembleResult

Also

• isRegistered / getRegisteredTypes exported from flint-chart/core
• flint-chart-mcp now consumes the core implementation; it only adds data.url resolution on top (render/assemble.ts shrinks to ~80 lines). Public MCP surface (validateInput, assembleForBackend, stripPrivateKeys, MAX_DATA_ROWS, MAX_CANVAS_DIM, validate_chart output) is unchanged.
• Docs: packages/flint-js/README.md, docs/api-reference.md (en + zh-CN), CHANGELOG [Unreleased]

Design notes

• Put it in src/validate/ rather than core/ because validation needs the backend assemblers and template registries, and core/ is intentionally backend-free.
• The core module requires inline data.values and stays pure JS (no fs). Local data.url reading remains an MCP concern.
• plotly is included as a validation backend since it has an assembler and template registry, even though MCP can't render it.

Test plan

• npm run typecheck (flint-js + flint-mcp)
• npm run lint — no new warnings
• npm run test:js — 1501 passed (incl. 17 new in tests/validate.test.ts)
• npm run test:mcp — 85 passed (existing validate_chart tests unchanged)

🤖 Generated with Claude Code

[Wei Tao (taoche)]

Validated this against the real host that motivated #104 (an LLM agent authoring ChartAssemblyInput behind a render_ui tool, no MCP in the loop).

Setup: npm pack from this branch → installed into the host → deleted its vendored copy of validate.ts / assemble.ts / a host-side semantic-types check (265 lines) → switched the one consumer to import { validateChart, validateSemanticTypes } from 'flint-chart/validate'.

Result: typecheck + lint clean, and all 17 of the host's FlintChart validation tests pass unchanged — unknown chart type, nonexistent field, unsupported channel, missing required channel, unregistered semantic_types, empty data, oversized canvas, values+url conflict, non-object rows, data.url resolution. The validateChart signature and assembly_failed / errors / warnings shape were a drop-in match for what the host had vendored.

One gap it surfaced (fixed in 300bf80): the vendored copy had pulled two checks out of resolveDataSource — rows must be objects and values/url are mutually exclusive — because a non-MCP host never goes through the data-source layer. My first cut only had them in MCP, so a standalone host passing values: [1, 2, 3] got a misleading field "x" does not exist (and [null] a TypeError). Both now live in validateChartInput, so MCP and standalone hosts enforce the same input contract.

Also worth noting for the semantic-types half of the issue: the host wants unregistered labels to be a hard error (an agent writing "quantitative" should be corrected, not silently degraded), while the library reasonably treats them as a warning. With validateSemanticTypes + getRegisteredTypes() exported, the host promotes them and hands the registry back to the agent in two lines — so the library doesn't need to pick a policy.

[Wei Tao (taoche)]

@microsoft-github-policy-service agree