requirements-as-code 0.1.0__py3-none-any.whl

rac/cli.py

@@ -0,0 +1,100 @@
+"""Command-line interface for RAC.
+
+Commands:
+    rac validate <file.md> [--json]
+    rac diff <old.md> <new.md> [--json]
+
+Exit codes:
+    0  success (validate: no errors; diff: always, when it runs)
+    1  validation found errors
+    2  usage / IO error (e.g. file not found)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from . import outputs
+from .diff import diff as diff_asts
+from .parser import parse_file
+from .validate import has_errors, validate
+
+EXIT_OK = 0
+EXIT_VALIDATION_FAILED = 1
+EXIT_USAGE = 2
+
+
+def _read(path: str):
+    """Parse a file, or print an error and exit with EXIT_USAGE."""
+    try:
+        return parse_file(path)
+    except FileNotFoundError:
+        print(f"rac: file not found: {path}", file=sys.stderr)
+        raise SystemExit(EXIT_USAGE)
+    except OSError as exc:
+        print(f"rac: cannot read {path}: {exc}", file=sys.stderr)
+        raise SystemExit(EXIT_USAGE)
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    product = _read(args.file)
+    issues = validate(product)
+    if args.json:
+        print(outputs.render_validation_json(product, issues))
+    else:
+        print(outputs.render_validation_human(product, issues))
+    return EXIT_VALIDATION_FAILED if has_errors(issues) else EXIT_OK
+
+
+def cmd_diff(args: argparse.Namespace) -> int:
+    old = _read(args.old)
+    new = _read(args.new)
+    result = diff_asts(old, new)
+    if args.json:
+        print(outputs.render_diff_json(result, args.old, args.new))
+    else:
+        print(outputs.render_diff_human(result, args.old, args.new))
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="rac",
+        description="Requirements As Code — lint and diff Markdown requirements.",
+    )
+    parser.add_argument("--version", action="version", version=f"rac {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_validate = sub.add_parser(
+        "validate", help="Validate a single requirement file."
+    )
+    p_validate.add_argument("file", help="Path to the requirement Markdown file.")
+    p_validate.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of human-readable text."
+    )
+    p_validate.set_defaults(func=cmd_validate)
+
+    p_diff = sub.add_parser(
+        "diff", help="Compare two versions of a requirement file."
+    )
+    p_diff.add_argument("old", help="Path to the old version.")
+    p_diff.add_argument("new", help="Path to the new version.")
+    p_diff.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of human-readable text."
+    )
+    p_diff.set_defaults(func=cmd_diff)
+
+    # Future commands (rac stats <dir>, rac review <file>) will register here.
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rac/diff.py

@@ -0,0 +1,69 @@
+"""Compare two :class:`~rac.models.Product` ASTs and classify the changes.
+
+Diffing operates purely on the AST, never on raw Markdown text.
+
+- Requirements are matched by ID:
+    * same ID, same text   -> unchanged (omitted)
+    * same ID, different    -> modified
+    * ID only in the new    -> added
+    * ID only in the old    -> removed
+- Metrics and risks are matched by exact string (set difference).
+"""
+
+from __future__ import annotations
+
+from .models import Diff, Product, Requirement, RequirementChange
+
+
+def _by_id(requirements: list[Requirement]) -> dict[str, Requirement]:
+    # On a duplicate ID (a validation error) the last occurrence wins; the diff
+    # is still well-defined.
+    return {r.id: r for r in requirements}
+
+
+def _ordered_difference(a: list[str], b: list[str]) -> list[str]:
+    """Items in ``a`` not present in ``b``, preserving ``a``'s order, de-duped."""
+    b_set = set(b)
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in a:
+        if item not in b_set and item not in seen:
+            seen.add(item)
+            out.append(item)
+    return out
+
+
+def diff(old: Product, new: Product) -> Diff:
+    """Return the classified :class:`Diff` between ``old`` and ``new``."""
+    old_reqs = _by_id(old.requirements)
+    new_reqs = _by_id(new.requirements)
+
+    result = Diff()
+
+    # Added / modified: iterate new (preserves new-file order).
+    for req_id, new_req in new_reqs.items():
+        old_req = old_reqs.get(req_id)
+        if old_req is None:
+            result.added_requirements.append(new_req)
+        elif old_req.text != new_req.text:
+            result.modified_requirements.append(
+                RequirementChange(
+                    id=req_id, old_text=old_req.text, new_text=new_req.text
+                )
+            )
+
+    # Removed: in old but not new (preserves old-file order).
+    for req_id, old_req in old_reqs.items():
+        if req_id not in new_reqs:
+            result.removed_requirements.append(old_req)
+
+    result.added_metrics = _ordered_difference(
+        new.success_metrics, old.success_metrics
+    )
+    result.removed_metrics = _ordered_difference(
+        old.success_metrics, new.success_metrics
+    )
+    result.added_risks = _ordered_difference(new.risks, old.risks)
+    result.removed_risks = _ordered_difference(old.risks, new.risks)
+
+    return result

