codd-dev 3.4.0__tar.gz → 3.6.0__tar.gz

{codd_dev-3.4.0 → codd_dev-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 3.4.0
+Version: 3.6.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
@@ -193,7 +193,8 @@ CoDD ships **39 ready-made "lexicons"** — checklists drawn from real industry
 
 ## Documentation
 
-- [`docs/explainer.md`](docs/explainer.md) — the full idea, from the connection map to AI-driven development
+- [`docs/explainer.md`](docs/explainer.md) — the full idea, from the connection map to AI-driven development ([English](docs/explainer.en.md) · [简体中文](docs/explainer.zh.md))
+- [`docs/positioning.md`](docs/positioning.md) — where CoDD sits vs Spec Kit / coding agents / Copilot, on the false-green axis
 - [`CHANGELOG.md`](CHANGELOG.md) — every release
 - `codd --help` — the full command reference (in any project, `codd check` is the best place to start)
 - [`docs/`](docs/) — architecture notes, setup guides, and a cookbook

{codd_dev-3.4.0 → codd_dev-3.6.0}/README.md

@@ -151,7 +151,8 @@ CoDD ships **39 ready-made "lexicons"** — checklists drawn from real industry
 
 ## Documentation
 
-- [`docs/explainer.md`](docs/explainer.md) — the full idea, from the connection map to AI-driven development
+- [`docs/explainer.md`](docs/explainer.md) — the full idea, from the connection map to AI-driven development ([English](docs/explainer.en.md) · [简体中文](docs/explainer.zh.md))
+- [`docs/positioning.md`](docs/positioning.md) — where CoDD sits vs Spec Kit / coding agents / Copilot, on the false-green axis
 - [`CHANGELOG.md`](CHANGELOG.md) — every release
 - `codd --help` — the full command reference (in any project, `codd check` is the best place to start)
 - [`docs/`](docs/) — architecture notes, setup guides, and a cookbook

{codd_dev-3.4.0 → codd_dev-3.6.0}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "3.4.0"
+__version__ = "3.6.0"

{codd_dev-3.4.0 → codd_dev-3.6.0}/codd/cli.py

@@ -742,11 +742,23 @@ def check_cmd(project_path: str, run_full: bool, apply_fixes: bool, output_forma
         status_value = _dag_result_status(result)
         if status_value == "opt_out":
             status = "OPT_OUT"
+        elif status_value in {"skip", "skipped"} or getattr(result, "skipped", False):
+            # A skipped check verified nothing — show it distinctly, never as PASS,
+            # so a run with silent skips is not indistinguishable from a clean one.
+            status = "SKIP"
         elif _dag_result_passed(result):
             status = "PASS"
         else:
             status = "WARN" if severity == "amber" else "FAIL"
         _line(f"  {status}  {_dag_result_name(result)} [{severity}]")
+    skipped_count = sum(
+        1
+        for result in dag_results
+        if _dag_result_status(result) in {"skip", "skipped"}
+        or getattr(result, "skipped", False)
+    )
+    if skipped_count:
+        _line(f"  {skipped_count} check(s) SKIP — verified nothing (dormant / unconfigured)")
     if failed_red or amber_findings:
         _line("  Run 'codd dag verify' for details.")
 
@@ -8436,6 +8448,10 @@ def dag_verify(
             status_value = _dag_result_status(result)
             if status_value == "opt_out":
                 status = "OPT_OUT"
+            elif status_value in {"skip", "skipped"} or getattr(result, "skipped", False):
+                # A skipped check verified nothing — show it distinctly, never as
+                # PASS, so silent skips are not indistinguishable from a clean run.
+                status = "SKIP"
             elif _dag_result_passed(result):
                 status = "PASS"
             else:
@@ -8444,6 +8460,16 @@ def dag_verify(
             for detail in _dag_result_details(result):
                 click.echo(f"    {detail}")
 
+        skipped_count = sum(
+            1
+            for result in results
+            if _dag_result_status(result) in {"skip", "skipped"}
+            or getattr(result, "skipped", False)
+        )
+        if skipped_count:
+            click.echo(
+                f"\n{skipped_count} check(s) SKIP — verified nothing (dormant / unconfigured)"
+            )
         if failed_red:
             click.echo(f"\n{len(failed_red)} check(s) FAILED (severity=red)")
         elif amber_findings:

{codd_dev-3.4.0 → codd_dev-3.6.0}/codd/dag/checks/resource_flow_coherence.py

@@ -105,7 +105,23 @@ class ResourceFlowCoherenceCheck(DagCheck):
             uses.extend(node_uses)
             alias_map.update(node_aliases)
 
+        malformed_warnings = self._malformed_contract_warnings(design_docs)
+
         if not uses:
+            if malformed_warnings:
+                # Contracts were declared but every entry is unusable (missing a
+                # required field). Surface that as amber — never a silent clean skip.
+                return ResourceFlowCoherenceResult(
+                    severity="amber",
+                    status="pass",
+                    passed=True,
+                    block_deploy=False,
+                    message=(
+                        f"resource_flow_coherence: {len(malformed_warnings)} declared "
+                        "contract entry(ies) unusable (malformed)"
+                    ),
+                    warnings=malformed_warnings,
+                )
             return ResourceFlowCoherenceResult(
                 severity="info",
                 status="skip",
@@ -127,7 +143,9 @@ class ResourceFlowCoherenceCheck(DagCheck):
                 consumers.append(use)
 
         violations: list[dict[str, Any]] = []
-        warnings: list[dict[str, Any]] = self._dead_resource_warnings(producers, consumers)
+        warnings: list[dict[str, Any]] = (
+            self._dead_resource_warnings(producers, consumers) + malformed_warnings
+        )
         for consumer in sorted(consumers, key=lambda c: (c.resource, c.capability or "", c.owner_node_id)):
             if not self._is_required(consumer):
                 continue
@@ -145,6 +163,11 @@ class ResourceFlowCoherenceCheck(DagCheck):
                             f"Required consumer reads {consumer.resource} but its capability "
                             "is not a required capability of any critical/high journey; not gated."
                         ),
+                        "remediation": (
+                            f"Add {consumer.capability} to a critical/high journey's "
+                            "required_capabilities to gate it, or mark the consumer "
+                            "required:false if it is not essential."
+                        ),
                     }
                 )
                 continue
@@ -163,6 +186,12 @@ class ResourceFlowCoherenceCheck(DagCheck):
                         f"Required consumer reads {consumer.resource}, but no producer / "
                         "provided-by obligation exists in the contract graph."
                     ),
+                    "remediation": (
+                        f"Declare a producer / provided-by obligation for {consumer.resource} "
+                        "(e.g. a capability that produces it, or externally_provided_by), or "
+                        "relax the consumer (required: false / on_missing: skip) if it is not "
+                        "truly required."
+                    ),
                 }
             )
 
