[Blueprints] Reject malformed v2 declarations before runtime setup

[adamziel]

Blueprint v2 was being type-cast, not validated.

That meant { "pluginz": [...] } quietly did nothing, { "plugins": "akismet" } leaked an entries is not a function exception, and malformed version constraints could fall through into runtime setup. A typo is not a supported feature.

This adds a generated v2 validator and runs it at the v2 support boundary, before PHP or WordPress versions are resolved and before an execution plan is built. Validation failures use the existing InvalidBlueprintError and carry concise JSON Pointer diagnostics, so callers get /plugins/0/source instead of a pile of errors from every union branch.

The generator needs ts-json-schema-generator 2.4 because 1.2 cannot parse v2's bigint template literals. The old generator stays pinned for v1, and the public v1 schema and validator remain byte-for-byte unchanged. The v2 schema patching covers the constraints TypeScript cannot carry into JSON Schema, including WHATWG HTTP URLs, execution-context paths, version expressions, record keys, and tagged unions.

The validator is a v2-only dynamic chunk: about 59 KB gzip in the production ESM build. It is not fetched on v1 or ordinary Playground loads. Invalid declarations also fail before the WordPress release catalog is consulted.

One schema correction is included because the runtime already supports it: posts.source arrays may mix file references and inline post objects. The old type forced existing runtime coverage to use an as any cast.

onBlueprintValidated now fires once at the actual schema-success boundary, before runtime resolution, and is not forwarded to the lowered v1 runner.

Behavior change: malformed v2 declarations that were previously ignored or failed later now stop immediately with InvalidBlueprintError.

Tests cover raw JSON, bundles, exact error paths, ambiguous data-reference unions, URL handling, path traversal, callback ordering, release-fetch avoidance, schema regeneration, the full Blueprints suite, lint, typecheck, and the production package build.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds strict schema validation for Blueprint v2 declarations at the v2 boundary so malformed inputs fail early with structured InvalidBlueprintErrors (JSON Pointer diagnostics), before any runtime resolution work happens.

Changes:

• Introduces a generated Blueprint v2 AJV validator with error “de-noising” and pointer normalization helpers.
• Moves v2 validation to the runtime configuration boundary and threads an onBlueprintValidated callback to fire exactly once on schema success.
• Updates schema/type support for mixed posts.source arrays and adds/updates tests to assert early failure behavior and exact error paths.

Reviewed changes

Copilot reviewed 11 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/playground/blueprints/src/lib/v2/validate-blueprint-v2.ts	Adds v2 AJV validator + actionable error selection/normalization + assertValid... helper.
packages/playground/blueprints/src/lib/v2/resolve-runtime-configuration.ts	Dynamically imports v2 validation and runs it before resolving runtime sources; triggers validation callback.
packages/playground/blueprints/src/lib/v2/compile.ts	Routes v2 compilation through the new v2 runtime resolver and threads onBlueprintValidated.
packages/playground/blueprints/src/lib/invalid-blueprint-error.ts	Centralizes InvalidBlueprintError for reuse across v1/v2.
packages/playground/blueprints/src/lib/v1/compile.ts	Re-exports shared InvalidBlueprintError to keep v1 behavior consistent.
packages/playground/blueprints/src/lib/v2/wep-1-blueprint-v2-schema/appendix-A-blueprint-v2-schema.ts	Adjusts posts.source typing to allow mixed inline posts + file refs.
packages/playground/blueprints/src/tests/v2/validate-blueprint-v2.spec.ts	Adds comprehensive v2 schema validation tests covering exact paths/messages.
packages/playground/blueprints/src/tests/v2/resolve-runtime-configuration.spec.ts	Ensures malformed v2 declarations fail before WordPress release resolution starts.
packages/playground/blueprints/src/tests/compile.spec.ts	Updates compilation tests for early v2 validation and callback ordering.
package.json	Adds aliased ts-json-schema-generator v2 for schema generation tooling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.