rac/models.py

@@ -0,0 +1,107 @@
+"""The Product AST and result types.
+
+These dataclasses are the *only* thing validation, diffing, and future analysis
+should operate on. The parser (``rac.parser``) is responsible for turning a
+Markdown file into a :class:`Product`; everything downstream reads the AST, never
+the raw text.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass
+class Requirement:
+    """A single requirement line, e.g. ``[REQ-001] User can view data``."""
+
+    id: str  # canonical ID, preserved exactly (e.g. "REQ-001")
+    text: str  # the description following the ID
+    line: int  # 1-based source line, for diagnostics
+
+
+@dataclass
+class MalformedRequirement:
+    """A non-empty line under ``## Requirements`` that is not a valid requirement.
+
+    Captured (rather than dropped) so validation can report *why* it is invalid
+    instead of silently ignoring it.
+    """
+
+    raw: str  # the raw line text
+    line: int
+    # The parsed ID if one was found but is malformed (e.g. "REQ-1A"); None if
+    # the line had no recognizable ID prefix at all.
+    bad_id: str | None = None
+    # True when an ID was present and well-formed but the description was blank.
+    empty_text: bool = False
+
+
+@dataclass
+class Product:
+    """The structured representation of a single requirement file."""
+
+    title: str | None
+    # Source lines of any *additional* top-level # titles (a file must have
+    # exactly one). Empty in a well-formed file.
+    extra_title_lines: list[int] = field(default_factory=list)
+    problem: str | None = None  # None = section absent; "" = present but empty
+    requirements: list[Requirement] = field(default_factory=list)
+    malformed_requirements: list[MalformedRequirement] = field(default_factory=list)
+    success_metrics: list[str] = field(default_factory=list)
+    risks: list[str] = field(default_factory=list)
+    # Distinguish "section absent" from "section present but empty".
+    has_problem_section: bool = False
+    has_requirements_section: bool = False
+    has_metrics_section: bool = False
+    has_risks_section: bool = False
+    source_path: str = ""
+
+
+@dataclass
+class Issue:
+    """A validation finding."""
+
+    severity: Severity
+    code: str  # stable machine code, e.g. "missing-title", "ambiguous-verb"
+    message: str  # human-readable explanation
+    line: int | None = None
+
+
+@dataclass
+class RequirementChange:
+    """A requirement whose text changed between two versions (same ID)."""
+
+    id: str
+    old_text: str
+    new_text: str
+
+
+@dataclass
+class Diff:
+    """The classified differences between two :class:`Product` ASTs."""
+
+    added_requirements: list[Requirement] = field(default_factory=list)
+    removed_requirements: list[Requirement] = field(default_factory=list)
+    modified_requirements: list[RequirementChange] = field(default_factory=list)
+    added_metrics: list[str] = field(default_factory=list)
+    removed_metrics: list[str] = field(default_factory=list)
+    added_risks: list[str] = field(default_factory=list)
+    removed_risks: list[str] = field(default_factory=list)
+
+    def is_empty(self) -> bool:
+        """True when nothing changed across any comparison unit."""
+        return not any(
+            (
+                self.added_requirements,
+                self.removed_requirements,
+                self.modified_requirements,
+                self.added_metrics,
+                self.removed_metrics,
+                self.added_risks,
+                self.removed_risks,
+            )
+        )

rac/output.py

@@ -0,0 +1,152 @@
+"""Rendering for RAC command results: human-readable text and JSON.
+
+Keeping this separate from :mod:`rac.cli` lets the CLI stay thin and makes the
+output formats easy to test directly.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+
+from .models import Diff, Issue, Product
+
+# --- Minimal color (auto-disabled when not writing to a TTY) ----------------
+
+_USE_COLOR = sys.stdout.isatty()
+
+
+def _c(text: str, code: str) -> str:
+    if not _USE_COLOR:
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+def _green(t: str) -> str:
+    return _c(t, "32")
+
+
+def _red(t: str) -> str:
+    return _c(t, "31")
+
+
+def _yellow(t: str) -> str:
+    return _c(t, "33")
+
+
+def _bold(t: str) -> str:
+    return _c(t, "1")
+
+
+def _loc(file: str, line: int | None) -> str:
+    return f"{file}:{line}" if line is not None else file
+
+
+# --- validate ---------------------------------------------------------------
+
+
+def render_validation_human(product: Product, issues: list[Issue]) -> str:
+    errors = [i for i in issues if i.severity == "error"]
+    warnings = [i for i in issues if i.severity == "warning"]
+    file = product.source_path or "<input>"
+
+    lines: list[str] = []
+    if errors:
+        lines.append(_red(_bold(f"FAIL  {file}")))
+    else:
+        lines.append(_green(_bold(f"PASS  {file}")))
+
+    for issue in errors:
+        lines.append(f"  {_red('error')}   [{issue.code}] {_loc(file, issue.line)}")
+        lines.append(f"          {issue.message}")
+    for issue in warnings:
+        lines.append(
+            f"  {_yellow('warning')} [{issue.code}] {_loc(file, issue.line)}"
+        )
+        lines.append(f"          {issue.message}")
+
+    lines.append("")
+    lines.append(
+        f"{len(errors)} error(s), {len(warnings)} warning(s)."
+    )
+    return "\n".join(lines)
+
+
+def render_validation_json(product: Product, issues: list[Issue]) -> str:
+    errors = [asdict(i) for i in issues if i.severity == "error"]
+    warnings = [asdict(i) for i in issues if i.severity == "warning"]
+    payload = {
+        "file": product.source_path or None,
+        "valid": not errors,
+        "errors": errors,
+        "warnings": warnings,
+    }
+    return json.dumps(payload, indent=2)
+
+
+# --- diff -------------------------------------------------------------------
+
+
+def render_diff_human(d: Diff, old_path: str, new_path: str) -> str:
+    if d.is_empty():
+        return "No changes."
+
+    blocks: list[str] = []
+
+    def list_block(title: str, items: list[str], sign: str) -> None:
+        """A titled block of single-line +/- entries (added/removed)."""
+        if not items:
+            return
+        color = _green if sign == "+" else _red
+        lines = [_bold(title), ""]
+        lines.extend(color(f"{sign} {item}") for item in items)
+        blocks.append("\n".join(lines))
+
+    list_block(
+        "Added Requirements",
+        [f"{r.id} {r.text}" for r in d.added_requirements],
+        "+",
+    )
+    list_block(
+        "Removed Requirements",
+        [f"{r.id} {r.text}" for r in d.removed_requirements],
+        "-",
+    )
+
+    if d.modified_requirements:
+        lines = [_bold("Modified Requirements"), ""]
+        for i, c in enumerate(d.modified_requirements):
+            if i:
+                lines.append("")
+            lines.append(f"~ {c.id}")
+            lines.append("")
+            lines.append("Before:")
+            lines.append(_red(c.old_text))
+            lines.append("")
+            lines.append("After:")
+            lines.append(_green(c.new_text))
+        blocks.append("\n".join(lines))
+
+    list_block("Added Metrics", d.added_metrics, "+")
+    list_block("Removed Metrics", d.removed_metrics, "-")
+    list_block("Added Risks", d.added_risks, "+")
+    list_block("Removed Risks", d.removed_risks, "-")
+
+    # Blank line between blocks.
+    return "\n\n".join(blocks)
+
+
+def render_diff_json(d: Diff, old_path: str, new_path: str) -> str:
+    payload = {
+        "old": old_path,
+        "new": new_path,
+        "added_requirements": [asdict(r) for r in d.added_requirements],
+        "removed_requirements": [asdict(r) for r in d.removed_requirements],
+        "modified_requirements": [asdict(c) for c in d.modified_requirements],
+        "added_metrics": d.added_metrics,
+        "removed_metrics": d.removed_metrics,
+        "added_risks": d.added_risks,
+        "removed_risks": d.removed_risks,
+    }
+    return json.dumps(payload, indent=2)

