astro(feat[builder]): Emit src/content.config.ts with collection wiring

why: Cycle 22 / Step 6 of notes/plans/astro.md. Pydantic owns the
canonical data shapes, so the Astro side's collection wiring should
also be generated rather than hand-maintained — that keeps the
defineCollection() registration in lockstep with the emitted
artefact paths (src/content/docs/**/*.json, src/content/api/
symbols.json, xref-index.json) and the parity-tested theme schemas
(documentSchema, symbolSchema, xrefEntrySchema). The Astro side now
inherits zero collection-wiring maintenance: drop the file in,
content collections work.

what:
- Add content_config.py with render_content_config() returning the
  TypeScript source as a single string. The template registers
  three collections:
    * docs   — glob({pattern: '**/*.json', base: './src/content/docs'})
               + documentSchema
    * api    — file('src/content/api/symbols.json') + symbolSchema
    * xrefs  — file('xref-index.json') + xrefEntrySchema
  Each import path points at the @gp-sphinx-astro/theme package
  schemas the parity tests already exercise. Header comment marks
  the file as auto-generated.
- Re-export render_content_config from gp_sphinx_astro_builder.__init__
- AstroBuilder.finish() writes <outdir>/src/content.config.ts
  (creates src/ directory if missing)
- Add 6 pytest tests:
    * returns a non-empty string
    * imports from each of the three theme schema modules
    * defines all three collections
    * uses glob() for docs and file() for api/xrefs
    * exports `const collections`
    * full source is byte-stable against a syrupy snapshot
- Add integration test asserting <outdir>/src/content.config.ts
  exists with the three collection blocks present after a real
  Sphinx build

Verification: Python 1391 passed (was 1383) / 3 skipped, 17 syrupy
snapshots green; ruff format / check / mypy strict all green.
Steps 0–6 of notes/plans/astro.md are now done.

Author: tony

packages/gp-sphinx-astro-builder/src/gp_sphinx_astro_builder/__init__.py

@@ -17,6 +17,7 @@
 import typing as t
 
 from gp_sphinx_astro_builder.builder import AstroBuilder
+from gp_sphinx_astro_builder.content_config import render_content_config
 from gp_sphinx_astro_builder.models import (
     AdmonitionNode,
     AdmonitionVariant,
@@ -93,6 +94,7 @@
     "export_doctree_schema",
     "export_symbol_schema",
     "export_xref_index_schema",
+    "render_content_config",
     "setup",
 ]
 

packages/gp-sphinx-astro-builder/src/gp_sphinx_astro_builder/builder.py

@@ -18,6 +18,7 @@
 from sphinx.util.inventory import InventoryFile
 from sphinx.util.osutil import _last_modified_time
 
+from gp_sphinx_astro_builder.content_config import render_content_config
 from gp_sphinx_astro_builder.intersphinx import build_xref_index_entries
 from gp_sphinx_astro_builder.schemas import (
     export_doctree_schema,
@@ -144,6 +145,16 @@ def finish(self) -> None:
             encoding="utf-8",
         )
 
+        # Astro content collection wiring: the TypeScript file that imports
+        # the parity-tested theme schemas and registers them with
+        # defineCollection() against the canonical artefact paths.
+        content_config_path = self.outdir / "src" / "content.config.ts"
+        content_config_path.parent.mkdir(parents=True, exist_ok=True)
+        content_config_path.write_text(
+            render_content_config(),
+            encoding="utf-8",
+        )
+
     def _target_path(self, docname: str):  # type: ignore[no-untyped-def]
         """Return the absolute path for the JSON file emitted for ``docname``."""
         return self.outdir / "src" / "content" / "docs" / (docname + self.out_suffix)

packages/gp-sphinx-astro-builder/src/gp_sphinx_astro_builder/content_config.py

@@ -0,0 +1,63 @@
+"""Generated ``src/content.config.ts`` rendering.
+
+The Astro side wires its content collections through a TypeScript file
+that imports Zod schemas from ``@gp-sphinx-astro/theme`` and registers
+them with ``defineCollection``. Pydantic owns the canonical data shapes,
+so it makes sense to also own the collection wiring — the TypeScript
+file is generated by the builder during ``finish()`` rather than
+hand-maintained, which keeps the schema registration in lockstep with
+the emitted artefacts (`src/content/docs/**/*.json`,
+`src/content/api/symbols.json`, `xref-index.json`).
+"""
+
+from __future__ import annotations
+
+_TEMPLATE = """\
+// AUTO-GENERATED by gp-sphinx-astro-builder. Do not edit by hand;
+// regenerate by running `sphinx-build -b astro <src> <out>`.
+
+import { defineCollection } from 'astro:content'
+import { file, glob } from 'astro/loaders'
+import { documentSchema } from '@gp-sphinx-astro/theme/schemas/doctree'
+import { symbolSchema } from '@gp-sphinx-astro/theme/schemas/symbol'
+import { xrefEntrySchema } from '@gp-sphinx-astro/theme/schemas/xref'
+
+export const collections = {
+  docs: defineCollection({
+    loader: glob({ pattern: '**/*.json', base: './src/content/docs' }),
+    schema: documentSchema,
+  }),
+  api: defineCollection({
+    loader: file('src/content/api/symbols.json'),
+    schema: symbolSchema,
+  }),
+  xrefs: defineCollection({
+    loader: file('xref-index.json'),
+    schema: xrefEntrySchema,
+  }),
+}
+"""
+
+
+def render_content_config() -> str:
+    """Return the canonical ``content.config.ts`` source.
+
+    The function is intentionally parameter-less for now — every consumer
+    of the builder needs the same three collections (``docs``, ``api``,
+    ``xrefs``), each pointed at the canonical artefact paths the builder
+    emits. Parametrise when a real consumer needs to disable or rename
+    one of the three.
+
+    Returns
+    -------
+    str
+        TypeScript source as a single string, newline-terminated.
+
+    Examples
+    --------
+    >>> from gp_sphinx_astro_builder.content_config import render_content_config
+    >>> source = render_content_config()
+    >>> "documentSchema" in source
+    True
+    """
+    return _TEMPLATE

