Skip to content

Commit e45ffd4

Browse files
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/hello-symbol.json

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"id": "demo_api.merge_demo",
3+
"kind": "function",
4+
"name": "merge_demo",
5+
"qualname": "merge_demo",
6+
"module": "demo_api",
7+
"signature": "(project: str, version: str = \"0.0.0\") -> dict[str, str]",
8+
"parameters": [
9+
{
10+
"name": "project",
11+
"annotation": "str",
12+
"default": null,
13+
"kind": "positional"
14+
},
15+
{
16+
"name": "version",
17+
"annotation": "str",
18+
"default": "\"0.0.0\"",
19+
"kind": "positional"
20+
}
21+
],
22+
"returns": "dict[str, str]",
23+
"docstring_summary": "Merge a tiny pseudo-config payload.",
24+
"docstring_body": [
25+
{
26+
"type": "paragraph",
27+
"children": [
28+
{
29+
"type": "text",
30+
"value": "Merge a tiny pseudo-config payload."
31+
}
32+
]
33+
}
34+
],
35+
"source": {
36+
"repo": "https://github.com/git-pull/gp-sphinx",
37+
"path": "demo_api.py",
38+
"line": 4
39+
}
40+
}

0 commit comments

Comments
 (0)