zard 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0551d23261849efc4c7967195baade2229626abf6b5dcdd653681787c968e19d
-  data.tar.gz: e08b3a10d55ec03987f22b505116f1e839d49769522d76f12c66efb9b7929990
+  metadata.gz: 9c9ab0c9576a9523bbbf9e28e700547c6867639e731cf7fb3365f5b1e6384c4f
+  data.tar.gz: 37182c341bb8ca6cb2cc1f4f27527d0551a28d78cf0c9d47867db31fcb8ae216
 SHA512:
-  metadata.gz: e6631158d5562709a1846e7088384139894e1774f8c74478de4fa776336922af76098532282bcccb6cbb3821640a63f27a2c70c8835faa3dc381f4d4a6ec00c4
-  data.tar.gz: efe0e597d3d2e4fbb255aaf0edeb01ea0242b4d2022d11816be0e045526cf78b8b36c11990bf2d68d1a4a05338a61b241d747872a9a98a536e7837ba6b2a387c
+  metadata.gz: adcab0e387452ebea5e0fa5b978600ecfcccfd1938bef002b19ea75699793680338cfcd0a2a08b481bb09a430f5931e37154b7f551d750e0709a27abef283066
+  data.tar.gz: b5b76cd72e4b9a03530f187719ea891597f52cbdb67abee884df86c90a20f0afe8b0b7e88cb323759fd59175ced12c751aa0eb9bd197f5c887dad1596719a2af

