codd-dev 3.7.1__tar.gz → 3.7.3__tar.gz

{codd_dev-3.7.1 → codd_dev-3.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 3.7.1
+Version: 3.7.3
 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-3.7.1 → codd_dev-3.7.3}/codd/__init__.py

@@ -1,3 +1,3 @@
 """CoDD — Coherence-Driven Development."""
 
-__version__ = "3.7.1"
+__version__ = "3.7.3"

{codd_dev-3.7.1 → codd_dev-3.7.3}/codd/cli.py

@@ -434,6 +434,30 @@ def _display_path(path: Path, project_root: Path) -> str:
         return path.as_posix()
 
 
+def _detect_bootstrap_test_dirs(project_root: Path) -> list[str]:
+    """Detect the project's test directories for the bootstrap codd.yaml.
+
+    Reuses the extractor's inventory (``test``/``tests``/``spec``/``__tests__``)
+    so a project that uses ``test/`` is not silently excluded by a hardcoded
+    ``tests/`` default (which yields a vacuous task_completion). Falls back to the
+    conventional ``tests/`` when none exist so the config stays valid + editable.
+    """
+    from codd.extractor import _detect_test_dirs
+
+    found = _detect_test_dirs(project_root)
+    return [f"{d}/" for d in found] if found else ["tests/"]
+
+
+def _detect_bootstrap_doc_dirs(project_root: Path) -> list[str]:
+    """Detect the project's documentation directories for the bootstrap codd.yaml.
+
+    Mirrors :func:`_detect_bootstrap_test_dirs`: prefer what exists (``docs``
+    vs ``doc``), fall back to the conventional ``docs/`` when none exist.
+    """
+    found = [d for d in ("docs", "doc", "documentation") if (project_root / d).is_dir()]
+    return [f"{d}/" for d in found] if found else ["docs/"]
+
+
 def _ensure_bootstrap_codd_yaml(
     project_root: Path,
     *,
@@ -456,6 +480,8 @@ def _ensure_bootstrap_codd_yaml(
             "project_name": project_root.name,
             "language": language,
             "source_dirs": _format_yaml_list(source_dirs),
+            "test_dirs": _format_yaml_list(_detect_bootstrap_test_dirs(project_root)),
+            "doc_dirs": _format_yaml_list(_detect_bootstrap_doc_dirs(project_root)),
             "graph_path": f"{codd_dir_name}/scan",
         },
     )
@@ -2323,11 +2349,15 @@ def init(
     (codd_dir / "reports").mkdir(parents=True)
     (codd_dir / "scan").mkdir(exist_ok=True)
 
-    # Copy templates
+    # Copy templates. Greenfield init uses the conventional test/doc layout
+    # (brownfield extract detects the project's real dirs instead — see
+    # _ensure_bootstrap_codd_yaml).
     _render_template("codd.yaml.tmpl", codd_dir / "codd.yaml", {
         "project_name": project_name,
         "language": language,
         "source_dirs": _format_yaml_list(["src/"]),
+        "test_dirs": _format_yaml_list(["tests/"]),
+        "doc_dirs": _format_yaml_list(["docs/"]),
         "graph_path": f"{config_dir}/scan",
     })
     _render_template("gitignore.tmpl", codd_dir / ".gitignore", {})

{codd_dev-3.7.1 → codd_dev-3.7.3}/codd/dag/builder.py

@@ -10,7 +10,7 @@ import warnings
 from copy import deepcopy
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
 import yaml
 
@@ -911,6 +911,19 @@ def _resolve_import_target(
     path_to_node: dict[Path, str],
     aliases: dict[str, list[str]],
 ) -> str | None:
+    # Java FQN specifiers (``com.x.Y`` / ``static com.x.Y.m`` / ``com.x.*`` /
+    # ``package com.x``) are dispatched by the IMPORTING file's ``.java`` suffix
+    # (DATA, not a ``language ==`` core branch) because their dotted shape
+    # otherwise collides with Python's project-rooted dotted resolution. Java
+    # types live under a source root (``src/main/java``), not the project root.
+    if file_path.suffix == ".java":
+        candidates = _java_import_candidates(import_ref, file_path, project_root, path_to_node)
+        for candidate in candidates:
+            resolved = _resolve_file_candidate(candidate, path_to_node)
+            if resolved:
+                return resolved
+        return None
+
     candidates: list[Path] = []
     if _is_js_relative_specifier(import_ref):
         # JS/TS relative: ``./foo`` / ``../foo`` — resolve against the file dir
@@ -981,6 +994,119 @@ def _python_relative_candidates(import_ref: str, file_path: Path) -> list[Path]:
     return [(base / Path(*remainder.split("."))).resolve()]
 
 
+#: Conventional Java/JVM source-root segment chains (Maven/Gradle). A type whose
+#: FQN is ``com.x.Y`` lives at ``<root>/com/x/Y.java`` under one of these roots.
+_JAVA_SOURCE_ROOT_SEGMENTS = (
+    ("src", "main", "java"),
+    ("src", "test", "java"),
+    ("src", "main", "kotlin"),
+    ("src", "test", "kotlin"),
+)
+
+
+def _java_source_roots(project_root: Path, path_to_node: dict[Path, str]) -> list[Path]:
+    """Return candidate Java source roots (deepest-first), derived from DATA.
+
+    Built from the actual node file-set rather than hard-coded paths: every
+    ``…/src/main/java`` (etc.) prefix that some node file sits under becomes a
+    root, plus the project root itself as a last resort (flat layouts / default
+    package). Deeper roots are tried first so ``src/main/java`` wins over the
+    project root when both could match.
+    """
+    roots: dict[str, Path] = {}
+    for file_path in path_to_node:
+        parts = file_path.parts
+        for segments in _JAVA_SOURCE_ROOT_SEGMENTS:
+            idx = _find_segment_chain(parts, segments)
+            if idx is not None:
+                root = Path(*parts[: idx + len(segments)])
+                roots[str(root)] = root
+    ordered = sorted(roots.values(), key=lambda path: len(path.parts), reverse=True)
+    ordered.append(project_root.resolve())
+    return ordered
+
+
+def _find_segment_chain(parts: tuple[str, ...], chain: tuple[str, ...]) -> int | None:
+    """Return the start index where ``chain`` appears contiguously in ``parts``."""
+    if not chain:
+        return None
+    for start in range(len(parts) - len(chain) + 1):
+        if parts[start : start + len(chain)] == chain:
+            return start
+    return None
+
+
+def _java_import_candidates(
+    import_ref: str,
+    file_path: Path,
+    project_root: Path,
+    path_to_node: dict[Path, str],
+) -> list[Path]:
+    """Map a Java specifier to filesystem candidates under the source roots.
+
+    Handles the four shapes emitted by the Java specifier extractor:
+
+    * ``package com.x`` → the file's OWN package dir, so same-package implicit
+      references (Java needs no import for siblings) yield edges to the package's
+      other files (the caller skips the self-edge).
+    * ``com.x.*`` (wildcard) → the package directory; the caller links to the
+      in-package files found there (or skips cleanly when none are nodes).
+    * ``static com.x.Y.m`` → the owning class file ``com/x/Y.java`` (member
+      ``m`` stripped).
+    * ``com.x.Y`` (normal) → ``com/x/Y.java``.
+
+    ``_resolve_file_candidate`` appends the real ``.java`` suffix once a directory
+    candidate is produced, so package/wildcard dirs resolve to a sibling file.
+    """
+    roots = _java_source_roots(project_root, path_to_node)
+
+    if import_ref.startswith("package "):
+        package = import_ref[len("package "):].strip()
+        return _java_package_dir_candidates(package, roots)
+
+    if import_ref.endswith(".*"):
+        package = import_ref[:-2].strip()
+        return _java_package_dir_candidates(package, roots)
+
+    fqn = import_ref
+    if fqn.startswith("static "):
+        # ``static com.x.Y.member`` → owning class ``com.x.Y`` (drop the member).
+        fqn = fqn[len("static "):].strip()
+        parts = fqn.split(".")
+        if len(parts) >= 2:
+            fqn = ".".join(parts[:-1])
+
+    parts = [part for part in fqn.split(".") if part]
+    if not parts:
+        return []
+    return [(root / Path(*parts)).resolve() for root in roots]
+
+
+def _java_package_dir_candidates(package: str, roots: list[Path]) -> list[Path]:
+    parts = [part for part in package.split(".") if part]
+    if not parts:
+        return []
+    candidates: list[Path] = []
+    for root in roots:
+        package_dir = (root / Path(*parts)).resolve()
+        # List the package dir's in-tree files as candidates (same-package /
+        # wildcard linkage). ``_resolve_file_candidate`` matches exact node paths,
+        # so we hand it each existing ``.java`` file directly.
+        for node_path in _sorted_java_dir_files(package_dir):
+            candidates.append(node_path)
+    return candidates
+
+
+def _sorted_java_dir_files(package_dir: Path) -> list[Path]:
+    if not package_dir.is_dir():
+        return []
+    return sorted(
+        child.resolve()
+        for child in package_dir.iterdir()
+        if child.is_file() and child.suffix == ".java"
+    )
+
+
 def _infer_test_targets(
     test_path: Path,
     project_root: Path,
@@ -1025,30 +1151,89 @@ def _extract_python_import_specifiers(file_path: Path) -> list[str]:
     return get_extractor("python", "source").extract_import_specifiers(content)
 
 
+# Regex fallback for Java ``import`` / ``package`` specifiers, used only when the
+# tree-sitter-java binding is unavailable (otherwise the registry backend's AST
+# extractor is preferred). Mirrors the SHAPES emitted by
+# ``treesitter._extract_java_import_specifiers`` (``static`` keyword + ``.*``
+# wildcard + ``package`` line preserved) so the Java resolver branch is agnostic
+# to which extractor produced the specifier.
+_JAVA_IMPORT_SPECIFIER_RE = re.compile(
+    r"^\s*import\s+(static\s+)?([\w.]+(?:\.\*)?)\s*;",
+    re.MULTILINE,
+)
+_JAVA_PACKAGE_SPECIFIER_RE = re.compile(r"^\s*package\s+([\w.]+)\s*;", re.MULTILINE)
+
+
+def _extract_java_import_specifiers(file_path: Path) -> list[str]:
+    """Return raw Java ``import``/``package`` specifiers for DAG edge building.
+
+    Prefers the registry's Java ``source`` backend (tree-sitter-java) so the SAME
+    extraction the scanner uses produces the DAG specifiers; degrades to a regex
+    when the binding is absent. Either way the SHAPES (``static …`` / ``….*`` /
+    ``package …``) match, so ``_resolve_import_target``'s Java branch — dispatched
+    by the ``.java`` suffix (DATA), not a ``language ==`` core branch — resolves
+    them identically. Mirrors ``_extract_python_import_specifiers``.
+    """
+
+    from codd.parsing import get_extractor
+
+    content = file_path.read_text(encoding="utf-8", errors="ignore")
+    specifiers = get_extractor("java", "source").extract_import_specifiers(content)
+    if specifiers:
+        return specifiers
+    # Fallback: tree-sitter-java unavailable → RegexExtractor returned []. Recover
+    # the same specifier shapes from a line regex so Java edges still form.
+    fallback: list[str] = []
+    package_match = _JAVA_PACKAGE_SPECIFIER_RE.search(content)
+    if package_match:
+        fallback.append(f"package {package_match.group(1)}")
+    for static_kw, name in _JAVA_IMPORT_SPECIFIER_RE.findall(content):
+        if name.endswith(".*"):
+            fallback.append(name)
+        elif static_kw:
+            fallback.append(f"static {name}")
+        else:
+            fallback.append(name)
+    return fallback
+
+
+#: Suffix → raw-specifier extractor (DATA dispatch). A source file whose language
+#: carries its intra-tree dependency graph in DOTTED specifiers (Python modules,
+#: Java FQNs) resolves edges from these, instead of the builder's quoted-string
+#: ``extract_imports`` seam (JS/TS ``from '…'`` / ``require('…')``). Adding a
+#: language here is pure data — no core ``if language ==`` branch.
+_SUFFIX_SPECIFIER_EXTRACTORS: dict[str, "Callable[[Path], list[str]]"] = {
+    ".py": _extract_python_import_specifiers,
+    ".java": _extract_java_import_specifiers,
+}
+
+
 def _extract_impl_imports(file_path: Path) -> list[str]:
     """Return raw import specifiers for an implementation file.
 
-    Python impl files go through AST-based specifier extraction (the same path
-    test files use) so impl→impl import edges form for Python — the core of the
-    fix. Every other language keeps the existing quoted-specifier extractor
-    (``extract_imports``: JS/TS ``from '…'`` / ``require('…')``), unchanged.
-    Dispatch is by file suffix (DATA), mirroring ``_extract_test_imports``.
+    Python and Java impl files go through their registry-backed specifier
+    extractors (the same path test files use) so impl→impl import edges form for
+    them — the core of the fix. Every other language keeps the existing
+    quoted-specifier extractor (``extract_imports``: JS/TS ``from '…'`` /
+    ``require('…')``), unchanged. Dispatch is by file suffix (DATA).
     """
 
-    if file_path.suffix == ".py":
-        return _extract_python_import_specifiers(file_path)
+    extractor = _SUFFIX_SPECIFIER_EXTRACTORS.get(file_path.suffix)
+    if extractor is not None:
+        return extractor(file_path)
     return extract_imports(file_path)
 
 
 def _extract_test_imports(file_path: Path) -> list[str]:
     imports = extract_imports(file_path)
-    if file_path.suffix != ".py":
+    extractor = _SUFFIX_SPECIFIER_EXTRACTORS.get(file_path.suffix)
+    if extractor is None:
         return imports
 
-    # AST-based Python specifiers (relative imports included). Combined with the
-    # quoted-specifier pass above so a polyglot test file (e.g. a ``.py`` test
-    # that also embeds a JS ``require('…')`` literal in a string) keeps both.
-    return [*imports, *_extract_python_import_specifiers(file_path)]
+    # Registry-backed dotted specifiers (Python relative imports / Java FQNs)
+    # combined with the quoted-specifier pass above so a polyglot test file keeps
+    # both seams' results.
+    return [*imports, *extractor(file_path)]
 
 
 def _resolve_python_import_target(import_ref: str, project_root: Path, path_to_node: dict[Path, str]) -> str | None:
@@ -1143,6 +1328,9 @@ def _convention_path_candidates(test_path: Path, project_root: Path, convention_
     return candidates
 
 
+_TEST_DIR_NAMES = {"tests", "test", "spec", "__tests__"}
+
+
 def _is_test_file(file_path: Path, project_root: Path) -> bool:
     relative_parts = _relative_id(file_path, project_root).split("/")
     name = file_path.name
@@ -1153,9 +1341,19 @@ def _is_test_file(file_path: Path, project_root: Path) -> bool:
         return True
     if file_path.suffix == ".bats":
         return True
-    if file_path.suffix == ".py" and any(part in {"tests", "test"} for part in relative_parts[:-1]):
-        return name.startswith("test_") or name.endswith("_test.py")
-    return False
+    in_test_dir = any(part in _TEST_DIR_NAMES for part in relative_parts[:-1])
+    if file_path.suffix == ".py":
+        # Python keeps the stricter pytest/unittest convention even under a test
+        # directory (``test_*.py`` / ``*_test.py``) to avoid pulling fixtures.
+        if in_test_dir:
+            return name.startswith("test_") or name.endswith("_test.py")
+        return False
+    # Other languages: a source file living under a conventional test directory
+    # is a test even without a ``.test.`` infix — e.g. Mocha/Tape ``test/app.js``
+    # (Express) or ``spec/foo.js``. The caller already gates on ``test_suffixes``
+    # and the configured ``test_file_patterns`` (scoped to the project's test
+    # dirs), so this never sweeps in arbitrary source files.
+    return in_test_dir
 
 
 def _load_import_aliases(project_root: Path, settings: dict[str, Any]) -> dict[str, list[str]]:

codd_dev-3.7.3/codd/dag/checks/transitive_closure.py

@@ -0,0 +1,211 @@
+"""Transitive closure DAG completeness check."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from codd.dag.checks import register_dag_check
+
+
+@dataclass
+class TransitiveClosureResult:
+    check_name: str = "transitive_closure"
+    severity: str = "amber"
+    unreachable_nodes: list[str] = field(default_factory=list)
+    common_node_count: int = 0
+    passed: bool = True
+    # ``status``/``skipped``/``checked_count`` close a vacuous-pass hole: an empty
+    # DAG (or one whose every node is ``common`` and therefore exempt from
+    # reachability) used to return a green PASS having examined zero nodes.
+    # ``checked_count`` is the number of non-common nodes whose reachability was
+    # actually evaluated; when it is 0 the run is a SKIP, not a clean pass.
+    status: str = "pass"
+    skipped: bool = False
+    checked_count: int = 0
+
+
+# Edge kinds that represent an in-project source-import dependency
+# (importer -> imported). Used to identify *code-entry roots*: source nodes that
+# nothing in the project imports. This is a structural classification of edges,
+# not a language/framework branch.
+_IMPORT_EDGE_KINDS = frozenset({"imports"})
+
+# Node kinds that are NOT first-class source nodes for entry-root detection:
+# design docs are handled by their own root rule, and ``common`` nodes are shared
+# infrastructure exempt from reachability. Anything else (``impl_file`` and any
+# future source kind) is treated as a source node — no per-language literal.
+_NON_SOURCE_KINDS = frozenset({"design_doc", "common"})
+
+
+@register_dag_check("transitive_closure")
+class TransitiveClosureCheck:
+    """Report unreachable nodes without blocking deploy.
+
+    A node is *reachable* if it can be reached from **any entry root**:
+
+    - **design_doc roots** — ``design_doc`` nodes with no incoming edge (the
+      classic "every artifact descends from a design document" model); and
+    - **code-entry roots** — source nodes (everything that is neither a
+      ``design_doc`` nor a ``common`` node) with no incoming in-project *import*
+      edge, i.e. the package's public entry points (e.g. a package
+      ``__init__`` or a CLI ``__main__`` that nothing else imports).
+
+    Seeding from the *union* of these makes reachability meaningful on doc-less
+    BROWNFIELD projects (raw external code with zero design docs but a fully
+    connected import graph) while leaving doc-rooted projects unchanged:
+    code-entry roots are purely additive. Only nodes unreachable from ALL entries
+    are flagged — genuine orphans.
+
+    Entry-root detection is structural (incoming-edge analysis on import-kind
+    edges), never a ``language ==`` branch.
+
+    Cycle / no-entry fallback: if a project has source nodes but none qualify as
+    a code-entry root (every source node has an in-project importer — a pure
+    cycle), reachability falls back to seeding from *all* source nodes for that
+    project, so connectivity is still measured rather than reported as a false
+    "everything unreachable". Cycles are traversed safely (visited-set guard).
+
+    Nodes with ``kind == "common"`` (shared infrastructure declared via
+    ``common_node_patterns`` or frontmatter ``node_type: common``) remain exempt
+    from unreachable detection. They participate in the DAG so change-impact
+    analysis still sees them, but they do not need to be the descendant of a
+    single design document.
+    """
+
+    def __init__(self, dag=None, project_root: Path | None = None, settings: dict[str, Any] | None = None):
+        self.dag = dag
+        self.project_root = project_root
+        self.settings = settings or {}
+
+    def run(
+        self,
+        dag=None,
+        project_root: Path | None = None,
+        settings: dict[str, Any] | None = None,
+    ) -> TransitiveClosureResult:
+        dag = dag or self.dag
+        if dag is None or not dag.nodes:
+            # No nodes at all → reachability examined nothing → SKIP (not a
+            # vacuous green PASS).
+            return TransitiveClosureResult(
+                status="skip",
+                skipped=True,
+                checked_count=0,
+            )
+
+        to_ids = {edge.to_id for edge in dag.edges}
+        design_roots = [
+            node.id
+            for node in dag.nodes.values()
+            if node.kind == "design_doc" and node.id not in to_ids
+        ]
+        code_roots = self._code_entry_roots(dag)
+
+        # Reachable from ANY entry: design-doc roots OR code-entry roots. The
+        # union keeps doc-rooted projects unchanged (design roots still seed) and
+        # makes doc-less brownfield projects measurable (code roots seed the
+        # connected impl graph).
+        roots = list(dict.fromkeys([*design_roots, *code_roots]))
+
+        visited = self._reachable_from(dag, roots)
+        common_count = sum(
+            1 for node in dag.nodes.values() if node.kind == "common"
+        )
+        # Common nodes are exempt from unreachable detection, so the number of
+        # nodes whose reachability is actually evaluated is the non-common set.
+        checked = sum(1 for node in dag.nodes.values() if node.kind != "common")
+        unreachable = [
+            node_id
+            for node_id, node in dag.nodes.items()
+            if node_id not in visited and node.kind != "common"
+        ]
+
+        if checked == 0:
+            # Every node is exempt (all ``common``): reachability examined nothing.
+            # A clean PASS here is a vacuous false-green → SKIP instead.
+            return TransitiveClosureResult(
+                unreachable_nodes=[],
+                common_node_count=common_count,
+                passed=True,
+                status="skip",
+                skipped=True,
+                checked_count=0,
+            )
+
+        return TransitiveClosureResult(
+            unreachable_nodes=unreachable,
+            common_node_count=common_count,
+            passed=True,
+            status="pass",
+            skipped=False,
+            checked_count=checked,
+        )
+
+    def _code_entry_roots(self, dag) -> list[str]:
+        """Public entry points of the import graph (heads nothing imports).
+
+        A *source node* is any node that is neither a ``design_doc`` (handled by
+        its own root rule) nor a ``common`` node (exempt infrastructure). A source
+        node is a *code-entry root* when it **participates in the import graph as a
+        head**: it has at least one outgoing in-project import edge (it imports
+        something) AND no incoming import edge (nothing imports it). These are the
+        package's public entry points (e.g. ``__init__`` / ``__main__``).
+
+        Requiring an *outgoing* import edge is what preserves no-false-green: a
+        node with zero import edges (isolated -- imported by nothing and importing
+        nothing) is a genuine orphan, NOT an entry root, and therefore stays
+        flagged. Only nodes that actually anchor an import chain seed reachability.
+
+        Fallback (pure cycle / no head): if no source node qualifies as a head but
+        some source nodes still *participate* in the import graph (a cycle where
+        every node has an importer), seed from all participating source nodes so
+        connectivity is still measured instead of a false "everything
+        unreachable". Isolated orphans (no import edges) are never seeded and stay
+        flagged even in the fallback.
+        """
+        source_ids = {
+            node.id
+            for node in dag.nodes.values()
+            if node.kind not in _NON_SOURCE_KINDS
+        }
+        if not source_ids:
+            return []
+
+        import_to: set[str] = set()
+        import_from: set[str] = set()
+        for edge in dag.edges:
+            if edge.kind in _IMPORT_EDGE_KINDS:
+                import_to.add(edge.to_id)
+                import_from.add(edge.from_id)
+
+        # Heads: import something in-project, imported by nothing in-project.
+        entry_roots = [
+            nid
+            for nid in source_ids
+            if nid in import_from and nid not in import_to
+        ]
+        if entry_roots:
+            return entry_roots
+
+        # No clean head (pure cycle): seed from source nodes that participate in
+        # the import graph at all, so connectivity is still measured. Nodes with
+        # no import edges remain genuine orphans (never seeded here).
+        return [nid for nid in source_ids if nid in import_to or nid in import_from]
+
+    def _reachable_from(self, dag, roots: list[str]) -> set[str]:
+        visited: set[str] = set()
+        queue = deque(roots)
+
+        while queue:
+            current = queue.popleft()
+            if current in visited:
+                continue
+            visited.add(current)
+            for edge in dag.edges:
+                if edge.from_id == current and edge.to_id not in visited:
+                    queue.append(edge.to_id)
+
+        return visited

{codd_dev-3.7.1 → codd_dev-3.7.3}/codd/extract_ai.py

@@ -57,6 +57,60 @@ CONFIG_FILES = [
 # IaC patterns
 IAC_EXTENSIONS = {".bicep", ".bicepparam", ".tf", ".tfvars", ".hcl"}
 
+
+def ai_command_has_tools(ai_command: str) -> bool:
+    """Return whether ``ai_command`` grants the model file/shell tools.
+
+    The extract prompt's "Extraction Procedure" enumerates the codebase via bash
+    (``find``/``ls``/``rg``). That only works when the AI CLI can actually shell
+    out. The default ``ai_command`` disables tools (``--tools ""``), and agentic
+    CLIs are hardened to read-only from an empty workspace elsewhere — so the
+    procedural bash framing pushes the model into agentic mode and it stubs or
+    hangs. We therefore treat NO TOOLS as the safe default and require an
+    explicit grant to keep the tool-enabled path.
+
+    Tools are considered AVAILABLE only when a ``--tools``/``--allowedTools``
+    flag carries a non-empty value. ``--tools ""`` (or the flag absent) → no
+    tools. Unparseable commands fail closed to no-tools (context-only is always
+    correct because the full PROJECT CONTEXT is embedded in the prompt).
+    """
+    import shlex
+
+    try:
+        parts = shlex.split(ai_command)
+    except ValueError:
+        return False
+
+    tool_flags = {"--tools", "--allowedTools", "--allowed-tools"}
+    for i, part in enumerate(parts):
+        flag, sep, inline = part.partition("=")
+        if flag in tool_flags:
+            value = inline if sep else (parts[i + 1] if i + 1 < len(parts) else "")
+            if value.strip():
+                return True
+    return False
+
+
+# Prepended to the prompt when the AI CLI has no tools: it overrides the
+# template's bash "Extraction Procedure" so the model extracts from the embedded
+# PROJECT CONTEXT instead of trying to shell out (which it cannot do).
+_NO_TOOLS_DIRECTIVE = """# ═══ EXECUTION MODE: NO TOOLS (context-only) ═══
+
+You are running WITHOUT shell or file-system tools. Do NOT call any tool, do NOT
+run bash/`find`/`ls`/`rg`/`cat`, and do NOT attempt to read files from disk.
+
+The COMPLETE pre-scanned codebase — the directory tree plus the full contents of
+every relevant source, config, IaC, and test file — is embedded verbatim under
+"PROJECT CONTEXT (pre-scanned)" further down this prompt. That embedded context
+is your ONLY source of truth.
+
+When the "Extraction Procedure" below shows ```bash``` enumeration commands,
+treat them as a DESCRIPTION of what to look for, NOT as commands to execute.
+Instead, derive the same information by reading the embedded file contents
+directly. Produce the full output document set in one response from that context.
+
+"""
+
 # Schema file patterns
 SCHEMA_PATTERNS = [
     "prisma/schema.prisma", "db/schema.rb", "alembic/versions",
@@ -360,10 +414,20 @@ def pre_scan(project_root: Path) -> PreScanResult:
 # Phase 2: AI prompt building
 # ═══════════════════════════════════════════════════════════
 
-def _build_prompt(scan: PreScanResult) -> str:
-    """Build the AI prompt from pre-scan results + extract template."""
+def _build_prompt(scan: PreScanResult, *, tools_available: bool = False) -> str:
+    """Build the AI prompt from pre-scan results + extract template.
+
+    ``tools_available`` reflects whether the AI CLI can shell out (see
+    :func:`ai_command_has_tools`). When False (the default for ``--tools ""``),
+    a NO-TOOLS directive is prepended so the model extracts from the embedded
+    PROJECT CONTEXT instead of trying to run the template's bash procedure.
+    """
     sections: list[str] = []
 
+    # No-tools mode: override the template's bash procedure up front.
+    if not tools_available:
+        sections.append(_NO_TOOLS_DIRECTIVE)
+
     # Load prompt template
     if PROMPT_TEMPLATE_FILE.exists():
         template = PROMPT_TEMPLATE_FILE.read_text(encoding="utf-8")
@@ -810,6 +874,10 @@ def run_extract_ai(
     # Phase 1: Pre-scan
     scan = pre_scan(project_root)
 
+    # Whether the AI CLI can shell out. The default ``--tools ""`` disables
+    # tools, so the prompt must NOT lean on its bash enumeration procedure.
+    tools_available = ai_command_has_tools(ai_command)
+
     # Phase 2: Build prompt (custom or baseline)
     if prompt_file:
         custom_path = Path(prompt_file)
@@ -819,10 +887,10 @@ def run_extract_ai(
         # Temporarily swap template for custom prompt
         import codd.extract_ai as _self
         _self.PROMPT_TEMPLATE_FILE = custom_path
-        prompt = _build_prompt(scan)
+        prompt = _build_prompt(scan, tools_available=tools_available)
         _self.PROMPT_TEMPLATE_FILE = original_template
     else:
-        prompt = _build_prompt(scan)
+        prompt = _build_prompt(scan, tools_available=tools_available)
 
     # Phase 3: AI invocation
     raw_output = _invoke_ai_command(ai_command, prompt)