requirements-as-code 0.7.2__tar.gz → 0.7.3__tar.gz

{requirements_as_code-0.7.2/requirements_as_code.egg-info → requirements_as_code-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requirements-as-code
-Version: 0.7.2
+Version: 0.7.3
 Summary: RAC — lint and diff product requirements written in Markdown.
 Author: tcballard
 License-Expression: MIT
@@ -935,6 +935,153 @@ Notes:
 
 ---
 
+## Portfolio
+
+A single-command repository intelligence summary: artifact counts, validation
+health, completeness, relationship integrity, actionable attention items, and an
+overall health score — without manually combining output from multiple commands.
+
+```bash
+rac portfolio ./docs
+rac portfolio ./docs --json
+rac portfolio ./docs --top-level   # don't recurse into subdirectories
+```
+
+```text
+Repository Summary
+==================
+
+Directory:  ./docs
+Artifacts:  42
+
+By Type
+-------
+
+  Requirement    18
+  Decision       12
+  Roadmap        5
+  Prompt         4
+  Design         2
+  Unknown        1
+
+Validation
+----------
+
+  Valid:    40
+  Invalid:  2
+
+Completeness
+------------
+
+  78% (94 / 120 recommended slots filled)
+
+Relationships
+-------------
+
+  Total:    65
+  Valid:    63
+  Broken:   2
+  Orphaned: 4
+  Coverage: 71%
+
+Attention (4 items)
+----------
+
+  ✗ search
+      Validation errors: missing-requirements
+  ! adr-004
+      Missing recommended sections: Alternatives Considered
+  ! q3-roadmap
+      Related Requirements references missing artifact: REQ-999
+  ! req-041
+      Missing recommended sections: Risks
+
+Health Score
+------------
+
+  87 / 100
+```
+
+`--json` returns the stable machine contract (all fields present regardless of
+content, versioned with `schema_version`):
+
+```json
+{
+  "schema_version": "1",
+  "directory": "./docs",
+  "recursive": true,
+  "artifacts": {
+    "total": 42,
+    "by_type": {
+      "requirement": 18,
+      "decision": 12,
+      "roadmap": 5,
+      "prompt": 4,
+      "design": 2,
+      "unknown": 1
+    }
+  },
+  "validation": { "valid": 40, "invalid": 2 },
+  "completeness": { "recommended_slots": 120, "filled": 94, "ratio": 0.7833 },
+  "relationships": {
+    "total": 65,
+    "valid": 63,
+    "broken": 2,
+    "orphaned": 4,
+    "coverage": 0.7143
+  },
+  "attention": [
+    {
+      "path": "requirements/search.md",
+      "identifier": "search",
+      "severity": "error",
+      "code": "invalid-artifact",
+      "message": "Validation errors: missing-requirements"
+    },
+    {
+      "path": "roadmaps/q3-roadmap.md",
+      "identifier": "q3-roadmap",
+      "severity": "warning",
+      "code": "broken-relationship",
+      "message": "Related Requirements references missing artifact: REQ-999"
+    }
+  ],
+  "health": { "score": 87 }
+}
+```
+
+**Health score formula** (deterministic, no AI):
+
+```
+score = round(100 × (0.5 × validity + 0.25 × completeness + 0.25 × rel_integrity))
+```
+
+where each sub-score is a simple ratio that defaults to `1.0` when its
+denominator is zero, so an empty repository always scores 100.
+
+Notes:
+
+- **Advisory command.** `rac portfolio` always exits `0` when a summary is
+  produced (`2` for usage errors — not a directory). For CI hard gates, use
+  `rac relationships --validate` (exits `1` on broken refs).
+- **Attention severity.** `error` means the artifact is structurally invalid;
+  `warning` means it is valid but needs attention (missing recommended sections
+  or a stale relationship reference). Items are ordered errors-first, then by
+  path, then by code — deterministically.
+- **`identifier`** is the artifact's canonical identifier (the same one
+  `rac relationships --validate` resolves against): an explicit `## ID`, else a
+  recognised `TYPE-NNN` filename prefix, else the filename stem.
+- **`rac stats` vs `rac portfolio`.** `rac stats` provides per-feature
+  requirement and metric breakdowns for requirement-focused portfolios.
+  `rac portfolio` provides a whole-repository intelligence rollup across all
+  artifact types.
+- **Orphaned** means no other artifact holds a resolved inbound reference to
+  it — the artifact may still declare outbound relationships.
+- **Coverage** is the fraction of known (non-unknown) artifacts that declare
+  at least one outbound relationship section.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.2 → requirements_as_code-0.7.3}/README.md

@@ -895,6 +895,153 @@ Notes:
 
 ---
 
