Commit e45ffd4
committed
astro(feat[parity]): Add Symbol schema export and Pydantic↔Zod parity
why: Cycle 19 closes Step 4 (autodoc → typed Symbol collection).
Symbols now have the same dual-schema contract as the doctree:
Pydantic emits canonical JSON Schema, the TS theme has hand-written
Zod that validates the same shape, behavioural parity tests prove
identical fixture payloads pass through both paths via
z.fromJSONSchema. Symbol.docstring_body transitively pulls every
doctree node model into the Symbol schema, so this single schema
file covers both the API-symbol shape AND the doctree subset that
docstrings render through.
what:
- Add export_symbol_schema() to schemas.py returning
Symbol.model_json_schema() (transitively includes Parameter,
SymbolSource, and every BlockNode/InlineNode under $defs)
- Re-export from gp_sphinx_astro_builder.__init__
- AstroBuilder.finish() also writes <outdir>/schemas/symbol.schema.json
alongside doctree.schema.json
- Commit astro/fixtures/symbol.schema.json (1137 lines, Pydantic
canonical export)
- Commit astro/fixtures/hello-symbol.json — canonical Symbol
fixture for parity testing (function with two parameters,
populated docstring_body and source)
- Extend test_schema_fixture.py: split the single drift-detection
test into doctree + symbol variants
- Add 4 schemas.py pytest tests (returns dict, defs membership for
Parameter+SymbolSource, canonical Symbol round-trip, full schema
syrupy snapshot)
- Add astro/packages/theme/src/schemas/symbol.ts with hand-written
Zod schemas (parameterKindSchema, parameterSchema,
symbolSourceSchema, symbolKindSchema, symbolSchema). Symbol
imports blockNodeSchema from doctree.ts so docstring_body inherits
the doctree validation.
- Add 10 symbol.test.ts validation tests
- Add 8 symbol-parity.test.ts behavioural-parity tests:
* fixture loading (defs + top-level shape)
* canonical hello-symbol passes hand-written symbolSchema
* canonical hello-symbol passes z.fromJSONSchema(pydantic)
* malformed kind rejected by both paths
* missing required field rejected by both paths
* test.each over the 2 symbol-specific $defs
Verification: Python 1370 passed (was 1364) / 3 skipped, 15
snapshots green; TS 88 vitest tests pass (was 70), type-check
clean, biome lint+format clean. Step 4 of notes/plans/astro.md is
complete: autodoc directives now produce typed Symbol entries in
src/content/api/symbols.json with Pydantic↔Zod parity end-to-end.1 parent 38158ac commit e45ffd4
11 files changed
Lines changed: 3045 additions & 26 deletions
File tree
- astro
- fixtures
- packages/theme
- src/schemas
- test/schemas
- packages/gp-sphinx-astro-builder/src/gp_sphinx_astro_builder
- tests/ext/astro_builder
- __snapshots__
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
0 commit comments