change refs emission to be for all named non-container types

[mathpirate]

Addresses/fixes Robin's feedback in https://linear.app/common-tools/issue/CT-884/named-types-should-get-entry-in-dollardefs.

Still does not auto-promote the root. Can easily change this, reviewers let me know your thoughts!

---

Summary by cubic

Switches the schema generator to hoist all named non-container types into definitions and use $ref for non-root uses. This reduces duplication, improves readability, and satisfies Linear CT-884.

• Refactors
  • Emit $ref for every named type except wrappers: Array, ReadonlyArray, Cell, Stream, Default, Date.
  • Root types remain inline (no auto-promotion yet).
  • $ref can appear with Common Tools extensions as siblings (e.g., asStream: true).
  • Updated fixtures/tests to expect definitions and $ref; added README notes.

[ubik2]

Not sure if you're done, since I am seeing updates, but this LGTM.
Edit: maybe I should wait until tests are passing, though I'm surprised they aren't.
Edit2: Here's the issue from the integration test:

Unresolved $ref in schema:  #/definitions/Item {"type":"object","properties":{"$TYPE":{"type":"string"},"argument":{"$schema":"https://json-schema.org/draft-07/schema#","type":"object","properties":{"title":{"type":"string","default":"My List"},"items":{"type":"array","items":{"$ref":"#/definitions/Item"},"default":[]}},"required":["title","items"],"definitions":{"Item":{"type":"object","properties":{"title":{"type":"string"}},"required":["title"]}}}},"required":["$TYPE"]}

Formatted:

{
  "type": "object",
  "properties": {
    "$TYPE": { "type": "string" },
    "argument": {
      "$schema": "https://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "title": { "type": "string", "default": "My List" },
        "items": {
          "type": "array",
          "items": { "$ref": "#/definitions/Item" },
          "default": []
        }
      },
      "required": ["title", "items"],
      "definitions": {
        "Item": {
          "type": "object",
          "properties": { "title": { "type": "string" } },
          "required": ["title"]
        }
      }
    }
  },
  "required": ["$TYPE"]
}

This looks like you've exposed a bug somewhere else where we combine schemas improperly.
schema.ts has a generateHandlerSchema, which does a similar thing (and doesn't handle the $schema property), but this isn't that path.
This looks like ListInput from ct-list.tsx, but this is specifically for the process cell (with the $TYPE).
Ah, probably syncCellsForRunningRecipe.

[ubik2]

If we change the emitted $schema to https://json-schema.org/draft/2020-12/schema, we won't need this as a disclaimer (since it would be legal), but I think we should also switch to $defs instead of definitions if we do that, and I'd rather see that in a later PR so this one lands earlier.
Both $defs and definitions are legal in 2020-12, but $defs is preferred.

[mathpirate]

Captured https://linear.app/common-tools/issue/CT-916/update-generated-json-schema-version as a follow-up to do this Soon(tm)

[ubik2]

At some point, I intend to stop passing around schema and rootSchema, and instead make sure all the definitions used for the child schema get copied into that object from the rootSchema. This may include hoisting Root to be a named node (if your children have a "$ref": "#").

[mathpirate]

Ok, sounds good. Let me know if/when I should make corresponding changes on this side!

[ubik2]

if typeof base is boolean, we don't need to scan for references.
collectReferencedDefnitions will just return an empty object.

You may still want to convert it to an object form so you can convey the $schema tag, but we don't need definitions. No personal preference on whether it gets converted to object with $schema tag or just boolean.

[mathpirate]

good point thanks, i went ahead and did the object form with $schema tag, PTAL

[ubik2]

logs good!