Skip to content

Add unified Description type for schema description handling#1

Merged
typedrat merged 9 commits intomasterfrom
feature/description-gaps-design
Mar 10, 2026
Merged

Add unified Description type for schema description handling#1
typedrat merged 9 commits intomasterfrom
feature/description-gaps-design

Conversation

@typedrat
Copy link
Member

Summary

  • Introduces a Description module (lib/TerranixCodegen/Description.hs) that encapsulates description text + kind (plain/markdown), metadata enrichment, and rendering to hnix NExpr AST
  • Replaces the internal buildDescription in OptionBuilder with Description.fromAttribute + Description.toNExpr
  • Block descriptions now get deprecated metadata enrichment via Description.fromBlock
  • Top-level resource/data source/provider descriptions now use the schema's actual block description when available, with fallback to the previous hardcoded strings
  • Markdown-kind descriptions are wrapped in lib.mdDoc for proper rendering in NixOS module documentation

Closes three description generation gaps:

  1. SchemaDescriptionKind was parsed but unused — now drives lib.mdDoc wrapping
  2. Block descriptions had no metadata enrichment — now enriched with deprecation notes
  3. Top-level module descriptions were hardcoded — now sourced from schema

Test plan

  • 161 tests pass (23 new tests added across DescriptionSpec, OptionBuilderSpec, ModuleGeneratorSpec)
  • nix flake check passes (build, format, lint)
  • Existing tests pass unchanged (backward-compatible — plain descriptions produce identical output)
  • New tests cover: fromAttribute/fromBlock metadata enrichment, markdown lib.mdDoc wrapping, top-level schema descriptions with fallbacks

Covers three gaps: unused SchemaDescriptionKind, missing block
metadata enrichment, and hardcoded top-level descriptions. Introduces
a unified Description type with mdDoc support for markdown-kind
descriptions.
Four tasks: create Description module, integrate into OptionBuilder,
integrate block descriptions in ModuleGenerator, integrate top-level
descriptions in ModuleGenerator. TDD approach with complete code.
@typedrat typedrat merged commit 1d90cdd into master Mar 10, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant