zard 0.0.1

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

@@ -0,0 +1,29 @@
+# Use an em dash for named or typed ZARD documentation tags
+
+ZARD uses an em dash `—` when a named documentation tag or an optional type must be separated from its description. A tag with neither a name nor a type writes its description directly. InlineRBS keeps `--` as its own contract-note syntax inside `@extrbs`; a YARD-like tag without the required `—` is not a ZARD type hint.
+
+## Consequences
+
+- `@param value — Input text.` is ZARD documentation.
+- `@param value [String] — Input text.` is ZARD documentation with a claim.
+- `@return Normalized text.` is ZARD documentation without a type claim.
+- `@return — Normalized text.` is accepted, but `zard-doc lint` recommends removing the redundant em dash.
+- `@return [String] — Normalized text.` is ZARD documentation with a claim.
+- `@return [String] Normalized text.` is YARD-like raw text, not a type hint.
+- `@yieldreturn yielded value.` follows the same rule as `@return`.
+- `@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.
+- `@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.
+- `zard-doc lint` may warn when a documentation claim repeats a contract type.
+- ZARD documentation tags require UTF-8 source text. Ruby source encoding declarations remain respected.
+- Every canonical ZARD documentation tag may continue across plain comment lines until another annotation or contract begins; no explicit continuation marker is used.
+- An annotation is recognized only in the first content column immediately after `# `. Indented `@` text remains description content.
+- Internal blank lines, relative indentation, and trailing whitespace are preserved. Leading and trailing blank continuation lines are removed from the normalized description.
+- A multiline description remains one LF-normalized string. Its source span and raw text cover the complete comment block, with raw source bytes and line endings preserved.
+- YARD-like and unknown tags keep their continuation lines as raw text and do not leak them into API documentation.
+- Empty descriptions are preserved with a `documentation.empty-description` warning.
+- Contract annotations end documentation continuation. Contract notes do not use documentation continuation rules.
+- Markdown renderers keep multiline descriptions inside their list item and do not automatically fence `@example` content as code.

data/docs/adr/0003-package-boundaries-and-rigor-lens.md

@@ -0,0 +1,15 @@
+# Keep the core independent from Rigor and pin the grammar
+
+The project uses a monorepo with separate gems for the ZARD core, API documentation, and Rigor integration. The core owns ZARD syntax, tag boundaries, source spans, provenance, and the versioned public model; it keeps `@extrbs` type payloads as text. Rigor owns the payload grammar, grammar revision, inference, and facts; API documentation consumes a versioned structured Rigor lens result when it is available. Subtree splitting is not part of the initial distribution plan.
+
+## Consequences
+
+- The core can parse and model ZARD without Rigor.
+- The core does not duplicate Rigor's type parser or type semantics.
+- An adapter declares the supported `rigor:v1` grammar revision.
+- `@extrbs` comes first in an annotation block and uses exactly `# @extrbs` with one space.
+- A formatter preserves that order and spacing.
+- Rigor generates `sig/`; the project does not hand-maintain duplicate contracts there.
+- API documentation can be generated without Rigor, but resolved type facts are then unavailable.
+- The Rigor adapter must not expose Rigor internal analyzer classes as the package boundary.
+- The first vertical slice carries class, module, constant, attribute, and method declarations from Ruby source through the ZARD model to Markdown documentation.

data/docs/agents/domain.md

@@ -0,0 +1,15 @@
+# Domain Docs
+
+Before exploring code, read `CONTEXT.md` at the repo root.
+Also read ADRs in `docs/adr/` that relate to the work.
+
+If these files do not exist, continue silently.
+
+This repo uses a single-context layout:
+
+- `CONTEXT.md`: domain terms and system context
+- `docs/adr/`: architecture decisions
+
+Use terms from `CONTEXT.md` in issue titles, plans, and tests.
+If a needed term is missing, note the gap.
+If a change conflicts with an ADR, call out the conflict.

