requirements-as-code 0.7.0__tar.gz → 0.7.1__tar.gz

{requirements_as_code-0.7.0/requirements_as_code.egg-info → requirements_as_code-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.7.0
+Version: 0.7.1
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -863,6 +863,78 @@ registered schemas are supported; custom schemas are out of scope.
 
 ---
 
+## Relationships
+
+Inspect the explicit [relationship metadata](#relationship-metadata) declared
+across a repository — a deterministic, read-only view of how artifacts reference
+one another, without opening every file.
+
+```bash
+rac relationships planning/
+rac relationships planning/ --json
+rac relationships planning/ --top-level     # don't recurse into subdirectories
+rac relationships requirements/search.md    # a single file works too
+```
+
+```text
+Relationships
+
+Files Inspected: 24
+Artifacts With Relationships: 8
+Relationships Found: 14
+
+By Type:
+- Related Requirements: 4
+- Related Decisions: 6
+- Related Roadmaps: 2
+- Related Prompts: 1
+- Supersedes: 1
+
+requirements/search.md
+  Related Decisions:
+  - ADR-004
+```
+
+`--json` returns structured data for automation and future viewers (ADR-015 —
+relationship intelligence lives in RAC Core, not the UI):
+
+```json
+{
+  "directory": "planning",
+  "recursive": true,
+  "total_files": 24,
+  "artifacts_with_relationships": 8,
+  "relationship_count": 14,
+  "counts": { "related_decisions": 6, "related_requirements": 4 },
+  "artifacts": [
+    {
+      "path": "requirements/search.md",
+      "type": "requirement",
+      "relationships": { "related_decisions": ["ADR-004"] }
+    }
+  ]
+}
+```
+
+Notes:
+
+- **Counts are individual references.** `relationship_count` equals
+  `sum(counts.values())`; an artifact listing two decisions contributes two.
+- **`total_files`** counts every Markdown file considered — including files with
+  no relationships and Unknown artifacts.
+- **Supersedes is a relationship here.** Unlike `rac inspect` (where `supersedes`
+  is a top-level scalar), this command reports it alongside the `related_*`
+  sections, in both `counts` and per-artifact `relationships`.
+- **Spec-driven.** Extraction is keyed off each artifact type's declared sections.
+  Unknown artifacts are counted but contribute no relationships (and never appear
+  in `artifacts`); RAC does not scan arbitrary Markdown.
+- **Read-only and exit `0`.** The command never modifies files and exits `0`
+  whether or not relationships are found (`2` only for a missing path or a
+  non-Markdown file). It does **not** resolve or validate targets — broken-link
+  detection is a later release.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.0 → requirements_as_code-0.7.1}/README.md

@@ -823,6 +823,78 @@ registered schemas are supported; custom schemas are out of scope.
 
 ---
 
+## Relationships
+
+Inspect the explicit [relationship metadata](#relationship-metadata) declared
+across a repository — a deterministic, read-only view of how artifacts reference
+one another, without opening every file.
+
+```bash
+rac relationships planning/
+rac relationships planning/ --json
+rac relationships planning/ --top-level     # don't recurse into subdirectories
+rac relationships requirements/search.md    # a single file works too
+```
+
+```text
+Relationships
+
+Files Inspected: 24
+Artifacts With Relationships: 8
+Relationships Found: 14
+
+By Type:
+- Related Requirements: 4
+- Related Decisions: 6
+- Related Roadmaps: 2
+- Related Prompts: 1
+- Supersedes: 1
+
+requirements/search.md
+  Related Decisions:
+  - ADR-004
+```
+
+`--json` returns structured data for automation and future viewers (ADR-015 —
+relationship intelligence lives in RAC Core, not the UI):
+
+```json
+{
+  "directory": "planning",
+  "recursive": true,
+  "total_files": 24,
+  "artifacts_with_relationships": 8,
+  "relationship_count": 14,
+  "counts": { "related_decisions": 6, "related_requirements": 4 },
+  "artifacts": [
+    {
+      "path": "requirements/search.md",
+      "type": "requirement",
+      "relationships": { "related_decisions": ["ADR-004"] }
+    }
+  ]
+}
+```
+
+Notes:
+
+- **Counts are individual references.** `relationship_count` equals
+  `sum(counts.values())`; an artifact listing two decisions contributes two.
+- **`total_files`** counts every Markdown file considered — including files with
+  no relationships and Unknown artifacts.
+- **Supersedes is a relationship here.** Unlike `rac inspect` (where `supersedes`
+  is a top-level scalar), this command reports it alongside the `related_*`
+  sections, in both `counts` and per-artifact `relationships`.
+- **Spec-driven.** Extraction is keyed off each artifact type's declared sections.
+  Unknown artifacts are counted but contribute no relationships (and never appear
+  in `artifacts`); RAC does not scan arbitrary Markdown.
+- **Read-only and exit `0`.** The command never modifies files and exits `0`
+  whether or not relationships are found (`2` only for a missing path or a
+  non-Markdown file). It does **not** resolve or validate targets — broken-link
+  detection is a later release.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.0 → requirements_as_code-0.7.1}/rac/artifacts.py

@@ -68,23 +68,11 @@ class ArtifactSpec:
 # extracted, but never scored, never templated, never reported as missing
 # (REQ-002). v0.7.0 treats them as metadata only — RAC extracts and counts the
 # references but does not resolve, validate, or graph them.
-
-# The cross-artifact "Related X" sections. These populate the ``relationships``
-# dict in ``rac inspect`` output. ``related designs`` is included so every peer
-# artifact type can be referenced.
-RELATED_SECTIONS: tuple[str, ...] = (
-    "related requirements",
-    "related decisions",
-    "related roadmaps",
-    "related prompts",
-    "related designs",
-)
-
-# The full relationship-section vocabulary, including ``supersedes``. ``stats``
-# counts presence across all of these. ``supersedes`` is the one exception that
-# does *not* appear in the inspect ``relationships`` dict: it remains a top-level
-# scalar field for backwards compatibility (see rac.inspect / ADR-007).
-RELATIONSHIP_SECTIONS: tuple[str, ...] = RELATED_SECTIONS + ("supersedes",)
+#
+# The relationship-section vocabulary and its canonical ordering live in
+# :mod:`rac.relationships` (the module that owns relationship logic). This module
+# only owns the human-facing ``descriptions`` for those sections, which the specs
+# below consume.
 
 # One-line descriptions for every relationship section, surfaced by `rac schema`.
 # Relationship sections deliberately carry no ``guidance`` — guidance gates

{requirements_as_code-0.7.0 → requirements_as_code-0.7.1}/rac/cli.py

@@ -8,9 +8,11 @@ Commands:
     rac inspect <file.md | -> [--json]
     rac improve <file.md | -> [--json | --template]
     rac schema [--list] [type] [--json | --template]
+    rac relationships <dir | file.md> [--json] [--top-level]
 
 Exit codes:
-    0  success (incl. inspect/improve reporting Unknown)
+    0  success (incl. inspect/improve reporting Unknown; relationships found or
+       not)
     1  validate: errors found; stats: no valid known artifacts; ingest:
        conversion failed
     2  usage / IO error (file not found, not a directory, unsupported type,
@@ -31,6 +33,10 @@ from .classification import score_artifacts
 from .improve import improve_product
 from .inspect import build_inspection, inspect_directory
 from .parser import parse, parse_file
+from .relationships import (
+    build_relationship_report,
+    build_relationship_report_file,
+)
 from .schema import available_schemas, schema_reference
 from .stats import collect_stats
 from .validate import has_errors, validate
@@ -236,6 +242,34 @@ def cmd_schema(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def cmd_relationships(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if path.is_dir():
+        # --recursive is the default; --top-level disables it. If both are given,
+        # --top-level wins (mirrors `rac inspect`).
+        report = build_relationship_report(args.path, recursive=not args.top_level)
+    elif path.is_file():
+        if path.suffix.lower() not in (".md", ".markdown"):
+            print(
+                f"rac: relationships expects a Markdown file or directory; "
+                f"convert it first with: rac ingest {args.path}",
+                file=sys.stderr,
+            )
+            raise SystemExit(EXIT_USAGE)
+        report = build_relationship_report_file(args.path)
+    else:
+        print(f"rac: path not found: {args.path}", file=sys.stderr)
+        raise SystemExit(EXIT_USAGE)
+
+    if args.json:
+        print(outputs.render_relationships_json(report))
+    else:
+        print(outputs.render_relationships_human(report))
+    # A completed inspection always succeeds — finding no relationships is a valid
+    # outcome, not an error (REQ-010).
+    return EXIT_OK
+
+
 def build_parser() -> argparse.ArgumentParser:
     version_str = f"rac {__version__}"
 
@@ -387,6 +421,29 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_schema.set_defaults(func=cmd_schema)
 
+    p_relationships = sub.add_parser(
+        "relationships",
+        help="Inspect explicit relationships across a directory (or single file).",
+        parents=[version_parent],
+    )
+    p_relationships.add_argument(
+        "path", help="A directory to scan, or a single Markdown file."
+    )
+    p_relationships.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of human-readable text."
+    )
+    p_relationships.add_argument(
+        "--top-level",
+        action="store_true",
+        help="When inspecting a directory, only its top-level files (no recursion).",
+    )
+    p_relationships.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Recurse into subdirectories (the default; accepted for clarity).",
+    )
+    p_relationships.set_defaults(func=cmd_relationships)
+
     return parser
 
 

{requirements_as_code-0.7.0 → requirements_as_code-0.7.1}/rac/outputs.py

@@ -16,6 +16,7 @@ from .improve import ImprovementResult
 from .ingest import IngestResult
 from .inspect import DirectoryInspection, InspectionResult
 from .models import Diff, Issue, Product
+from .relationships import RelationshipReport
 from .schema import SchemaReference, template_sections
 from .stats import PortfolioStats
 
@@ -623,6 +624,61 @@ def render_schema_template(ref: SchemaReference) -> str:
     return "\n\n".join(blocks) + "\n"
 
 
+# --- relationships -----------------------------------------------------------
+
+
+def _relationship_label(snake_section: str) -> str:
+    """``related_decisions`` -> ``Related Decisions``; ``supersedes`` -> ``Supersedes``."""
+    return snake_section.replace("_", " ").title()
+
+
+def render_relationships_human(report: RelationshipReport) -> str:
+    lines = [
+        _bold("Relationships"),
+        "",
+        f"Files Inspected: {report.total_files}",
+        f"Artifacts With Relationships: {report.artifacts_with_relationships}",
+        f"Relationships Found: {report.relationship_count}",
+    ]
+
+    counts = report.counts
+    if counts:
+        lines += ["", _bold("By Type:")]
+        lines.extend(
+            f"- {_relationship_label(section)}: {count}"
+            for section, count in counts.items()
+        )
+
+    # Per-artifact detail (REQ-005), only for artifacts that declare relationships.
+    for artifact in report.artifacts:
+        lines += ["", artifact.path]
+        for section, refs in artifact.relationships.items():
+            lines.append(f"  {_relationship_label(section)}:")
+            lines.extend(f"  - {ref}" for ref in refs)
+
+    return "\n".join(lines)
+
+
+def render_relationships_json(report: RelationshipReport) -> str:
+    payload = {
+        "directory": report.directory,
+        "recursive": report.recursive,
+        "total_files": report.total_files,
+        "artifacts_with_relationships": report.artifacts_with_relationships,
+        "relationship_count": report.relationship_count,
+        "counts": report.counts,
+        "artifacts": [
+            {
+                "path": artifact.path,
+                "type": artifact.type,
+                "relationships": artifact.relationships,
+            }
+            for artifact in report.artifacts
+        ],
+    }
+    return json.dumps(payload, indent=2)
+
+
 # --- ingest ------------------------------------------------------------------
 
 

requirements_as_code-0.7.1/rac/relationships.py

@@ -0,0 +1,241 @@
+"""Relationship metadata service — extract cross-artifact references (v0.7.0).
+
+Relationships are explicit Markdown sections (``## Related Decisions``,
+``## Supersedes``, ...) that reference other artifacts (ADR-016). This module is
+the single home for turning those sections into reference strings, shared by
+``rac inspect`` (which exposes them as the additive ``relationships`` field) and
+``rac stats`` (which counts their presence).
+
+It is pure and deterministic (ADR-002 / ADR-016): it parses section text only and
+never resolves, validates, or graphs the references — v0.7.0 is metadata only.
+
+Recognition is spec-driven (REQ-002): only the relationship sections an artifact
+type declares in :attr:`ArtifactSpec.optional` are considered, so a section is
+recognized exactly where its schema allows it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .artifacts import ArtifactSpec, spec_for
+from .classification import classify
+from .fs import find_markdown_files
+from .models import Product
+from .parser import parse_file
+
+# The cross-artifact "Related X" sections. These populate the ``relationships``
+# dict in ``rac inspect`` output. ``related designs`` is included so every peer
+# artifact type can be referenced.
+RELATED_SECTIONS: tuple[str, ...] = (
+    "related requirements",
+    "related decisions",
+    "related roadmaps",
+    "related prompts",
+    "related designs",
+)
+
+# The full relationship-section vocabulary and its canonical ordering, including
+# ``supersedes``. This module owns the ordering; ``stats`` and the
+# ``relationships`` command both render by-type output in this order. ``supersedes``
+# is the one section that does *not* appear in the inspect ``relationships`` dict:
+# there it stays a top-level scalar for backwards compatibility (ADR-007).
+RELATIONSHIP_SECTIONS: tuple[str, ...] = RELATED_SECTIONS + ("supersedes",)
+
+# A *well-formed* leading Markdown list marker: ``-``, ``*``, ``+``, or ``N.``
+# followed by whitespace. Only these are stripped; any other leading text is
+# preserved verbatim, so references like "REQ-001 (blocked)" or a path beginning
+# with "../" survive intact (the whole line is the reference, per ADR-016).
+_LIST_MARKER_RE = re.compile(r"^(?:[-*+]|\d+\.)\s+")
+
+
+def _snake(section: str) -> str:
+    return section.replace(" ", "_")
+
+
+def parse_references(body: str) -> list[str]:
+    """Split a relationship section body into individual reference strings.
+
+    One reference per non-empty line. A well-formed leading list marker is
+    stripped; otherwise the line is preserved verbatim. No ID parsing and no
+    resolution — the line text *is* the reference.
+    """
+    references: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        references.append(_LIST_MARKER_RE.sub("", stripped, count=1).strip())
+    return references
+
+
+def _collect(
+    product: Product, spec: ArtifactSpec, allowed: tuple[str, ...]
+) -> dict[str, list[str]]:
+    """References for the relationship sections in ``spec.optional`` ∩ ``allowed``.
+
+    Returns ``{snake_section -> [references]}`` in ``spec.optional`` order (each
+    artifact's own schema order), including only sections present with at least
+    one parsed reference. The single core behind the two public extractors.
+    """
+    relationships: dict[str, list[str]] = {}
+    for section in spec.optional:
+        if section not in allowed:
+            continue
+        body = product.sections.get(section)
+        if not body:
+            continue
+        refs = parse_references(body)
+        if refs:
+            relationships[_snake(section)] = refs
+    return relationships
+
+
+def extract_relationships(product: Product, spec: ArtifactSpec) -> dict[str, list[str]]:
+    """Cross-artifact references for ``rac inspect``.
+
+    Excludes ``supersedes`` — that stays a top-level scalar in inspect output
+    (ADR-007). Order follows ``spec.optional`` (the artifact's own schema order).
+    """
+    return _collect(product, spec, RELATED_SECTIONS)
+
+
+def extract_relationships_full(
+    product: Product, spec: ArtifactSpec
+) -> dict[str, list[str]]:
+    """Cross-artifact references for ``rac relationships`` — *including* Supersedes.
+
+    The repository-level relationship command treats Supersedes as a first-class
+    relationship (REQ-003), so it is reported here alongside the ``related_*``
+    sections. Order follows ``spec.optional``.
+    """
+    return _collect(product, spec, RELATIONSHIP_SECTIONS)
+
+
+def present_relationship_sections(product: Product, spec: ArtifactSpec) -> list[str]:
+    """Relationship sections ``product`` declares *and* populates.
+
+    Spec-driven and inclusive of ``supersedes`` (unlike
+    :func:`extract_relationships`). A section counts only when present with at
+    least one parsed reference (REQ-011). Returns the normalized section names in
+    ``spec.optional`` order, for ``rac stats`` declared-presence counts.
+    """
+    present: list[str] = []
+    for section in spec.optional:
+        if section not in RELATIONSHIP_SECTIONS:
+            continue
+        body = product.sections.get(section)
+        if body and parse_references(body):
+            present.append(section)
+    return present
+
+
+# --- Repository-level relationship inspection (v0.7.1) -----------------------
+#
+# `rac relationships <path>` discovers the explicit relationships declared across
+# a tree of artifacts (ADR-015: repository intelligence in Core, exposed via CLI +
+# JSON for future consumers). It is read-only and deterministic: it reports the
+# references that exist, but never resolves, validates, or graphs them.
+
+
+@dataclass
+class ArtifactRelationships:
+    """One artifact's relationships in a repository report.
+
+    ``relationships`` includes Supersedes (unlike ``rac inspect``) and is keyed by
+    snake_case section name in the artifact's own ``spec.optional`` order.
+    """
+
+    path: str
+    type: str
+    relationships: dict[str, list[str]]
+
+
+@dataclass
+class RelationshipReport:
+    """Repository-level relationship inspection result (ADR-003).
+
+    ``total_files`` counts every Markdown file considered — including files with
+    no relationships and Unknown artifacts. ``artifacts`` lists only those with at
+    least one relationship. Counts are *reference* counts (each declared target is
+    one relationship), aggregated by type in the canonical
+    :data:`RELATIONSHIP_SECTIONS` order.
+    """
+
+    directory: str
+    recursive: bool
+    total_files: int
+    artifacts: list[ArtifactRelationships] = field(default_factory=list)
+
+    @property
+    def artifacts_with_relationships(self) -> int:
+        return len(self.artifacts)
+
+    @property
+    def counts(self) -> dict[str, int]:
+        """References per relationship type, canonical order, zero types omitted."""
+        totals: dict[str, int] = {}
+        for artifact in self.artifacts:
+            for section, refs in artifact.relationships.items():
+                totals[section] = totals.get(section, 0) + len(refs)
+        return {
+            _snake(section): totals[_snake(section)]
+            for section in RELATIONSHIP_SECTIONS
+            if _snake(section) in totals
+        }
+
+    @property
+    def relationship_count(self) -> int:
+        """Total references found across all artifacts (sum of ``counts``)."""
+        return sum(self.counts.values())
+
+
+def _artifact_relationships(path: str) -> tuple[str, dict[str, list[str]]]:
+    """Classify the file at ``path`` and extract its full relationships.
+
+    Returns ``(type, relationships)``. Unknown artifacts (no spec) yield an empty
+    relationship dict — extraction stays spec-driven (REQ-007), no generic scan.
+    """
+    product = parse_file(path)
+    artifact_type = classify(product).type
+    spec = spec_for(artifact_type)
+    relationships = extract_relationships_full(product, spec) if spec else {}
+    return artifact_type, relationships
+
+
+def _build_report(
+    directory: str, paths: list, recursive: bool
+) -> RelationshipReport:
+    """Assemble a :class:`RelationshipReport` from ``paths`` (already ordered)."""
+    artifacts: list[ArtifactRelationships] = []
+    for path in paths:
+        artifact_type, relationships = _artifact_relationships(str(path))
+        if relationships:
+            artifacts.append(
+                ArtifactRelationships(
+                    path=str(path), type=artifact_type, relationships=relationships
+                )
+            )
+    return RelationshipReport(
+        directory=directory,
+        recursive=recursive,
+        total_files=len(paths),
+        artifacts=artifacts,
+    )
+
+
+def build_relationship_report(
+    directory: str, recursive: bool = True
+) -> RelationshipReport:
+    """Inspect explicit relationships across a directory of Markdown files."""
+    paths = find_markdown_files(directory, recursive=recursive)
+    return _build_report(directory, paths, recursive)
+
+
+def build_relationship_report_file(path: str) -> RelationshipReport:
+    """Inspect relationships in a single file (REQ-009).
+
+    Same model as a directory report, with one file and ``recursive=False``.
+    """
+    return _build_report(path, [path], recursive=False)

{requirements_as_code-0.7.0 → requirements_as_code-0.7.1}/rac/stats.py

@@ -19,11 +19,11 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 
-from .artifacts import RELATIONSHIP_SECTIONS, spec_for
+from .artifacts import spec_for
 from .fs import find_markdown_files
 from .inspect import build_inspection
 from .parser import parse_file
-from .relationships import present_relationship_sections
+from .relationships import RELATIONSHIP_SECTIONS, present_relationship_sections
 from .validate import validate
 
 

{requirements_as_code-0.7.0 → requirements_as_code-0.7.1/requirements_as_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.7.0
+Version: 0.7.1
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -863,6 +863,78 @@ registered schemas are supported; custom schemas are out of scope.
 
 ---
 
+## Relationships
+
+Inspect the explicit [relationship metadata](#relationship-metadata) declared
+across a repository — a deterministic, read-only view of how artifacts reference
+one another, without opening every file.
+
+```bash
+rac relationships planning/
+rac relationships planning/ --json
+rac relationships planning/ --top-level     # don't recurse into subdirectories
+rac relationships requirements/search.md    # a single file works too
+```
+
+```text
+Relationships
+
+Files Inspected: 24
+Artifacts With Relationships: 8
+Relationships Found: 14
+
+By Type:
+- Related Requirements: 4
+- Related Decisions: 6
+- Related Roadmaps: 2
+- Related Prompts: 1
+- Supersedes: 1
+
+requirements/search.md
+  Related Decisions:
+  - ADR-004
+```
+
+`--json` returns structured data for automation and future viewers (ADR-015 —
+relationship intelligence lives in RAC Core, not the UI):
+
+```json
+{
+  "directory": "planning",
+  "recursive": true,
+  "total_files": 24,
+  "artifacts_with_relationships": 8,
+  "relationship_count": 14,
+  "counts": { "related_decisions": 6, "related_requirements": 4 },
+  "artifacts": [
+    {
+      "path": "requirements/search.md",
+      "type": "requirement",
+      "relationships": { "related_decisions": ["ADR-004"] }
+    }
+  ]
+}
+```
+
+Notes:
+
+- **Counts are individual references.** `relationship_count` equals
+  `sum(counts.values())`; an artifact listing two decisions contributes two.
+- **`total_files`** counts every Markdown file considered — including files with
+  no relationships and Unknown artifacts.
+- **Supersedes is a relationship here.** Unlike `rac inspect` (where `supersedes`
+  is a top-level scalar), this command reports it alongside the `related_*`
+  sections, in both `counts` and per-artifact `relationships`.
+- **Spec-driven.** Extraction is keyed off each artifact type's declared sections.
+  Unknown artifacts are counted but contribute no relationships (and never appear
+  in `artifacts`); RAC does not scan arbitrary Markdown.
+- **Read-only and exit `0`.** The command never modifies files and exits `0`
+  whether or not relationships are found (`2` only for a missing path or a
+  non-Markdown file). It does **not** resolve or validate targets — broken-link
+  detection is a later release.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.