+## Portfolio
+
+A single-command repository intelligence summary: artifact counts, validation
+health, completeness, relationship integrity, actionable attention items, and an
+overall health score — without manually combining output from multiple commands.
+
+```bash
+rac portfolio ./docs
+rac portfolio ./docs --json
+rac portfolio ./docs --top-level   # don't recurse into subdirectories
+```
+
+```text
+Repository Summary
+==================
+
+Directory:  ./docs
+Artifacts:  42
+
+By Type
+-------
+
+  Requirement    18
+  Decision       12
+  Roadmap        5
+  Prompt         4
+  Design         2
+  Unknown        1
+
+Validation
+----------
+
+  Valid:    40
+  Invalid:  2
+
+Completeness
+------------
+
+  78% (94 / 120 recommended slots filled)
+
+Relationships
+-------------
+
+  Total:    65
+  Valid:    63
+  Broken:   2
+  Orphaned: 4
+  Coverage: 71%
+
+Attention (4 items)
+----------
+
+  ✗ search
+      Validation errors: missing-requirements
+  ! adr-004
+      Missing recommended sections: Alternatives Considered
+  ! q3-roadmap
+      Related Requirements references missing artifact: REQ-999
+  ! req-041
+      Missing recommended sections: Risks
+
+Health Score
+------------
+
+  87 / 100
+```
+
+`--json` returns the stable machine contract (all fields present regardless of
+content, versioned with `schema_version`):
+
+```json
+{
+  "schema_version": "1",
+  "directory": "./docs",
+  "recursive": true,
+  "artifacts": {
+    "total": 42,
+    "by_type": {
+      "requirement": 18,
+      "decision": 12,
+      "roadmap": 5,
+      "prompt": 4,
+      "design": 2,
+      "unknown": 1
+    }
+  },
+  "validation": { "valid": 40, "invalid": 2 },
+  "completeness": { "recommended_slots": 120, "filled": 94, "ratio": 0.7833 },
+  "relationships": {
+    "total": 65,
+    "valid": 63,
+    "broken": 2,
+    "orphaned": 4,
+    "coverage": 0.7143
+  },
+  "attention": [
+    {
+      "path": "requirements/search.md",
+      "identifier": "search",
+      "severity": "error",
+      "code": "invalid-artifact",
+      "message": "Validation errors: missing-requirements"
+    },
+    {
+      "path": "roadmaps/q3-roadmap.md",
+      "identifier": "q3-roadmap",
+      "severity": "warning",
+      "code": "broken-relationship",
+      "message": "Related Requirements references missing artifact: REQ-999"
+    }
+  ],
+  "health": { "score": 87 }
+}
+```
+
+**Health score formula** (deterministic, no AI):
+
+```
+score = round(100 × (0.5 × validity + 0.25 × completeness + 0.25 × rel_integrity))
+```
+
+where each sub-score is a simple ratio that defaults to `1.0` when its
+denominator is zero, so an empty repository always scores 100.
+
+Notes:
+
+- **Advisory command.** `rac portfolio` always exits `0` when a summary is
+  produced (`2` for usage errors — not a directory). For CI hard gates, use
+  `rac relationships --validate` (exits `1` on broken refs).
+- **Attention severity.** `error` means the artifact is structurally invalid;
+  `warning` means it is valid but needs attention (missing recommended sections
+  or a stale relationship reference). Items are ordered errors-first, then by
+  path, then by code — deterministically.
+- **`identifier`** is the artifact's canonical identifier (the same one
+  `rac relationships --validate` resolves against): an explicit `## ID`, else a
+  recognised `TYPE-NNN` filename prefix, else the filename stem.
+- **`rac stats` vs `rac portfolio`.** `rac stats` provides per-feature
+  requirement and metric breakdowns for requirement-focused portfolios.
+  `rac portfolio` provides a whole-repository intelligence rollup across all
+  artifact types.
+- **Orphaned** means no other artifact holds a resolved inbound reference to
+  it — the artifact may still declare outbound relationships.
+- **Coverage** is the fraction of known (non-unknown) artifacts that declare
+  at least one outbound relationship section.
+
+---
+
 ## Review (Planned)
 
 AI-assisted product review.

{requirements_as_code-0.7.2 → requirements_as_code-0.7.3}/planning/adr/adr-016-relationships-as-structural-references.md

@@ -506,3 +506,5 @@ Review after the first v0.7.x relationship implementation, or before introducing
 * Explorer relationship visualisation
 * workflow-like dependency management
 * relationship scoring
+
+**v0.7.3 note:** `rac portfolio` introduces a health score that includes relationship integrity as one of four weighted factors (0.25 weight). This is the first instance of relationship scoring in RAC Core. The formula is fully deterministic, documented in `rac/portfolio.py`, and uses only counts already produced by `summarize_relationships`. This ADR was reviewed before v0.7.3 implementation; no architectural objections were raised.

{requirements_as_code-0.7.2 → requirements_as_code-0.7.3}/rac/cli.py

@@ -9,10 +9,11 @@ Commands:
     rac improve <file.md | -> [--json | --template]
     rac schema [--list] [type] [--json | --template]
     rac relationships <dir | file.md> [--validate] [--json] [--top-level]
