codd-dev 2.29.0__tar.gz → 2.31.0__tar.gz

{codd_dev-2.29.0 → codd_dev-2.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.29.0
+Version: 2.31.0
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev

{codd_dev-2.29.0 → codd_dev-2.31.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "2.29.0"
+__version__ = "2.31.0"

{codd_dev-2.29.0 → codd_dev-2.31.0}/codd/e2e_generator.py

@@ -375,6 +375,17 @@ def _render_header_comments(scenario: UserScenario, context: GenerationContext,
     if scenario.kind == "operational":
         source_operation = _source_operation_label(scenario)
         coverage_axis = scenario.coverage_axis or "unspecified"
+        # Machine-injection guard (anti-false-coverage): injecting a coverage
+        # marker is ONLY safe here because the mapping is HARNESS-OWNED and
+        # machine-known — this is a skeleton the harness itself generates for
+        # ``operation=<X>`` and the marker names that same operation. NEVER
+        # inject ``codd: covers vb=<id>`` into a free-form unit/integration test
+        # by guessing the VB from a test name or nearby text: a guessed marker is
+        # a false coverage claim the authenticity gate exists to reject. A VB
+        # marker may only be authored by the SUT on a test that genuinely proves
+        # the behavior, or attached to a harness-generated VB-specific skeleton
+        # whose asserting body the SUT fills in (still subject to the
+        # assertion-presence gate).
         lines.extend(
             [
                 "// Operational E2E policy: run the whole generated suite, collect all failures, then repair after the full campaign finishes.",

{codd_dev-2.29.0 → codd_dev-2.31.0}/codd/generator.py

@@ -226,6 +226,7 @@ _TEST_DOC_CANONICAL_VB_HEAD = [
     "- Every verifiable behavior must map to at least one test scenario — if a design document specifies a transition chain (e.g. action → intermediate state → final state), each link in the chain requires a separate assertion.",
     "- Include a traceability section that lists each verifiable behavior and its corresponding test scenario(s). Flag any behavior that lacks coverage.",
     "- Write that traceability section as a Markdown table whose FIRST column is a stable verifiable-behavior id of the form `VB-<id>` (e.g. `VB-01`, `VB-AUTH-02`), one row per verifiable behavior. Header wording and language are free; CoDD machine-parses the `VB-` id in the first cell (`codd test audit`), so never merge multiple behaviors into one row and never omit the id column.",
+    "- Each VB id must be ATOMIC — name exactly one behavior. Never use range or list shorthand in an id (no `VB-EVAL-02..06`, no `VB-02,03`, no `VB-02〜06`); write one row with a distinct atomic id per behavior instead. A range id cannot be honestly covered by a single test marker, and its members would read as permanently uncovered.",
     "- Declare each behavior under exactly one stable id; do not split one behavior across two ids or reuse an id for two different behaviors.",
     "- Treat design-time `operation_flow` records as the authoritative source for operational test obligations. Do not invent E2E-only behavior that is absent from requirements or design; instead flag missing design obligations.",
 ]

{codd_dev-2.29.0 → codd_dev-2.31.0}/codd/greenfield/pipeline.py

@@ -733,16 +733,29 @@ class GreenfieldPipeline:
         # — code that does not even typecheck cannot have meaningful VB coverage.
         self._enforce_implement_oracle_gate(project_root, tasks, options)
 
-        # Project-wide VB coverage gate — ONCE, after every implement task has
-        # run and all covering tests therefore exist. Per-task enforcement was
-        # disabled in _default_implement_task_runner precisely because the gate
-        # is project-wide; this is where it belongs. Honors the greenfield
-        # coverage_gate option (--no-coverage-gate / greenfield.coverage_gate:
-        # false) — when the owner turned it off, the final gate is skipped too.
+        # Project-wide VB coverage + marker-authenticity gate — ONCE, after every
+        # implement task has run and all covering tests therefore exist. Per-task
+        # enforcement was disabled in _default_implement_task_runner precisely
+        # because the gate is project-wide; this is where it belongs. Honors the
+        # greenfield coverage_gate option (--no-coverage-gate /
+        # greenfield.coverage_gate: false) — when the owner turned it off, the
+        # final gate is skipped too. The rerun is wired (was dormant): an
+        # uncovered VB drives a bounded, TEST-SCOPED re-implementation (source is
+        # never edited by a VB rerun) with gap feedback, and the native oracle is
+        # re-asserted after each test edit.
+        coverage_on = bool(options.get("coverage_gate", True))
         _enforce_stage_coverage_gate(
             project_root,
-            coverage_gate=bool(options.get("coverage_gate", True)),
+            coverage_gate=coverage_on,
             echo=self.echo,
+            rerun=self._make_vb_rerun_callback(project_root, tasks, options) if coverage_on else None,
+            rerun_oracle=(
+                (lambda: self._enforce_implement_oracle_gate(project_root, tasks, options))
+                if coverage_on
+                else None
+            ),
+            scope_resolver=self._make_vb_scope_resolver(project_root, tasks) if coverage_on else None,
+            authenticity_profile=self._resolve_layout_profile(project_root) if coverage_on else None,
         )
         record["detail"] = f"{len(tasks)} task(s) implemented"
 
@@ -1051,6 +1064,91 @@ class GreenfieldPipeline:
                 feedback=feedback,
             )
 
+    def _make_vb_rerun_callback(
+        self,
+        project_root: Path,
+        tasks: list[ImplementTaskRef],
+        options: dict[str, Any],
+    ) -> Callable[[str, Any], None]:
+        """A ``rerun(feedback, scope)`` for the VB coverage gate's feedback loop.
+
+        Reuses the oracle's scoped, write-fenced rerun dispatch
+        (:meth:`_rerun_tasks_with_feedback`): a TEST-scoped
+        :class:`~codd.implement_oracle_scope.OracleRerunScope` re-implements ONLY
+        its test tasks, fenced to test files/helpers, so a VB coverage rerun can
+        never rewrite production source.
+        """
+
+        def _rerun(feedback: str, scope: Any = None) -> None:
+            self._rerun_tasks_with_feedback(project_root, tasks, feedback, options, scope=scope)
+
+        return _rerun
+
+    def _make_vb_scope_resolver(
+        self,
+        project_root: Path,
+        tasks: list[ImplementTaskRef],
+    ) -> Callable[[list[str]], Any]:
+        """A resolver mapping uncovered VB source docs → a TEST-scoped rerun scope.
+
+        Delegates to :func:`codd.vb_rerun_scope.derive_vb_rerun_scope` with the
+        pipeline's ``_output_paths_for_task`` so each task's outputs resolve the
+        same way the rerun itself resolves them. A derivation failure degrades to
+        a broad scope (never aborts the gate).
+        """
+        from codd.config import load_project_config
+
+        def _resolve(uncovered_source_docs: list[str]) -> Any:
+            try:
+                config = load_project_config(project_root)
+            except (FileNotFoundError, ValueError):
+                config = {}
+            try:
+                from codd.vb_rerun_scope import derive_vb_rerun_scope
+
+                return derive_vb_rerun_scope(
+                    uncovered_source_docs,
+                    tasks,
+                    config=config,
+                    path_resolver=_output_paths_for_task,
+                )
+            except Exception as exc:  # noqa: BLE001 — degrade to broad, never abort.
+                self.echo(f"[greenfield] VB rerun: scope derivation failed ({exc}); rerun stays broad.")
+                from codd.implement_oracle_scope import SCOPE_BROAD, OracleRerunScope
+
+                return OracleRerunScope(
+                    rung=SCOPE_BROAD,  # canonical broad ⇒ is_broad() True ⇒ unfenced
+                    task_ids=tuple(task.task_id for task in tasks),
+                    allowed_paths=(),
+                    detail="VB rerun: scope derivation error — broad fallback",
+                )
+
+        return _resolve
+
+    def _resolve_layout_profile(self, project_root: Path) -> Any:
+        """Resolve the active :class:`~codd.project_types.LayoutProfile` (or None).
+
+        Used by the marker-authenticity gate to obtain the per-language
+        test-block adapter (``profile.test_block_profile()``). Best-effort: any
+        resolution failure returns ``None`` so the gate degrades to its
+        language-agnostic stage-1 (orphan) check rather than aborting.
+        """
+        try:
+            from codd.project_types import resolve_layout_profile
+
+            config, language, source_dirs, test_dirs = self._layout_inputs(project_root)
+            return resolve_layout_profile(
+                language=language,
+                project_name=self._layout_project_name(project_root, config),
+                source_dirs=source_dirs,
+                test_dirs=test_dirs,
+                config=config,
+                project_root=project_root,
+            )
+        except Exception as exc:  # noqa: BLE001 — authenticity degrades without a profile.
+            self.echo(f"[greenfield] VB authenticity: layout profile unavailable ({exc}); stage-1 only.")
+            return None
+
     def _default_implement_task_runner(
         self,
         project_root: Path,
@@ -1997,8 +2095,12 @@ def _enforce_stage_coverage_gate(
     *,
     coverage_gate: bool,
     echo: Callable[[str], None],
+    rerun: Callable[[str, Any], None] | None = None,
+    rerun_oracle: Callable[[], None] | None = None,
+    scope_resolver: Callable[[list[str]], Any] | None = None,
+    authenticity_profile: Any = None,
 ) -> None:
-    """Project-wide verifiable-behavior coverage gate for the implement STAGE.
+    """Project-wide verifiable-behavior coverage + authenticity gate (implement STAGE).
 
     Runs ONCE after every implement task has completed, so all covering tests
     already exist. This is the correct granularity for the project-wide VB
@@ -2008,20 +2110,35 @@ def _enforce_stage_coverage_gate(
     — an early fixtures/helper task that writes no covering tests would
     otherwise hard-fail against the whole project's VBs.)
 
-    No ``rerun`` is wired: by stage end the build is complete, so any remaining
-    uncovered VB is a genuine failure of the whole implement stage, not a
-    transient gap to re-implement away. The failure is raised as a
-    :class:`StageError` carrying the gap list, which the pipeline records on the
-    implement stage record and surfaces through the existing checkpoint/resume
-    machinery.
-
-    Honors the greenfield ``coverage_gate`` option: when it is off
-    (``--no-coverage-gate`` / ``greenfield.coverage_gate: false``) the gate is
-    skipped entirely. The project-level ``test_coverage.gate`` config is also
-    respected (via :func:`run_implement_coverage_gate`).
+    Two gates, both HARD (raise :class:`StageError` on failure):
+
+    1. **Coverage** (:func:`run_implement_coverage_gate`): every declared VB has a
+       ``covers``/``blocked`` marker. When a ``rerun`` callback is wired, an
+       uncovered gap drives a bounded, TEST-SCOPED re-implementation with gap
+       feedback (the previously-dormant feedback loop, now live) before failing.
+    2. **Authenticity** (:func:`build_authenticity_report`): each ``covers``
+       marker is a *credible* claim — attached to an executable test block that
+       contains an assertion (anti-false-green; "add a marker" cannot be
+       satisfied by marking an empty/skipped test). Gracefully degrades for
+       stacks/files it cannot structurally parse.
+
+    ``rerun(feedback, scope)`` re-implements the scoped TEST tasks under a
+    write-fence (source is never edited by a VB rerun). ``scope_resolver`` maps
+    the uncovered VB source docs to that scope. ``rerun_oracle`` re-runs the
+    native implement-oracle AFTER a VB rerun (a test edit can break a helper
+    symbol; the pipeline order is oracle→VB, so the oracle must be re-asserted).
+
+    Honors the greenfield ``coverage_gate`` option and the project-level
+    ``test_coverage.gate`` config.
     """
     from codd.config import load_project_config
-    from codd.verifiable_behavior_audit import run_implement_coverage_gate
+    from codd.verifiable_behavior_audit import (
+        build_vb_coverage_audit,
+        coverage_gate_enabled,
+        coverage_gate_max_retries,
+        format_gap_feedback,
+        run_implement_coverage_gate,
+    )
 
     if not coverage_gate:
         return
@@ -2031,6 +2148,9 @@ def _enforce_stage_coverage_gate(
     except (FileNotFoundError, ValueError):
         config = {}
 
+    if not coverage_gate_enabled(config):
+        return
+
     # Pass the configured test dirs as the audited output paths so the gate
     # treats this as a test-related run (it is — every test the build will ever
     # have now exists) and evaluates the FULL project VB universe in one pass.
@@ -2040,13 +2160,52 @@ def _enforce_stage_coverage_gate(
     else:
         audited_paths = ["tests/"]
 
+    # --- Gate 1: coverage, with the (now-live) TEST-scoped feedback rerun. ---
+    if rerun is not None and scope_resolver is not None:
+        # Drive the bounded feedback loop HERE so each rerun is TEST-scoped (the
+        # scope is recomputed from the current gap) and the native oracle is
+        # re-asserted after each test edit. ``run_implement_coverage_gate`` is
+        # then called once more with rerun=None to produce the final verdict +
+        # gap reporting (no second loop).
+        max_retries = coverage_gate_max_retries(config)
+        report = build_vb_coverage_audit(project_root, config=config)
+        attempt = 0
+        while report.rows and report.uncovered_rows and attempt < max_retries:
+            attempt += 1
+            uncovered_docs = sorted({row.source_doc for row in report.uncovered_rows if row.source_doc})
+            scope = scope_resolver(uncovered_docs)
+            echo(
+                f"Test coverage gate: {len(report.uncovered_rows)} uncovered verifiable behavior(s); "
+                f"re-running TEST tasks with gap feedback (attempt {attempt}/{max_retries})"
+            )
+            try:
+                rerun(format_gap_feedback(report), scope)
+                if rerun_oracle is not None:
+                    # A VB test rerun can break test↔helper symbol coherence;
+                    # re-assert the native oracle so a type/import break never
+                    # rides into verify.
+                    rerun_oracle()
+            except Exception as exc:  # noqa: BLE001
+                # A rerun that cannot proceed (e.g. a codegen/environment error)
+                # must NOT mask the gate's verdict: log and stop the bounded loop,
+                # then fall through to the final coverage audit, which fails
+                # HONESTLY on whatever VBs are still uncovered. (The oracle gate
+                # treats its rerun failures as hard because they ARE the defect;
+                # here the authority is the coverage audit below, not the rerun.)
+                echo(
+                    f"Test coverage gate: re-run attempt {attempt} could not complete ({exc}); "
+                    "stopping the feedback loop and evaluating coverage as-is."
+                )
+                break
+            report = build_vb_coverage_audit(project_root, config=config)
+
     passed = run_implement_coverage_gate(
         project_root,
         config=config,
         design_node=None,
         output_paths=audited_paths,
         opt_out=not coverage_gate,
-        rerun=None,
+        rerun=None,  # the scoped loop (above) already ran; this is the final verdict
         echo=echo,
         echo_error=echo,
     )
@@ -2057,6 +2216,29 @@ def _enforce_stage_coverage_gate(
             "marker after all implement tasks completed (see the gap list above)"
         )
 
+    # --- Gate 2: marker authenticity (anti-false-green). HARD gate. ---
+    from codd.vb_marker_authenticity import build_authenticity_report
+
+    auth = build_authenticity_report(project_root, config=config, profile=authenticity_profile)
+    if auth.degraded_paths:
+        echo(
+            "Test coverage gate: marker-authenticity attachment/assertion checks skipped for "
+            f"{len(auth.degraded_paths)} un-parseable file(s) (stage-1 orphan check still applied): "
+            + ", ".join(auth.degraded_paths)
+        )
+    if not auth.passed:
+        for violation in auth.violations:
+            echo(violation.message)
+        raise StageError(
+            "verifiable-behavior marker-authenticity gate failed for the implement stage: "
+            f"{len(auth.violations)} `codd: covers vb=` marker(s) are not credible coverage claims "
+            "(attached to a skipped/empty test, an orphan id, or a test with no assertion). A "
+            "covers marker must sit on an executable test that asserts the behavior."
+        )
+    echo(
+        f"Test coverage gate: marker authenticity OK ({len(auth.degraded_paths)} file(s) stage-1-only)."
+    )
+
 
 def _default_verify_runner(
     project_root: Path,

{codd_dev-2.29.0 → codd_dev-2.31.0}/codd/implementer.py

@@ -1884,9 +1884,10 @@ def _build_implementation_prompt(
     if _spec_targets_tests(spec, config):
         lines.extend(
             [
-                "Verifiable-behavior traceability markers:",
-                "- If the design or dependency test documents declare verifiable-behavior ids (a traceability table whose first column is `VB-<id>`), annotate each generated test with a comment marker `codd: covers vb=<id>` for every behavior that test proves (`codd test audit` reconciles these markers).",
-                "- If a declared behavior cannot be tested yet, add an explicit `codd: blocked vb=<id> reason=<short_reason>` comment marker instead of leaving it silently uncovered.",
+                "Verifiable-behavior traceability markers (release-blocking — the implement stage gate fails the build on any gap):",
+                "- The design and its dependency test documents declare verifiable behaviors in a traceability table whose first column is `VB-<id>`. Reconcile EVERY declared VB id against the tests you write: for each VB, produce either a real test that PROVES it (carrying a `codd: covers vb=<id>` comment marker) or, if it genuinely cannot be tested yet, an explicit `codd: blocked vb=<id> reason=<short_reason>` marker. Never leave a declared VB silently uncovered.",
+                "- A `codd: covers vb=<id>` marker is a CLAIM that the test proves that behavior. Only attach it to a test that (a) is actually executed — not `it.skip`/`test.todo`/`describe.skip`/`@pytest.mark.skip`/disabled — and (b) contains at least one assertion that would FAIL if the behavior were broken. A marker on an empty test, a skipped test, or a smoke test with no assertion is a false coverage claim and the authenticity gate will reject it. If no proving test exists, create or extend a real one FIRST, then mark it — do not add the marker to make the gate pass.",
+                "- One marker per behavior, placed inside the test file (a comment immediately above the proving test). Example (pytest): `# codd: covers vb=VB-07` directly above `def test_rejects_missing_id(): ...` whose body asserts the rejection. Example (vitest): `// codd: covers vb=VB-07` directly above the `it('rejects missing id', () => { expect(...).toThrow(); })`.",
                 "",
                 "Scoped assertions (precision, not weakening):",
                 "- When a test asserts a CONTENT constraint over rendered or serialized output (e.g. \"displayed amounts contain no decimal point\", \"no personal data appears in the response\", \"every listed price shows a currency symbol\"), assert ONLY against the specific values or elements the constraint governs: parse and read the relevant nodes/fields under test (DOM elements, table cells, the parsed JSON values, the matched record), not the whole response body.",

{codd_dev-2.29.0 → codd_dev-2.31.0}/codd/project_types.py

@@ -589,6 +589,34 @@ class LayoutProfile:
 
         return tuple(paths)
 
+    def test_block_profile(self) -> Any:
+        """Resolve this stack's test-structure adapter for the VB authenticity gate.
+
+        Returns a ``codd.vb_marker_authenticity.TestBlockProfile`` (a per-language
+        parser that locates executable test blocks and resolves skip/assertion
+        facts) or ``None`` for a stack with no adapter — in which case the
+        authenticity gate gracefully degrades to its language-agnostic stage 1
+        (orphan-marker) check only. This is the SINGLE registration point for a
+        new stack's test parser, mirroring :meth:`harness_owned_scaffold_paths`
+        (dispatch on ``self.language``, no per-language logic in the gate). The
+        import is lazy so the authenticity module (which imports the VB audit) is
+        never pulled in at ``project_types`` import time.
+        """
+
+        try:
+            from codd.vb_marker_authenticity import (
+                PythonTestBlockProfile,
+                TypeScriptTestBlockProfile,
+            )
+        except Exception:  # noqa: BLE001 — adapter is optional; degrade if unavailable.
+            return None
+
+        if self.language == "python":
+            return PythonTestBlockProfile()
+        if self.language in ("typescript", "node", "javascript"):
+            return TypeScriptTestBlockProfile()
+        return None
+
 
 def normalize_package_name(project_name: str | None, *, fallback: str = "app") -> str:
     """Derive a valid Python package identifier from a project name.