data/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live in GitHub Issues. Use the `gh` CLI.
+
+## Writing style
+
+Write issue and PR titles, descriptions, and comments in concise English. Lead with the requested behavior or final change. Retain acceptance criteria, dependencies, and relevant validation; link to shared evidence instead of repeating it.
+
+## Conventions
+
+- Create: `gh issue create --title "..." --body "..."`
+- Read: `gh issue view <number> --comments`
+- List: `gh issue list --state open`
+- Comment: `gh issue comment <number> --body "..."`
+- Add a label: `gh issue edit <number> --add-label "..."`
+- Remove a label: `gh issue edit <number> --remove-label "..."`
+- Close: `gh issue close <number> --comment "..."`
+
+PRs are not a triage request surface.
+
+When a skill says to publish to the issue tracker, create a GitHub issue.
+When a skill says to fetch a ticket, run `gh issue view <number> --comments`.

data/docs/agents/triage-labels.md

@@ -0,0 +1,11 @@
+# Triage Labels
+
+Use these labels for the five triage roles.
+
+| Role | Label | Meaning |
+| --- | --- | --- |
+| Needs triage | `needs-triage` | A maintainer must review the issue |
+| Needs information | `needs-info` | The reporter must provide more information |
+| Ready for agent | `ready-for-agent` | The issue is ready for an agent |
+| Ready for human | `ready-for-human` | A human must implement the work |
+| Won't fix | `wontfix` | The issue will not be fixed |

data/docs/supported-ruby-syntax.md

@@ -0,0 +1,55 @@
+# Supported Ruby Semantics
+
+The ZARD parser models modern Ruby declarations statically without executing code. Runtime ancestry, dynamic metaprogramming, and foreign object evaluations are intentionally left unresolved.
+
+### Visibility & Modifiers
+
+- Declarations record `public`, `protected`, or `private` visibility. Markdown output includes public declarations only.
+- Bare visibility calls, inline forms (`private def`, `private attr_reader`), named method modifiers (`private :read`), and `private_class_method` / `public_class_method` are supported.
+- Visibility calls received by `self` belong to the current scope (method scope for instance visibility, singleton method scope for class methods).
+- `module_function` records its private instance method and public singleton copy as separate declarations with shared provenance. Bare, named, inline, and splatted forms (`module_function(*attr_accessor(:name))`) are supported.
+- `module_function` received by `self` belongs to the current module, like its bare form. Named `module_function` calls may target generated attribute methods, preserving the other accessor side with its original visibility.
+
+### Attributes, Aliases & Method Removal
+
+- Ruby `attr` declarations default to readers; the legacy `attr :name, true` form is preserved as an accessor. Attributes received by `self` belong to the current owner.
+- Named attribute visibility modifiers are diagnosed because one attribute declaration may generate two methods; use lexical or inline visibility instead.
+- Method aliases preserve their target name and inherit visibility and parameters when declared in the same source scope. Generated attribute readers and writers are valid alias targets (writer aliases use the conventional `value` parameter).
+- Inline visibility and `module_function` modifiers around `alias_method` apply to the resulting alias. `alias_method` received by `self` belongs to the current method scope.
+- Alias documentation remains separate from target documentation.
+- `undef`, `undef_method`, and `remove_method` remove declarations from the current method scope. Removing or replacing one side of an attribute accessor preserves the other side.
+- Later method, alias, and attribute definitions replace earlier declarations of the same name in the same source scope.
+
+### Dynamic Definitions & Evaluation Blocks
+
+- Literal `define_method` and `define_singleton_method` calls produce method declarations with preserved block parameters, visibility, receiver, refinement scope, and documentation provenance.
+- `define_method` received by `self` belongs to the current method scope.
+- Inline `private define_method`, `module_function define_method`, and class-method visibility modifiers around `define_singleton_method` preserve the visibility produced by Ruby.
+- Declarations in bare or `self` evaluation blocks remain in the current owner. Blocks evaluated by another receiver are not attributed to the lexical owner.
+- In bare or `self.instance_eval` blocks, bare `def` becomes a singleton method, while method-definition calls, attributes, and constants retain their lexical owner. Foreign instance-evaluation blocks are not resolved.
+
+### Classes, Modules & Container Builders
+
+- Class declarations preserve explicit superclass expressions and source spans without resolving runtime ancestry.
+- Assignments from `Data.define`, `Struct.new`, and `Class.new` produce class declarations; assignments from `Module.new` produce module declarations. Container builders preserve generated attributes and block members within the container scope.
+- Literal Symbol and String member names produce generated attributes; the leading String class name accepted by `Struct.new` is not a member.
+- Named subclasses (e.g. `class Point < Data.define(:x)`) preserve generated attributes while retaining the explicit superclass expression.
+- `Class.new(Struct.new(...))` and `Class.new(Data.define(...))` chains preserve inherited generated attributes when no intermediate factory block can override them.
+- Standard library `DelegateClass(Target)` calls are treated as class builders and preserve the delegated target expression as source provenance.
+- Conditional container builders (`||=`, `Registry = Registry || Module.new`) and transparent `.freeze` tails (including repeated or block forms) are supported.
+
+### Mixins, Singletons & Refinements
+
+- `include`, `prepend`, and `extend` targets are preserved with source spans and listed in documented containers without resolving inheritance trees. Mixin calls received by `self` belong to the current container.
+- Singleton methods and attributes preserve explicit receiver expressions (or `class <<` expressions).
+- Ruby `refine` blocks and their members remain scoped to the refinement target and separate from ordinary module members. `refine` received by `self` belongs to the current module.
+
+### Constants & Namespaces
+
+- `private_constant` and `public_constant` update constant visibility in the same namespace. Constant visibility calls received by `self` belong to the current namespace.
+- Bare or `self.autoload` calls with literal Symbol or String names produce constant declarations for the current ordinary owner without guessing the loaded value's kind.
+- Bare or `self.const_set` calls with literal names produce declarations in the current ordinary class or module body; container-builder values retain their generated scope.
+- `remove_const` removes matching declarations and their nested APIs from the current namespace. Unconditional assignments and literal `const_set` replace earlier declarations, while conditional initialization (`||=`) is non-destructive.
+
+See the [usage guide](usage.md) for installation, model access, and CLI behavior.
+