+    rac portfolio <directory> [--json] [--top-level]
 
 Exit codes:
     0  success (incl. inspect/improve reporting Unknown; relationships found or
-       not; --validate with all references resolved)
+       not; --validate with all references resolved; portfolio summary produced)
     1  validate: errors found; stats: no valid known artifacts; ingest:
        conversion failed; relationships --validate: broken/ambiguous/self
        references or duplicate identifiers found
@@ -34,6 +35,7 @@ from .classification import score_artifacts
 from .improve import improve_product
 from .inspect import build_inspection, inspect_directory
 from .parser import parse, parse_file
+from .portfolio import build_portfolio_summary
 from .relationships import (
     build_relationship_report,
     build_relationship_report_file,
@@ -290,6 +292,19 @@ def cmd_relationships(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def cmd_portfolio(args: argparse.Namespace) -> int:
+    if not Path(args.directory).is_dir():
+        print(f"rac: not a directory: {args.directory}", file=sys.stderr)
+        raise SystemExit(EXIT_USAGE)
+    recursive = not args.top_level
+    summary = build_portfolio_summary(args.directory, recursive=recursive)
+    if args.json:
+        print(outputs.render_portfolio_json(summary))
+    else:
+        print(outputs.render_portfolio_human(summary))
+    return EXIT_OK
+
+
 def build_parser() -> argparse.ArgumentParser:
     version_str = f"rac {__version__}"
 
@@ -470,6 +485,27 @@ def build_parser() -> argparse.ArgumentParser:
     )
     p_relationships.set_defaults(func=cmd_relationships)
 
+    p_portfolio = sub.add_parser(
+        "portfolio",
+        help="Repository intelligence summary: artifact counts, health score, and attention items.",
+        parents=[version_parent],
+    )
+    p_portfolio.add_argument("directory", help="Directory to scan recursively for *.md.")
+    p_portfolio.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of human-readable text."
+    )
+    p_portfolio.add_argument(
+        "--top-level",
+        action="store_true",
+        help="Only the top-level files in the directory (no recursion).",
+    )
+    p_portfolio.add_argument(
+        "--recursive",
+        action="store_true",
+        help="Recurse into subdirectories (the default; accepted for clarity).",
+    )
+    p_portfolio.set_defaults(func=cmd_portfolio)
+
     return parser
 
 

{requirements_as_code-0.7.2 → requirements_as_code-0.7.3}/rac/outputs.py

@@ -754,3 +754,73 @@ def render_ingest_json(result: IngestResult, output_path: str | None) -> str:
         "markdown": result.markdown,
     }
     return json.dumps(payload, indent=2)
+
+
+# --- portfolio ---------------------------------------------------------------
+
+
+def render_portfolio_human(s) -> str:
+    """Human-readable `rac portfolio` output."""
+    lines = [
+        _bold("Repository Summary"),
+        "==================",
+        "",
+        f"Directory:  {s.directory}",
+        f"Artifacts:  {s.total_artifacts}",
+        "",
+        _bold("By Type"),
+        "-------",
+        "",
+    ]
+    for type_name, count in s.by_type.items():
+        if count > 0:
+            lines.append(f"  {type_name.title():<14} {count}")
+
+    lines += [
+        "",
+        _bold("Validation"),
+        "----------",
+        "",
+        f"  Valid:    {s.valid_artifacts}",
+        f"  Invalid:  {s.invalid_artifacts}",
+        "",
+        _bold("Completeness"),
+        "------------",
+        "",
+        f"  {s.completeness:.0%} ({s.filled_slots} / {s.recommended_slots} recommended slots filled)",
+        "",
+        _bold("Relationships"),
+        "-------------",
+        "",
+        f"  Total:    {s.relationships.total}",
+        f"  Valid:    {s.relationships.valid}",
+        f"  Broken:   {s.relationships.broken}",
+        f"  Orphaned: {s.relationships.orphaned}",
+        f"  Coverage: {s.relationships.coverage:.0%}",
+    ]
+
+    if s.attention:
+        lines += ["", _bold(f"Attention ({len(s.attention)} items)"), "----------", ""]
+        for item in s.attention:
+            icon = _red("✗") if item.severity == "error" else _yellow("!")
+            lines.append(f"  {icon} {item.identifier}")
+            lines.append(f"      {item.message}")
+    else:
+        lines += ["", _green("✓ No attention items.")]
+
+    score = s.health_score
+    score_color = _green if score >= 80 else _yellow if score >= 60 else _red
+    lines += [
+        "",
+        _bold("Health Score"),
+        "------------",
+        "",
+        f"  {score_color(str(score))} / 100",
+    ]
+
+    return "\n".join(lines)
+
+
+def render_portfolio_json(s) -> str:
+    """JSON `rac portfolio` output (stable contract, ADR-007)."""
+    return json.dumps(s.to_dict(), indent=2)