@ggts-sh/spec 0.43.0

package/dist/validate.js

@@ -0,0 +1,178 @@
+/**
+ * Spec validation orchestrator — tier 1 (schema shape) plus opt-in tier 2
+ * (structural grammar, data-aware checks, optional lint).
+ *
+ * Tier-1 mechanism (decision 0004): TypeBox 1.x compiled checks plus
+ * `Value.Errors` over the same schemas that emit `schema/v0.json` — one
+ * artifact, no drift.
+ * Layer/plot shape walks: validate-schema-shape.ts (shared GEOM_BRANCHES;
+ * also hands per-layer branch-ok indices to the tier-2 structural gate).
+ * Raw TypeBox union noise is mapped to the agent error contract in
+ * validate-map-errors.ts (schema walk: validate-schema-walk.ts; channel/data
+ * form classification: validate-map-forms.ts).
+ * Data-free grammar rules live in validate-structure*.ts (layers / color
+ * schemes / facet form). Data-aware checks live in validate-data*.ts
+ * (evidence + checks modules, barrel at validate-data.ts).
+ *
+ * Output: `{ ok: true, spec }` or `{ ok: false, errors: SpecError[] }` with
+ * the agent error contract from errors.ts. Messages are snapshot-tested.
+ */
+import { Settings } from "typebox/system";
+// Precompiled at build time (scripts/gen-plot-validator.ts) — compiling the
+// full plot union at runtime costs seconds; the generated module is pinned
+// against a runtime-compiled validator by plot-spec-validator-generated.test.
+import { Check as plotSpecSchemaCheck } from "./generated/plot-spec-validator.js";
+import { lintSpec } from "./lint.js";
+import { ensureTemporalPolyfill } from "./temporal-polyfill.js";
+import { dataChecks, DEFAULT_VALIDATE_LIMITS, jsonDepth, resolveLayerFieldEvidence, } from "./validate-data.js";
+import { collectSchemaShapeErrors, GEOM_BRANCHES } from "./validate-schema-shape.js";
+import { structuralGateErrors } from "./structural-gate.js";
+import { facetStructuralErrors, layerStructuralErrors } from "./validate-structure.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Validate a spec. Tier 1 (always): schema shape, no data needed. Tier 2
+ * (opt-in — pass an `options` argument, even `{}`): the grammar's structural
+ * rules (required channels per geom, bar/count y ban, rule forms) plus
+ * data-aware checks against the spec's inline data or the provided
+ * DataProfile, under documented input limits (DEFAULT_VALIDATE_LIMITS).
+ *
+ * On success, returns the input typed as PortableSpec (no copy is made).
+ */
+export function validate(input, options) {
+    // Agent validate path may inspect temporal columns / IANA zones — load the
+    // polyfill here so lean `@ggts-sh/core/render` graphs never need it.
+    ensureTemporalPolyfill();
+    const limits = { ...DEFAULT_VALIDATE_LIMITS, ...options?.limits };
+    // Depth guard first: pathological nesting must not reach the schema walker.
+    if (jsonDepth(input, limits.maxDepth) > limits.maxDepth) {
+        return {
+            ok: false,
+            errors: [
+                {
+                    code: "validation-limit",
+                    path: "",
+                    message: `The spec nests deeper than ${limits.maxDepth} levels (documented maxDepth limit); validation refused.`,
+                },
+            ],
+        };
+    }
+    const errors = [];
+    // TypeBox Settings are process-global. Align with tsconfig exactOptionalPropertyTypes
+    // and raise maxErrors so Value.Errors is not truncated at the default of 8.
+    const previousMaxErrors = Settings.Get().maxErrors;
+    const previousExactOptional = Settings.Get().exactOptionalPropertyTypes;
+    Settings.Set({
+        maxErrors: Math.max(limits.maxDiagnostics, previousMaxErrors),
+        exactOptionalPropertyTypes: true,
+    });
+    try {
+        // TypeBox's interpreted Value.Check / Value.Errors walk the cyclic schema
+        // graph for every inline row. Use the compiled plot validator for the
+        // common valid path, and Value.Errors only when building invalid diagnostics.
+        const schemaValid = plotSpecSchemaCheck(input);
+        // Tier-2 structural gate: run layerStructuralErrors only on branch-valid
+        // layers. When the compiled plot check passed, LayerSpec's geom-discriminated
+        // union already proves every layer matches its GEOM_BRANCHES member — skip
+        // a second interpreted walk. When it failed, reuse the shape walk's per-layer
+        // Value.Errors emptiness set (#1279).
+        let branchOkLayers = "all";
+        if (!schemaValid) {
+            if (!isRecord(input)) {
+                return {
+                    ok: false,
+                    errors: [
+                        {
+                            code: "invalid-spec-root",
+                            path: "",
+                            message: `A plot spec must be a JSON object with a "layers" array (got ${Array.isArray(input) ? "an array" : typeof input}).`,
+                            fix: {
+                                description: "Provide an object with at least one layer.",
+                                example: {
+                                    layers: [{ geom: "point", aes: { x: { field: "x" }, y: { field: "y" } } }],
+                                },
+                            },
+                        },
+                    ],
+                };
+            }
+            const shape = collectSchemaShapeErrors(input);
+            errors.push(...shape.errors);
+            branchOkLayers = shape.branchOkLayerIndices;
+        }
+        // TypeBox-free structural gates (shared with pipeline render path).
+        if (schemaValid) {
+            errors.push(...structuralGateErrors(input));
+        }
+        // --- tier 2 (opt-in via options): structural grammar checks ----------------
+        // Required channels, the bar/count y ban, and the rule form rules are part
+        // of the tier-2 contract (the pipeline enforces them at render time with
+        // equivalent structured errors); tier 1 stays schema-shape-only so partial
+        // specs remain composable.
+        // Eligibility: record layers with a known geom whose branch is valid
+        // (see branchOkLayers above). Uses shared GEOM_BRANCHES for known-geom keys.
+        // --- tier 2 (opt-in): facet form rules --------------------------------------
+        // Runs for any record-valued facet, even when the facet is schema-invalid.
+        errors.push(...collectLayerGrammarErrors(input, options, branchOkLayers), ...collectFacetGrammarErrors(input, options));
+        // --- tier 2 (opt-in): data-aware checks + optional lint --------------------
+        // One resolveLayerFieldEvidence pass for plot + layer tables; dataChecks and
+        // lintSpec share it. On limit/profile errors, lint gets no shared map so it
+        // does not re-scan data that data-aware validation already refused.
+        const advisories = collectDataValidation(input, options, limits, errors);
+        const withAdvisories = advisories !== undefined && advisories.length > 0 ? { advisories } : {};
+        if (errors.length > limits.maxDiagnostics) {
+            const kept = errors.slice(0, limits.maxDiagnostics);
+            kept.push({
+                code: "validation-limit",
+                path: "",
+                message: `Diagnostics truncated: ${errors.length} problems found, showing the first ${limits.maxDiagnostics} (documented maxDiagnostics limit).`,
+            });
+            return { ok: false, errors: kept, ...withAdvisories };
+        }
+        if (errors.length > 0)
+            return { ok: false, errors, ...withAdvisories };
+        return { ok: true, spec: input, ...withAdvisories };
+    }
+    finally {
+        Settings.Set({
+            maxErrors: previousMaxErrors,
+            exactOptionalPropertyTypes: previousExactOptional,
+        });
+    }
+}
+function collectLayerGrammarErrors(input, options, branchOkLayers) {
+    if (options === undefined || !isRecord(input) || !Array.isArray(input["layers"]))
+        return [];
+    const errors = [];
+    const plotAes = isRecord(input["aes"]) ? input["aes"] : undefined;
+    const layers = input["layers"];
+    for (let index = 0; index < layers.length; index++) {
+        const layer = layers[index];
+        if (!isRecord(layer))
+            continue;
+        const geom = layer["geom"];
+        if (typeof geom !== "string" || !Object.hasOwn(GEOM_BRANCHES, geom))
+            continue;
+        if (branchOkLayers !== "all" && !branchOkLayers.has(index))
+            continue;
+        errors.push(...layerStructuralErrors(layer, geom, index, plotAes));
+    }
+    return errors;
+}
+function collectFacetGrammarErrors(input, options) {
+    if (options === undefined || !isRecord(input) || !isRecord(input["facet"]))
+        return [];
+    return facetStructuralErrors(input["facet"]);
+}
+function collectDataValidation(input, options, limits, errors) {
+    if (options === undefined || !isRecord(input))
+        return undefined;
+    const layerResolved = resolveLayerFieldEvidence(input, options, limits);
+    errors.push(...dataChecks(input, options, limits, layerResolved));
+    if (options.lint !== true)
+        return undefined;
+    const shared = layerResolved.status === "ok" ? layerResolved.plot : null;
+    return lintSpec(input, options, shared);
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

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

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ggts-sh/spec",
+  "version": "0.43.0",
+  "description": "ggts plot spec: TypeBox schemas, PortableSpec types, normalize(), validate() with agent errors, fluent builder, JSON Schema artifact.",
+  "keywords": [
+    "agents",
+    "charts",
+    "dataviz",
+    "ggplot2",
+    "grammar-of-graphics",
+    "json-schema",
+    "plot",
+    "spec",
+    "validation",
+    "visualization"
+  ],
+  "homepage": "https://ggts.sh/",
+  "bugs": "https://github.com/ggts-sh/ggts/issues",
+  "license": "MIT",
+  "author": "Liam O'Dea",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ggts-sh/ggts.git",
+    "directory": "packages/spec"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./portable": {
+      "types": "./dist/portable-entry.d.ts",
+      "default": "./dist/portable-entry.js"
+    },
+    "./schema/v0.json": "./schema/v0.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1",
+    "typebox": "^1.3.8"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}