data/docs/usage.md

@@ -0,0 +1,124 @@
+# ZARD 0.0.1 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:
+
+```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"
+```
+
+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.
+
+## Parse and render
+
+```ruby
+require "zard"
+require "zard/doc"
+
+source = File.read("lib/example.rb")
+document = Zard.parse(source, path: "lib/example.rb")
+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.
+
+## 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`.
+
+Documentation entries are `DocumentationTag` objects with `name`, `owner`, `subject`, `claim`, `description`, `span`, and `raw`. Contract entries are `Contract` objects with `channel`, `payload`, `note`, `span`, and `raw`. Mixins expose `kind`, `target`, and `span`. Diagnostics expose `code`, `severity`, `message`, and `span`.
+
+Every source span exposes `path`, `start_line`, `start_column`, `end_line`, `end_column`, `start_offset`, and `end_offset`. Lines are one-based; columns and byte offsets are zero-based, and end positions are exclusive. Raw source and spans make it possible to trace modeled content back to its source. For example:
+
+```ruby
+document.declarations.each do |declaration|
+  declaration.contracts.each do |contract|
+    puts "#{contract.channel}: #{contract.payload} at #{contract.span.path}:#{contract.span.start_line}"
+  end
+end
+
+document.diagnostics.each do |diagnostic|
+  span = diagnostic.span
+  warn "#{span.path}:#{span.start_line}: #{diagnostic.severity} #{diagnostic.code}: #{diagnostic.message}"
+end
+```
+
+## Contracts and API documentation
+
+Use `@rbs` or `#:` for plain RBS contracts and `@extrbs` for Rigor-specific type information. The parser preserves contract payloads as text; it does not parse or validate their types. Keep contracts distinct from API prose. The `zard-doc` renderer does not copy contract text into Markdown.
+
+ZARD uses an em dash (`—`) between a named documentation tag (or an optional type claim) and its description:
+
+```ruby
+# @extrbs return: non-empty-string
+# @rbs path: String
+# @rbs return: String
+# @param path — Path to the name file.
+# @return The stored name.
+# @raise IOError — If the file cannot be read.
+def read_name(path)
+  File.read(path).strip
+end
+```
+
+For example, `@param path [String] — The file path.` carries an optional documentation claim. It is not a substitute for `@rbs path: String` and is not checked by this project: there is no Rigor claim checking in this release. The parser may diagnose malformed or noncanonical documentation syntax, but does not validate claims against contracts.
+
+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`.
+
+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.
+
+## Visibility and analysis boundaries
+
+Declarations carry `:public`, `:protected`, or `:private` visibility. `zard-doc` renders only public declarations. The parser statically models supported Ruby declaration forms; it does not execute the program. Runtime-generated declarations, dynamic names, and effects that cannot be determined from supported syntax are not resolved. Superclass, mixin, receiver, and refinement expressions are retained as source references; runtime ancestry and object identity are not inferred.
+
+Visibility forms supported by the parser include bare visibility calls, inline forms such as `private def` and `private attr_reader`, named method modifiers such as `private :read`, and `private_class_method` / `public_class_method`. Named attribute modifiers produce a diagnostic because an attribute declaration can generate more than one method. See the [supported Ruby syntax guide](supported-ruby-syntax.md) for detailed coverage.
+
+## Command line
+
+`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
+zard-doc lint lib
+zard-doc lint --fail-on warning lib/example.rb
+```
+
+`zard-doc render PATH...` renders Markdown to standard output:
+
+```sh
+zard-doc render lib
+```
+
+Use `-` as a path to read Ruby source from standard input with either command:
+
+```sh
+printf '%s\n' '# @return A value.' 'def value = 1' | zard-doc render -
+printf '%s\n' '# @param value [String] A value.' 'def value = 1' | zard-doc lint -
+```
+
+Exit codes:
+
+- `0`: success; for `lint`, no diagnostic reached the configured failure threshold.
+- `1`: `lint` found a diagnostic at or above its threshold, or `render` found an error diagnostic.
+- `2`: invalid command or options, no Ruby sources found, or an input could not be read.
+
+The default lint threshold is `error`. Lint diagnostics are written to standard output. Render diagnostics are written to standard error, and rendering does not emit partial Markdown when an input cannot be read or has an error diagnostic. Calling `Zard::Doc.render` directly does not enforce this CLI error policy; inspect `document.diagnostics` before rendering in an application.
+
+## Complete example
+
+The repository includes a multi-file catalog example and its expected Markdown:
+
+```sh
+bundle exec zard-doc lint examples/catalog/lib
+bundle exec zard-doc render examples/catalog/lib
+```
+
+See [the example source](../examples/catalog/lib) and [expected output](../examples/catalog/expected.md). The default verification task exercises this example through the CLI and checks retained contracts and source provenance in the model.

data/examples/catalog/expected.md

@@ -0,0 +1,51 @@
+## Module `Catalog`
+
+Catalog keeps a small collection of named entries.
+
+## Constant `Catalog::DEFAULT_LIMIT`
+
+The default number of entries returned by a search.
+
+## Class `Catalog::Entry`
+
+A named entry in a catalog.
+This description continues on a plain comment line
+until the next annotation or declaration.
+
+## `Catalog::Entry.read_name(path)`
+
+### Parameters
+
+- `path` — Path to the name file.
+
+### Returns
+
+The stored name.
+
+## `Catalog::Entry#initialize(name)`
+
+### Parameters
+
+- `name` — Name to store.
+
+### Returns
+
+The new entry.
+
+## Attribute reader `Catalog::Entry#name`
+
+The stored entry name.
+
+## `Catalog::Entry#label()`
+
+### Returns
+
+The entry name.
+
+## Alias `Catalog::Entry#title`
+
+Alias of `Catalog::Entry#label`.
+
+### Returns
+
+The entry name.

