fix(json-schema): stop merging descriptions of sibling $ref properties

[schani]

Bug

With a JSON Schema like:

{
    "$defs": {
        "name": { "type": "string", "description": "name description" },
        "surname": { "type": "string", "description": "surname description" }
    },
    "type": "object",
    "properties": {
        "name": { "$ref": "#/$defs/name" },
        "surname": { "$ref": "#/$defs/surname" }
    }
}

running node dist/index.js --src-lang schema --lang schema input.schema produced both properties with the same, concatenated description ("name description\nsurname description") instead of each keeping its own.

Root cause

name and surname are both plain string types defined via separate $defs entries with distinct descriptions. Because the two types are structurally identical (both just "string"), quicktype's type-graph unification collapsed them onto a single shared type, and each $ref's description got combined (via descriptionTypeAttributeKind.combine, a set union) onto that one shared type's attributes. Since both properties then pointed at that single unified type, both properties reported the same combined description.

An earlier attempt at this fix made descriptions part of type identity (inIdentity), which prevented the collapse but broke type-graph reconstitution more broadly — it crashed with Internal error: Can't add different identity type attributes to an existing type on real-world schemas with more complex $ref/union structures (e.g. test/inputs/schema/vega-lite.schema).

Fix

Instead of changing type identity, JSONSchemaInput now captures each property's description from its $ref target and attaches it to the containing object's propertyDescriptions attribute — the same per-property description mechanism already used elsewhere in the renderer pipeline (see ConvenienceRenderer.descriptionForClassProperty). The JSON Schema renderer now prefers this property-specific description over the shared type's own description when one is present. This keeps type unification behavior unchanged and only affects how per-property descriptions are attributed.

Test coverage

• test/unit/schema-description-ref.test.ts: regression unit test asserting each property keeps its own description (fails on unfixed code, passes after the fix). A unit test is used because this is about metadata in the generated schema output (descriptions/doc-comments), which the standard fixture round-trip (JSON data in → JSON data out) cannot express — matching this repo's documented convention that unit tests are for what fixtures can't cover.
• test/inputs/schema/description-ref.schema + .1.json: added to test/inputs/schema/, so it's automatically picked up by every schema-* fixture (JSON round-trip / compile coverage across all target languages), giving incidental broader coverage too.

Verification

• npm run build — passes
• npx vitest run test/unit — 164/164 passed
• Repro re-run: name → "name description", surname → "surname description", no merging
• QUICKTEST=true FIXTURE=schema-golang script/test — 68/68 passed, including vega-lite.schema (the schema that crashed under the earlier, reverted inIdentity approach)

CI will validate the remaining language fixtures.

Fixes #1582

🤖 Generated with Claude Code

[github-actions]

Generated-output differences

100 files differ — 73 modified, 27 new, 0 deleted
2245 changed lines — +2231 / −14

Open the generated-output report →