Add docs block parsing to M1 manifest

Adds native Zig docs block parsing and literal doc() manifest support for the M1 parser slice.

Author: sabino

.agent/research/m1-docs-block-slice.md

@@ -0,0 +1,39 @@
+# M1 Docs Block Slice
+
+## Scope
+
+This slice extends the native Zig parser and partial manifest writer with a dbt Core-compatible docs block subset:
+
+- discover `.md` files under configured model paths
+- parse `{% docs name %}` / `{% enddocs %}` blocks
+- emit `docs` manifest entries keyed as `doc.<package>.<name>`
+- resolve whole-description literal `{{ doc("name") }}` and `{{ doc('name') }}`
+- attach resolved doc block IDs to model and column `doc_blocks`
+- fail loudly for malformed docs blocks, duplicate docs names, missing docs, and dynamic `doc` calls
+
+The product runtime remains Zig. Python changes are limited to tests.
+
+## Compatibility Evidence
+
+The fixture was checked against dbt Core 1.10 with the DuckDB adapter. The written Core manifest showed:
+
+- docs entries include `unique_id`, `resource_type`, `package_name`, `name`, `path`, `original_file_path`, and `block_contents`
+- docs `path` is relative to the model path, while `original_file_path` includes the model path
+- docs block contents are trimmed before manifest emission
+- literal `doc` descriptions are rendered into model and column descriptions
+- model and column `doc_blocks` list referenced doc unique IDs
+- docs entries do not appear as lineage keys in `child_map`
+
+Fusion preview was also checked as a secondary signal, but Core remains the contract for this M1 slice.
+
+## Validation
+
+Required before merging this slice:
+
+- `zig fmt --check src/project.zig src/root.zig build.zig`
+- `zig build`
+- `zig build test`
+- `pytest -q`
+- `git diff --check`
+- public-safety and runtime-boundary scans
+- public Jaffle Shop DuckDB parse smoke, if the fixture checkout is available

PLAN.md

@@ -514,7 +514,7 @@ Exit criteria:
 
 - M0 is under PR review as the Zig `0.16.0` runtime scaffold.
 - M1 has started on stacked branches with native Zig artifact-first parser slices.
-- `dxt parse` now targets the supported Tier 0 subset: project name/model paths/seed paths, SQL model discovery, CSV seed discovery, literal `ref` to models or seeds, literal `source`, inline `config(materialized=..., tags=...)`, narrow YAML model properties for scalar descriptions, simple columns, tags, materialization, disabled SQL models, dependency maps, and deterministic partial `manifest.json`. Generic tests are parsed for later graph work but are not yet emitted as dbt-shaped `test.*` nodes.
+- `dxt parse` now targets the supported Tier 0 subset: project name/model paths/seed paths, SQL model discovery, CSV seed discovery, docs block discovery, literal `ref` to models or seeds, literal `source`, literal `doc` in descriptions, inline `config(materialized=..., tags=...)`, narrow YAML model properties for scalar descriptions, simple columns, tags, materialization, disabled SQL models, dependency maps, and deterministic partial `manifest.json`. Generic tests are parsed for later graph work but are not yet emitted as dbt-shaped `test.*` nodes.
 - `dxt ls` now lists resources from the same parser graph with stable text/JSON output and basic name, tag, path, resource type, and exact exclude filters.
-- Synthetic fixtures cover one model, model refs, seed refs, source refs, combined source/model YAML, inline config/tag selection, YAML model properties and columns, disabled models, disabled ref diagnostics, unmatched model-property warnings, duplicate model diagnostics, unsupported dynamic ref diagnostics, and unsupported macro-call diagnostics.
-- The current M1 manual gate parses the public Jaffle Shop DuckDB project into a partial manifest with SQL models and CSV seeds. The next M1 slices should add published schema validation, docs blocks, macros, generic test nodes, stronger selector parity, and deeper Jaffle artifact parity.
+- Synthetic fixtures cover one model, model refs, seed refs, source refs, combined source/model YAML, inline config/tag selection, YAML model properties and columns, docs blocks with literal `doc` descriptions, disabled models, disabled ref diagnostics, unmatched model-property warnings, duplicate model and docs diagnostics, unsupported dynamic ref/doc diagnostics, missing doc diagnostics, malformed docs block diagnostics, and unsupported macro-call diagnostics.
+- The current M1 manual gate parses the public Jaffle Shop DuckDB project into a partial manifest with SQL models and CSV seeds. The next M1 slices should add published schema validation, macros, dbt-shaped generic test nodes, stronger selector parity, and deeper Jaffle artifact parity.

README.md

@@ -35,7 +35,7 @@ Implemented pre-alpha commands:
 ./zig-out/bin/dxt ls --project-dir tests/fixtures/model_ref --output json
 ```
 
-`parse` and `ls` currently support only the documented M1 parser subset: `dbt_project.yml` name/model paths/seed paths/target path, SQL model discovery, CSV seed discovery, literal `ref` to models or seeds, literal `source`, basic inline `config`, narrow YAML model properties for scalar descriptions, simple columns, tags, materialization and disabled SQL models, deterministic partial `manifest.json`, and simple name/tag/path/resource filters. dbt-shaped generic test nodes, `compile`, `build`, and `docs generate` remain planned placeholders.
+`parse` and `ls` currently support only the documented M1 parser subset: `dbt_project.yml` name/model paths/seed paths/target path, SQL model discovery, CSV seed discovery, docs block discovery, literal `ref` to models or seeds, literal `source`, literal `doc` in descriptions, basic inline `config`, narrow YAML model properties for scalar descriptions, simple columns, tags, materialization and disabled SQL models, deterministic partial `manifest.json`, and simple name/tag/path/resource filters. dbt-shaped generic test nodes, `compile`, `build`, and `docs generate` remain planned placeholders.
 
 ## Development