@@ -185,7 +214,10 @@ class ResourceFlowCoherenceCheck(DagCheck):
             status="pass",
             passed=True,
             block_deploy=False,
-            message="resource_flow_coherence PASS",
+            message=(
+                f"resource_flow_coherence PASS "
+                f"({len(consumers)} consumer(s), {len(producers)} producer(s) checked)"
+            ),
             warnings=warnings,
         )
 
@@ -329,10 +361,57 @@ class ResourceFlowCoherenceCheck(DagCheck):
                     "message": (
                         f"Resource {resource} has producer obligation(s) but no declared consumers."
                     ),
+                    "remediation": (
+                        f"Consume {resource} where it is needed, or drop the producer / mark "
+                        "it externally_provided_by if it is intentionally external."
+                    ),
                 }
             )
         return warnings
 
+    def _malformed_contract_warnings(self, design_docs: list[Any]) -> list[dict[str, Any]]:
+        # A declared contract entry missing its required key field is unusable: the
+        # collectors above drop it silently. Surface it as amber so a malformed
+        # declaration is never an invisible no-op.
+        warnings: list[dict[str, Any]] = []
+        for node in design_docs:
+            attrs = getattr(node, "attributes", None) or {}
+            for index, entry in enumerate(self._entries(attrs, "capability_contracts")):
+                if not self._str(entry.get("capability")):
+                    warnings.append(
+                        self._malformed(node.id, f"capability_contracts[{index}]", "missing 'capability'")
+                    )
+                for sub_key in ("consumes", "produces"):
+                    for j, sub in enumerate(self._dict_list(entry.get(sub_key))):
+                        if not self._str(sub.get("resource")):
+                            warnings.append(
+                                self._malformed(
+                                    node.id,
+                                    f"capability_contracts[{index}].{sub_key}[{j}]",
+                                    "missing 'resource'",
+                                )
+                            )
+            for index, entry in enumerate(self._entries(attrs, "resource_contracts")):
+                if not self._str(entry.get("resource")):
+                    warnings.append(
+                        self._malformed(node.id, f"resource_contracts[{index}]", "missing 'resource'")
+                    )
+        return warnings
+
+    @staticmethod
+    def _malformed(owner_node_id: str, location: str, detail: str) -> dict[str, Any]:
+        return {
+            "type": "malformed_contract",
+            "severity": "amber",
+            "owner_node_id": owner_node_id,
+            "location": location,
+            "message": (
+                f"Declared contract entry at {location} is unusable ({detail}); "
+                "it would otherwise be dropped silently."
+            ),
+            "remediation": f"Fix the entry at {location} ({detail}), or remove it if unintended.",
+        }
+
     # ---------------------------------------------------------- canonical/parse
     def _canonical(self, resource: str, alias_map: dict[str, str]) -> str:
         value = (resource or "").strip()

{codd_dev-3.4.0 → codd_dev-3.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codd-dev"
-version = "3.4.0"
+version = "3.6.0"
 description = "CoDD: Coherence-Driven Development — cross-artifact change impact analysis"
 readme = "README.md"
 license = "MIT"