data/examples/catalog/lib/catalog/entry.rb

@@ -0,0 +1,45 @@
+module Catalog
+  # A named entry in a catalog.
+  # This description continues on a plain comment line
+  # until the next annotation or declaration.
+  class Entry
+    # @extrbs return: non-empty-string
+    # @rbs path: String
+    # @rbs return: String -- The stored value.
+    # @param path — Path to the name file.
+    # @return The stored name.
+    def self.read_name(path)
+      File.read(path).strip
+    end
+
+    # @param name — Name to store.
+    # @return The new entry.
+    def initialize(name)
+      @name = name
+    end
+
+    # The stored entry name.
+    attr_reader :name
+
+    # @return The entry name.
+    def label
+      name
+    end
+
+    # @return The entry name.
+    alias_method :title, :label
+
+    # @return Internal identifier.
+    def internal_id
+      name
+    end
+    private :internal_id
+
+    protected
+
+    # @return Whether the entry matches.
+    def matches?(candidate)
+      name == candidate
+    end
+  end
+end

data/examples/catalog/lib/catalog.rb

@@ -0,0 +1,5 @@
+# Catalog keeps a small collection of named entries.
+module Catalog
+  # The default number of entries returned by a search.
+  DEFAULT_LIMIT = 10
+end

data/lib/zard/model/v1.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Zard
+  module Model
+    module V1
+      class SourceSpan
+        attr_reader :path, :start_line, :start_column, :end_line, :end_column, :start_offset, :end_offset
+
+        def initialize(path:, start_line:, start_column:, end_line:, end_column:, start_offset:, end_offset:)
+          @path = path
+          @start_line = start_line
+          @start_column = start_column
+          @end_line = end_line
+          @end_column = end_column
+          @start_offset = start_offset
+          @end_offset = end_offset
+          freeze
+        end
+      end
+
+      class Diagnostic
+        attr_reader :code, :severity, :message, :span
+
+        def initialize(code:, severity:, message:, span:)
+          @code = code
+          @severity = severity
+          @message = message
+          @span = span
+          freeze
+        end
+      end
+
+      class Contract
+        attr_reader :channel, :payload, :note, :span, :raw
+
+        def initialize(channel:, payload:, note:, span:, raw:)
+          @channel = channel
+          @payload = payload
+          @note = note
+          @span = span
+          @raw = raw
+          freeze
+        end
+      end
+
+      class DocumentationTag
+        attr_reader :name, :owner, :subject, :claim, :description, :span, :raw
+
+        def initialize(name:, owner:, subject:, claim:, description:, span:, raw:)
+          @name = name
+          @owner = owner
+          @subject = subject
+          @claim = claim
+          @description = description
+          @span = span
+          @raw = raw
+          freeze
+        end
+      end
+
+      class MixinReference
+        attr_reader :kind, :target, :span
+
+        def initialize(kind:, target:, span:)
+          @kind = kind
+          @target = target
+          @span = 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
+
+        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)
+          @kind = kind
+          @name = name
+          @namespace = namespace
+          @visibility = visibility
+          @parameters = parameters
+          @receiver = receiver
+          @receiver_span = receiver_span
+          @refinement = refinement
+          @refinement_span = refinement_span
+          @alias_target = alias_target
+          @superclass = superclass
+          @superclass_span = superclass_span
+          @container_builder = container_builder
+          @container_builder_span = container_builder_span
+          @mixins = mixins
+          @span = span
+          @comment_span = comment_span
+          @documentation = documentation
+          @contracts = contracts
+          freeze
+        end
+      end
+
+      class Document
+        attr_reader :path, :declarations, :diagnostics
+
+        def initialize(path:, declarations:, diagnostics:)
+          @path = path
+          @declarations = declarations
+          @diagnostics = diagnostics
+          freeze
+        end
+      end
+    end
+  end
+end