JSON Schema transformer rewrite (#1726)

* feat(schema-generator): add modular JSON Schema generator + plugin; integrate with js-runtime transformer; add unit/integration tests

- New package packages/schema-generator: formatter chain (primitive/object/array/common-tools), robust generic handling, cycle detection, / policy, Date/any/unknown mapping, Default<T,V> default propagation, plugin surface
- Switch js-runtime transformer to use createSchemaTransformerV2
- Add js-runtime tests: Cell/Array comparison, integration, nested wrappers, opaque  decisions, fixture sanity
- Remove debug logs; improve type utils and fixture compatibility

Work-in-progress: finalize cycle / policy to match fixtures (only source-named defs; pure  between them).

* schema-generator: rewrite passes 20/20 schema fixtures; Stream<Cell<T>> flagging fixed; node-first inner generation; cleanup debug logging (CT-841)

* schema-generator: handler-schema intersections merged; union literal tweak; all fixture groups green (CT-841)

* tests: move opaque-ref-map fixture under schema-transform and align expected with OpaqueRef spread expansion

* fixes for last two broken tests

* plan for remaining refactor path

* improvments to test harness

* checkpoint on redoing fixtures approach to be more similar to the previous one and do full string comparison

* updates to js-runtime fixtures to make them work with --show-transformed; add a couple of new test fixtures in schema-generator

* remove unnecessary depth checking from cycle detection

* fixes to fixtures for default export expectations; fixes to schema-generator to get all fixtures back to green

* fix incorrect cycle detection issue on erased Default type

* remove some test logs

* fix lint/compile errors

* streamline exports and delete unuseful test file

* much cleanup and improvement to various formatters; one change/fix(?) to an old fixture

* refactor common tools formatter

* fix fixtures, or start to

* improve fixture runner to do semantic equality check and fix one more bug with cycle detection of Default types

* add date types fixture and fix test runner to import typescript lib types correctly

* remove completed plans, update overall plan

* refactor schema generator; also update many tests to account for new library loading pattern

* undo unnecessary changes to intersection formatter

* simplify some things in schema generator

* further simplifications

* doc explaining root ref promotion change to discuss

* remove debug script

* consolidate and simplify new tests

* format checks

* format md files

* one more deno fmt fix

* finally delete lots of old stuff

* satisfy linter

* remove old fixtures that are superseded by new ones; rename fixtures to use dashes instead of underscores

* simplifications, comment on  strategy

* some cleanups

* small refactor and a couple new tests

* fix and move failing fixtures out of js-runtime

* remove unnecessary definitions ordering

* change oneOf to anyOf throughout; fmt correctly

* comment for explaining behavior

* use mutable version of core commontools jsonschema interface instead of making a separate schemadefinition one. extend commontools' jsonschema to have  and  properties

* stop incorrectly entirely rejecting intersection types w call/construct signatures

* better handling for various fallback cases; changed to thrown errors in many cases and added better  in others

* properly handle arrays of any and never types

* attempt to update runner in light of json schema type changes

* fix tests for new behaviors

* fix formatting

* re-compile commontools api after jsonschema changes

* various simplifications and fixes for the common tools formatter and default type handling; not yet finished

* finish simplifying common tools formatter

* update complex defaults test in light of anyOf decisions

* address robin's code review comments

* fixes for robin's improvements to jsonschema to support booleans; typechecking works now

* deno fmt

Author: mathpirate

deno.json

@@ -11,6 +11,7 @@
     "./packages/iframe-sandbox",
     "./packages/integration",
     "./packages/js-runtime",
+    "./packages/schema-generator",
     "./packages/llm",
     "./packages/memory",
     "./packages/patterns",
@@ -85,6 +86,7 @@
       "packages/seeder/templates/",
       "packages/static/assets/",
       "packages/js-runtime/test/fixtures",
+      "packages/schema-generator/test/fixtures",
       "packages/vendor-astral"
     ]
   },

deno.lock

@@ -214,6 +214,8 @@ export type JSONSchemaObj = {
   readonly readOnly?: boolean;
   readonly writeOnly?: boolean;
   readonly examples?: readonly Readonly<JSONValue>[];
+  readonly $schema?: string;
+  readonly $comment?: string;
 
   // Common Tools extensions
   readonly [ID]?: unknown;

packages/api/index.ts

@@ -6,10 +6,7 @@ interface CounterState {
 interface RecipeState {
     value: Default<number, 0>;
 }
-const increment = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const increment = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         value: {
@@ -21,10 +18,7 @@ const increment = handler({
 } as const satisfies JSONSchema, (e, state) => {
     state.value.set(state.value.get() + 1);
 });
-const decrement = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const decrement = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         value: {

packages/js-runtime/test/fixtures/ast-transform/counter-recipe.expected.tsx

@@ -7,10 +7,7 @@ declare global {
         }
     }
 }
-const handleClick = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const handleClick = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         count: {

packages/js-runtime/test/fixtures/ast-transform/event-handler-no-derive.expected.tsx

@@ -4,10 +4,7 @@ interface State {
     value: Cell<number>;
     name?: Cell<string>;
 }
-const myHandler = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const myHandler = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         value: {

packages/js-runtime/test/fixtures/ast-transform/handler-object-literal.expected.tsx

@@ -1,9 +1,6 @@
 /// <cts-enable />
 import { Cell, derive, h, handler, NAME, recipe, str, UI, JSONSchema } from "commontools";
-const adder = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const adder = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         values: {

packages/js-runtime/test/fixtures/ast-transform/recipe-array-map.expected.tsx

@@ -6,10 +6,7 @@ interface Item {
 interface ListState {
     items: Cell<Item[]>;
 }
-const removeItem = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const removeItem = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         items: {
@@ -40,10 +37,7 @@ const removeItem = handler({
 type ListStateWithIndex = ListState & {
     index: number;
 };
-const removeItemAlias = handler({
-    type: "object",
-    additionalProperties: true
-} as const satisfies JSONSchema, {
+const removeItemAlias = handler({} as const satisfies JSONSchema, {
     type: "object",
     properties: {
         items: {

packages/js-runtime/test/fixtures/handler-schema/array-cell-remove-intersection.expected.ts

@@ -1,5 +1,7 @@
 /// <cts-enable />
 import { handler, Cell, recipe, JSONSchema } from "commontools";
+// Updated 2025-09-03: String literal unions now generate correct JSON Schema
+// (enum instead of array) due to schema-generator UnionFormatter improvements
 interface UserEvent {
     user: {
         name: string;
@@ -36,10 +38,7 @@ const userHandler = handler({
             required: ["name", "email"]
         },
         action: {
-            type: "array",
-            items: {
-                type: "string"
-            }
+            enum: ["create", "update", "delete"]
         }
     },
     required: ["user", "action"]

packages/js-runtime/test/fixtures/handler-schema/complex-nested-types.expected.ts

@@ -1,6 +1,8 @@
 /// <cts-enable />
 import { handler, Cell, recipe } from "commontools";
 
+// Updated 2025-09-03: String literal unions now generate correct JSON Schema
+// (enum instead of array) due to schema-generator UnionFormatter improvements
 interface UserEvent {
   user: {
     name: string;