rac/parser.py

@@ -0,0 +1,159 @@
+"""Turn a Markdown requirement file into a :class:`~rac.models.Product` AST.
+
+We tokenize with ``markdown-it-py`` and walk the (flat) token stream, tracking the
+current ``##`` section. This module performs *structural extraction only* — it does
+not enforce any rules. All rule-checking lives in :mod:`rac.validate`, so that
+diffing and future analysis share a single source of truth.
+
+Heading matching is case-insensitive and whitespace-trimmed, so ``## problem`` and
+``##  Problem `` both work.
+"""
+
+from __future__ import annotations
+
+import re
+
+from markdown_it import MarkdownIt
+
+from .models import MalformedRequirement, Product, Requirement
+
+# A requirement line: a leading ``[...]`` ID token followed by description text.
+# We capture anything inside the brackets so we can distinguish a *malformed* ID
+# from a missing one, then validate the ID shape separately.
+_BRACKET_RE = re.compile(r"^\[(?P<id>[^\]]*)\]\s*(?P<text>.*)$")
+# Canonical requirement ID, e.g. REQ-001.
+_CANONICAL_ID_RE = re.compile(r"^REQ-\d+$")
+
+# Recognized section headings, normalized (stripped + casefolded).
+_SECTIONS = {
+    "problem": "problem",
+    "requirements": "requirements",
+    "success metrics": "success_metrics",
+    "risks": "risks",
+}
+
+
+def _normalize_heading(text: str) -> str:
+    return text.strip().casefold()
+
+
+def _content_lines(content: str, start_line: int) -> list[tuple[str, int]]:
+    """Split an inline token's content into ``(text, 1-based-line)`` pairs.
+
+    ``start_line`` is the 0-based line where the enclosing block begins (from the
+    token's ``.map``). Blank lines are dropped but still advance the line counter.
+    """
+    pairs: list[tuple[str, int]] = []
+    for offset, raw in enumerate(content.split("\n")):
+        stripped = raw.strip()
+        if stripped:
+            pairs.append((stripped, start_line + offset + 1))
+    return pairs
+
+
+def _classify_requirement_line(text: str, line: int):
+    """Return either a :class:`Requirement` or :class:`MalformedRequirement`."""
+    m = _BRACKET_RE.match(text)
+    if not m:
+        # No recognizable ``[...]`` prefix at all.
+        return MalformedRequirement(raw=text, line=line, bad_id=None)
+    req_id = m.group("id").strip()
+    desc = m.group("text").strip()
+    if not _CANONICAL_ID_RE.match(req_id):
+        return MalformedRequirement(raw=text, line=line, bad_id=req_id)
+    if not desc:
+        return MalformedRequirement(
+            raw=text, line=line, bad_id=req_id, empty_text=True
+        )
+    return Requirement(id=req_id, text=desc, line=line)
+
+
+def parse(text: str, source_path: str = "") -> Product:
+    """Parse Markdown ``text`` into a :class:`Product`."""
+    tokens = MarkdownIt("commonmark").parse(text)
+
+    title: str | None = None
+    extra_title_lines: list[int] = []
+    section: str | None = None  # current tracked section key, or None/"other"
+
+    problem_lines: list[str] = []
+    requirement_lines: list[tuple[str, int]] = []
+    metric_lines: list[str] = []
+    risk_lines: list[str] = []
+
+    has = {
+        "problem": False,
+        "requirements": False,
+        "success_metrics": False,
+        "risks": False,
+    }
+
+    for i, tok in enumerate(tokens):
+        if tok.type == "heading_open":
+            heading_text = tokens[i + 1].content if i + 1 < len(tokens) else ""
+            if tok.tag == "h1":
+                if title is None:
+                    title = heading_text.strip()
+                else:
+                    extra_title_lines.append((tok.map[0] + 1) if tok.map else 0)
+                section = None  # content directly under the title is ignored
+            elif tok.tag == "h2":
+                key = _SECTIONS.get(_normalize_heading(heading_text))
+                section = key
+                if key is not None:
+                    has[key] = True
+            else:
+                section = "other"
+            continue
+
+        if tok.type != "inline" or section is None or section == "other":
+            continue
+
+        # Skip the inline that *is* a heading's text.
+        if i > 0 and tokens[i - 1].type == "heading_open":
+            continue
+
+        start_line = tok.map[0] if tok.map else 0
+        lines = _content_lines(tok.content, start_line)
+
+        if section == "problem":
+            problem_lines.extend(t for t, _ in lines)
+        elif section == "requirements":
+            requirement_lines.extend(lines)
+        elif section == "success_metrics":
+            metric_lines.extend(t for t, _ in lines)
+        elif section == "risks":
+            risk_lines.extend(t for t, _ in lines)
+
+    requirements: list[Requirement] = []
+    malformed: list[MalformedRequirement] = []
+    for line_text, line_no in requirement_lines:
+        result = _classify_requirement_line(line_text, line_no)
+        if isinstance(result, Requirement):
+            requirements.append(result)
+        else:
+            malformed.append(result)
+
+    # None = section absent; "" = present but empty; otherwise the joined text.
+    problem = "\n".join(problem_lines).strip() if has["problem"] else None
+
+    return Product(
+        title=title,
+        extra_title_lines=extra_title_lines,
+        problem=problem,
+        requirements=requirements,
+        malformed_requirements=malformed,
+        success_metrics=metric_lines,
+        risks=risk_lines,
+        has_problem_section=has["problem"],
+        has_requirements_section=has["requirements"],
+        has_metrics_section=has["success_metrics"],
+        has_risks_section=has["risks"],
+        source_path=source_path,
+    )
+
+
+def parse_file(path: str) -> Product:
+    """Read ``path`` and parse it into a :class:`Product`."""
+    with open(path, encoding="utf-8") as fh:
+        return parse(fh.read(), source_path=path)