tests/ext/astro_builder/__snapshots__/test_content_config.ambr

@@ -0,0 +1,29 @@
+# serializer version: 1
+# name: test_render_content_config_matches_snapshot
+  '''
+  // AUTO-GENERATED by gp-sphinx-astro-builder. Do not edit by hand;
+  // regenerate by running `sphinx-build -b astro <src> <out>`.
+  
+  import { defineCollection } from 'astro:content'
+  import { file, glob } from 'astro/loaders'
+  import { documentSchema } from '@gp-sphinx-astro/theme/schemas/doctree'
+  import { symbolSchema } from '@gp-sphinx-astro/theme/schemas/symbol'
+  import { xrefEntrySchema } from '@gp-sphinx-astro/theme/schemas/xref'
+  
+  export const collections = {
+    docs: defineCollection({
+      loader: glob({ pattern: '**/*.json', base: './src/content/docs' }),
+      schema: documentSchema,
+    }),
+    api: defineCollection({
+      loader: file('src/content/api/symbols.json'),
+      schema: symbolSchema,
+    }),
+    xrefs: defineCollection({
+      loader: file('xref-index.json'),
+      schema: xrefEntrySchema,
+    }),
+  }
+  
+  '''
+# ---

tests/ext/astro_builder/test_content_config.py

@@ -0,0 +1,56 @@
+"""Tests for :mod:`gp_sphinx_astro_builder.content_config`."""
+
+from __future__ import annotations
+
+import typing as t
+
+from gp_sphinx_astro_builder.content_config import render_content_config
+
+if t.TYPE_CHECKING:
+    from syrupy.assertion import SnapshotAssertion
+
+
+def test_render_content_config_returns_string() -> None:
+    """``render_content_config`` returns a non-empty TypeScript source string."""
+    source = render_content_config()
+    assert isinstance(source, str)
+    assert source.strip()
+
+
+def test_render_content_config_imports_canonical_zod_schemas() -> None:
+    """The generated source imports the parity-tested theme schemas."""
+    source = render_content_config()
+    assert "from '@gp-sphinx-astro/theme/schemas/doctree'" in source
+    assert "from '@gp-sphinx-astro/theme/schemas/symbol'" in source
+    assert "from '@gp-sphinx-astro/theme/schemas/xref'" in source
+
+
+def test_render_content_config_defines_three_collections() -> None:
+    """The generated source declares ``docs``, ``api``, and ``xrefs`` collections."""
+    source = render_content_config()
+    assert "docs: defineCollection" in source
+    assert "api: defineCollection" in source
+    assert "xrefs: defineCollection" in source
+
+
+def test_render_content_config_uses_glob_for_docs_and_file_for_data() -> None:
+    """The generated source wires ``glob()`` for docs and ``file()`` for symbols/xrefs."""
+    source = render_content_config()
+    # glob() for the per-document JSON
+    assert "glob({ pattern: '**/*.json', base: './src/content/docs' })" in source
+    # file() for the flat-array data collections
+    assert "file('src/content/api/symbols.json')" in source
+    assert "file('xref-index.json')" in source
+
+
+def test_render_content_config_emits_export_const_collections() -> None:
+    """The generated source ends with the canonical ``export const collections``."""
+    source = render_content_config()
+    assert "export const collections" in source
+
+
+def test_render_content_config_matches_snapshot(
+    snapshot: SnapshotAssertion,
+) -> None:
+    """The full generated source is byte-stable against a syrupy snapshot."""
+    assert render_content_config() == snapshot

tests/ext/astro_builder/test_integration.py

@@ -332,6 +332,34 @@ def test_astro_builder_emits_objects_inv_round_trippable(
     ), f"expected demo_api.merge_demo in inventory; got types: {list(inventory.keys())}"
 
 
+@pytest.mark.integration
+def test_astro_builder_emits_content_config_ts(
+    tmp_path: pathlib.Path,
+) -> None:
+    """``finish()`` writes ``src/content.config.ts`` with the canonical wiring."""
+    cache_root = derive_sphinx_scenario_cache_root(tmp_path)
+    scenario = SphinxScenario(
+        buildername="astro",
+        files=(
+            ScenarioFile("conf.py", _CONF_PY),
+            ScenarioFile("index.rst", _INDEX_RST),
+        ),
+    )
+    result = build_isolated_sphinx_result(cache_root, tmp_path, scenario)
+
+    config_path = result.outdir / "src" / "content.config.ts"
+    assert config_path.exists(), (
+        f"expected {config_path} to be emitted; "
+        f"outdir contents: {list(result.outdir.rglob('*'))}"
+    )
+
+    source = config_path.read_text("utf-8")
+    assert "export const collections" in source
+    assert "docs: defineCollection" in source
+    assert "api: defineCollection" in source
+    assert "xrefs: defineCollection" in source
+
+
 @pytest.mark.integration
 def test_astro_builder_emission_matches_snapshot(
     tmp_path: pathlib.Path,