spec-tracer 0.1.0__tar.gz

spec_tracer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ampyard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spec_tracer-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: spec-tracer
+Version: 0.1.0
+Summary: CLI tool that collates test results from **Unit, Integration, and E2E** test suites into a single HTML report.
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: behave-modern-html-report>=2.2.2
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: pytest-html>=4.2.0
+Dynamic: license-file

spec_tracer-0.1.0/README.md

@@ -0,0 +1,213 @@
+# SpecTracer
+
+<div align="center">
+<img src="docs/hero-image.png" style="align: center; width:50%; height: auto"></img>
+
+<p>
+
+[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)   [![CI](https://github.com/ampyard/spec-tracer/actions/workflows/ci.yml/badge.svg)](https://github.com/ampyard/spec-tracer/actions/workflows/ci.yml)
+
+</p>
+</div>
+
+A CLI tool that takes your Gherkin `.feature` files as the source of truth for what needs testing, then collates test results from your **Unit**, **Integration**, and **E2E** suites into a single, self-contained HTML report — plus an optional machine-readable JSON twin for CI automation.
+
+Feature files define the scope. Tags on scenarios link them to test results across layers. The report shows:
+
+- What percentage of scenarios actually have test coverage (the headline metric).
+- Where that coverage exists across layers (per-scenario pass/fail/skip breakdown).
+- The overall test pyramid — test count, duration, and pass rate per layer.
+- Every failure's stack trace, in one place.
+
+An optional JSON report (conforming to [`spectracer-report.schema.json`](spectracer-report.schema.json)) mirrors the same data for scripting — PR bots, custom gating, dashboards — without scraping HTML.
+
+The tool is tech-stack agnostic: it only needs Gherkin `.feature` files, JUnit XML, and Cucumber JSON, so it works regardless of what languages or frameworks produced them.
+
+## Why
+
+- **Fragmented visibility** — unit, integration, and E2E tests usually live in different directories or repos, with no single view of overall coverage.
+- **Inverted pyramids** — teams unknowingly accumulate slow E2E tests instead of fast unit tests, and don't notice until CI is painfully slow.
+- **No traceability** — it's hard to know if a specific business scenario is actually tested across all the layers it should be.
+- **Tooling lock-in** — most reporting tools are tied to one framework (Allure for Java, Cypress Dashboard for Cypress). This one isn't.
+
+## Installation
+
+Requires Python 3.12+.
+
+```bash
+uv sync
+```
+
+This installs the tool along with its only runtime dependency, Jinja2.
+
+To build a wheel for local testing:
+
+```bash
+uv build
+```
+
+The wheel is written to `dist/unified_test_tracer-*.whl`. Install it with `uv pip install dist/*.whl`.
+
+## Quick Start
+
+1. Write `.feature` files describing your scenarios, tagged so test results can link back to them (see [Tagging Convention](#tagging-convention) below).
+2. Run your test suites and produce JUnit XML (unit/integration) and/or Cucumber JSON (E2E) output.
+3. Create a `specspectracer.config.json` in your project root:
+
+   ```json
+   {
+     "features": ["./features"],
+     "unit": { "": ["./reports/unit.xml"] },
+     "integration": { "": ["./reports/integration.xml"] },
+     "e2e": ["./reports/e2e.json"],
+     "output": "./report.html"
+   }
+   ```
+
+4. Run the tool:
+
+   ```bash
+   uv run python build_pyramid.py
+   ```
+
+   It auto-discovers `spectracer.config.json` in the current directory — no flags needed. Open the generated `report.html` in a browser.
+
+To point at a config file with a different name or location, pass it as the only argument:
+
+```bash
+uv run python build_pyramid.py path/to/other-config.json
+```
+
+> **Note on shells:** use forward slashes (`./spectracer.config.json`) or a bare filename. A leading `.\` (PowerShell-style) can be mangled by POSIX-style shells (Git Bash, WSL), since backslash is their escape character there.
+
+## Tagging Convention
+
+Feature files and test results connect via **shared tags**. There are two kinds of tags a scenario can carry:
+
+```gherkin
+Feature: User Login
+
+  @FC-42 @regression @require-unit:auth @require-integration:auth @require-e2e
+  Scenario: Successful login with valid credentials
+    Given the user is on the login page
+    When they enter valid credentials
+    Then they should be redirected to the dashboard
+
+  @FC-43
+  Scenario: Login with invalid password shows error
+    Given the user is on the login page
+    When they enter an invalid password
+    Then an error message should be displayed
+```
+
+- **Linking tags** (`@FC-42`, `@regression`) — shared with test results. Any test result carrying a matching tag links to that scenario.
+- **Layer requirement tags** (`@require-unit`, `@require-integration`, `@require-e2e`) — declare which layers *must* have coverage for this scenario. These are never used for linking, and the tool flags any declared layer that ends up with zero linked results.
+
+### Module-scoped requirements
+
+`@require-unit` and `@require-integration` accept an optional `:modulename` suffix, e.g. `@require-unit:auth`. This pairs with module-keyed entries in the config file's `unit`/`integration` objects (see below) — a module-scoped requirement is only satisfied by a result registered under that exact module. An unscoped result (config key `""`) never satisfies it, and a bare `@require-unit` (no module) is satisfied by any linked unit result regardless of module.
+
+`@require-e2e` does not accept a module suffix, since E2E scenarios typically span multiple modules by nature.
+
+### Matching rules
+
+- **Exact string match** — `@FC-42` matches `@FC-42` only, not `@FC-4` or `@FC-42-smoke`.
+- **OR logic** — a scenario tagged `[@FC-42, @regression]` links to a test carrying just `@regression`.
+- **Scenario tags only** — tags on the `Feature:` line are **not** inherited by scenarios.
+- **`@require-*` tags** are excluded from linking — no collision with linking tags is possible.
+- **Tag collisions link everywhere** — if two scenarios (in the same or different feature files) share a tag, one matching test result links to both.
+
+### Where the tool looks for tags in test results
+
+- **JUnit XML (unit/integration):** the `name` attribute, `classname` attribute, or `<properties><property>` elements — whichever your framework populates.
+- **Cucumber JSON (E2E):** the native scenario-level `tags` array.
+
+## Configuration File
+
+The tool is configured entirely through a JSON file — there are no CLI flags. Default filename is `spectracer.config.json` at the project root; pass an explicit path as the sole CLI argument to use a different one.
+
+```json
+{
+  "features": ["./features"],
+  "unit": {
+    "": ["./reports/unit.xml"],
+    "billing": ["./reports/billing-unit.xml"]
+  },
+  "integration": {
+    "": ["./reports/integration.xml"]
+  },
+  "e2e": ["./reports/e2e.json"],
+  "output": "./report.html",
+  "output_json": "./report.json",
+  "error_on_failure": false,
+  "health_checks": {
+    "progress_threshold_green": 80,
+    "progress_threshold_amber": 50,
+    "e2e_duration_amber_seconds": 600,
+    "e2e_duration_red_seconds": 1800
+  }
+}
+```
+
+| Key | Required | Description |
+|---|---|---|
+| `features` | Yes | Array of Gherkin `.feature` file or directory paths (directories are searched recursively). |
+| `unit` | No | Object keyed by module name. Each value is an array of JUnit XML file/directory paths. Use `""` as the key for results not tied to any module. Matched against `@require-unit` / `@require-unit:<module>` tags. |
+| `integration` | No | Same shape as `unit`, matched against `@require-integration` / `@require-integration:<module>` tags. |
+| `e2e` | No | Array of Cucumber JSON file/directory paths. E2E results are never module-scoped. |
+| `output` | Yes | Path for the generated HTML report. Created if the parent directory doesn't exist; overwritten if it already exists. |
+| `output_json` | No | Path for a machine-readable JSON report, conforming to [`spectracer-report.schema.json`](spectracer-report.schema.json). Omit to skip JSON output entirely (default). Same directory-creation/overwrite semantics as `output`. |
+| `error_on_failure` | No | If `true`, exit non-zero when any test result is a failure. Default: `false`. Health checks never affect the exit code — this is the only thing that does. |
+| `health_checks` | No | Overrides for the default thresholds shown above. |
+
+## The Report
+
+The generated HTML is a single self-contained file (all CSS/JS inlined — no external assets, safe to email or archive) with five sections:
+
+1. **Coverage Progress Summary** — the headline `Tested: X / Y scenarios (Z%)` metric, plus a per-feature breakdown. Color-coded green/amber/red using the configurable thresholds.
+2. **Global Pyramid Dashboard** — a 3-tier visualization (E2E / Integration / Unit) with test counts, duration, and pass rate per layer, plus health indicators for an inverted pyramid or an E2E layer with excessive runtime.
+3. **Feature Traceability & Scenario Matrix** — a searchable, expandable tree: Feature → Scenario → Layer results, with full Gherkin text, declared layer requirements (✓/✗), and per-test pass/fail/skip status with failure stack traces.
+4. **Detailed Failure Breakdown** — every failed test across all layers, with feature/scenario context and full stack trace on expand.
+5. **Unlinked Tests** — test results whose tags didn't match any scenario, to help catch orphaned or mis-tagged tests.
+
+## Machine-Readable JSON Report
+
+Setting `output_json` in the config produces a JSON file alongside the HTML report, built from the exact same internal data — the two outputs can never drift apart. It conforms to [`spectracer-report.schema.json`](spectracer-report.schema.json) (Draft 7), which is the authoritative contract; the highlights:
+
+- `summary.coverage` / `summary.pyramid` / `summary.health` — the same headline metric, per-layer stats, and health status (`green`/`amber`/`red` with `reasons[]`) shown on the HTML dashboard.
+- `features[].scenarios[].results[]` — every linked test result per scenario, with `duration` (milliseconds) and `failureMessage` **omitted** rather than `null` when not available, and layer requirement satisfaction under `requirements[]`.
+- `unlinkedTests[]` — the same orphaned results shown in the HTML report's "Unlinked Tests" page.
+- `config` — a verbatim echo of the resolved config used to produce the report, for provenance if the JSON is archived independently of the repo.
+
+```json
+{
+  "features": ["./features"],
+  "unit": { "": ["./reports/unit.xml"] },
+  "e2e": ["./reports/e2e.json"],
+  "output": "./report.html",
+  "output_json": "./report.json"
+}
+```
+
+Useful for PR bots, custom CI gating beyond `error_on_failure`, or feeding coverage numbers into a dashboard — without scraping the HTML.
+
+## Behavior Reference
+
+| Scenario | Behavior |
+|---|---|
+| No config file found and none specified | Errors out — a config file is mandatory. |
+| Config missing `features` or `output` | Errors out — both are mandatory keys. |
+| Empty or missing test result path | Silently ignored (zero tests for that layer). |
+| Malformed JUnit XML or Cucumber JSON | Aborts with a clear error message. |
+| Test matches no scenario | Listed in "Unlinked Tests". |
+| Scenario matches no test | Shown as "untested". |
+| Scenario has `@require-*` but no matching test | That layer is flagged as missing. |
+| Feature-level tags | Not inherited by scenarios — only scenario-level tags are used for matching. |
+| Scenario Outline / Examples, `Rule:`, `Background:`, non-English dialects | Deferred to whatever your Gherkin/E2E framework does with them — the tool doesn't parse Gherkin syntax beyond `Feature:`, tags, and `Scenario:` lines. |
+| Unicode / special characters | Preserved, HTML-escaped in the report. |
+
+## What This Tool Doesn't Do
+
+- **Not a test runner** — it only parses results after your tests have already run.
+- **Not a source-code parser** — it never reads your `.java`/`.py`/`.js` files, only `.feature` files and test-result output.
+- **No tag expressions** — matching is exact string equality only; no `not`/`and`/`or` boolean tag logic.

spec_tracer-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "spec-tracer"
+version = "0.1.0"
+description = "CLI tool that collates test results from **Unit, Integration, and E2E** test suites into a single HTML report."
+requires-python = ">=3.12"
+dependencies = [
+  "behave-modern-html-report>=2.2.2",
+  "Jinja2>=3.1",
+  "pytest-html>=4.2.0",
+]
+[project.scripts]
+spec-tracer = "spec_tracer.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "behave>=1.2",
+  "jsonschema>=4.23",
+]
+[tool.setuptools.packages.find]
+exclude = ["features*", "reports*"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.behave]
+formatters.modern = "behave_modern_html_report.formatter:ModernHTMLFormatter"

spec_tracer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spec_tracer-0.1.0/spec_tracer/__init__.py

@@ -0,0 +1,3 @@
+from spec_tracer.cli import main
+
+__all__ = ["main"]

spec_tracer-0.1.0/spec_tracer/aggregator.py

@@ -0,0 +1,188 @@
+from collections import defaultdict
+from typing import Dict, List
+
+from spec_tracer.models import Scenario, ScenarioView, TestResult
+
+
+class ReportAggregator:
+
+    LAYER_ORDER = ["e2e", "integration", "unit"]
+
+    @staticmethod
+    def build_views(
+        scenarios: List[Scenario],
+        links: Dict[int, List[TestResult]],
+    ) -> List[ScenarioView]:
+        layer_rank = {layer: i for i, layer in enumerate(ReportAggregator.LAYER_ORDER)}
+        views: List[ScenarioView] = []
+        for scenario in scenarios:
+            linked = sorted(links.get(id(scenario), []), key=lambda r: layer_rank.get(r.layer, len(layer_rank)))
+            by_layer: Dict[str, List[TestResult]] = {}
+            for result in linked:
+                by_layer.setdefault(result.layer, []).append(result)
+            layers = [by_layer.get(layer, []) for layer in ReportAggregator.LAYER_ORDER if by_layer.get(layer)]
+            views.append(ScenarioView(scenario=scenario, linked_results=linked, layers=layers))
+        return views
+
+    @staticmethod
+    def coverage_stats(views: List[ScenarioView]) -> dict:
+        total = len(views)
+        tested = sum(1 for v in views if v.is_tested)
+        percentage = int(round((tested / total * 100) if total else 0))
+        return {"total": total, "tested": tested, "percentage": percentage}
+
+    @staticmethod
+    def feature_breakdown(views: List[ScenarioView]) -> List[dict]:
+        features: Dict[str, List[ScenarioView]] = defaultdict(list)
+        for view in views:
+            features[view.scenario.feature].append(view)
+
+        breakdown: List[dict] = []
+        for feature_name, feature_views in sorted(features.items()):
+            feature_tested = sum(1 for v in feature_views if v.is_tested)
+            feature_total = len(feature_views)
+            feature_pct = int(round((feature_tested / feature_total * 100) if feature_total else 0))
+            breakdown.append({
+                "name": feature_name,
+                "tested": feature_tested,
+                "total": feature_total,
+                "percentage": feature_pct,
+            })
+        return breakdown
+
+    MIN_TIER_WIDTH_PCT = 28
+
+    @staticmethod
+    def layer_stats(views: List[ScenarioView]) -> List[dict]:
+        linked_results = [result for view in views for result in view.linked_results]
+        metrics: List[dict] = []
+        for layer in ReportAggregator.LAYER_ORDER:
+            layer_results = [result for result in linked_results if result.layer == layer]
+            if not layer_results:
+                continue
+            passed = sum(1 for result in layer_results if result.status == "passed")
+            failed = sum(1 for result in layer_results if result.status == "failed")
+            skipped = sum(1 for result in layer_results if result.status == "skipped")
+            duration = sum(result.duration for result in layer_results)
+            total = len(layer_results)
+            metrics.append(
+                {
+                    "name": layer,
+                    "label": layer.upper(),
+                    "count": total,
+                    "passed": passed,
+                    "failed": failed,
+                    "skipped": skipped,
+                    "duration": duration,
+                    "pass_pct": int(round((passed / total * 100) if total else 0)),
+                    "fail_pct": int(round((failed / total * 100) if total else 0)),
+                    "skip_pct": int(round((skipped / total * 100) if total else 0)),
+                }
+            )
+        max_count = max((metric["count"] for metric in metrics), default=0)
+        for metric in metrics:
+            share = (metric["count"] / max_count * 100) if max_count else 0
+            metric["width_pct"] = round(max(share, ReportAggregator.MIN_TIER_WIDTH_PCT if metric["count"] else 0), 1)
+        return metrics
+
+    @staticmethod
+    def failure_breakdown(views: List[ScenarioView]) -> List[dict]:
+        features: Dict[str, List[ScenarioView]] = defaultdict(list)
+        for view in views:
+            if any(result.status == "failed" for result in view.linked_results):
+                features[view.scenario.feature].append(view)
+
+        breakdown: List[dict] = []
+        for feature_name, feature_views in sorted(features.items()):
+            scenarios = []
+            for view in feature_views:
+                failed_results = [r for r in view.linked_results if r.status == "failed"]
+                scenarios.append({"view": view, "failed_results": failed_results})
+            breakdown.append({
+                "name": feature_name,
+                "scenarios": scenarios,
+                "failed_count": sum(len(s["failed_results"]) for s in scenarios),
+            })
+        return breakdown
+
+    @staticmethod
+    def health_checks(
+        views: List[ScenarioView],
+        layer_stats: List[dict],
+        progress_stats: dict,
+        unlinked_count: int = 0,
+        progress_threshold_green: float = 80,
+        progress_threshold_amber: float = 50,
+        e2e_duration_amber_seconds: float = 600,
+        e2e_duration_red_seconds: float = 1800,
+    ) -> dict:
+        progress_pct = progress_stats["percentage"]
+        if progress_pct >= progress_threshold_green:
+            progress_status = "pass"
+            progress_message = "Progress is healthy."
+        elif progress_pct >= progress_threshold_amber:
+            progress_status = "warn"
+            progress_message = "Progress still needs attention."
+        else:
+            progress_status = "fail"
+            progress_message = "Progress is below the comfort threshold."
+
+        unit_count = next((metric["count"] for metric in layer_stats if metric["name"] == "unit"), 0)
+        integration_count = next((metric["count"] for metric in layer_stats if metric["name"] == "integration"), 0)
+        e2e_count = next((metric["count"] for metric in layer_stats if metric["name"] == "e2e"), 0)
+        if unit_count > integration_count + e2e_count:
+            pyramid_status = "pass"
+            pyramid_message = "Unit coverage is strong enough for the pyramid."
+        elif unit_count == integration_count + e2e_count:
+            pyramid_status = "warn"
+            pyramid_message = "Unit coverage is exactly at parity — add more unit tests."
+        else:
+            pyramid_status = "fail"
+            pyramid_message = "The pyramid is inverted and needs more unit coverage."
+
+        e2e_duration = next((metric["duration"] for metric in layer_stats if metric["name"] == "e2e"), 0.0)
+        if e2e_duration <= e2e_duration_amber_seconds:
+            e2e_status = "pass"
+            e2e_message = "End to end Runtime is within the healthy envelope."
+        elif e2e_duration <= e2e_duration_red_seconds:
+            e2e_status = "warn"
+            e2e_message = "End to end Runtime is getting slow."
+        else:
+            e2e_status = "fail"
+            e2e_message = "End to end Runtime exceeds the configured threshold."
+
+        if unlinked_count == 0:
+            unlinked_status = "pass"
+            unlinked_message = "Every parsed result was linked to a scenario."
+        elif unlinked_count <= 3:
+            unlinked_status = "warn"
+            unlinked_message = "A few results didn't link to any scenario."
+        else:
+            unlinked_status = "fail"
+            unlinked_message = "Several results didn't link to any scenario."
+
+        return {
+            "Progress": {"status": progress_status, "message": progress_message, "value": f"{progress_stats['tested']}/{progress_stats['total']}"},
+            "pyramid": {
+                "status": pyramid_status,
+                "message": pyramid_message,
+                "value": f"e2e {e2e_count} · integration {integration_count} · unit {unit_count}",
+                "layers": [
+                    {"name": "e2e", "count": e2e_count},
+                    {"name": "integration", "count": integration_count},
+                    {"name": "unit", "count": unit_count},
+                ],
+            },
+            "end_to_end_runtime": {"status": e2e_status, "message": e2e_message, "value": f"{e2e_duration:.1f}s"},
+            "unlinked": {"status": unlinked_status, "message": unlinked_message, "value": str(unlinked_count)},
+        }
+
+    @staticmethod
+    def unlinked_results(scenarios: List[Scenario], results: List[TestResult]) -> List[TestResult]:
+        scenario_tags = {tag for scenario in scenarios for tag in scenario.tags}
+        return [
+            result
+            for result in results
+            if not any(tag in scenario_tags for tag in result.tags)
+            and any(tag.startswith("@FC-") for tag in result.tags)
+        ]

spec_tracer-0.1.0/spec_tracer/cli.py

@@ -0,0 +1,153 @@
+import base64
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, List
+
+from spec_tracer.aggregator import ReportAggregator
+from spec_tracer.collectors import FileCollector
+from spec_tracer.linker import ResultLinker
+from spec_tracer.parsers import CucumberParser, FeatureParser, JunitParser
+from spec_tracer.renderers import HtmlRenderer
+from spec_tracer.report_model import build_report
+
+DEFAULT_CONFIG_NAME = "spectracer.config.json"
+
+
+def _find_config_path(argv: List[str] | None = None) -> Path:
+    args = sys.argv[1:] if argv is None else argv
+    if args:
+        path = Path(args[0])
+    else:
+        path = Path(DEFAULT_CONFIG_NAME)
+    if not path.exists():
+        raise FileNotFoundError(f"Config file not found: {path}")
+    return path
+
+
+def _load_config(path: Path) -> dict:
+    config = json.loads(path.read_text(encoding="utf-8"))
+    if "features" not in config:
+        raise ValueError("Config is missing required key: 'features'")
+    if "output" not in config:
+        raise ValueError("Config is missing required key: 'output'")
+    return config
+
+
+def _load_logo(config_dir: Path) -> str:
+    logo_path = config_dir / "docs" / "logo.png"
+    if logo_path.exists():
+        data = logo_path.read_bytes()
+        encoded = base64.b64encode(data).decode("ascii")
+        return f"data:image/png;base64,{encoded}"
+    return ""
+
+
+def _collect_and_parse_features(paths: List[str], base_dir: Path) -> tuple:
+    files = FileCollector.feature_files(paths)
+    if not files:
+        raise FileNotFoundError("No feature files were found")
+    scenarios = []
+    feature_files: Dict[str, str] = {}
+    parser = FeatureParser()
+    resolved_base = base_dir.resolve()
+    for f in files:
+        parsed = parser.parse(f)
+        relative = os.path.relpath(f, resolved_base)
+        for scenario in parsed:
+            feature_files.setdefault(scenario.feature, relative.replace("\\", "/"))
+        scenarios.extend(parsed)
+    return scenarios, feature_files
+
+
+def _collect_and_parse_junit_results(entries: Dict[str, List[str]], parser: JunitParser, layer: str) -> List:
+    results = []
+    for module, paths in entries.items():
+        files = FileCollector.xml_files(paths)
+        results.extend(parser.parse(files, layer=layer, module=module))
+    return results
+
+
+def _collect_and_parse_e2e_results(paths: List[str], parser: CucumberParser) -> List:
+    files = FileCollector.json_files(paths)
+    return parser.parse(files, layer="e2e")
+
+
+def main(argv: List[str] | None = None) -> int:
+    config_path = _find_config_path(argv)
+    config = _load_config(config_path)
+
+    scenarios, feature_files = _collect_and_parse_features(config["features"], config_path.parent)
+
+    junit_parser = JunitParser()
+    unit_results = _collect_and_parse_junit_results(config.get("unit", {}), junit_parser, "unit")
+    integration_results = _collect_and_parse_junit_results(config.get("integration", {}), junit_parser, "integration")
+
+    cucumber_parser = CucumberParser()
+    e2e_results = _collect_and_parse_e2e_results(config.get("e2e", []), cucumber_parser)
+
+    results = e2e_results + unit_results + integration_results
+
+    links = ResultLinker.link(scenarios, results)
+    views = ReportAggregator.build_views(scenarios, links)
+    stats = ReportAggregator.coverage_stats(views)
+    breakdown = ReportAggregator.feature_breakdown(views)
+    layer_stats = ReportAggregator.layer_stats(views)
+    failed_results = [result for result in results if result.status == "failed"]
+    unlinked_results = ReportAggregator.unlinked_results(scenarios, results)
+    health_check_config = config.get("health_checks", {})
+    health_checks = ReportAggregator.health_checks(
+        views,
+        layer_stats,
+        stats,
+        unlinked_count=len(unlinked_results),
+        progress_threshold_green=health_check_config.get("progress_threshold_green", 80),
+        progress_threshold_amber=health_check_config.get("progress_threshold_amber", 50),
+        e2e_duration_amber_seconds=health_check_config.get("e2e_duration_amber_seconds", 600),
+        e2e_duration_red_seconds=health_check_config.get("e2e_duration_red_seconds", 1800),
+    )
+    failure_breakdown = ReportAggregator.failure_breakdown(views)
+
+    renderer = HtmlRenderer()
+    html = renderer.render(
+        views,
+        stats,
+        breakdown,
+        layer_stats=layer_stats,
+        health_checks=health_checks,
+        failed_results=failed_results,
+        unlinked_results=unlinked_results,
+        failure_breakdown=failure_breakdown,
+        logo_data_uri=_load_logo(config_path.parent),
+    )
+
+    output_path = Path(config["output"])
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(html, encoding="utf-8")
+
+    if config.get("output_json"):
+        report = build_report(
+            config,
+            views,
+            stats,
+            layer_stats,
+            health_checks,
+            unlinked_results,
+            feature_files=feature_files,
+        )
+        output_json_path = Path(config["output_json"])
+        output_json_path.parent.mkdir(parents=True, exist_ok=True)
+        output_json_path.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+    if config.get("error_on_failure", False) and any(result.status == "failed" for result in results):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except Exception as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(1) from exc

spec_tracer-0.1.0/spec_tracer/collectors.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+from typing import List
+
+
+class FileCollector:
+
+    @staticmethod
+    def feature_files(paths: List[str]) -> List[Path]:
+        files: List[Path] = []
+        for raw_path in paths:
+            path = Path(raw_path)
+            if not path.exists():
+                raise FileNotFoundError(f"Feature path does not exist: {path}")
+            if path.is_file() and path.suffix == ".feature":
+                files.append(path)
+            elif path.is_dir():
+                files.extend(sorted(path.rglob("*.feature")))
+        return sorted({path.resolve() for path in files})
+
+    @staticmethod
+    def xml_files(paths: List[str]) -> List[Path]:
+        files: List[Path] = []
+        for raw_path in paths:
+            path = Path(raw_path)
+            if not path.exists():
+                continue
+            if path.is_file():
+                files.append(path)
+            elif path.is_dir():
+                files.extend(sorted(path.rglob("*.xml")))
+        return sorted({path.resolve() for path in files})
+
+    @staticmethod
+    def json_files(paths: List[str]) -> List[Path]:
+        files: List[Path] = []
+        for raw_path in paths:
+            path = Path(raw_path)
+            if not path.exists():
+                continue
+            if path.is_file():
+                files.append(path)
+            elif path.is_dir():
+                files.extend(sorted(path.rglob("*.json")))
+        return sorted({path.resolve() for path in files})