rac/validate.py

@@ -0,0 +1,174 @@
+"""Validate a :class:`~rac.models.Product` against RAC's format rules.
+
+Returns a flat list of :class:`~rac.models.Issue` objects (errors and warnings);
+it never stops at the first problem. Whether a run "fails" is the CLI's decision,
+based on whether any ``error``-severity issues are present.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+from .models import Issue, Product
+
+# A file with more requirements than this earns a (non-failing) warning.
+MAX_REQUIREMENTS = 50
+
+# Vague verbs that tend to hide unspecified behavior.
+AMBIGUOUS_VERBS = ("support", "handle", "allow", "enable")
+_AMBIGUOUS_RE = re.compile(
+    r"\b(" + "|".join(AMBIGUOUS_VERBS) + r")\b", re.IGNORECASE
+)
+
+
+def has_errors(issues: list[Issue]) -> bool:
+    """True if any issue is error-severity."""
+    return any(issue.severity == "error" for issue in issues)
+
+
+def validate(product: Product) -> list[Issue]:
+    """Check ``product`` and return all structural and quality findings."""
+    issues: list[Issue] = []
+
+    # --- Hard failures: structure -------------------------------------------
+    if not product.title:
+        issues.append(Issue("error", "missing-title", "File has no top-level # title."))
+
+    if product.extra_title_lines:
+        # One error regardless of how many extra titles there are; point at the
+        # first offending title.
+        issues.append(
+            Issue(
+                "error",
+                "multiple-titles",
+                "File has more than one top-level # title; expected exactly one.",
+                product.extra_title_lines[0],
+            )
+        )
+
+    if not product.has_problem_section:
+        issues.append(
+            Issue("error", "missing-problem", "File is missing a ## Problem section.")
+        )
+
+    if not product.has_requirements_section:
+        issues.append(
+            Issue(
+                "error",
+                "missing-requirements",
+                "File is missing a ## Requirements section.",
+            )
+        )
+
+    # --- Hard failures: malformed requirement lines -------------------------
+    for m in product.malformed_requirements:
+        if m.bad_id is None:
+            issues.append(
+                Issue(
+                    "error",
+                    "req-missing-id",
+                    f"Requirement line has no [REQ-NNN] ID: {m.raw!r}",
+                    m.line,
+                )
+            )
+        elif m.empty_text:
+            issues.append(
+                Issue(
+                    "error",
+                    "empty-req-text",
+                    f"Requirement [{m.bad_id}] has no description text.",
+                    m.line,
+                )
+            )
+        else:
+            issues.append(
+                Issue(
+                    "error",
+                    "malformed-req-id",
+                    f"Malformed requirement ID [{m.bad_id}]; expected form [REQ-NNN].",
+                    m.line,
+                )
+            )
+
+    # --- Hard failures: duplicate IDs ---------------------------------------
+    id_counts = Counter(r.id for r in product.requirements)
+    seen: set[str] = set()
+    for r in product.requirements:
+        if id_counts[r.id] > 1 and r.id not in seen:
+            seen.add(r.id)
+            issues.append(
+                Issue(
+                    "error",
+                    "duplicate-req-id",
+                    f"Duplicate requirement ID {r.id} (used {id_counts[r.id]} times).",
+                    r.line,
+                )
+            )
+
+    # --- Warnings: missing optional sections --------------------------------
+    if not product.has_metrics_section:
+        issues.append(
+            Issue(
+                "warning",
+                "missing-success-metrics",
+                "No ## Success Metrics section (optional, but recommended).",
+            )
+        )
+    if not product.has_risks_section:
+        issues.append(
+            Issue(
+                "warning",
+                "missing-risks",
+                "No ## Risks section (optional, but recommended).",
+            )
+        )
+
+    # --- Warnings: empty problem --------------------------------------------
+    if product.has_problem_section and not (product.problem or "").strip():
+        issues.append(
+            Issue("warning", "empty-problem", "## Problem section is empty.")
+        )
+
+    # --- Warnings: too many requirements ------------------------------------
+    if len(product.requirements) > MAX_REQUIREMENTS:
+        issues.append(
+            Issue(
+                "warning",
+                "too-many-requirements",
+                f"{len(product.requirements)} requirements "
+                f"(more than {MAX_REQUIREMENTS}); consider splitting the feature.",
+            )
+        )
+
+    # --- Warnings: duplicate requirement text -------------------------------
+    text_counts = Counter(r.text.strip().casefold() for r in product.requirements)
+    seen_text: set[str] = set()
+    for r in product.requirements:
+        key = r.text.strip().casefold()
+        if text_counts[key] > 1 and key not in seen_text:
+            seen_text.add(key)
+            issues.append(
+                Issue(
+                    "warning",
+                    "duplicate-req-text",
+                    f"Duplicate requirement text: {r.text!r}.",
+                    r.line,
+                )
+            )
+
+    # --- Warnings: ambiguous verbs ------------------------------------------
+    for r in product.requirements:
+        found = _AMBIGUOUS_RE.findall(r.text)
+        if found:
+            verbs = ", ".join(sorted({v.lower() for v in found}))
+            issues.append(
+                Issue(
+                    "warning",
+                    "ambiguous-verb",
+                    f"{r.id} uses ambiguous verb(s) ({verbs}); be more specific.",
+                    r.line,
+                )
+            )
+
+    return issues

requirements_as_code-0.1.0.dist-info/METADATA

@@ -0,0 +1,440 @@
+Metadata-Version: 2.4
+Name: requirements-as-code
+Version: 0.1.0
+Summary: RAC — lint and diff product requirements written in Markdown.
+Author: RAC
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: markdown-it-py>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# RAC (Requirements-as-Code)
+
+> Lint, diff, and analyse product requirements from the command line
+
+Product requirements are often trapped in documents, making them difficult to review, validate, and track over time.
+
+RAC brings software engineering workflows to product requirements.
+
+Write requirements in Markdown. Store them in Git. Validate them, compare versions, and analyse change over time.
+
+```text
+Markdown
+    ↓
+Product Model
+    ↓
+Validation
+    ↓
+Diffing
+    ↓
+Portfolio Analysis
+    ↓
+AI Review (future)
+```
+
+## Why RAC?
+
+Engineers have mature tooling for code:
+
+- Linters
+- Code review
+- Diffs
+- Static analysis
+- Version control
+
+Product requirements typically have none of these.
+
+RAC applies the same principles to product requirements.
+
+### Validate
+
+```bash
+rac validate bond_dashboard.md
+```
+
+### Compare
+
+```bash
+rac diff bond_dashboard_v1.md bond_dashboard_v2.md
+```
+
+### Analyse
+
+```bash
+rac stats ./features
+```
+
+*(planned for v0.2)*
+
+---
+
+# Example
+
+Create a requirement file:
+
+```markdown
+# Bond Dashboard
+
+## Problem
+
+Retail investors struggle to understand interest-rate exposure.
+
+## Requirements
+
+- [REQ-001] User can view portfolio holdings
+- [REQ-002] User can view portfolio duration
+- [REQ-003] User can view portfolio yield
+
+## Success Metrics
+
+- Monthly Active Users
+- Dashboard Views
+
+## Risks
+
+- Inaccurate market data
+```
+
+Validate it:
+
+```bash
+rac validate bond_dashboard.md
+```
+
+Output:
+
+```text
+PASS
+```
+
+Now compare two versions:
+
+```bash
+rac diff bond_dashboard_v1.md bond_dashboard_v2.md
+```
+
+Output:
+
+```text
+Added Requirements
+
++ REQ-004 View projected yield forecast
+
+Modified Requirements
+
+~ REQ-002
+
+Before:
+User can view portfolio duration
+
+After:
+User can view and compare portfolio duration
+```
+
+RAC compares **product changes**, not just text changes.
+
+---
+
+# Installation
+
+## Using pip
+
+```bash
+pip install requirements-as-code
+```
+
+## Using uv
+
+```bash
+uv tool install requirements-as-code
+```
+
+Verify installation:
+
+```bash
+rac --help
+```
+
+---
+
+# Quick Start
+
+Create a file:
+
+```bash
+touch feature.md
+```
+
+Add requirements:
+
+```markdown
+# Trade Alerts
+
+## Problem
+
+Investors miss important market movements.
+
+## Requirements
+
+- [REQ-001] User can create a trade alert
+- [REQ-002] User can edit a trade alert
+- [REQ-003] User can delete a trade alert
+```
+
+Validate:
+
+```bash
+rac validate feature.md
+```
+
+Compare versions:
+
+```bash
+rac diff old.md new.md
+```
+
+---
+
+# Philosophy
+
+RAC follows a few simple principles.
+
+## Markdown First
+
+Requirements should remain easy to write and review.
+
+RAC uses Markdown as the source format.
+
+No proprietary editors.
+
+No custom file formats.
+
+## Git Native
+
+Requirements should work naturally inside:
+
+- GitHub
+- GitLab
+- VS Code
+- Cursor
+- Claude Code
+
+## AI Optional
+
+RAC should be useful without AI.
+
+The foundation is:
+
+- structure
+- validation
+- diffing
+- analysis
+
+AI is an enhancement, not a dependency.
+
+## Product Model
+
+Internally, RAC converts Markdown into a structured Product Model.
+
+```text
+Markdown
+    ↓
+Parser
+    ↓
+Feature Model
+    ↓
+Validation
+    ↓
+Diffing
+    ↓
+Stats
+```
+
+This enables reliable analysis without relying on fragile text processing.
+
+---
+
+# Markdown Specification
+
+Every feature is represented by a single Markdown file.
+
+Example:
+
+```markdown
+# Feature Title
+
+## Problem
+
+Problem statement.
+
+## Requirements
+
+- [REQ-001] Requirement text
+- [REQ-002] Requirement text
+
+## Success Metrics
+
+- Metric 1
+
+## Risks
+
+- Risk 1
+```
+
+## Required Sections
+
+Required:
+
+- `# Title`
+- `## Problem`
+- `## Requirements`
+
+Optional (recommended):
+
+- `## Success Metrics`
+- `## Risks`
+
+---
+
+# Commands
+
+## Validate
+
+Validate a requirement file.
+
+```bash
+rac validate feature.md
+```
+
+Checks:
+
+- Required sections exist
+- Requirement IDs are valid
+- Requirement IDs are unique
+- Requirement text is not empty
+
+Warnings:
+
+- Missing risks
+- Missing success metrics
+- Duplicate requirement text
+- Ambiguous wording
+
+---
+
+## Diff
+
+Compare two versions of a feature.
+
+```bash
+rac diff old.md new.md
+```
+
+Detects:
+
+- Added requirements
+- Removed requirements
+- Modified requirements
+- Added metrics
+- Removed metrics
+- Added risks
+- Removed risks
+
+Requirements are matched by ID.
+
+---
+
+## Stats (Planned)
+
+Portfolio-level analysis.
+
+```bash
+rac stats ./features
+```
+
+Example output:
+
+```text
+Portfolio Overview
+==================
+
+Features: 12
+
+Requirements: 87
+
+Success Metrics: 24
+
+Risks: 18
+
+Features Missing Risks: 3
+
+Features Missing Metrics: 2
+```
+
+---
+
+## Review (Planned)
+
+AI-assisted product review.
+
+```bash
+rac review feature.md
+```
+
+Potential checks:
+
+- Missing requirements
+- Missing risks
+- Ambiguity
+- Product concerns
+- Engineering concerns
+
+RAC will use the user's configured AI provider rather than requiring hosted infrastructure.
+
+---
+
+# Roadmap
+
+## v0.1
+
+- Markdown parser
+- Product Model (AST)
+- Validation
+- Diffing
+- CLI
+
+## v0.2
+
+- Portfolio statistics
+- Quality metrics
+- Repository-wide analysis
+
+## v0.3
+
+- AI review
+- Provider abstraction
+- Git-aware workflows
+
+## v1.0
+
+- Product intelligence
+- Daily product briefs
+- VS Code integration
+
+---
+
+# Contributing
+
+Contributions, ideas, and feedback are welcome.
+
+The project is intentionally focused on one goal:
+
+> Treat product requirements like code.
+
+---
+
+# License
+
+MIT

requirements_as_code-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+rac/cli.py,sha256=OJtnI0aW_RDoiVhIg3x6uADSs_mjkiLE0lhq-1kjYt4,2996
+rac/diff.py,sha256=bIgV5b7HSLqnkqVO_7XIwfbcKW1v0x5n4b6u-pOPU68,2354
+rac/models.py,sha256=qQ1AASbUhgCpGHpsZtui_wXVt8ymZIWDPY8h6BmAjLA,3581
+rac/output.py,sha256=3EIBxJHwGmKrOhX1V2RzwSUyLimsy55B4bYjGq01yWc,4446
+rac/parser.py,sha256=PwW5ZgdaAA2RLD2qmDRSKtxfidRyqzA2i9EIvGzAgQ8,5729
+rac/validate.py,sha256=Xm1sa_DLltLx1v2n-mUk-BnGz7BaIThMO9QASJaWAL8,5913
+requirements_as_code-0.1.0.dist-info/METADATA,sha256=pt16b3A6zBvmA1kY87SeO-CjUP3bQyI9RkGm3mqm4ms,5603
+requirements_as_code-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+requirements_as_code-0.1.0.dist-info/entry_points.txt,sha256=qcG8cyRxeHDQ0XisELlsOZaefADoDEvHMLRbWO4igr4,37
+requirements_as_code-0.1.0.dist-info/top_level.txt,sha256=XEcpL2fCC4e7IAX56SQgC_MY8kOSXUDKLeDQdo5qwIE,4
+requirements_as_code-0.1.0.dist-info/RECORD,,

requirements_as_code-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

requirements_as_code-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rac = rac.cli:main

requirements_as_code-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rac