data/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.0.2] - 2026-10-19
+
+Generate scoped API documentation and versioned JSON for static sites, optionally enriched by released Rigor lens facts. This release also adds annotation formatting and an unstyled Astro presentation package; consumer sites own styling and publication.
+
+### Added
+
+- Build hierarchical Markdown documentation for explicitly configured monorepo scopes, with namespace or file organization, direct dependency links, navigation indexes, and managed output updates.
+- Link YARD-style `@see` references and URLs in generated Markdown, including cross-file CLI references and equivalent `.#` and `?.` module-function spellings.
+- Link BitClust Markdown and RD-compatible references in prose and documentation tags while preserving code regions, existing Markdown links, and source provenance.
+- Format annotation layout through `Zard.format` and `zard-doc format`, with safe contract ordering, redundant-marker removal, check/write modes, and reparsed source provenance.
+- Export experimental `zard-doc/v0` revision 1 JSON with public declarations, exact Ruby parameter syntax, source snapshots, scoped links and written superclass/mixin relationships ([#22](https://github.com/rigortype/zard/pull/22), [#23](https://github.com/rigortype/zard/pull/23), [#25](https://github.com/rigortype/zard/pull/25)).
+- Enrich exports through the optional `zard-rigor` gem and released Rigor 0.4.5 CLI, preserving shared signatures, per-definition returns, provenance and explicit unavailable reasons without loading analyzer internals ([#24](https://github.com/rigortype/zard/pull/24), [#27](https://github.com/rigortype/zard/pull/27)).
+- Consume constant value types, aliases, module functions and readable declared block types with exact source matching and separate instance/singleton member bindings; only Rigor 0.4.5 is supported.
+- Provide the experimental, unpublished `zard-doc-astro` package with unstyled accessible HTML, Starlight routes, grouped member navigation, definition/name sorting, native documentation disclosures and class/module relationship browsing.
+
 ## [0.0.1] - 2026-10-11
 
 The first ZARD release separates Ruby API documentation from RBS and Rigor contracts. Parse Ruby source into a versioned model, generate public API Markdown, and lint documentation from files, directories, or standard input without installing Rigor.
@@ -23,5 +38,6 @@ The first ZARD release separates Ruby API documentation from RBS and Rigor contr
 - Provide `zard-doc render` and `zard-doc lint` for files, recursive directories, and standard input, with deterministic path ordering and no partial Markdown on input errors.
 - Distribute `zard` and `zard-doc` as separate gems for Ruby 3.2 and newer, with a usage guide and a complete multi-file example.
 
-[Unreleased]: https://github.com/rigortype/zard/compare/v0.0.1...HEAD
+[Unreleased]: https://github.com/rigortype/zard/compare/v0.0.2...HEAD
+[0.0.2]: https://github.com/rigortype/zard/compare/v0.0.1...v0.0.2
 [0.0.1]: https://github.com/rigortype/zard/tree/v0.0.1

data/CONTEXT.md

@@ -4,6 +4,22 @@ ZARD is a Ruby self-documentation notation for people and AI agents. It uses pla
 
 ## Language
 
+**Source mapping**:
+A correspondence between a source tree and a destination within the API documentation tree.
+_Avoid_: Ruby module, gem boundary
+
+**Documentation scope**:
+A named, explicitly defined API documentation context containing one or more source trees and their declarations, contracts, and facts. Applications have separate documentation scopes by default, even when they share Ruby namespace names.
+_Avoid_: Ruby namespace, source mapping, automatically detected application
+
+**Documentation dependency**:
+An explicitly declared documentation scope whose API declarations may be referenced from another scope.
+_Avoid_: runtime dependency, implicit global lookup
+
+**Documentation root**:
+The common destination for API documentation trees produced by source mappings.
+_Avoid_: source root, repository root
+
 **ZARD**:
 The self-documentation language defined by this project.
 _Avoid_: YARD, RDoc

data/README.md

@@ -16,7 +16,7 @@ ZARD separates contracts from API documentation:
 - **API Documentation (`@param`, `@return`, etc.)**: Human- and AI-facing prose explains *what* and *why* without repeating type signatures.
 - **Structured Declaration Model**: The parser captures declarations, contracts, documentation, and diagnostics with precise source spans and provenance—ideal for IDEs, automated tooling, and AI agents.
 
-The current release preserves contract payloads as text. It does not parse or validate their types, check documentation claims against contracts, or integrate with the Rigor lens.
+The current release preserves contract payloads as text. It does not parse or validate their types or check documentation claims against contracts. The development checkout also provides an optional experimental Rigor lens adapter, described below.
 
 ---
 
@@ -46,31 +46,24 @@ end
 
 ## Architecture & Packages
 
-This repository provides two coordinated gems:
+The 0.0.2 release contains parser, documentation and optional adapter gems:
 
 | Gem | Role | Description |
 | --- | --- | --- |
 | [`zard`](.) | Parser & Model | Parses Ruby source into a versioned, static document model (`Zard::Model::V1`) with source spans and provenance. |
 | [`zard-doc`](zard-doc) | Renderer & CLI | Renders API documentation from the ZARD model into Markdown, and provides the `zard-doc` CLI tool. |
+| [`zard-rigor`](zard-rigor) | Optional adapter | Enriches JSON exports through the released Rigor 0.4.5 CLI (`lens/v0` revision 1), without loading analyzer internals. |
 
 ---
 
 ## Installation
 
-The `0.0.1` release candidate is not yet published on RubyGems. Use the repository as the Gem source:
+Install [zard](https://rubygems.org/gems/zard) and [zard-doc](https://rubygems.org/gems/zard-doc) 0.0.2 from RubyGems by adding the pair to your Gemfile:
 
 ```ruby
 # Gemfile
-gem "zard", github: "rigortype/zard"
-gem "zard-doc", github: "rigortype/zard"
-```
-
-Once published, install with:
-
-```ruby
-# Gemfile
-gem "zard", "~> 0.0.1"
-gem "zard-doc", "~> 0.0.1"
+gem "zard", "~> 0.0.2"
+gem "zard-doc", "~> 0.0.2"
 ```
 
 Run `bundle install` after adding the gems to your Gemfile.
@@ -127,6 +120,10 @@ markdown = Zard::Doc.render(document)
 
 The renderer emits documented public declarations and supports class, module, constant, attribute, and method prose, as well as `@param`, `@return`, `@yieldparam`, `@yieldreturn`, `@option`, `@raise`, `@note`, `@see`, `@deprecated`, and `@example`. Contracts remain in the model and are not duplicated into API prose.
 
+Version 0.0.2 provides `zard-doc build --config zard-doc.yml --format json` for static-site consumers. It exports public declarations, documentation, unparsed contracts, source provenance, and scoped page/link metadata to stdout without publishing files. This experimental [JSON export](docs/json-export.md) works independently of Rigor; install the optional `zard-rigor` gem to enrich it with reviewed lens facts.
+
+The experimental [`zard-doc-astro`](zard-doc-astro/README.md) JavaScript package owns unstyled API presentation and a separate Starlight adapter. Consumer sites own CSS, source acquisition, localization and publication; the Ruby gems do not depend on Astro.
+
 ---
 
 ## Supported Ruby Semantics

data/docs/adr/0002-em-dash-zard-documentation-marker.md

@@ -14,6 +14,7 @@ ZARD uses an em dash `—` when a named documentation tag or an optional type mu
 - `@option options :format — Output format.` is ZARD documentation.
 - `@option options :format [Symbol] — Output format.` is ZARD documentation with a claim.
 - Tags with no name and no type, such as `@note`, `@see`, `@deprecated`, and `@example`, write their description directly.
+- For YARD compatibility, `@see` descriptions may contain a reference followed by a whitespace-separated display label; this form does not require `—`.
 - `@param value [String] Input text.` is preserved as raw text, not as a type hint.
 - Named tags such as `@param`, `@option`, `@yieldparam`, and `@raise` require `—` before their description.
 - `zard-doc lint` warns about YARD-like tags and can promote the warning to an error.

data/docs/adr/0004-documentation-reference-syntax.md

@@ -0,0 +1,112 @@
+# Use BitClust references and YARD-compatible see tags
+
+ZARD adopts BitClust Markdown references, accepts their RD link forms for compatibility, and supports YARD-style shorthand in `@see`. All forms share reference resolution, while original comment text and source provenance remain available. Compatibility makes existing Ruby documentation familiar and avoids a separate ZARD spelling for each kind of method.
+
+Status: Accepted. The current implementation covers shorthand `@see` references, URLs, and the explicit BitClust and RD forms below. Availability describes repository support rather than a published gem version.
+
+## Problem Statement
+
+Authors need links between Ruby declarations in API documentation. BitClust and YARD provide familiar conventions, but differ in delimiters, labels, and module-function spelling. Documentation must retain its original text even when a reference cannot be linked.
+
+## Solution
+
+Use explicit BitClust forms in prose and allow concise YARD-compatible targets in `@see`. Accept both `Kernel.#puts` and `Kernel?.puts` with identical meaning. Generated documentation links only to destinations it can identify reliably.
+
+## User Stories
+
+1. As an author, I want to link an instance method, so that readers can find related behavior.
+2. As an author, I want to link a class method, so that readers can find construction and utility APIs.
+3. As an author, I want either module-function spelling to work, so that existing comments remain usable.
+4. As an author, I want relative method targets, so that comments need not repeat their owner.
+5. As an author, I want an absolute target, so that a local namespace cannot change its meaning.
+6. As an author, I want a custom label, so that references fit the surrounding explanation.
+7. As an author, I want RD links accepted, so that migrating documentation does not require rewriting every reference.
+8. As an author, I want links in prose and documentation tags, so that related APIs can be mentioned where they matter.
+9. As an author, I want code examples preserved, so that literal reference syntax is not expanded inside code.
+10. As a reader, I want links across generated input files, so that related declarations remain reachable.
+11. As a reader, I want unresolved references preserved, so that incomplete documentation retains useful context.
+12. As a tool author, I want original comments and source spans, so that normalization does not erase provenance.
+
+## Implementation Decisions
+
+### Accepted forms
+
+| Form | Meaning | Availability |
+| --- | --- | --- |
+| `[m:Foo#bar]` | Explicit instance-method reference | Implemented |
+| `[m:Foo.bar]` | Explicit class-method reference | Implemented |
+| `[m:Kernel?.puts]` | Explicit module-function reference | Implemented |
+| `[label](m:Foo#bar)` | Explicit reference with a display label | Implemented |
+| `[c:Foo]` | Class or module reference | Implemented |
+| `[m:Math::PI]` | Constant reference | Implemented |
+| `[[m:Foo#bar]]` | RD-compatible method reference | Implemented |
+| `[[m:Kernel.#puts]]` | RD-compatible module-function reference | Implemented |
+| `[[c:Foo]]` | RD-compatible class or module reference | Implemented |
+| `@see Foo#bar` | Shorthand instance-method reference | Implemented |
+| `@see Foo` / `@see Foo::CONST` | Shorthand class, module, or constant reference | Implemented |
+| `@see Foo.bar Label` | Shorthand class-method reference with a label | Implemented |
+| `@see #bar` / `@see .bar` | Reference relative to the current owner | Implemented |
+| `@see Kernel.#puts` / `@see Kernel?.puts` | Equivalent module-function references | Implemented |
+| `@see https://example.com Label` | External URL with an optional label | Implemented |
+
+The `@see` examples are comment payloads, written as `# @see ...` in Ruby source. Explicit forms also belong in `@see` descriptions; they are not shorthand target tokens and must be recognized before shorthand parsing.
+
+### Targets and normalization
+
+- `Foo#bar` selects an instance method. `Foo.bar` selects a singleton method.
+- `Kernel.#puts` and `Kernel?.puts` select the same module-function reference and link to its public singleton copy. Normalization preserves the original spelling for display and provenance. Relative `.#puts` and `?.puts` follow the same rule.
+- A leading `::` requests a root target. Relative `#bar` and `.bar` use the current class or module; shorthand top-level instance methods use the empty owner.
+- Qualified targets search the current namespace and its namespace prefixes. This matches YARD's namespace-based convention, including qualified openings such as `class Outer::Caller`; it does not reproduce Ruby's lexical constant lookup.
+- A nearer declared owner shadows outer owners. If its requested member is missing, private, or undocumented, resolution stops and preserves the reference as text.
+- Attribute writers use their actual method name with `=`. An accessor exposes reader and writer references, which may share one rendered declaration. A replacement reader remains distinct from a retained writer.
+- Valid Unicode owners and method names participate in lookup. Method punctuation remains part of the target; normalization changes only the owner/method separator.
+- Explicit constant receiver paths are matched against declared namespace candidates. Dynamic receiver expressions and runtime aliases do not establish object identity.
+
+### Labels and comment boundaries
+
+- Shorthand `@see` uses the first whitespace-separated token as its target and the remaining text as an optional display label. Leading and trailing whitespace is trimmed for rendering. No `—` is required, as clarified by ADR 0002.
+- If no label is supplied, the original target spelling supplies the display text. Labels and destinations must be escaped appropriately for generated Markdown.
+- Existing documentation continuation rules apply. Continuation lines remain part of the same `@see` description and, for a resolved shorthand reference, its label.
+- Explicit Markdown forms use `[label](m:target)` for labels. A label consisting entirely of a backtick code span keeps that code presentation, following BitClust.
+- Method names containing brackets use BitClust escaping: `[m:Hash#\[\]]`. RD compatibility accepts the historical form `[[m:Hash#[] ]]`, including its delimiter-separating space.
+- References are recognized in prose, including documentation tag descriptions, while inline code and fenced or indented code blocks remain literal. An `@example` code region is not implicitly a reference region.
+- RD compatibility covers link syntax only. It does not reinterpret the entire comment as an RD document.
+
+### Resolution and output
+
+- Resolve against explicit declarations in the generated input set. The single-document API uses that document; the CLI uses all input files in its combined output.
+- A destination must identify exactly one public declaration with rendered API documentation. Private, undocumented, ambiguous, unresolved, and refinement targets remain text with their original description intact.
+- Equivalent forms resolve to the same destination. References to a shared declaration use one stable, collision-free anchor, independent of parameter display and heading slug rules.
+- URL shorthand supports HTTP, HTTPS, and mailto. It does not require declaration lookup.
+- Declaration lookup does not follow inheritance or mixins, evaluate Ruby, infer runtime receiver identity, or fetch external API inventories. These limits are deliberate even where YARD can resolve more broadly.
+- The core retains documentation descriptions, raw source, and spans. Reference interpretation belongs to documentation generation and does not turn a reference into a contract or documentation claim.
+- A future structured reference representation must preserve provenance and respect the versioned model boundary; this ADR does not add a public model field or resolver API.
+
+## Testing Decisions
+
+Use the existing parse API, Markdown generation API, and CLI as the acceptance seams. Assert rendered destinations and preserved source text rather than requiring a new resolver interface.
+
+- Cover qualified and relative instance/class methods, root targets, namespace-prefix lookup, and shadowing.
+- Verify that both module-function spellings, with or without an owner, produce the same destination and one anchor.
+- Cover reader/writer accessors, aliases, operator methods, Unicode owners, and Unicode method names.
+- Verify labels, continuation lines, spacing, URL escaping, empty descriptions, and punctuation-only unresolved targets.
+- Verify private, undocumented, missing, ambiguous, dynamic-receiver, and refinement cases retain text rather than linking to an unrelated declaration.
+- Exercise multiple CLI input files, deterministic output, and cross-file ambiguity through the existing CLI.
+- Verify BitClust/RD equivalence, bracket escaping, custom labels, literal code regions, and unchanged raw comments and source spans through the same seams.
+
+## Out of Scope
+
+Full RD rendering, YARD's `{target}` prose syntax, documentation copying via `(see target)`, runtime ancestry resolution, external reference databases, BitClust schemes beyond `m:` and `c:`, BitClust document/method fragment schemes, and the proposed `[label][m:target]` reference-style form are outside this decision. Unresolved-reference lint diagnostics are a separate decision; this ADR requires lossless fallback rather than a new warning policy.
+
+## Further Notes
+
+The explicit forms are a compatibility subset, not a claim of complete BitClust or YARD rendering compatibility. ADR 0001 keeps API documentation separate from contracts, ADR 0002 governs documentation markers and continuation, and ADR 0003 preserves the core/documentation package boundary.
+
+Primary references:
+
+- [BitClust Markdown specification, cross references](https://github.com/rurema/bitclust/blob/581943661862910ff2035df2974709aef816a1c0/doc/markdown-samples/MARKUP_SPEC.md#7-クロスリファレンスハイパーリンク).
+- [BitClust Markdown reference implementation](https://github.com/rurema/bitclust/blob/581943661862910ff2035df2974709aef816a1c0/lib/bitclust/mdcompiler.rb#L849).
+- [Rurema Markdown migration notes](https://blog.n-z.jp/blog/2026-07-23-rurema-to-markdown.html).
+- [YARD reference syntax and automatic `@see` linking](https://github.com/lsegal/yard/blob/3d8670543d2408baea3a1360b2258fde2ee65917/docs/GettingStarted.md#L395-L409).
+- [YARD `@see` tag definition](https://github.com/lsegal/yard/blob/3d8670543d2408baea3a1360b2258fde2ee65917/lib/yard/tags/library.rb#L503-L513).
+- [YARD namespace lookup](https://github.com/lsegal/yard/blob/3d8670543d2408baea3a1360b2258fde2ee65917/lib/yard/registry_resolver.rb#L50-L100).

data/docs/adr/0005-safe-annotation-formatting.md

@@ -0,0 +1,28 @@
+# Format annotations with semantic preservation checks
+
+Status: Accepted.
+
+ZARD formatting normalizes annotation layout without interpreting contract payloads or converting ambiguous documentation into claims. Moving a contract can change the ownership of documentation continuation lines, so source layout alone is not sufficient to establish a safe edit.
+
+## Interface and package
+
+The core provides `Zard.format(source, path:)`. Its result exposes `source`, `document`, `diagnostics`, and `changed?`. Formatting does not mutate the input or read or write files. The result contains a freshly parsed document whose raw text and spans refer to the formatted source. Invalid byte encodings that cannot enter the parser produce an empty document with an error diagnostic. Formatting diagnostics also refer to the returned source.
+
+The existing `zard-doc` executable provides `format PATH`, `format --check PATH...`, and `format --write PATH...`. Plain mode prints one formatted input; `-` reads standard input. Check and write modes support recursive directory inputs. Write mode rejects standard input. Check and write are mutually exclusive.
+
+Exit status is 0 on success, 1 for source errors or changes required in check mode, and 2 for invocation or I/O errors. Warnings, including ambiguous documentation left unchanged, do not fail formatting. All inputs are read and validated before write mode changes any file. It leaves unchanged files untouched. Filesystem write failures are reported, but multi-file writes are not transactional.
+
+## Allowed transformations
+
+- Normalize the comment prefix of standalone `@extrbs` annotations to `# @extrbs`, retaining indentation, payloads, notes, and trailing whitespace. A noncanonical annotation with nonblank continuation text is left unchanged because its intended boundary is ambiguous.
+- Stably move `@extrbs` lines before other annotations within an attached contiguous comment block. Preserve the relative order of contract lines and all other lines. Preserve the original sequence of line terminators, including mixed LF/CRLF and an absent final newline.
+- Remove a redundant em dash from parsed `@return` and `@yieldreturn` tags without claims, except when removal would reinterpret the description's leading bracket or em dash. Keep those ambiguous descriptions with the existing diagnostic. Canonical named or typed markers already have their required delimiter and need no conversion.
+- Keep missing markers, YARD-like tags, unknown tags, indented documentation, examples, string literals, embedded documents, and detached comments unchanged. Retain the parser's diagnostics rather than guessing a documentation boundary.
+
+Before accepting a contract reorder, reparse it and compare declarations, documentation fields and order, and contract payloads/notes. Contract ordering may change only through stable `@extrbs` placement. Reject a reorder that changes these values, keep the safe spacing/marker edits, and emit `format.unsafe-extrbs-order`. This protects continuation ownership and declaration attachment. Noncanonical `@extrbs` prefix repair intentionally makes a previously raw annotation a contract; it is the only such conversion.
+
+Malformed Ruby and non-UTF-8 source are returned unchanged with errors. The formatter does not validate types, rewrite Ruby code, generalize comment spacing, format RBS payloads, infer missing documentation markers, or migrate YARD documentation.
+
+## Verification
+
+Use the formatting API, existing parse API, and real CLI. Verify payloads, notes, multiline descriptions, raw text, byte spans, indentation, line terminators, safe and unsafe reorder cases, ambiguous comments, and a byte-identical second pass. Exercise stdout, stdin, check and write modes, directories, read errors, and invalid inputs before writing.

data/docs/adr/0006-hierarchical-documentation-output.md

@@ -0,0 +1,85 @@
+---
+status: accepted
+---
+
+# Separate documentation scopes from page organization
+
+Monorepos need separate application documentation even when applications share Ruby namespace names. Applications have separate documentation scopes by default. Each scope is named and explicitly configured; directory conventions and gemspecs do not automatically establish scope boundaries. Multiple source trees assigned to one scope aggregate together. A shared documentation root accommodates hierarchical output, while page organization can use source files or Ruby namespaces; a CLI option overrides the page organization selected in the configuration file. Contracts and Rigor facts must retain their association with declarations independently of page organization.
+
+Source files without publishable declarations produce no API page. In namespace organization, documented top-level methods and constants appear on a dedicated top-level page. Script explanations and execution instructions belong in separate guides.
+
+References first resolve within their own scope. If no local target is found, lookup searches explicitly configured documentation dependencies. Sharing Ruby namespace names does not implicitly enable references between scopes.
+
+Each source mapping selects files using include and exclude globs relative to its source root, independently of Git tracking and gemspec contents. Namespace organization is the default; file organization remains selectable. Both modes resolve references against all selected files in their scope.
+
+Shared source files may belong to multiple scopes, with separate scope-specific declaration identities. Within one scope, overlapping inputs parse the same physical source file once. Ambiguous local references do not fall back to dependencies; ambiguous dependency references do not select the first match. Ambiguous references remain literal and produce warnings identifying candidate scopes and source locations.
+
+Generation validates all selected scopes before updating output. Parse errors, unreadable inputs, and output collisions prevent publication of the entire selected output set; warnings alone permit generation. Filesystem publication failures use the recovery policy below.
+
+## Configuration
+
+Use YAML with `docroot`, `layout`, and named `scopes`. Each scope defines a `destination`, explicit `references`, and `sources` containing a `root` with include and exclude globs. Paths are relative to the configuration file. Source mappings may define an output prefix to distinguish source trees in file organization. CLI options override configured page organization and select scopes to generate.
+
+```yaml
+docroot: docs/api
+layout: namespace
+scopes:
+  rigor:
+    destination: rigor
+    sources:
+      - root: lib
+        include: ["**/*.rb"]
+      - root: plugins
+        include: ["*/lib/**/*.rb"]
+  playground:
+    destination: playground
+    references: [rigor]
+    sources:
+      - root: apps/rigor-playground/lib
+        include: ["**/*.rb"]
+```
+
+## Aggregation and initial delivery
+
+Reopened classes and modules share one namespace page, retaining descriptions, contracts, and provenance from each definition rather than replacing one description with another. Repeated method definitions remain separately represented; no runtime winner is inferred, and references to multiple competing method definitions are ambiguous. A namespace reference identifies the aggregate namespace page.
+
+The initial implementation covers configuration, declaration aggregation, page organization, and cross-scope links using the existing parse model. External RBS ingestion requires a separate specification. Rigor lens integration is deferred to the `v0.1.0` goal and is not required for this workflow. Existing contract payloads retain their association with source declarations; this work does not introduce contract text rendering or type inference.
+
+## Generated output ownership
+
+A generation manifest records ZARD-managed pages. Regeneration removes obsolete managed pages while preserving unowned files, including handwritten guides. If a managed page has been edited since generation, publication stops before overwriting or deleting it. Output is prepared in a staging area; publication failures trigger recovery attempts. Failed recovery produces a non-success exit and actionable recovery information. This does not promise an atomic filesystem transaction across all pages.
+
+## CLI and dependency generation
+
+Add `zard-doc build --config zard-doc.yml`; retain the existing `render PATH...` combined Markdown stream and existing APIs. Configuration is explicitly selected. Without `--scope`, build all configured scopes; repeated `--scope` selects named scopes. `--layout namespace|file` overrides the configured layout.
+
+```sh
+zard-doc build --config zard-doc.yml
+zard-doc build --config zard-doc.yml --scope playground --layout file
+```
+
+Build selected scopes together with their recursive documentation dependency closure so generated links have destinations. Reference lookup still searches only the current scope and its directly declared dependencies; transitive generation does not expand lookup visibility. Dependency cycles are allowed, and each scope is generated once.
+
+## Path validation and navigation
+
+Missing source roots, unknown documentation dependencies, scopes selecting no Ruby files, and conflicting output paths are errors before publication. Output destinations must stay within `docroot`. Input symlinks must not lead outside explicitly declared input roots. Within one scope, repeated inclusion of one physical file is deduplicated when the output assignment agrees, but conflicting output assignments are errors.
+
+Generate `docroot/index.md` listing scopes and a scope-local `index.md` listing its pages. In namespace organization, publishable top-level declarations use `_top-level.md` within their scope. Links use relative output paths and stable anchors. Collisions between API pages and reserved navigation paths are errors.
+
+## Acceptance scenarios
+
+- Generate two applications defining the same namespace without mixing declarations or links.
+- Aggregate multiple source trees and reopened namespaces within one scope while preserving all definition provenance.
+- Generate namespace and file layouts from the same selected declarations; CLI layout overrides configuration.
+- Honor include and exclude globs independently of Git and gem packaging.
+- Include shared source in separate scopes without cross-scope identity leakage; deduplicate identical assignments within one scope.
+- Resolve local references before direct documentation dependencies; preserve and warn on ambiguous targets.
+- Generate selected scopes and recursive dependency closure, including cycles, without making transitive dependencies visible to reference lookup.
+- Omit API pages for files without publishable declarations and place top-level declarations in the dedicated namespace-layout page.
+- Reject invalid roots, dependencies, empty source selections, escaped paths, and output collisions before changing output.
+- Generate relative links and navigation pages; reject collisions with reserved paths.
+- Remove obsolete managed pages, preserve handwritten guides, and reject overwriting edited managed pages.
+- Preserve existing output when pre-publication validation fails; exercise publication failure recovery and report unrecovered failures.
+- Preserve existing parse, render, lint, and format behavior outside the new build workflow.
+
+The initial file-oriented example maps `app/foo/hoge/fuga.rb` to `docs/api/foo/hoge/fuga.md` and `ext/foo-bar/hoge/fuga_foo.rb` to `docs/api/foo-bar/hoge/fuga_foo.md`. It illustrates file organization, rather than requiring that hierarchy for namespace organization. External contract and fact ingestion is deferred to a separate design.

data/docs/json-export.md

@@ -0,0 +1,103 @@
+# JSON API documentation export
+
+Repository builds support an experimental static-site producer:
+
+```sh
+zard-doc build --config zard-doc.yml --format json > api.json
+```
+
+This is ZARD documentation data, not a Rigor lens result. Plain generation does not execute Ruby source, parse contract types, infer signatures, or require Rigor. The optional `zard-rigor` adapter can associate facts with source declarations without replacing their documentation or provenance.
+
+Framework-specific HTML lives in [`zard-doc-astro`](../zard-doc-astro/README.md), with Starlight conventions isolated in its adapter. Styling, source acquisition and publication belong to each consumer. This export does not embed an Astro component or stylesheet.
+
+## Invocation and publication
+
+The existing build configuration, source selection, explicit documentation scopes, dependency closure and `--layout` / `--scope` options apply. `--format markdown` remains the default and retains its managed-page behavior.
+
+JSON exports the selected scopes and their recursive documentation dependencies as one document to stdout, after validation. It does not read a previous generation manifest or create, edit or remove anything under `docroot`. The export is self-contained for those selected scopes; it does not merge a previous partial export. Consumers own their output publication. Shell redirection itself can truncate an existing destination before ZARD runs; callers that publish artifacts should write a temporary file and replace the artifact only after success.
+
+Source errors return 1; invalid configuration or invocation, unreadable inputs, output-path collisions and serialization errors return 2. Neither emits partial JSON. Warnings permit export and also appear on stderr. A process or stdout I/O failure can leave truncated output, so consumers must check both exit status and JSON parsing before accepting an artifact.
+
+## Envelope
+
+| Field | Meaning |
+| --- | --- |
+| `schema` | Exactly `zard-doc/v0`. |
+| `revision` | Integer `1` for this experimental representation. |
+| `producer` | `zard` and `zard_doc` gem versions. |
+| `layout` | `namespace` or `file`. |
+| `scopes` | Selected documentation scopes, ordered by name. |
+| `links` | Resolved documentation links grouped by source page path, with target `path` and `anchor`. |
+| `warnings` | Reference-resolution warning strings, including ambiguous candidates; diagnostic prose is not a machine-readable enum. |
+
+Consumers should reject unsupported schema/revision pairs. This format is experimental; a breaking change increments the revision before any stable schema commitment. It has its own lifecycle, independent of `lens/v0`, `lens/v1` and the `rigor:v1` type grammar revision. No generation timestamp, absolute configuration path or inferred fact is added. Repeated exports of identical inputs with the same producer versions are byte-identical.
+
+## Documentation scopes and pages
+
+Each scope has `name`, `destination`, its explicit direct documentation dependency names in `references`, `files`, `declarations`, and `pages`.
+
+Each page has a `path` and an ordered array of declaration `id` values. Reopened classes/modules share a namespace page while retaining distinct source declarations. Namespace pages can exist for members of an undocumented container. Top-level declarations use the existing `_top-level.md` assignment. File organization uses source mappings and prefixes. Page paths are logical paths relative to `docroot`, with Markdown extensions, not a promise of emitted Markdown files or final website URLs. Website consumers map these paths to their routes.
+
+The site can derive scope landing pages and navigation from this metadata. Generated Markdown index pages are not included in `pages` because they own no declarations. A file without public declarations produces no page.
+
+JSON exports all public declarations, including those without API prose, so a site can present the selected API surface before documentation is complete. Private/protected declarations remain available to internal reference lookup but are not exported or linked. The Markdown format continues to publish only documented public declarations. This publication distinction is intentional and is not an inference that a Ruby-public declaration is a stable supported product API.
+
+## Declarations
+
+| Fields | Meaning |
+| --- | --- |
+| `id`, `page`, `anchor` | Scope-specific identity and logical page destination; `id` combines the documentation scope with the existing stable anchor. |
+| `kind`, `name`, `namespace`, `display_name`, `visibility` | Original declaration kind/name, lexical namespace, display/reference name and visibility. |
+| `parameters` | Existing source parameter labels, not a structured typed signature. |
+| `parameter_details` | Additive Ruby syntax metadata: ordered `kind`, nullable `name`, exact `source`, source `span`, nullable default-expression `default` and `default_span`. No types or evaluated values. |
+| `references` | Names by which this declaration participates in documentation reference lookup. |
+| `span`, `comment_span` | Declaration and attached comment provenance. |
+| `documentation` | Original tag data plus resolved Markdown descriptions. |
+| `contracts` | Unparsed contract channels, payloads, notes and provenance. |
+| `receiver`, `refinement`, `superclass`, `container_builder` | Written source expressions with their corresponding `*_span` fields. |
+| `alias_target` | Recorded alias target, without copying the target's documentation. |
+| `mixins` | Written mixin `kind`, `target` and `span`. |
+
+Absent optional fields are `null`; arrays remain arrays. A repeated method definition has its own identity/anchor. Nothing chooses a runtime-winning definition, resolves dynamic receivers, or asserts effective ancestry. Attribute accessors remain a source declaration with multiple reference names, rather than separate inferred getter/setter signatures.
+
+`parameter_details` is additive within revision 1; older exports may omit it and consumers fall back to `parameters`. It is `null` when no source-backed parameter list is available (including aliases and generated attributes), and `[]` for an explicit parameterless method. Kinds are `required`, `optional`, `rest`, `post`, `required_keyword`, `optional_keyword`, `keyword_rest`, `block`, `forwarding`, `no_keywords` and `implicit_rest`. Anonymous and destructured forms retain their exact source patterns with a nullable name; destructured required/post parameters keep their positional kind. Visibility changes and module-function copies retain metadata. Default expressions are never executed. A heredoc default's body is not contiguous with its parameter header: its header remains in `source`, `default`/`default_span` are unavailable and `parameter.unsupported-default` is emitted rather than presenting the opener as a complete expression.
+
+Documentation entries carry `name`, `owner`, `subject`, optional `claim`, `description`, `raw`, and `span`, matching the source model. `rendered_description` contains Markdown with resolvable ZARD references linked, using the same resolution rules as a documentation build. Original descriptions remain unchanged. Examples, raw text and inline/fenced code preserve literal reference syntax. Consumers must use their normal safe Markdown rendering policy; strings in JSON are not trusted HTML.
+
+Contract entries carry `channel`, `payload`, `note`, `raw`, and `span`. They are source text, not parsed or validated types. A documentation claim does not become a contract, signature or Rigor fact.
+
+## Source provenance and diagnostics
+
+Each selected source file has `path`, its full SHA-256 `digest` over the bytes parsed, and structured parser `diagnostics` with `code`, `severity`, `message` and `span`. Files without public declarations remain listed for provenance and diagnostics.
+
+All generated source paths are relative to the real directory containing the build configuration. Explicit source roots outside that directory can produce `../` paths; these are source identifiers, not output destinations. No absolute checkout paths are generated in provenance or reference warnings. Source-authored prose and raw text are preserved, including any paths the author wrote.
+
+Spans retain the model's 1-based lines, 0-based columns and byte offsets, including an exclusive `end_offset`. Digests cover the entire source file, including documentation comments. Neither the digest nor a declaration ID proves the semantic inputs of a future Rigor analysis are unchanged.
+
+Reference lookup searches the current documentation scope, then only its explicit direct documentation dependencies. Transitive dependencies are generated without becoming visible to lookup. Ambiguous references remain literal with warnings. The `links` entries target actual exported pages/anchors and provide route mapping input without requiring consumers to reverse-engineer references from text.
+
+## Written class and module relationships
+
+The additive `relationships` array on each declaration records written
+`superclass`, `include`, `prepend`, `extend` and `container_builder` references.
+Each entry carries the original `expression` and `span`, a `status` (`resolved`,
+`unresolved` or `expression`), and `targets`. Each target has `scope`,
+`declaration_id`, `path` and `anchor`, and names a published class or module.
+Resolved reopenings retain all published definition targets, including file
+layout. Older exports may omit the field.
+
+Resolution uses the existing documentation lookup: local before direct scope
+dependencies, without transitive fallback or first-match ambiguity resolution.
+Superclass expressions use the enclosing lexical namespace; mixins use the
+class/module body context. A local constant or unpublished target prevents
+fallthrough to a dependency. Non-constant expressions and container builders
+remain literal; no application code is loaded or evaluated. Unresolved
+relationships produce diagnostics. Target links are included in `links`.
+
+These are documentation relationships, not runtime ancestry, lookup precedence,
+overrides or inherited member facts. Consumers must retain conflicting written
+parents and guard traversal against cycles. The Astro presentation generates a
+per-scope hierarchy with separate module usage, reports cycles/conflicts, and
+preserves each definition's own source location. The `hierarchy` route within a
+scope is reserved when the extension is present; route collisions fail before
+publication. Legacy exports without the extension keep their existing routes.

data/docs/usage.md

@@ -1,17 +1,10 @@
-# ZARD 0.0.1 usage
+# ZARD 0.0.2 usage
 
-ZARD parses Ruby source into a versioned model. The separate `zard-doc` gem renders the model's human-facing API documentation as Markdown. Both `0.0.1` gems are release candidates and are not yet published on RubyGems. Until publication, use the repository as the Gem source:
+ZARD parses Ruby source into a versioned model. The separate `zard-doc` gem renders human-facing API documentation. Install the 0.0.2 pair with Bundler:
 
 ```ruby
-gem "zard", github: "rigortype/zard"
-gem "zard-doc", github: "rigortype/zard"
-```
-
-After `0.0.1` is published, install the released pair with Bundler:
-
-```ruby
-gem "zard", "~> 0.0.1"
-gem "zard-doc", "~> 0.0.1"
+gem "zard", "~> 0.0.2"
+gem "zard-doc", "~> 0.0.2"
 ```
 
 The gems require Ruby 3.2 or newer. The project is pre-1.0: the model has an explicit `Zard::Model::V1` namespace, but no general compatibility guarantee has been established yet. Review release notes when upgrading; pre-1.0 releases may change APIs and behavior.
@@ -29,6 +22,30 @@ markdown = Zard::Doc.render(document)
 
 `Zard.parse` accepts Ruby source text and a required `path:` used in provenance and diagnostics. The path labels the source; the parser does not read that file. For in-memory input, use a label such as `"example.rb"`. `Zard::Doc.render` accepts the resulting document and returns Markdown. The renderer emits documented public declarations; it does not print contracts as API prose.
 
+## Format annotations
+
+Version 0.0.2 provides `Zard.format` and `zard-doc format`:
+
+```ruby
+result = Zard.format(source, path: "lib/example.rb")
+puts result.source if result.changed?
+document = result.document
+diagnostics = result.diagnostics
+```
+
+The result contains formatted source and a freshly parsed document with spans and raw text referring to that source. The input remains unchanged. `diagnostics` includes parser diagnostics and formatting warnings.
+
+```sh
+zard-doc format lib/example.rb
+zard-doc format --check lib
+zard-doc format --write lib
+printf '# @return — Value.\ndef read = nil\n' | zard-doc format -
+```
+
+Plain mode prints one input to stdout. Check mode returns 1 if any input would change; write mode updates changed files after reading and validating all inputs. Both modes accept files and recursive directories. Standard input is supported in plain and check modes. Invocation and I/O errors return 2; source errors return 1. Warnings are printed to stderr and do not fail formatting.
+
+Formatting normalizes standalone `@extrbs` prefixes and moves them before other annotations only when reparsing preserves documentation and contract content. It removes redundant markers from untyped `@return` and `@yieldreturn`. Payloads, notes, multiline descriptions, unrelated bytes, and the original sequence of line endings are retained. YARD-like tags and ambiguous continuation boundaries are diagnosed without conversion. Invalid Ruby and non-UTF-8 source remain unchanged with errors. See [ADR 0005](adr/0005-safe-annotation-formatting.md) for the transformation limits.
+
 ## Inspect the model
 
 The document is available through `document.path`, `document.declarations`, and `document.diagnostics`. A declaration exposes `kind`, `name`, `namespace`, `visibility`, `parameters`, `receiver`, `receiver_span`, `refinement`, `refinement_span`, `alias_target`, `superclass`, `superclass_span`, `container_builder`, `container_builder_span`, `mixins`, `span`, `comment_span`, `documentation`, and `contracts`.
@@ -72,6 +89,41 @@ For example, `@param path [String] — The file path.` carries an optional docum
 
 Tags without a name or type write their description directly: `@return Normalized value.`, `@note Keep this in mind.`, and `@example Call the method.` Named tags such as `@param`, `@yieldparam`, `@raise`, and `@option` require the marker. `@option options :format — Output format.` documents an option. `@yieldreturn yielded value.` describes a yielded result. Supported tags include `@param`, `@return`, `@yieldparam`, `@yieldreturn`, `@option`, `@raise`, `@note`, `@see`, `@deprecated`, and `@example`.
 
+### See also references
+
+The complete syntax decision, including BitClust and RD compatibility forms, is recorded in [ADR 0004](adr/0004-documentation-reference-syntax.md).
+
+`@see` accepts YARD-style references followed by an optional display label, without an em dash:
+
+```ruby
+# @see Foo#bar
+# @see Foo.build Build a Foo
+# @see #bar Related instance method
+# @see .build Related class method
+# @see Kernel.#puts Legacy module-function spelling
+# @see Kernel?.puts Modern module-function spelling
+# @see https://example.com/reference Reference guide
+```
+
+`#` selects an instance method and `.` selects a class method. `.#` and `?.` are equivalent module-function spellings and link to the public singleton copy. Relative references use the current class or module; qualified references search namespace prefixes as YARD does, and a leading `::` starts at the root. This lookup also applies to qualified class openings such as `class Outer::Caller`; it does not reproduce Ruby's lexical constant lookup. A nearer declared owner prevents fallback to an unrelated outer owner when its member is missing. The first whitespace-separated token is the target and the remaining text is the display label. HTTP, HTTPS, and mailto targets become external links.
+
+`zard-doc` links references to uniquely identified public declarations with documentation in the generated output. The CLI resolves references across all input files. Unresolved, undocumented, private, ambiguous, and refinement references remain plain text. Lookup uses explicit declarations, without following inheritance or mixins or evaluating dynamic receivers. The document model retains the original description, raw comment, and source span.
+
+Explicit references work in prose and documentation tag descriptions, including `@see`:
+
+```ruby
+# Read [m:Foo#bar] or [[m:Foo#bar]].
+# @note See [c:Foo] and [m:Foo::LIMIT].
+# @see [Read a value](m:Foo#bar)
+# @see [`Foo#bar()`](m:Foo#bar)
+# @see [m:Kernel?.puts]
+# @see [[m:Kernel.#puts]]
+```
+
+`m:` selects methods or constants; `c:` selects classes or modules. BitClust's single brackets and RD's double brackets resolve to the same destinations. `[label](m:target)` supplies a display label; a label consisting entirely of a backtick code span keeps its code presentation. Escape operator brackets as `[m:Foo#\[\]]`, or use the historical RD form `[[m:Foo#[] ]]` with its delimiter-separating space.
+
+Inline code, fenced and indented code blocks, and `@example` content retain literal reference syntax. Existing Markdown links and images are preserved. Explicit forms in `@see` take precedence over shorthand parsing; unresolved forms retain their original text.
+
 Plain comment lines continue the preceding canonical documentation tag until another annotation or contract begins. No continuation marker is needed. Contract notes use ` -- ` after the contract payload and remain contract notes, not API prose. Familiar YARD-like tags without the em dash can be retained as raw text, but are not treated as documentation claims.
 
 ZARD documentation requires UTF-8 source text. Ruby source encoding declarations are respected; non-UTF-8 source can still contain contracts, but documentation text in it receives a diagnostic.
@@ -84,6 +136,52 @@ Visibility forms supported by the parser include bare visibility calls, inline f
 
 ## Command line
 
+### Build a documentation tree
+
+Version 0.0.2 provides `zard-doc build`. Define named documentation scopes in a YAML file:
+
+```yaml
+docroot: docs/api
+layout: namespace
+scopes:
+  core:
+    destination: core
+    sources:
+      - root: lib
+        include: ["**/*.rb"]
+        exclude: ["fixtures/**"]
+  playground:
+    destination: playground
+    references: [core]
+    sources:
+      - root: apps/playground/lib
+        include: ["**/*.rb"]
+```
+
+```sh
+zard-doc build --config zard-doc.yml
+zard-doc build --config zard-doc.yml --scope playground --layout file
+zard-doc build --config zard-doc.yml --format json > api.json
+```
+
+Paths are relative to the configuration file. The default layout is `namespace`: reopened classes and modules share a page, preserving each definition's description and source location. `file` preserves each source root's relative file hierarchy with `.md` extensions. A source mapping can set `prefix` to distinguish multiple roots in file layout. `include` defaults to `["**/*.rb"]`; `exclude` defaults to `[]`. Source selection uses globs independently of Git and gemspecs.
+
+CLI layout overrides configuration. With no `--scope`, all scopes are built; repeat `--scope` to select several. Selected scopes include their recursive documentation dependencies for generation. References search the current scope first, then only directly declared dependencies. Separate scopes do not merge declarations even when Ruby namespace names match. Ambiguous references remain text with warnings; local shadowing prevents fallback to unrelated dependency declarations.
+
+The default `--format markdown` publishes managed Markdown pages. `--format json` instead prints one experimental, versioned JSON document after validation and leaves `docroot` untouched. JSON includes public declarations even without prose, their original documentation and unparsed contracts, source spans and digests, page assignments, stable anchors, and resolved documentation links. Private and protected declarations are excluded. See the [JSON export contract](json-export.md) for the schema, path conventions, and differences from Markdown publication. This export does not require Rigor or a Rigor lens result.
+
+`Declaration#parameter_details` additionally records ordered Ruby parameter syntax and default-expression provenance. `Declaration#parameters` retains its existing labels for compatibility, and the Markdown renderer remains unchanged. Astro presentation uses the richer syntax when available, without assigning parameter types or evaluating defaults.
+
+Each scope has an index. Namespace pages follow Ruby namespace hierarchy, with documented top-level members in `_top-level.md`. Files without publishable declarations produce no API page. The documentation root has an index linking the scopes. Links use relative paths and stable anchors.
+
+Build reports diagnostics to stderr and does not print generated Markdown to stdout. Source errors return 1; configuration, input, ownership, and publication errors return 2. Warnings permit generation. All selected inputs and destinations are validated before publication. Missing roots or dependencies, empty source selections, conflicting destinations, and paths escaping declared roots are errors.
+
+The output manifest tracks generated pages and resolved API links. Regeneration removes obsolete managed pages, retains unrelated handwritten files, and refuses to overwrite edited managed pages or existing unowned destination files. Partial scope builds retain other scopes' managed pages and refuse changes that would invalidate their generated links; include the affected scopes or run a full build instead. Publication prepares output before writing, attempts recovery on filesystem failures, and reports recovery failures; it is not a filesystem-wide atomic transaction.
+
+This workflow uses the existing ZARD parse model. The optional `zard-rigor` gem enriches JSON through the released Rigor CLI; see its [setup and limitations](../zard-rigor/README.md). External RBS ingestion and stable lens semantics remain separate work. See [ADR 0006](adr/0006-hierarchical-documentation-output.md).
+
+### Lint and render to stdout
+
 `zard-doc lint PATH...` checks Ruby files. Directories are searched recursively for `*.rb`; paths are sorted and duplicates removed. Warnings do not fail by default. Use `--fail-on warning` to make warnings fail:
 
 ```sh

data/lib/zard/formatting/formatter.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Zard
+  class FormatResult
+    attr_reader :source, :document, :diagnostics
+
+    def initialize(source:, document:, diagnostics:, changed:)
+      @source = source.dup.freeze
+      @document = document
+      @diagnostics = diagnostics.freeze
+      @changed = changed
+      freeze
+    end
+
+    def changed?
+      @changed
+    end
+  end
+
+  module Formatting
+    class Formatter
+      def self.call(source, path:)
+        new(source, path).call
+      end
+
+      def initialize(source, path)
+        @source = source
+        @path = path
+      end
+
+      def call
+        unless @source.encoding.ascii_compatible?
+          return encoding_error("format.unsupported-encoding", "Formatting requires UTF-8 source text.")
+        end
+        parsed = Prism.parse(@source.b)
+        unless @source.dup.force_encoding(parsed.encoding).valid_encoding?
+          return encoding_error("format.invalid-encoding", "Source bytes are invalid for the declared encoding.")
+        end
+        original = Zard.parse(@source, path: @path)
+        if original.diagnostics.any? { |diagnostic| diagnostic.severity == :error }
+          return result(@source, original)
+        end
+        unless parsed.encoding == Encoding::UTF_8
+          diagnostic = format_diagnostic("format.unsupported-encoding", :error, "Formatting requires UTF-8 source text.", original.declarations.first&.span)
+          return result(@source, original, [diagnostic])
+        end
+
+        output = @source.b.dup
+        unsafe_lines = []
+        blocks = original.declarations.filter_map(&:comment_span).uniq { |span| [span.start_offset, span.end_offset] }
+        blocks.sort_by(&:start_offset).reverse_each do |span|
+          start = line_start(span.start_offset)
+          ending = (@source.b.index("\n", span.end_offset) || (@source.bytesize - 1)) + 1
+          block = @source.byteslice(start, ending - start).dup.force_encoding(parsed.encoding)
+          normalized = normalize(block, span, original)
+          ordered = reorder(normalized, literal_lines(normalized))
+          if ordered != normalized
+            baseline = replace(output, start, block.bytesize, normalized)
+            candidate = replace(output, start, block.bytesize, ordered)
+            if snapshot(Zard.parse(baseline.force_encoding(@source.encoding), path: @path)) == snapshot(Zard.parse(candidate.force_encoding(@source.encoding), path: @path))
+              normalized = ordered
+            else
+              unsafe_lines << span.start_line
+            end
+          end
+          output = replace(output, start, block.bytesize, normalized)
+        end
+        output.force_encoding(@source.encoding)
+        document = Zard.parse(output, path: @path)
+        diagnostics = unsafe_lines.sort.map do |line|
+          span = document.declarations.filter_map(&:comment_span).find { |item| item.start_line == line }
+          format_diagnostic("format.unsafe-extrbs-order", :warning, "Leave @extrbs in place because moving it would change documentation or contract content.", span)
+        end
+        result(output, document, diagnostics)
+      end
+
+      private
+
+      def result(source, document, diagnostics = [])
+        FormatResult.new(source: source, document: document, diagnostics: document.diagnostics + diagnostics, changed: source.b != @source.b)
+      end
+
+      def encoding_error(code, message)
+        diagnostic = format_diagnostic(code, :error, message, nil)
+        document = Model::V1::Document.new(path: @path, declarations: [].freeze, diagnostics: [diagnostic].freeze)
+        result(@source, document)
+      end
+
+      def line_start(offset)
+        offset.zero? ? 0 : (@source.b.rindex("\n", offset - 1) || -1) + 1
+      end
+
+      def replace(source, start, length, replacement)
+        source.byteslice(0, start).b + replacement.b + source.byteslice(start + length, source.bytesize).b
+      end
+
+      def normalize(block, span, document)
+        literal = literal_lines(block)
+        blocked = document.declarations.flat_map do |declaration|
+          declaration.documentation.each_with_index.filter_map do |tag, index|
+            next unless tag.name == :raw
+
+            continuation = tag.raw.lines.drop(1).any? { |line| !line.sub(/\A[ \t]*# ?/, "").strip.empty? }
+            example = index.positive? && declaration.documentation[index - 1].name == :example
+            tag.span.start_line if continuation || example
+          end
+        end
+        redundant = document.diagnostics.select { |diagnostic| diagnostic.code == "documentation.redundant-marker" }.map { |diagnostic| diagnostic.span.start_line }
+        ambiguous = document.declarations.flat_map(&:documentation).select do |tag|
+          %i[return yieldreturn].include?(tag.name) && tag.claim.nil? && tag.description.start_with?("[", "—")
+        end.map { |tag| tag.span.start_line }
+        block.lines.each_with_index.map do |line, index|
+          number = span.start_line + index
+          if literal.include?(index)
+            line
+          elsif !blocked.include?(number) && line.match?(/\A[ \t]*#[ \t]*@extrbs(?:[ \t]|\r?\n|\z)/)
+            line.sub(/\A([ \t]*)#[ \t]*@extrbs/, '\1# @extrbs')
+          elsif redundant.include?(number) && !ambiguous.include?(number)
+            line.sub(/(@(?:return|yieldreturn)[ \t])— ?/, '\1')
+          else
+            line
+          end
+        end.join
+      end
+
+      def literal_lines(block)
+        protected = []
+        example = false
+        fence = nil
+        block.lines.each_with_index do |line, index|
+          body = line.sub(/\A[ \t]*# ?/, "")
+          content = fence ? body : body.sub(/\A@(?:example|note|deprecated|see)(?:[ \t]|\z)/, "")
+          marker = content.match(/\A {0,3}(`{3,}|~{3,})([^\r\n]*)/)
+          if fence
+            protected << index
+            fence = nil if marker && marker[1][0] == fence[0] && marker[1].length >= fence.length && marker[2].strip.empty?
+            next
+          end
+          canonical = line.match?(/\A[ \t]*#(?: @|:)/)
+          if canonical
+            example = body.match?(/\A@example(?:[ \t]|\r?\n|\z)/)
+          elsif example
+            protected << index
+          end
+          if marker && (marker[1][0] != "`" || !marker[2].include?("`"))
+            fence = marker[1]
+            protected << index
+          end
+        end
+        protected
+      end
+
+      def reorder(block, protected)
+        lines = block.lines
+        first = lines.index { |line| line.match?(/\A[ \t]*#(?: @|:)/) }
+        return block unless first
+
+        terminators = lines.map { |line| line[/\r?\n\z/].to_s }
+        bodies = lines.map { |line| line.delete_suffix(line[/\r?\n\z/].to_s) }
+        annotations = bodies.drop(first)
+        extrbs, remaining = annotations.each_with_index.partition { |line, index| !protected.include?(first + index) && line.match?(/\A[ \t]*# @extrbs(?:[ \t]|\z)/) }
+        (bodies.take(first) + (extrbs + remaining).map(&:first)).each_with_index.map { |line, index| line + terminators[index] }.join
+      end
+
+      def snapshot(document)
+        document.declarations.map do |declaration|
+          tags = declaration.documentation.map { |tag| [tag.name, tag.owner, tag.subject, tag.claim, tag.description] }
+          contracts = declaration.contracts.map { |contract| [contract.channel, contract.payload, contract.note] }.sort_by(&:inspect)
+          [declaration.kind, declaration.name, declaration.namespace, declaration.receiver, declaration.refinement, tags, contracts]
+        end
+      end
+
+      def format_diagnostic(code, severity, message, span)
+        span ||= Model::V1::SourceSpan.new(path: @path, start_line: 1, start_column: 0, end_line: 1, end_column: 0, start_offset: 0, end_offset: 0)
+        Model::V1::Diagnostic.new(code: code, severity: severity, message: message, span: span)
+      end
+    end
+  end
+end

data/lib/zard/model/v1.rb

@@ -69,15 +69,30 @@ module Zard
         end
       end
 
+      class Parameter
+        attr_reader :kind, :name, :source, :span, :default, :default_span
+
+        def initialize(kind:, name:, source:, span:, default: nil, default_span: nil)
+          @kind = kind
+          @name = name
+          @source = source
+          @span = span
+          @default = default
+          @default_span = default_span
+          freeze
+        end
+      end
+
       class Declaration
-        attr_reader :kind, :name, :namespace, :visibility, :parameters, :receiver, :receiver_span, :refinement, :refinement_span, :alias_target, :superclass, :superclass_span, :container_builder, :container_builder_span, :mixins, :span, :comment_span, :documentation, :contracts
+        attr_reader :kind, :name, :namespace, :visibility, :parameters, :parameter_details, :receiver, :receiver_span, :refinement, :refinement_span, :alias_target, :superclass, :superclass_span, :container_builder, :container_builder_span, :mixins, :span, :comment_span, :documentation, :contracts
 
-        def initialize(kind:, name:, namespace:, visibility:, parameters:, span:, comment_span:, documentation:, contracts:, receiver: nil, receiver_span: nil, refinement: nil, refinement_span: nil, alias_target: nil, superclass: nil, superclass_span: nil, container_builder: nil, container_builder_span: nil, mixins: [].freeze)
+        def initialize(kind:, name:, namespace:, visibility:, parameters:, span:, comment_span:, documentation:, contracts:, parameter_details: nil, receiver: nil, receiver_span: nil, refinement: nil, refinement_span: nil, alias_target: nil, superclass: nil, superclass_span: nil, container_builder: nil, container_builder_span: nil, mixins: [].freeze)
           @kind = kind
           @name = name
           @namespace = namespace
           @visibility = visibility
           @parameters = parameters
+          @parameter_details = parameter_details
           @receiver = receiver
           @receiver_span = receiver_span
           @refinement = refinement

data/lib/zard/parsing/parser.rb

@@ -924,6 +924,7 @@ module Zard
           namespace: namespace,
           visibility: visibility,
           parameters: parameters,
+          parameter_details: declaration_parameters(node, kind, alias_target),
           receiver: receiver,
           receiver_span: receiver_span,
           refinement: refinement,
@@ -1315,6 +1316,7 @@ module Zard
           namespace: declaration.namespace,
           visibility: visibility,
           parameters: parameters,
+          parameter_details: declaration.parameter_details,
           receiver: declaration.receiver,
           receiver_span: declaration.receiver_span,
           refinement: declaration.refinement,
@@ -1332,6 +1334,47 @@ module Zard
         )
       end
 
+      def declaration_parameters(node, kind, alias_target)
+        return if alias_target || !%i[instance_method singleton_method].include?(kind)
+
+        parameters = if node.is_a?(Prism::DefNode)
+          node.parameters
+        elsif node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode)
+          node.block.parameters&.parameters
+        else
+          return
+        end
+        return [].freeze unless parameters
+
+        groups = [[parameters.requireds, :required], [parameters.optionals, :optional],
+          [[parameters.rest].compact, :rest], [parameters.posts, :post],
+          [parameters.keywords, :required_keyword], [[parameters.keyword_rest].compact, :keyword_rest],
+          [[parameters.block].compact, :block]]
+        groups.flat_map do |nodes, kind|
+          nodes.map { |parameter| parameter_detail(parameter, kind) }
+        end.sort_by { |parameter| parameter.span.start_offset }.freeze
+      end
+
+      def parameter_detail(parameter, kind)
+        kind = case parameter
+        when Prism::OptionalKeywordParameterNode then :optional_keyword
+        when Prism::ForwardingParameterNode then :forwarding
+        when Prism::NoKeywordsParameterNode then :no_keywords
+        when Prism::ImplicitRestNode then :implicit_rest
+        else kind
+        end
+        value = parameter.value if parameter.is_a?(Prism::OptionalParameterNode) || parameter.is_a?(Prism::OptionalKeywordParameterNode)
+        if value.respond_to?(:heredoc?) && value.heredoc?
+          @diagnostics << Model::V1::Diagnostic.new(code: "parameter.unsupported-default", severity: :warning,
+            message: "Heredoc parameter defaults retain their header; a contiguous default expression is unavailable.", span: span(value.location))
+          value = nil
+        end
+        Model::V1::Parameter.new(kind: kind,
+          name: parameter.respond_to?(:name) ? parameter.name&.to_s : nil,
+          source: parameter.location.slice, span: span(parameter.location),
+          default: value&.location&.slice, default_span: value ? span(value.location) : nil)
+      end
+
       def parameter_names(parameters)
         return [] unless parameters
 

data/lib/zard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zard
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/zard.rb

@@ -3,6 +3,7 @@
 require_relative "zard/version"
 require_relative "zard/model/v1"
 require_relative "zard/parsing/parser"
+require_relative "zard/formatting/formatter"
 
 module Zard
   class Error < StandardError; end
@@ -11,5 +12,9 @@ module Zard
     Parsing::Parser.call(source, path: path)
   end
 
-  private_constant :Parsing
+  def self.format(source, path:)
+    Formatting::Formatter.call(source, path: path)
+  end
+
+  private_constant :Parsing, :Formatting
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zard
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - USAMI Kenta
@@ -38,15 +38,20 @@ files:
 - docs/adr/0001-contract-and-documentation-channels.md
 - docs/adr/0002-em-dash-zard-documentation-marker.md
 - docs/adr/0003-package-boundaries-and-rigor-lens.md
+- docs/adr/0004-documentation-reference-syntax.md
+- docs/adr/0005-safe-annotation-formatting.md
+- docs/adr/0006-hierarchical-documentation-output.md
 - docs/agents/domain.md
 - docs/agents/issue-tracker.md
 - docs/agents/triage-labels.md
+- docs/json-export.md
 - docs/supported-ruby-syntax.md
 - docs/usage.md
 - examples/catalog/expected.md
 - examples/catalog/lib/catalog.rb
 - examples/catalog/lib/catalog/entry.rb
 - lib/zard.rb
+- lib/zard/formatting/formatter.rb
 - lib/zard/model/v1.rb
 - lib/zard/parsing/parser.rb
 - lib/zard/version.rb
@@ -74,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.20
+rubygems_version: 4.0.16
 specification_version: 4
 summary: AI-friendly Ruby documentation built on RBS and Rigor extensions
 test_files: []