ai-codeindex 0.26.2__tar.gz → 0.27.0__tar.gz

{ai_codeindex-0.26.2 → ai_codeindex-0.27.0}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-06-28
+
+**Theme**: graph-export + parser robustness. Ships the new `codeindex
+graph-export` command — codeindex's write-once data contract with loomgraph
+(ADR-007, gated GREEN/YELLOW by the LoomGraph#30 consumption spike) — plus
+the in-run AI retry (#97) and the cross-language partial-parse recovery (#95)
+that were sitting unreleased on master. graph-export is **additive**: it is a
+standalone command, the new `GraphBuffer` IR (#101) it reuses is dormant
+(unwired into `scan-all`), and existing `scan-all` / `parse` / `symbols`
+output is unchanged. No migration needed.
+
+### Added
+
+- **`codeindex graph-export` — write-once graph artifact for loomgraph** (GH #102, ADR-007, **experimental schema_version 0**): a standalone command that does its own clean whole-tree parse and dumps NDJSON of code entities (`class`/`function`/`method`, module-qualified id + `source_id` + first-line description + `provenance`) and `CALLS`/`INHERITS` edges. It is **decoupled from `scan-all`/README render** — the LoomGraph#30 consumption spike (verdict 🟡 YELLOW) justified the export but not the #101 render-flip, and the two are architecturally independent (export needs the buffer *populated*, not the render path *flipped*). The parser emits *file-local* names, so the export performs the only cross-file resolution pass: every edge carries a **`resolution_qualifier`** (`resolved` / `ambiguous` / `unresolved`, with `candidates` on ambiguous) so a consumer never reads an unresolved edge as real, plus **`dst_raw`** (the original best-effort name) so a consumer can still synthesise an external stub or filter framework noise when `dst` is null, and the meta header carries **`provenance_completeness`** flagging that AST extraction misses dynamic dispatch / reflection (the spike's E-class finding — an absent edge means "not statically resolvable", not "none"). Schema is experimental and Python-validated; a TS spot-check precedes any stable-contract promise. Reuses the #101 `GraphBuffer` purely as the parsed-data container; ships no persistent/mutable state (ADR-007).
+- **`scan-all --ai` retries transient AI failures in-run** (GH #97): a serial enrichment pass that hit a one-off haiku timeout / rate-limit / 5xx previously lost that directory until a manual re-run (observed 12/50 transient failures in the GH #94 A/B). `invoke_ai_cli` now takes `max_attempts` (scan paths use 3) and retries with exponential backoff, but **only** on recognised-transient signals (`_is_transient`: timeout, rate-limit, 429, 502/503/529, overload, connection reset, …). Permanent failures — a misconfigured `ai_command` (`command not found`, exit 127) or any unlabeled non-zero exit — **fail fast** (single attempt) so they are not hammered N× across every directory. Not a backend/direct-API change: the agent-CLI invocation stays the only transport. Default `max_attempts=1` preserves single-shot behavior for every other caller.
+
+### Fixed
+
+- **TypeScript parser no longer zeroes out a whole file on one unsupported construct** (GH #95): the bundled `tree-sitter-typescript` grammar (0.23.2 — the latest published, so this is *not* a stale pin but upstream grammar lag) does not parse some modern-TS constructs, e.g. `export type *` (TS 5.0) and generic-typed tagged templates like Prisma `$queryRaw<{...}[]>`...``. The parser bailed the moment `tree.root_node.has_error` was true, returning `symbols: []` — so a single unparseable line dropped the file's entire class/method set from `PROJECT_SYMBOLS.md` and its directory `README_AI.md` (hit 2/608 `.ts` files on a real monorepo, silently). tree-sitter error recovery is *local*, so the surrounding symbols are still in the tree. `TypeScriptParser.parse` now extracts symbols regardless of `has_error`, returns whatever is recoverable flagged with a new `ParseResult.partial=True`, and only surfaces the hard `error="Syntax error in source file"` when nothing at all could be recovered. Consumers that branch on `result.error` (enrichment, tech-debt, error counts) are unaffected — a partial file has `error=None` so its recovered symbols flow through. Verified: `LockController.ts` with a `$queryRaw<T>` line went from `symbols: []` to recovering its class + all 4 members.
+- **Same partial-parse recovery applied to all remaining parsers** (GH #95 fast-follow): the identical `has_error` early-bail existed in `base` (used by Swift), `python`, `java`, `php`, and `objc`. All now extract regardless of `has_error`, return recoverable symbols flagged `partial=True`, and only emit the hard error when nothing is recoverable — so a single malformed construct no longer zeroes a whole file in any supported language. Cross-language regression test (`tests/test_parser_partial_recovery.py`) covers python/java/php/swift/objc; two Java tests that asserted the old all-or-nothing contract were updated to the graceful-degradation contract.
+
 ## [0.26.2] - 2026-06-22
 
 **Theme**: enrichment-quality patch. `scan-all --ai` was silently writing punt

{ai_codeindex-0.26.2 → ai_codeindex-0.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-codeindex
-Version: 0.26.2
+Version: 0.27.0
 Summary: AI-native code indexing tool for large codebases
 Project-URL: Homepage, https://github.com/dreamlx/codeindex
 Project-URL: Documentation, https://github.com/dreamlx/codeindex

ai_codeindex-0.27.0/docs/guides/graph-export.md

@@ -0,0 +1,128 @@
+# graph-export — codeindex → loomgraph data contract
+
+> **Status: EXPERIMENTAL (`schema_version: 0`).** Validated on Python; a
+> TypeScript spot-check precedes any stable-contract promise. Fields and
+> format may change without deprecation while at version 0.
+
+`codeindex graph-export` dumps a **write-once** NDJSON graph of the codebase
+for downstream consumers (loomgraph) to read. Per [ADR-007](../architecture/adr/007-codeindex-stateless-graph-ownership.md)
+codeindex stays a stateless emitter: this command holds **no** persistent or
+mutable state — no `.db`, no incremental sync, no vector index.
+
+## Usage
+
+```bash
+codeindex graph-export --root . -o graph-export.ndjson
+codeindex graph-export --root . -o -        # stdout
+```
+
+It does its **own clean whole-tree parse** (every source file exactly once)
+and is fully decoupled from `scan-all` / README rendering — running it never
+touches `README_AI.md`.
+
+## Format
+
+NDJSON. Line 1 is the `meta` record; then `entity` records; then `edge`
+records. All records carry a `type` tag.
+
+```jsonc
+{"type":"meta","schema_version":0,"generator":"codeindex","provenance_completeness":"ast-only: ..."}
+{"type":"entity","id":"app.service.AuthService","entity_type":"class","source_id":"app/service.py:8","description":"Authenticates users.","provenance":"ast"}
+{"type":"edge","kind":"CALLS","src":"app.service.AuthService.login","dst":"app.service.AuthService.authenticate","resolution_qualifier":"resolved","source_id":"app/service.py:15"}
+{"type":"edge","kind":"CALLS","src":"app.workers.kickoff","dst":null,"resolution_qualifier":"ambiguous","candidates":["app.workers.Builder.run","app.workers.Packer.run"],"source_id":"app/workers.py:15"}
+```
+
+### Naming convention (`id`)
+
+Entity ids are **fully-qualified and path-derived**: the module is the file
+path *relative to the scan root* with the extension dropped and `/` → `.`,
+then the file-local symbol name appended. So `src/loomgraph/cli/_common.py`'s
+`prepare_workspace_store` becomes `src.loomgraph.cli._common.prepare_workspace_store`.
+
+Fully-qualified is deliberate — it resolves same-name collisions across
+sibling classes/modules (the spike's F-class) and makes ownership explicit.
+
+> **src-layout caveat.** Because the module is *path*-derived, not
+> *import*-derived, a `src/`-layout project carries the layout dir in the id
+> (`src.loomgraph.…`, where the real Python import path is `loomgraph.…`).
+> codeindex does **not** strip it in v0 — there is no robust, config-free way
+> to tell a layout dir (`src/`, strip) from a genuine top package (`app/`,
+> keep). A consumer that maintains its own import-path index should normalise
+> the layout prefix when ingesting these ids (it knows the project layout;
+> codeindex, scanning a bare tree, does not). A codeindex-side `module_root` option is a
+> possible v1 addition if multiple consumers need it.
+
+### Entity
+
+| field | meaning |
+|---|---|
+| `id` | fully-qualified, path-derived name (see above), e.g. `app.service.AuthService.login` |
+| `entity_type` | `class` \| `function` \| `method` |
+| `source_id` | `relpath:line` |
+| `description` | first line of the docstring (may be empty) |
+| `provenance` | `ast` (L1 structural) |
+
+### Edge
+
+| field | meaning |
+|---|---|
+| `kind` | `CALLS` \| `INHERITS` |
+| `src` | resolved entity id of the caller / child class |
+| `dst` | resolved entity id of the callee / parent, or `null` if not resolved |
+| `dst_raw` | the original best-effort name the resolver tried (file-local). Always present; **load-bearing when `dst` is null** — it is the only record of *what* was called, so a consumer can synthesise an external stub or filter framework noise (e.g. `expect`, `Date.now`) |
+| `resolution_qualifier` | `resolved` \| `ambiguous` \| `unresolved` |
+| `candidates` | (ambiguous only) the entity ids the name could refer to |
+| `source_id` | `relpath:line` of the call / class definition |
+
+## Scope — a structural slice, not a full graph index
+
+The export is codeindex's **structural slice** (L1+L2): real code symbols
+(`class` / `function` / `method`) and their `CALLS` / `INHERITS` edges. It is
+**not** a complete graph index and is **not** meant to replace a consumer's
+own index.
+
+Deliberately **not** emitted (the consumer synthesises these around the
+slice during ingestion, per ADR-007):
+
+- **file / module container nodes** — derivable from each entity's `source_id`.
+  Consequence: a `<module>`-level call has a `src` (the dotted module path)
+  with no backing `entity` record; that's expected, the consumer materialises
+  the container if it wants one. (`entity_type: "module"` may be added in v1
+  if synthesising modules proves painful downstream.)
+- **external / stdlib stubs** — these are exactly where `unresolved` edges
+  point (see below); the consumer decides whether to materialise stub nodes.
+
+This matches the LoomGraph#30 GREEN field set (which contained no module/file
+nodes) and keeps the codeindex/loomgraph division clean: codeindex emits the
+symbol-level truth, loomgraph builds the container + external + semantic
+scaffolding on top.
+
+## Consumer contract — read these two caveats
+
+The parser emits **file-local** names; the export runs the only cross-file
+resolution pass. Two metadata mechanisms exist because that resolution and
+the underlying AST extraction are lossy — **a consumer that ignores them will
+draw wrong conclusions**:
+
+1. **`resolution_qualifier`** — never treat an `unresolved` or `ambiguous`
+   edge as a confirmed relationship. `unresolved` usually means external /
+   stdlib or a name not in the tree (with `dst: null`); `ambiguous` means the
+   name matched several entities (see `candidates`, `dst: null`). A **high
+   unresolved fraction is normal** — most calls in real code go to stdlib /
+   third-party / methods AST cannot statically resolve (≈59% on a real
+   loomgraph round-trip). The consumer owns the dangling-edge policy: drop,
+   keep as dangling, or materialise an external stub node as the `dst`.
+   codeindex emits no sentinel/placeholder entity — the entity set contains
+   only real code symbols.
+2. **`provenance_completeness`** (meta) — extraction is AST-only. Dynamic
+   dispatch (`getattr` / duck-typing / event handlers), reflection /
+   metaclasses, and decorator wiring are **not** captured. An **absent edge
+   means "not statically resolvable", not "none"** — this was the decisive
+   finding of the LoomGraph#30 consumption spike.
+
+## What this is NOT
+
+Per ADR-007, codeindex does not own a persistent graph. No mutable `.db`,
+incremental sync, corruption recovery, or `sqlite-vec` index — those, plus L3
+(design-doc LLM extraction), are loomgraph's. This artifact is a one-shot
+snapshot loomgraph reads (process-decoupled, decision (a)).

ai_codeindex-0.27.0/docs/releases/RELEASE_NOTES_v0.27.0.md

@@ -0,0 +1,60 @@
+# Release Notes - v0.27.0
+
+**Theme**: graph-export + parser robustness.
+
+This release ships codeindex's first **write-once graph artifact** — the data
+contract with loomgraph (per [ADR-007](../architecture/adr/007-codeindex-stateless-graph-ownership.md)) —
+alongside the AI-retry and partial-parse robustness fixes that were sitting
+unreleased on master.
+
+> **Upgrade is safe and additive.** `graph-export` is a brand-new standalone
+> command; the `GraphBuffer` IR it reuses is dormant (not wired into
+> `scan-all`); and existing `scan-all` / `parse` / `symbols` output is
+> unchanged. No migration, no cache flush needed.
+
+## New: `codeindex graph-export`
+
+A standalone command that does its own clean whole-tree parse and emits a
+**write-once NDJSON** graph for downstream consumers (loomgraph):
+
+```bash
+codeindex graph-export --root . -o graph-export.ndjson
+codeindex graph-export --root . -o -        # stdout
+```
+
+- **Entities** — `class` / `function` / `method`, module-qualified id,
+  `source_id` (`relpath:line`), first-line description, `provenance`.
+- **Edges** — `CALLS` / `INHERITS`, each carrying a `resolution_qualifier`
+  (`resolved` / `ambiguous` / `unresolved`) plus `dst_raw` (the original
+  name, load-bearing when `dst` is null) and `candidates` on ambiguous.
+- **Meta** — `schema_version` + `provenance_completeness` flagging that AST
+  extraction does not capture dynamic dispatch / reflection.
+
+**Status: experimental (`schema_version: 0`).** The schema may change without
+deprecation while at version 0; validated on Python with a TypeScript
+spot-check. Full contract + consumer caveats: [docs/guides/graph-export.md](../guides/graph-export.md).
+
+Decoupling note: the LoomGraph#30 consumption spike (verdict 🟡 YELLOW)
+justified this export but **not** an internal render-flip (#101 Phase 2);
+the two are architecturally independent and the flip is deferred.
+
+## Robustness (previously unreleased on master)
+
+- **In-run AI retry/backoff** (#97): `scan-all --ai` now retries
+  *recognised-transient* failures (timeout / rate-limit / 5xx) with
+  exponential backoff (scan paths use 3 attempts); permanent failures
+  (e.g. misconfigured `ai_command`) still fail fast. Agent-CLI stays the
+  only transport.
+- **Cross-language partial-parse recovery** (#95): a single unparseable
+  construct no longer zeroes a whole file's symbols. All parsers
+  (python / typescript / java / php / swift / objc) now return recoverable
+  symbols flagged `partial=True`, surfacing a hard error only when nothing
+  is recoverable.
+
+## Internal
+
+- **GraphBuffer IR** (#101): a per-run in-memory IR between parse and render,
+  shipped dormant (unwired) with a characterization safety net. Reused by
+  `graph-export`; no user-facing behavior change.
+
+See [CHANGELOG.md](../../CHANGELOG.md) for the full entry list.

{ai_codeindex-0.26.2 → ai_codeindex-0.27.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ai-codeindex"
-version = "0.26.2"
+version = "0.27.0"
 description = "AI-native code indexing tool for large codebases"
 readme = "README.md"
 requires-python = ">=3.10"

{ai_codeindex-0.26.2 → ai_codeindex-0.27.0}/src/codeindex/README_AI.md

@@ -1,12 +1,12 @@
 <!-- codeindex navigation index — agent: drill into source via Read/Grep for precise mechanism; do not treat this as final word. -->
-<!-- Generated by codeindex (detailed) at 2026-06-21T23:56:14.087118 -->
+<!-- Generated by codeindex (detailed) at 2026-06-27T20:08:49.478875 -->
 
 # codeindex
 
 ## Overview
 
-- **Files**: 89
-- **Symbols**: 574
+- **Files**: 92
+- **Symbols**: 599
 
 ## Files
 
@@ -125,6 +125,15 @@ _Documentation CLI commands for codeindex._
 - `def docs()`
 - `def show_ai_guide()`
 
+### cli_graph_export.py
+_CLI graph-export command — write-once graph artifact for loomgraph (GH #102).
+
+Standalone (Path A): does its own clean whole-tree parse and dumps a
+wr_
+
+**Functions:**
+- `def graph_export(root: Path, output: str, quiet: bool)`
+
 ### cli_hooks.py
 _Git Hooks management module for codeindex.
 
@@ -337,15 +346,7 @@ _Configuration management for codeindex._
 ### config_help.py
 _Configuration help documentation for codeindex (Epic 15 Story 15.3).
 
-This module provides comprehensive help documentation for all .codeindex.yaml
-co_
-
-**Functions:**
-- `def show_full_config_help() -> None`
-- `def _show_param_section(param_name: str) -> None`
-- `def explain_parameter(
-    param_name: str, current_value: Optional[any] = None, cpu_count: Optional[int] = None
-
+This module provides comprehensive help documentatio
 
 ---
 _Content truncated due to size limit. See individual module README files for details._

{ai_codeindex-0.26.2 → ai_codeindex-0.27.0}/src/codeindex/cli.py

@@ -12,6 +12,7 @@ from .cli_claude_md import claude_md, print_outdated_warning
 from .cli_config import doctor, init, list_dirs, status
 from .cli_config_commands import config
 from .cli_docs import docs
+from .cli_graph_export import graph_export
 from .cli_hooks import hooks
 from .cli_parse import parse
 from .cli_scan import scan, scan_all
@@ -44,6 +45,7 @@ main.add_command(affected)
 main.add_command(tech_debt)
 main.add_command(tech_debt, name="debt-scan")  # Alias for backward compatibility (v0.22.0+)
 main.add_command(hooks)
+main.add_command(graph_export)
 main.add_command(docs)
 main.add_command(claude_md)
 

ai_codeindex-0.27.0/src/codeindex/cli_graph_export.py

@@ -0,0 +1,65 @@
+"""CLI graph-export command — write-once graph artifact for loomgraph (GH #102).
+
+Standalone (Path A): does its own clean whole-tree parse and dumps a
+write-once NDJSON graph. Does not touch scan-all / README render.
+See ``codeindex.graph_export`` and ADR-007.
+"""
+
+from pathlib import Path
+
+import click
+
+from .cli_common import console
+from .config import Config
+from .graph_export import build_export, dump_ndjson, walk_and_parse
+
+
+@click.command(name="graph-export")
+@click.option(
+    "--root",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=Path("."),
+    help="Project root to export (default: current directory).",
+)
+@click.option(
+    "--output",
+    "-o",
+    default="graph-export.ndjson",
+    help="Output NDJSON path, or '-' for stdout (default: graph-export.ndjson).",
+)
+@click.option("--quiet", "-q", is_flag=True, help="Minimal output.")
+def graph_export(root: Path, output: str, quiet: bool):
+    """Export the code graph (entities + CALLS/INHERITS edges) as write-once NDJSON.
+
+    EXPERIMENTAL (schema_version 0): the contract with loomgraph per ADR-007.
+    Each edge carries a resolution_qualifier (resolved / ambiguous / unresolved)
+    so a consumer never mistakes an unresolved edge for a real one.
+    """
+    config_path = root / ".codeindex.yaml"
+    config = Config.load(config_path if config_path.exists() else None)
+
+    buffer = walk_and_parse(root, config)
+    model = build_export(buffer, root)
+    text = dump_ndjson(model)
+
+    if output == "-":
+        click.echo(text, nl=False)
+        return
+
+    out_path = Path(output)
+    if not out_path.is_absolute():
+        out_path = root / out_path
+    out_path.write_text(text, encoding="utf-8")
+
+    if not quiet:
+        n_amb = sum(
+            1 for e in model.edges if e.resolution_qualifier == "ambiguous"
+        )
+        n_unres = sum(
+            1 for e in model.edges if e.resolution_qualifier == "unresolved"
+        )
+        console.print(
+            f"[green]✓[/green] graph-export → {out_path} "
+            f"[dim]({len(model.entities)} entities, {len(model.edges)} edges; "
+            f"{n_amb} ambiguous, {n_unres} unresolved)[/dim]"
+        )

{ai_codeindex-0.26.2 → ai_codeindex-0.27.0}/src/codeindex/cli_scan.py

@@ -14,6 +14,7 @@ from .config import Config
 from .directory_tree import DirectoryTree
 from .docstring_processor import DocstringProcessor
 from .invoker import (
+    AI_SCAN_MAX_ATTEMPTS,
     clean_ai_output,
     format_prompt,
     invoke_ai_cli,
@@ -331,7 +332,9 @@ def _generate_ai_readme(
         console.print(f"  [dim]→ Invoking AI CLI (timeout: {timeout}s)...[/dim]")
         console.print(f"  [dim]  Command: {config.ai_command[:50]}...[/dim]")
 
-    invoke_result = invoke_ai_cli(config.ai_command, prompt, timeout=timeout)
+    invoke_result = invoke_ai_cli(
+        config.ai_command, prompt, timeout=timeout, max_attempts=AI_SCAN_MAX_ATTEMPTS
+    )
 
     if not invoke_result.success:
         console.print(f"[red]✗ AI CLI error:[/red] {invoke_result.error}")
@@ -775,8 +778,10 @@ def _enrich_directories_with_ai(
         parent_name = dir_path.parent.name if dir_path.parent != dir_path else ""
         prompt = build_enrich_prompt(dir_path.name, summary, parent_name)
 
-        # Invoke AI CLI
-        invoke_result = invoke_ai_cli(config.ai_command, prompt, timeout=timeout)
+        # Invoke AI CLI (retry transient timeout / rate-limit in-run, GH #97)
+        invoke_result = invoke_ai_cli(
+            config.ai_command, prompt, timeout=timeout, max_attempts=AI_SCAN_MAX_ATTEMPTS
+        )
 
         if not invoke_result.success:
             reason = (invoke_result.error or "unknown").strip().split("\n")[0][:200]

ai_codeindex-0.27.0/src/codeindex/graph_buffer.py

@@ -0,0 +1,116 @@
+"""In-memory IR between parse and render (GH #101, ADR-007).
+
+``GraphBuffer`` is a per-run, in-memory intermediate representation of a
+scanned project. It sits between the *parse* stage and the README *render*
+stage, decoupling :class:`~codeindex.writers.SmartWriter` from the live
+scan/parse loop.
+
+Scope — Phase 1 (strangler step), deliberately minimal:
+
+* Holds one :class:`DirNode` per indexed directory: the render inputs
+  (``level``, ``parse_results``, ``child_dirs``) the renderer currently
+  consumes.
+* Provides :func:`render_directory` — the seam the eventual SmartWriter flip
+  will call. Rendering *from* the buffer must stay byte-identical to the
+  direct ``parse -> write_readme`` path (proven by
+  ``tests/characterization/test_graphbuffer_equivalence.py``).
+
+Deliberately **out of scope** for Phase 1:
+
+* The global call / inheritance graph and the write-once graph-export
+  artifact. Per ADR-007 that substrate is gated on LoomGraph#30 and is not
+  built until that consumption spike comes back GREEN.
+* Wiring into the production ``scan-all`` loop (the flip). Until the buffer
+  is the renderer's source of truth, paying its RAM cost in production buys
+  nothing, so it stays test-only for now.
+
+This module is pure data plus a thin adapter: no AI, no I/O of its own beyond
+what :meth:`SmartWriter.write_readme` already performs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .parser import ParseResult
+from .writers import LevelType, SmartWriter, WriteResult
+
+
+@dataclass
+class DirNode:
+    """One indexed directory's render inputs, captured in the buffer.
+
+    Attributes mirror exactly the arguments
+    :meth:`SmartWriter.write_readme` consumes, so the buffer is a faithful,
+    lossless capture of the renderer's input at the moment of the scan.
+    """
+
+    path: Path
+    level: LevelType
+    parse_results: list[ParseResult] = field(default_factory=list)
+    child_dirs: list[Path] = field(default_factory=list)
+
+
+class GraphBuffer:
+    """Per-run, in-memory map of directory -> :class:`DirNode`.
+
+    Insertion is single-threaded *by contract*: callers may produce
+    ``parse_results`` with a parallel pool, but each directory is recorded
+    once from a single collecting thread. The buffer performs no locking.
+    """
+
+    def __init__(self) -> None:
+        self._dirs: dict[Path, DirNode] = {}
+
+    def record_directory(
+        self,
+        dir_path: Path,
+        level: LevelType,
+        parse_results: list[ParseResult],
+        child_dirs: list[Path],
+    ) -> DirNode:
+        """Capture one directory's render inputs and return the node."""
+        node = DirNode(
+            path=dir_path,
+            level=level,
+            parse_results=list(parse_results),
+            child_dirs=list(child_dirs),
+        )
+        self._dirs[dir_path] = node
+        return node
+
+    def get(self, dir_path: Path) -> DirNode | None:
+        """Return the buffered node for ``dir_path`` (or ``None``)."""
+        return self._dirs.get(dir_path)
+
+    def directories(self) -> list[DirNode]:
+        """Return all buffered nodes (insertion order)."""
+        return list(self._dirs.values())
+
+    def __len__(self) -> int:
+        return len(self._dirs)
+
+    def __contains__(self, dir_path: object) -> bool:
+        return dir_path in self._dirs
+
+
+def render_directory(
+    writer: SmartWriter,
+    node: DirNode,
+    output_file: str = "README_AI.md",
+) -> WriteResult:
+    """Render one directory's README from a buffered :class:`DirNode`.
+
+    This is the seam the eventual SmartWriter flip will use: the renderer's
+    inputs come from the buffer, not from a fresh inline parse. It must stay
+    byte-identical to ``writer.write_readme(... parse_results ...)`` on the
+    same inputs.
+    """
+    return writer.write_readme(
+        dir_path=node.path,
+        parse_results=node.parse_results,
+        level=node.level,
+        child_dirs=node.child_dirs,
+        output_file=output_file,
+    )