ai-dev-cli-tools 0.5.0a1__py3-none-any.whl

ai_dev_cli_tools-0.5.0a1.dist-info/METADATA

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: ai-dev-cli-tools
+Version: 0.5.0a1
+Summary: Cross-platform CLI helpers that give AI coding agents concise, deterministic development reports.
+Project-URL: Homepage, https://github.com/MatthiasLew/ai-dev-cli-tools
+Project-URL: Repository, https://github.com/MatthiasLew/ai-dev-cli-tools
+Project-URL: Issues, https://github.com/MatthiasLew/ai-dev-cli-tools/issues
+Project-URL: Changelog, https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/CHANGELOG.md
+Author: Mateusz Lewandowski
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,automation,cli,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AI Dev CLI Tools
+
+Cross-platform Python CLI helpers for AI coding agents and humans who want concise, deterministic development reports instead of huge logs.
+
+`ai-dev` runs repeatable project checks locally, stores full logs under `.ai/logs/`, and returns compact Markdown/JSON summaries under `.ai/reports/`.
+
+## Problem
+
+AI coding agents often spend tokens reading full test output, repository trees, dependency noise, repeated warnings, and raw Git diffs. This project follows one rule:
+
+```text
+Scripts do the work and collect data.
+AI reads a short report and decides what to do next.
+Full logs stay on disk until needed.
+
+Generated state under `.ai/logs/`, `.ai/reports/`, `.ai/context/`, `.ai/cache/`,
+`.ai/runtime/`, and `.ai/tmp/` is local and ignored by Git. Logs, reports, and context
+artifacts may be removed when no longer needed; cache, runtime, and temporary state must always
+be safe for `ai-dev` to recreate.
+```
+
+## Install
+
+```bash
+python -m pip install --upgrade pipx
+pipx install ai-dev-cli-tools==0.5.0a1
+ai-dev --help
+```
+
+For a source checkout before the public alpha is published, use `pipx install .`. See
+`docs/DISTRIBUTION.md` for the Trusted Publishing and upgrade policy.
+
+For development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Windows
+
+```powershell
+.\ai.ps1 doctor
+ai-dev scan --project "C:\path with spaces\project"
+```
+
+## Linux and macOS
+
+```bash
+./ai.sh doctor
+ai-dev check --mode fast --project "/path/with spaces/project"
+```
+
+## Commands
+
+```bash
+ai-dev doctor
+ai-dev scan
+ai-dev map --max-files 500 --max-depth 6
+ai-dev check --mode fast
+ai-dev check --mode changed  # reports changed files and falls back safely when test mapping is uncertain
+ai-dev check --mode full --jobs 4
+ai-dev check --mode changed --policy feedback-first --resume
+ai-dev index update
+ai-dev cache status
+ai-dev baseline create main
+ai-dev baseline compare main
+ai-dev explain issue:<id> --tail 100
+ai-dev feedback --task "fix authentication timeout"
+ai-dev session status
+ai-dev diagnostics
+ai-dev completion bash
+ai-dev test affected
+ai-dev logs summarize
+ai-dev context build
+ai-dev git status
+ai-dev git inspect
+ai-dev finish
+```
+
+All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version` at the top level.
+
+
+## Bootstrap
+
+`ai-dev bootstrap` prepares a detected project with conservative, project-local commands. Use `--explain` to see the plan without modifications, `--dry-run` to validate planning without executing modifying commands, and `--create-env` to allow copying `.env.example` to `.env` only when `.env` is missing.
+
+Supported strategies include Python uv, Poetry, pip with `pyproject.toml`, pip with `requirements.txt`, Node npm/pnpm/Yarn, Maven wrapper or system Maven, Gradle wrapper or system Gradle, Cargo, and Composer.
+
+See `docs/BOOTSTRAP.md` for safety rules and configuration.
+
+## Managed application runtime
+
+`ai-dev run` supports explain, dry-run, foreground, and supervised background modes.
+`ai-dev stop` sends a token-authenticated request to the matching local supervisor and never
+kills an arbitrary PID read from stale state. See `docs/RUNTIME.md`.
+
+## Context Builder
+
+`ai-dev context build` creates a bounded local context package for coding agents without calling any LLM, embedding API, or cloud service.
+
+```bash
+ai-dev context build --task "fix auth tests"
+ai-dev context build --changed-only --max-chars 50000
+ai-dev context build --incremental  # emits only candidates changed since the last pack
+ai-dev context build --profile review
+ai-dev context build --include "src/**/*.py" --exclude "tests/fixtures/**"
+ai-dev context build --explain --json
+```
+
+Artifacts are written to `.ai/context/context-latest.md` and `.ai/context/context-latest.json` by default. The builder includes detected technologies, git state, changed files, related tests, validation plan, recent commits, selected snippets, limited diffs, latest check errors, masked secret findings, and budget/truncation metadata. Large Python files use AST-aware symbol snippets with line ranges instead of blindly returning only the beginning of the file.
+
+Incremental mode stores a schema-versioned manifest under `.ai/cache/` and reports changed versus reused files. Default limits are `--max-chars 50000`, `--max-files 30`, `--max-file-chars 8000`, and `--max-diff-chars 15000`. Secret-bearing and generated paths such as `.env`, private keys, caches, build output, `.ai/logs`, and `.ai/reports` are excluded from snippets.
+## Reports and Logs
+
+Validation results are cached by default using repository, command, workspace, runtime, and platform fingerprints; use `check --no-cache` to force execution. `check --resume` reuses only exact successful checkpoint fingerprints. `--policy feedback-first` runs cheaper waves first and cancels later expensive waves after a required failure; `complete` retains comprehensive execution. `index status/update/rebuild` manages the reusable repository index, while `cache status/prune/clear` provides bounded local cache maintenance. See `docs/CACHE_AND_INDEX.md`.
+
+Short reports are written to `.ai/reports/` as Markdown and JSON. Full command output is written to `.ai/logs/` and ignored by Git. Check summaries include exit codes, durations, first failure hints, grouped repeated messages, test counts, and full log paths.
+
+JSON reports use schema `1.1` with `schema_version`, `tool_version`, `command`, `status`, `exit_code`, timestamps, `project_root`, `summary`, `issues`, `artifacts`, and `metadata`.
+
+`ai-dev feedback` combines Git changes, changed validation, incremental context, focused rerun hints, stage timings, and local session state into one compact agent protocol report.
+
+Every expandable issue, check, file, snippet, diff, workspace, and artifact receives a stable local `evidence_id`. The report metadata lists references; `ai-dev explain <evidence-id> --tail 100` retrieves only that evidence. `ai-dev baseline create <name>` stores a compact local snapshot under `.ai/cache/baselines/`, and `baseline compare <name>` leads with new/resolved failures, issue codes, and status regressions.
+
+## Auto Detection
+
+`scan` detects Python, Node.js, Java, Rust, PHP, Docker, Make, CI workflows, package managers, scripts, entrypoints, tests, lint, formatters, type checkers, and `.env.example` variables.
+
+Supported examples:
+
+- Python: `pyproject.toml`, `requirements.txt`, `pytest`, `ruff`, `black`, `mypy`, `coverage`.
+- Node.js: `package.json`, npm, pnpm, yarn, Jest, Vitest, ESLint, Prettier, TypeScript.
+- Java: Maven, Gradle, tests, Checkstyle, SpotBugs, JaCoCo when configured.
+- Rust: Cargo test, fmt, clippy.
+- PHP: Composer, PHPUnit, PHPStan, PHP-CS-Fixer when configured.
+
+## Configuration
+
+Optional `.ai-dev-tools.toml`:
+
+```toml
+[project]
+name = "example-project"
+
+[commands]
+test = "pytest"
+lint = "ruff check ."
+typecheck = "mypy src"
+
+[ignore]
+paths = ["node_modules", ".venv", "dist", "build"]
+
+[reports]
+directory = ".ai/reports"
+logs_directory = ".ai/logs"
+```
+
+Configuration takes precedence over auto detection. Invalid or unknown configuration is reported through `config_warnings` instead of crashing normal scans.
+## Local Validation
+
+Before pushing a larger stage, run:
+
+```bash
+python -m ruff check .
+python -m mypy src tests scripts
+python -m coverage run -m pytest
+python -m coverage report --fail-under=90
+python -m build
+python scripts/validate_ci.py
+python scripts/test_installed_package.py
+git diff --check
+```
+
+`python scripts/test_installed_package.py` rebuilds the wheel, installs only that wheel into a clean virtual environment in a path containing spaces, and verifies the installed `ai-dev` entrypoint without editable install or `PYTHONPATH`.
+
+## Command Status
+
+| Command | Status |
+| --- | --- |
+| doctor | implemented |
+| scan | implemented |
+| map | implemented |
+| check | implemented |
+| check --explain | implemented |
+| test affected | implemented |
+| index status/update/rebuild | implemented |
+| cache status/prune/clear | implemented |
+| logs summarize | implemented |
+| context build | implemented |
+| diagnostics | implemented |
+| capabilities | implemented |
+| git status | implemented |
+| git inspect | implemented |
+| finish | implemented |
+| bootstrap | implemented |
+| run | implemented |
+| stop | implemented |
+
+## Scope Notes
+
+- Monorepo/workspace detection and per-subproject command routing: implemented.
+- Per-subproject check and bootstrap working directories: implemented.
+- Runtime version validation: partial.
+- `context build` is implemented as a bounded local context pack builder.
+- `bootstrap` is implemented as a conservative local setup planner/executor.
+- Auto-commit, auto-push, and GUI remain out of scope or planned.
+
+## Intentional Limits
+Version 0.5.0a1 does not reset, clean, commit, push, merge, clone organizations, synchronize repositories, delete containers, publish releases, or remove user files.
+
+Shell completion scripts are generated with `ai-dev completion bash|zsh|fish|powershell` and can be sourced or installed using the normal mechanism for the selected shell.

ai_dev_cli_tools-0.5.0a1.dist-info/RECORD

@@ -0,0 +1,60 @@
+ai_dev_tools/__init__.py,sha256=gcZy3Dv5W7LjZwt6A24kOUR1D9TCRyDsf_LFbf7unoA,49
+ai_dev_tools/cli.py,sha256=ilgDBx9zc8V9mgwRe_08wzobrKvSoJQh1hFNLQ8pIwQ,14246
+ai_dev_tools/completion.py,sha256=pZwxo4KoueUeDIK1C8013o_T0517nhf1hrzuSnw12DI,1929
+ai_dev_tools/config.py,sha256=uZsEn7xe2XHHnknYmRg1qhg5FNgwBZm3L8zKPVPDezM,7998
+ai_dev_tools/cache/__init__.py,sha256=cQ0ONFQ2MRhwnabuooeiiR9iKgujoWpxFTtgrgnOUn0,235
+ai_dev_tools/cache/graph.py,sha256=WOpm_TLLgUOK4SCxhkt7llEvCKUx12joZgstTJzayVk,5296
+ai_dev_tools/cache/repository.py,sha256=2t9_5vu5U0zaJ1UDhYh35joQPSiv2I8Yw0A9rzNEeoU,5506
+ai_dev_tools/cache/validation.py,sha256=j8Vl9dAsgMc660zzs0yw5qG5j3DTQt6IgUJ2EsStSjA,4141
+ai_dev_tools/context/__init__.py,sha256=QUXob-3eD2d0evw6eTUpy6yaaNrhiGO1-Ynx_y-D4l8,154
+ai_dev_tools/context/builder.py,sha256=6Vb0EhEtifhWAetE2UN9yPkuRy7KOy_fCh0Lbbo6za8,18713
+ai_dev_tools/context/incremental.py,sha256=VNhjdnQxvRKkJgSc-PT7zlBOGLHhYttS85gpft9aIpc,3520
+ai_dev_tools/context/models.py,sha256=tfYnZWvAsUNQ9RsU1etzRz3gX5MAGZn0lxRDruxQj2Y,1452
+ai_dev_tools/context/profiles.py,sha256=VteAM-YNqGHUpOQG3Aq2T60WuR_Ik2-2oOYSrrRACMA,1218
+ai_dev_tools/context/selection.py,sha256=spu7CjZWJBR3VXQs3YBxPOxQit1H145IDz4BKmrQFJQ,9957
+ai_dev_tools/context/symbols.py,sha256=NwEJ3_lBUPc7nZRSMLzfmbvG25gKm8P0IBy1KfeCJNE,5339
+ai_dev_tools/detectors/__init__.py,sha256=FHCytKbvq-UnxBTHvMD3abeEVyAzG-OYRelp84GFfkU,41
+ai_dev_tools/detectors/environment.py,sha256=98Wc7OUog-CKfyrxFr6yZlazeryhsL28tWM2_koLZos,4622
+ai_dev_tools/detectors/project.py,sha256=iS3aykw0GoRItjLR1pdGBC-UuRe-blGviETf4fo0yC0,7213
+ai_dev_tools/detectors/repository_map.py,sha256=4a7p1_6UcleFEDRWnc5cQiJuMqp3e1088sgEneKIwS8,4026
+ai_dev_tools/detectors/runtime.py,sha256=QzVucMF_OSc8EGLUhpAh8HghC3UAtPT7NCn6U4gRRrY,6827
+ai_dev_tools/detectors/workspaces.py,sha256=GnGMw7k9ST8sJRvc3PAs39cJtiMxTYKxFvOKA1DSjio,8404
+ai_dev_tools/git/__init__.py,sha256=72rVU6ALOpCNljDnkRrbyCs4zfWwoSAaF4sRnQKWXPk,30
+ai_dev_tools/git/inspect.py,sha256=bUsUMosmSM6p-CmbVkazDe0eX_oyr6qhT0yTcEP4F2E,7777
+ai_dev_tools/models/__init__.py,sha256=zCWnVsKHBP8Myr5K4p1O3mh5u0h0Ee2cqNvGnHyFXJg,26
+ai_dev_tools/models/report.py,sha256=evyUrZIN98Rv6rLEbS61t_nn5S7BjIF6fIVBRT4vMRg,2848
+ai_dev_tools/models/workspace.py,sha256=KBHhn4FDH08OPm8fzqJbbW431B3gq21fmUrhH1FQ1Fk,1461
+ai_dev_tools/parsers/__init__.py,sha256=CTeRzVPM4WA4KgU9q9fFxeKYruQsbCTkou9YOsQamxM,22
+ai_dev_tools/parsers/logs.py,sha256=W4ieWdz9ixrGRjIVgnlEGzI5EuQxJMqS2qTvzqYwK1o,14121
+ai_dev_tools/parsers/registry.py,sha256=Eye1NLCy2W6TF2OZ7tIOaFPj_tvPm7MyJRy_pyltuAg,2050
+ai_dev_tools/reporters/__init__.py,sha256=JWR2WoPfAOilOoKesREl7dqZofYHmfn1Oask7pLUhbQ,22
+ai_dev_tools/reporters/progressive.py,sha256=Z40kwEH5v4puyjT6AnU1a_fg0eChWnfBPodI08GtQe4,5599
+ai_dev_tools/reporters/writer.py,sha256=yf6v-NSR9mxI3zSnlxUFl6N7cUK0vBnNWkg3gE5x-bM,2517
+ai_dev_tools/runners/__init__.py,sha256=EMkZFuAQJdiVCAS8qsJmIj25XgzHvBoACqoKdKa9LG8,23
+ai_dev_tools/runners/baseline.py,sha256=gNVcP1nWYTAh_6kCIJ2Fk8s9Ca_Q8oc1xhiMGpm6zyo,7285
+ai_dev_tools/runners/bootstrap.py,sha256=xo7Xl9OFw-bnWdKYTA1i2UyBWwc5FoYuVuHZOvsFjuk,7762
+ai_dev_tools/runners/bootstrap_models.py,sha256=ABdgCF9qUsp8lM2gWO1UUSNXgbd28stV4qQICZ0MW8U,1960
+ai_dev_tools/runners/bootstrap_strategies.py,sha256=8tpNfiT_KRtZFxKbIQYJNU0fvRB3rJTHbSNLzE_9ET8,14115
+ai_dev_tools/runners/cache.py,sha256=U_MBMBfJ6cSRPEl4GZZakXknONAWdd9rSgqNlnrnUhI,669
+ai_dev_tools/runners/check.py,sha256=1sZlsPxY5E4iKpWwGJIj2I_2y8XT6M5GgAYQexYR5kQ,19316
+ai_dev_tools/runners/check_checkpoint.py,sha256=7h7XzRjE10C6NqKePGYNDZWqB64ftLExzPW_1JcuVg0,1545
+ai_dev_tools/runners/check_models.py,sha256=BrHTxq2yVSzpTxRuZ6jB7zOmbXFvVuVU7q0hwrPvy2g,1312
+ai_dev_tools/runners/check_scheduler.py,sha256=tjMzKyqEFptgNK-CJjb7jtNXTvEjhjGBt3rrAE8I6sY,3165
+ai_dev_tools/runners/check_selection.py,sha256=LlWmj4kK5bQUuZBl1LeUs8HGicSD7tInA2s3YCbOgJs,9650
+ai_dev_tools/runners/diagnostics.py,sha256=7M1Zula_nUoBv3a8n9ioBsnHgM-qkoYVXydU8P4VjUY,3623
+ai_dev_tools/runners/feedback.py,sha256=5Xo4OFaFMGf2UZ9SdHBOcCOdrztCJ1VPsEQZRSqRFQc,6642
+ai_dev_tools/runners/finish.py,sha256=Za3SkW5o54NRQr_bo1WSKhrVfImv7TWVzszsDlFIceA,4102
+ai_dev_tools/runners/focused.py,sha256=RierjyU6WChD4sSq53GsvFLcpQGrpsEZ9mOsaTzrSms,1347
+ai_dev_tools/runners/index.py,sha256=GU581MlHrUtcYZu7P4Hy9Re24UfhJinQDYD0bFGF0dM,1467
+ai_dev_tools/runtime/__init__.py,sha256=Pb-djv_Kcze8cKc5tiYh_3YeQzCENrBhKG00uYpCpWs,151
+ai_dev_tools/runtime/runner.py,sha256=PbBIXfOQFR5hK1TgrD6dlQMiS9ZDcJDCyOQswqKYvN4,13689
+ai_dev_tools/runtime/supervisor.py,sha256=ym7iQ92jF8hYUt4dSUo5sjeMwLAUDoxb6X0Xz70Aqj0,4713
+ai_dev_tools/security/__init__.py,sha256=e6X0XtAGkfFSBGRxHZOHm7-ZMg8Pnypq3Z3IONu7Fho,25
+ai_dev_tools/security/secrets.py,sha256=N97uz0qAGybvhzXSTf_D3hT5i_VmmesMavXXobME7sk,2151
+ai_dev_tools/utils/__init__.py,sha256=vTzpzAhwZwhp9xdzSN95SWmf02qgw7Asc0ULXG4aEok,23
+ai_dev_tools/utils/subprocess.py,sha256=Jjt2ezr8RM3fmbdrTCw13Qi8KYxgix-d7rXQkzwDHZ8,2266
+ai_dev_cli_tools-0.5.0a1.dist-info/METADATA,sha256=d7f71_XPlQxJykInHceUIGD4eVgBX5phkVUAxTlToqM,10363
+ai_dev_cli_tools-0.5.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ai_dev_cli_tools-0.5.0a1.dist-info/entry_points.txt,sha256=xKNwzY-s7fmCWs65waRZ5gzMpYlXl03S_P1btlxj3E4,49
+ai_dev_cli_tools-0.5.0a1.dist-info/licenses/LICENSE,sha256=Nc0_ePANo7Sy4FWWgVlFx6mNbKnByDAcQA7jGAYJX0w,1076
+ai_dev_cli_tools-0.5.0a1.dist-info/RECORD,,

ai_dev_cli_tools-0.5.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_dev_cli_tools-0.5.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ai-dev = ai_dev_tools.cli:main

ai_dev_cli_tools-0.5.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateusz Lewandowski
+
+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.

ai_dev_tools/__init__.py

@@ -0,0 +1,3 @@
+"""AI Dev CLI Tools."""
+
+__version__ = "0.5.0a1"

ai_dev_tools/cache/__init__.py

@@ -0,0 +1,11 @@
+from ai_dev_tools.cache.repository import (
+    read_repository_index,
+    repository_fingerprint,
+    update_repository_index,
+)
+
+__all__ = [
+    "read_repository_index",
+    "repository_fingerprint",
+    "update_repository_index",
+]

ai_dev_tools/cache/graph.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import posixpath
+import re
+from pathlib import Path
+
+
+def build_impact_graph(
+    root: Path,
+    paths: set[str],
+    *,
+    reused_paths: set[str] | None = None,
+    previous_edges: object = None,
+) -> list[dict[str, str]]:
+    reused_paths = reused_paths or set()
+    old_by_source = _edges_by_source(previous_edges)
+    edges: set[tuple[str, str, str]] = set()
+    for relative in sorted(paths):
+        if relative in reused_paths and relative in old_by_source:
+            edges.update(old_by_source[relative])
+            continue
+        source = root / relative
+        for target, kind in _references(source, relative, paths):
+            edges.add((relative, target, kind))
+        for target in _candidate_tests(relative, paths):
+            edges.add((relative, target, "test"))
+    return [{"from": source, "to": target, "kind": kind} for source, target, kind in sorted(edges)]
+
+
+def related_tests(graph: object, changed_files: list[str]) -> list[str]:
+    changed = {path.replace("\\", "/") for path in changed_files}
+    selected: set[str] = set()
+    if not isinstance(graph, list):
+        return []
+    for edge in graph:
+        if (
+            isinstance(edge, dict)
+            and edge.get("kind") == "test"
+            and edge.get("from") in changed
+            and isinstance(edge.get("to"), str)
+        ):
+            selected.add(str(edge["to"]))
+    return sorted(selected)
+
+
+def _references(source: Path, relative: str, paths: set[str]) -> list[tuple[str, str]]:
+    if source.suffix.lower() not in {".py", ".js", ".jsx", ".ts", ".tsx", ".rs"}:
+        return []
+    try:
+        text = source.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+    if source.suffix.lower() == ".py":
+        return _python_references(relative, text, paths)
+    if source.suffix.lower() in {".js", ".jsx", ".ts", ".tsx"}:
+        return _js_references(relative, text, paths)
+    return _rust_references(relative, text, paths)
+
+
+def _python_references(relative: str, text: str, paths: set[str]) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    for match in re.finditer(
+        r"^\s*(?:from\s+([A-Za-z_][\w.]*)\s+import|import\s+([A-Za-z_][\w.]*))",
+        text,
+        re.MULTILINE,
+    ):
+        module = match.group(1) or match.group(2)
+        module_path = module.replace(".", "/")
+        candidates = [
+            f"{module_path}.py",
+            f"src/{module_path}.py",
+            f"{module_path}/__init__.py",
+            f"src/{module_path}/__init__.py",
+        ]
+        result.extend((candidate, "import") for candidate in candidates if candidate in paths)
+    return result
+
+
+def _js_references(relative: str, text: str, paths: set[str]) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    directory = posixpath.dirname(relative)
+    for match in re.finditer(r"(?:from\s+|require\()(['\"])(\.{1,2}/[^'\"]+)\1", text):
+        base = posixpath.normpath(posixpath.join(directory, match.group(2)))
+        candidates = [
+            base,
+            *[f"{base}{suffix}" for suffix in (".ts", ".tsx", ".js", ".jsx")],
+            *[f"{base}/index{suffix}" for suffix in (".ts", ".tsx", ".js", ".jsx")],
+        ]
+        result.extend((candidate, "import") for candidate in candidates if candidate in paths)
+    return result
+
+
+def _rust_references(relative: str, text: str, paths: set[str]) -> list[tuple[str, str]]:
+    directory = posixpath.dirname(relative)
+    result: list[tuple[str, str]] = []
+    for match in re.finditer(r"^\s*mod\s+([A-Za-z_][\w]*)\s*;", text, re.MULTILINE):
+        name = match.group(1)
+        for candidate in (f"{directory}/{name}.rs", f"{directory}/{name}/mod.rs"):
+            normalized = candidate.lstrip("/")
+            if normalized in paths:
+                result.append((normalized, "import"))
+    return result
+
+
+def _candidate_tests(relative: str, paths: set[str]) -> list[str]:
+    path = Path(relative)
+    stem = path.stem
+    candidates: list[str] = []
+    if path.suffix == ".py":
+        parts = list(path.parts)
+        source_parts = parts[1:] if parts and parts[0] in {"src", "lib"} else parts
+        if source_parts:
+            source_parts[-1] = f"test_{stem}.py"
+            candidates.append(Path("tests", *source_parts).as_posix())
+        candidates.append(Path("tests", f"test_{stem}.py").as_posix())
+    elif path.suffix.lower() in {".js", ".jsx", ".ts", ".tsx"}:
+        candidates.extend(
+            [
+                path.with_name(f"{stem}.test{path.suffix}").as_posix(),
+                path.with_name(f"{stem}.spec{path.suffix}").as_posix(),
+            ]
+        )
+    return sorted({candidate for candidate in candidates if candidate in paths})
+
+
+def _edges_by_source(value: object) -> dict[str, set[tuple[str, str, str]]]:
+    result: dict[str, set[tuple[str, str, str]]] = {}
+    if not isinstance(value, list):
+        return result
+    for edge in value:
+        if not isinstance(edge, dict):
+            continue
+        source, target, kind = edge.get("from"), edge.get("to"), edge.get("kind")
+        if all(isinstance(item, str) for item in (source, target, kind)):
+            result.setdefault(str(source), set()).add((str(source), str(target), str(kind)))
+    return result

ai_dev_tools/cache/repository.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TypedDict
+
+from ai_dev_tools.cache.graph import build_impact_graph
+from ai_dev_tools.config import DEFAULT_IGNORES
+
+INDEX_SCHEMA_VERSION = "1"
+INDEX_RELATIVE_PATH = Path(".ai/cache/repository-index.json")
+
+
+class IndexEntry(TypedDict):
+    path: str
+    size: int
+    mtime_ns: int
+    sha256: str
+
+
+def update_repository_index(root: Path, *, rebuild: bool = False) -> dict[str, object]:
+    resolved_root = root.resolve()
+    index_path = resolved_root / INDEX_RELATIVE_PATH
+    previous = {} if rebuild else read_repository_index(resolved_root)
+    previous_entries = _entry_map(previous.get("entries"))
+    entries: list[IndexEntry] = []
+    reused = 0
+    hashed = 0
+    reused_paths: set[str] = set()
+
+    for path in _project_files(resolved_root):
+        relative = path.relative_to(resolved_root).as_posix()
+        stat = path.stat()
+        old = previous_entries.get(relative)
+        if old is not None and old["size"] == stat.st_size and old["mtime_ns"] == stat.st_mtime_ns:
+            digest = old["sha256"]
+            reused += 1
+            reused_paths.add(relative)
+        else:
+            digest = _sha256(path)
+            hashed += 1
+        entries.append(
+            {
+                "path": relative,
+                "size": stat.st_size,
+                "mtime_ns": stat.st_mtime_ns,
+                "sha256": digest,
+            }
+        )
+
+    graph = build_impact_graph(
+        resolved_root,
+        {item["path"] for item in entries},
+        reused_paths=reused_paths,
+        previous_edges=previous.get("graph"),
+    )
+
+    payload: dict[str, object] = {
+        "schema_version": INDEX_SCHEMA_VERSION,
+        "project_root": str(resolved_root),
+        "generated_at": datetime.now(UTC).isoformat(),
+        "entries": entries,
+        "graph": graph,
+        "summary": {
+            "files": len(entries),
+            "hashed": hashed,
+            "reused": reused,
+            "removed": len(set(previous_entries) - {item["path"] for item in entries}),
+            "graph_edges": len(graph),
+        },
+    }
+    _write_json(index_path, payload)
+    return payload
+
+
+def read_repository_index(root: Path) -> dict[str, object]:
+    path = root.resolve() / INDEX_RELATIVE_PATH
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(value, dict) or value.get("schema_version") != INDEX_SCHEMA_VERSION:
+        return {}
+    return value
+
+
+def repository_fingerprint(
+    entries: object, workspace: str = "", extra: tuple[str, ...] = ()
+) -> str:
+    prefix = workspace.replace(chr(92), "/").strip("/")
+    selected = []
+    for entry in _entry_list(entries):
+        path = entry["path"]
+        if not prefix or path == prefix or path.startswith(prefix + "/"):
+            selected.append((path, entry["sha256"]))
+    payload = json.dumps(
+        {"workspace": prefix, "files": selected, "extra": extra},
+        sort_keys=True,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _project_files(root: Path) -> list[Path]:
+    ignored = {item.replace(chr(92), "/").strip("/") for item in DEFAULT_IGNORES}
+    ignored_names = {Path(item).name for item in ignored}
+    files: list[Path] = []
+    for current, directories, names in os.walk(root, followlinks=False):
+        current_path = Path(current)
+        directories[:] = sorted(
+            name
+            for name in directories
+            if name not in ignored_names
+            and not (current_path.name in {"test", "tests"} and name == "fixtures")
+        )
+        for name in sorted(names):
+            path = current_path / name
+            if path.is_symlink() or not path.is_file():
+                continue
+            relative = path.relative_to(root).as_posix()
+            if any(relative == item or relative.startswith(item + "/") for item in ignored):
+                continue
+            files.append(path)
+    return files
+
+
+def _entry_map(value: object) -> dict[str, IndexEntry]:
+    return {entry["path"]: entry for entry in _entry_list(value)}
+
+
+def _entry_list(value: object) -> list[IndexEntry]:
+    if not isinstance(value, list):
+        return []
+    result: list[IndexEntry] = []
+    for item in value:
+        if (
+            isinstance(item, dict)
+            and isinstance(item.get("path"), str)
+            and isinstance(item.get("size"), int)
+            and isinstance(item.get("mtime_ns"), int)
+            and isinstance(item.get("sha256"), str)
+        ):
+            result.append(
+                {
+                    "path": item["path"],
+                    "size": item["size"],
+                    "mtime_ns": item["mtime_ns"],
+                    "sha256": item["sha256"],
+                }
+            )
+    return result
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _write_json(path: Path, value: dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, path)