codetour-cli 0.2.0__tar.gz → 0.3.0__tar.gz

codetour_cli-0.3.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: codetour-cli
+Version: 0.3.0
+Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
+Author: Jérémie Lumbroso
+License: MIT
+Project-URL: Homepage, https://github.com/jlumbroso/codetour-cli
+Project-URL: Repository, https://github.com/jlumbroso/codetour-cli
+Keywords: codetour,code-tour,vscode,git,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gitpython
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog
+Requires-Dist: rich
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: json-source-edit<2,>=1.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# CodeTour CLI
+
+[![Tests](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml/badge.svg)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
+[![Coverage ≥60%](https://img.shields.io/badge/coverage-%E2%89%A560%25-yellowgreen)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/codetour-cli)](https://pypi.org/project/codetour-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codetour-cli)](https://pypi.org/project/codetour-cli/)
+[![Downloads](https://static.pepy.tech/badge/codetour-cli)](https://pepy.tech/projects/codetour-cli)
+[![License](https://img.shields.io/github/license/jlumbroso/codetour-cli)](https://github.com/jlumbroso/codetour-cli/blob/main/LICENSE)
+
+**Algorithmic maintenance of [CodeTour](https://github.com/microsoft/codetour) files: keep `.tour` walkthroughs accurate as the code they narrate evolves.**
+
+> **Unofficial companion tool.** `codetour-cli` is an independent,
+> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
+> the VS Code extension by Jonathan Carter (Microsoft). It is not
+> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
+> project. It exists to *serve* CodeTour and its users — keeping `.tour`
+> files accurate as the code they walk through evolves.
+
+---
+
+## The problem
+
+A CodeTour step pinned to `src/auth.py:42` is correct the day it's written. Twenty commits later, line 42 is something else entirely — and every tour in the repository is silently lying. Tours are the best onboarding artifact a codebase can have, *if* someone keeps them true. Nobody keeps them true by hand.
+
+`codetour-cli` tracks each step across the commits between a tour's pinned `ref` and `HEAD` (git hunk mapping plus content heuristics), applies high-confidence line updates automatically with **byte-preserving surgical edits** (your diff shows the step change, not a rewritten file — via [`json-source-edit`](https://pypi.org/project/json-source-edit/)), and routes everything it isn't sure about to a review report designed to be worked by humans *and* AI agents alike.
+
+## Install
+
+```bash
+pip install codetour-cli        # Python ≥ 3.10
+```
+
+## Quickstart
+
+```bash
+codetour-cli status                  # which tours lag HEAD?
+codetour-cli migrate --dry-run       # preview: what would move, what needs review
+codetour-cli migrate                 # apply confident updates; write review report
+codetour-cli lint                    # ground-truth check tours against the workspace
+```
+
+## The maintenance loop
+
+```
+author tour ──► lint ──► commit, pin `ref`
+     ▲                        │
+     │               ...code evolves...
+     │                        │
+     │                   status  (tour lags HEAD?)
+     │                        │
+apply-review ◄── review report ◄── migrate [--dry-run]
+(checked steps            (auto-applies confident updates;
+ written back)             low-confidence → the report)
+```
+
+Steps the migration can't confidently place land in `MIGRATION-REVIEW-{tour}-{commit}.md`: each entry carries the step's original description (its *intent*), old → new location, why confidence dropped, and the actual code now at the proposed location. Check the boxes you approve — or correct the locations inline — then:
+
+```bash
+codetour-cli apply-review MIGRATION-REVIEW-mytour-abc12345.md
+```
+
+**The report is deliberately dual-audience**: an AI agent can read it, judge each proposed location against the step's stated intent, mark the checkboxes, and apply — the same workflow, no human bottleneck for the easy calls. (A companion [Claude skill](https://github.com/jlumbroso/codetour-skill/releases) teaches agents both tour authoring and this maintenance loop.)
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Set up `.codetour-cli.yml` configuration |
+| `status` | Health of every tour: current vs. lagging HEAD |
+| `check [tour]` | Validate tour structure without migrating |
+| `lint [paths]` | Step-level checks against the workspace: missing files, out-of-range lines, non-matching or ambiguous patterns, broken `nextTour` links (`--format json`, `--strict`) |
+| `migrate [tour]` | Track steps to HEAD; apply confident updates; report the rest |
+| `apply-review <report>` | Write checked corrections back to the tour file |
+| `undo [tour]` | Restore from the `.tour.backup` files migrate creates |
+
+**Flags worth knowing** (`migrate`): `--threshold X` — the auto-apply confidence bar (note: confidence takes 5 exact values, not a smooth dial; see `docs/adr/0016-*.md`); `--clean-reviews` — drop stale review reports from earlier target commits; `--context-lines N` — code context in reports (default 7, config `review.context_lines`). (`apply-review`): `--auto-approve-above X` — also apply *unchecked* steps at or above that confidence; steps marked for deletion are **never** auto-approved.
+
+## MCP server
+
+For agents on MCP-capable surfaces, the same operations are exposed as structured tools:
+
+```bash
+pip install "codetour-cli[mcp]"
+codetour-mcp                       # stdio MCP server
+```
+
+Five tools — `tour_status`, `lint_tours`, `migrate_tour` (defaults to dry-run; a model-facing tool must not mutate by default), `read_review_report`, `apply_review` — each a thin wrapper calling the exact functions the CLI verbs call, with identical semantics (including: deletion-marked steps are never auto-approved). Register it e.g. in `.mcp.json`:
+
+```json
+{ "mcpServers": { "codetour": { "command": "codetour-mcp" } } }
+```
+
+## Design record
+
+This tool is developed with the [ADRs4AI](https://github.com/jlumbroso) methodology — every architectural decision, including the ones that were later reversed, lives in `docs/adr/` as a first-class deliberation record: the byte-preserving editing contract, the confidence quantization study, the review-workflow design, and the retirement of ideas that eight months of shipped reality outvoted.
+
+## License
+
+[MIT](LICENSE) — like CodeTour itself.

codetour_cli-0.3.0/README.md

@@ -0,0 +1,99 @@
+# CodeTour CLI
+
+[![Tests](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml/badge.svg)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
+[![Coverage ≥60%](https://img.shields.io/badge/coverage-%E2%89%A560%25-yellowgreen)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/codetour-cli)](https://pypi.org/project/codetour-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codetour-cli)](https://pypi.org/project/codetour-cli/)
+[![Downloads](https://static.pepy.tech/badge/codetour-cli)](https://pepy.tech/projects/codetour-cli)
+[![License](https://img.shields.io/github/license/jlumbroso/codetour-cli)](https://github.com/jlumbroso/codetour-cli/blob/main/LICENSE)
+
+**Algorithmic maintenance of [CodeTour](https://github.com/microsoft/codetour) files: keep `.tour` walkthroughs accurate as the code they narrate evolves.**
+
+> **Unofficial companion tool.** `codetour-cli` is an independent,
+> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
+> the VS Code extension by Jonathan Carter (Microsoft). It is not
+> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
+> project. It exists to *serve* CodeTour and its users — keeping `.tour`
+> files accurate as the code they walk through evolves.
+
+---
+
+## The problem
+
+A CodeTour step pinned to `src/auth.py:42` is correct the day it's written. Twenty commits later, line 42 is something else entirely — and every tour in the repository is silently lying. Tours are the best onboarding artifact a codebase can have, *if* someone keeps them true. Nobody keeps them true by hand.
+
+`codetour-cli` tracks each step across the commits between a tour's pinned `ref` and `HEAD` (git hunk mapping plus content heuristics), applies high-confidence line updates automatically with **byte-preserving surgical edits** (your diff shows the step change, not a rewritten file — via [`json-source-edit`](https://pypi.org/project/json-source-edit/)), and routes everything it isn't sure about to a review report designed to be worked by humans *and* AI agents alike.
+
+## Install
+
+```bash
+pip install codetour-cli        # Python ≥ 3.10
+```
+
+## Quickstart
+
+```bash
+codetour-cli status                  # which tours lag HEAD?
+codetour-cli migrate --dry-run       # preview: what would move, what needs review
+codetour-cli migrate                 # apply confident updates; write review report
+codetour-cli lint                    # ground-truth check tours against the workspace
+```
+
+## The maintenance loop
+
+```
+author tour ──► lint ──► commit, pin `ref`
+     ▲                        │
+     │               ...code evolves...
+     │                        │
+     │                   status  (tour lags HEAD?)
+     │                        │
+apply-review ◄── review report ◄── migrate [--dry-run]
+(checked steps            (auto-applies confident updates;
+ written back)             low-confidence → the report)
+```
+
+Steps the migration can't confidently place land in `MIGRATION-REVIEW-{tour}-{commit}.md`: each entry carries the step's original description (its *intent*), old → new location, why confidence dropped, and the actual code now at the proposed location. Check the boxes you approve — or correct the locations inline — then:
+
+```bash
+codetour-cli apply-review MIGRATION-REVIEW-mytour-abc12345.md
+```
+
+**The report is deliberately dual-audience**: an AI agent can read it, judge each proposed location against the step's stated intent, mark the checkboxes, and apply — the same workflow, no human bottleneck for the easy calls. (A companion [Claude skill](https://github.com/jlumbroso/codetour-skill/releases) teaches agents both tour authoring and this maintenance loop.)
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Set up `.codetour-cli.yml` configuration |
+| `status` | Health of every tour: current vs. lagging HEAD |
+| `check [tour]` | Validate tour structure without migrating |
+| `lint [paths]` | Step-level checks against the workspace: missing files, out-of-range lines, non-matching or ambiguous patterns, broken `nextTour` links (`--format json`, `--strict`) |
+| `migrate [tour]` | Track steps to HEAD; apply confident updates; report the rest |
+| `apply-review <report>` | Write checked corrections back to the tour file |
+| `undo [tour]` | Restore from the `.tour.backup` files migrate creates |
+
+**Flags worth knowing** (`migrate`): `--threshold X` — the auto-apply confidence bar (note: confidence takes 5 exact values, not a smooth dial; see `docs/adr/0016-*.md`); `--clean-reviews` — drop stale review reports from earlier target commits; `--context-lines N` — code context in reports (default 7, config `review.context_lines`). (`apply-review`): `--auto-approve-above X` — also apply *unchecked* steps at or above that confidence; steps marked for deletion are **never** auto-approved.
+
+## MCP server
+
+For agents on MCP-capable surfaces, the same operations are exposed as structured tools:
+
+```bash
+pip install "codetour-cli[mcp]"
+codetour-mcp                       # stdio MCP server
+```
+
+Five tools — `tour_status`, `lint_tours`, `migrate_tour` (defaults to dry-run; a model-facing tool must not mutate by default), `read_review_report`, `apply_review` — each a thin wrapper calling the exact functions the CLI verbs call, with identical semantics (including: deletion-marked steps are never auto-approved). Register it e.g. in `.mcp.json`:
+
+```json
+{ "mcpServers": { "codetour": { "command": "codetour-mcp" } } }
+```
+
+## Design record
+
+This tool is developed with the [ADRs4AI](https://github.com/jlumbroso) methodology — every architectural decision, including the ones that were later reversed, lives in `docs/adr/` as a first-class deliberation record: the byte-preserving editing contract, the confidence quantization study, the review-workflow design, and the retirement of ideas that eight months of shipped reality outvoted.
+
+## License
+
+[MIT](LICENSE) — like CodeTour itself.

{codetour_cli-0.2.0 → codetour_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codetour-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension"
 authors = [{name = "Jérémie Lumbroso"}]
 readme = "README.md"
@@ -41,6 +41,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+# MCP server (ADR-0017): thin wrapper over the same machinery the CLI
+# verbs call, exposed as `codetour-mcp` (stdio).
+mcp = [
+    "mcp>=1.2",
+]
 dev = [
     "pytest",
     "pytest-cov",
@@ -51,6 +56,10 @@ dev = [
 
 [project.scripts]
 codetour-cli = "codetour_cli.cli:main"
+# Installed unconditionally; the mcp SDK lives in the [mcp] extra, and the
+# launcher answers a bare install with an install hint, not a traceback
+# (the json-source-edit playground-launcher pattern).
+codetour-mcp = "codetour_cli.mcp_server:main"
 
 [project.urls]
 Homepage = "https://github.com/jlumbroso/codetour-cli"

codetour_cli-0.3.0/src/codetour_cli/mcp_server.py

@@ -0,0 +1,279 @@
+"""MCP server for codetour-cli — structured tour operations for AI agents.
+
+ADR-0017 (Accepted 2026-08-30): a THIN WRAPPER over the exact machinery the
+CLI verbs call — `discovery.discover_repository`, `lint.lint_collection`,
+`cli.migrate_command`, `review_parser.parse_review_report`,
+`cli.apply_review_command`. Any behavioral drift between a CLI verb and its
+MCP tool is a bug by definition; nothing here reimplements an operation.
+
+Entry-point seam (same pattern as json-source-edit's playground launcher):
+setuptools installs console scripts unconditionally, so a bare
+`pip install codetour-cli` puts `codetour-mcp` on PATH while the `mcp` SDK
+lives in the `[mcp]` extra. `main()` is deliberately import-light — nothing
+above it may import outside the standard library and this package — so the
+first thing a stranger types answers with an install hint, not a traceback.
+
+Two deliberate, documented parameter-default choices (not behavior drift —
+per-operation behavior is identical to the CLI at equal flag values):
+- `migrate_tour` defaults to `dry_run=True`: a model-facing tool must not
+  mutate files by default; pass dry_run=False for the CLI's default-live
+  behavior.
+- `apply_review` exposes the CLI's `--yes` as `approve_warned_descriptions`
+  and feeds declined prompts a "n" stream, because an MCP server has no
+  interactive stdin — skip-on-warning is exactly what pressing enter at the
+  CLI's [y/N] prompt does.
+"""
+
+from __future__ import annotations
+
+import io
+import sys
+from contextlib import redirect_stdout
+from dataclasses import asdict
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, Optional
+
+_INSTALL_HINT = (
+    "codetour-mcp is the optional MCP server, and its dependency is not "
+    "installed (missing: {missing}).\n"
+    "Install it with:\n\n"
+    '    pip install "codetour-cli[mcp]"\n'
+)
+
+
+# ── tool implementations (plain functions; registered onto FastMCP in main) ──
+# Kept SDK-free so tests can exercise them without the [mcp] extra installed.
+
+
+def tour_status_impl() -> dict:
+    """Structured health of every tour in the repository."""
+    from codetour_cli.discovery import discover_repository, is_tour_up_to_date
+
+    info = discover_repository()
+    tours = []
+    for t in info.tours:
+        tours.append({
+            "file": str(t.path),
+            "title": getattr(t.tour, "title", None),
+            "steps": len(getattr(t.tour, "steps", []) or []),
+            "source_commit": t.source_commit,
+            "source_confidence": t.source_confidence,
+            "source_method": t.source_method,
+            "commits_behind": t.commits_behind,
+            "up_to_date": is_tour_up_to_date(t),
+        })
+    return {
+        "repo_path": str(info.repo_path),
+        "tours_dir": str(info.tours_dir),
+        "tours": tours,
+    }
+
+
+def lint_tours_impl(paths: Optional[list[str]] = None, strict: bool = False) -> dict:
+    """Ground-truth lint findings, structured (same checks as `codetour-cli lint`)."""
+    from codetour_cli.discovery import find_repo_root, find_tours_directory, scan_tours
+    from codetour_cli.lint import has_errors, lint_collection
+
+    repo_root = find_repo_root()
+    if paths:
+        tour_paths = []
+        for raw in paths:
+            p = Path(raw)
+            if not p.is_absolute():
+                p = repo_root / p
+            if p.is_dir():
+                tour_paths.extend(scan_tours(p))
+            else:
+                tour_paths.append(p)
+    else:
+        tours_dir = find_tours_directory(repo_root)
+        tour_paths = scan_tours(tours_dir) if tours_dir else []
+
+    findings = lint_collection(tour_paths, repo_root)
+    errors = sum(1 for f in findings if f.severity == "error")
+    return {
+        "tours_checked": len(tour_paths),
+        "errors": errors,
+        "warnings": len(findings) - errors,
+        "clean": not has_errors(findings, strict=strict),
+        "findings": [asdict(f) if hasattr(f, "__dataclass_fields__") else vars(f)
+                     for f in findings],
+    }
+
+
+def _run_command(command_fn, args: SimpleNamespace, stdin_text: str = "") -> dict:
+    """Run a CLI command function verbatim, capturing stdout; feed a scripted
+    stdin so interactive prompts resolve to their conservative default."""
+    from codetour_cli.config import load_config
+
+    config = load_config()
+    buf = io.StringIO()
+    old_stdin = sys.stdin
+    sys.stdin = io.StringIO(stdin_text)
+    try:
+        with redirect_stdout(buf):
+            exit_code = command_fn(args, config)
+    finally:
+        sys.stdin = old_stdin
+    return {"exit_code": exit_code, "output": buf.getvalue()}
+
+
+def migrate_tour_impl(
+    tour_file: Optional[str] = None,
+    dry_run: bool = True,
+    threshold: Optional[float] = None,
+    to_commit: str = "HEAD",
+    from_commit: Optional[str] = None,
+    clean_reviews: bool = False,
+    context_lines: Optional[int] = None,
+) -> dict:
+    """Migrate a tour (or all out-of-date tours) via the CLI's own command path."""
+    from codetour_cli.cli import migrate_command
+
+    args = SimpleNamespace(
+        tour_file=tour_file,
+        from_commit=from_commit,
+        to_commit=to_commit,
+        threshold=threshold,
+        no_backup=False,
+        interactive=False,
+        dry_run=dry_run,
+        no_guidance=False,
+        no_lint=False,
+        clean_reviews=clean_reviews,
+        context_lines=context_lines,
+    )
+    result = _run_command(migrate_command, args)
+    result["reports"] = [
+        line.split("Review report", 1)[1].split(":", 1)[1].strip()
+        for line in result["output"].splitlines()
+        if "Review report" in line and ":" in line.split("Review report", 1)[1]
+    ]
+    result["dry_run"] = dry_run
+    return result
+
+
+def read_review_report_impl(report_file: str) -> dict:
+    """Parse a MIGRATION-REVIEW-*.md report into structured step reviews."""
+    from codetour_cli.review_parser import parse_review_report
+
+    review = parse_review_report(Path(report_file))
+    return {
+        "tour_name": review.tour_name,
+        "source_commit": review.source_commit,
+        "target_commit": review.target_commit,
+        "mode": review.mode,
+        "step_reviews": [asdict(r) for r in review.step_reviews],
+    }
+
+
+def apply_review_impl(
+    report_file: str,
+    auto_approve_above: Optional[float] = None,
+    approve_warned_descriptions: bool = False,
+) -> dict:
+    """Apply a review report via the CLI's own command path."""
+    from codetour_cli.cli import apply_review_command
+
+    args = SimpleNamespace(
+        report_file=report_file,
+        auto_approve=approve_warned_descriptions,
+        auto_approve_above=auto_approve_above,
+    )
+    # "n\n" stream: any description-warning prompt resolves to skip — the
+    # CLI's own conservative default at its [y/N] prompt.
+    return _run_command(apply_review_command, args, stdin_text="n\n" * 1000)
+
+
+# ── server assembly ──────────────────────────────────────────────────────────
+
+
+def build_server() -> Any:
+    """Construct the MCP server (requires the [mcp] extra).
+
+    SDK v2 renamed FastMCP → MCPServer (same tool/run surface, verified
+    empirically 2026-08-30 — the stdio smoke test caught the v1 prior
+    before it shipped); import v2 first, fall back to v1 for pinned
+    environments."""
+    try:
+        from mcp.server.mcpserver import MCPServer as _Server  # mcp >= 2
+    except ImportError:
+        from mcp.server.fastmcp import FastMCP as _Server  # mcp 1.x
+
+    server = _Server("codetour-cli")
+
+    server.tool(
+        name="tour_status",
+        description=(
+            "Structured health of every CodeTour in the repository: per tour, "
+            "its pinned source commit, detection confidence/method, how many "
+            "commits behind HEAD it is, and whether it is up to date."
+        ),
+    )(tour_status_impl)
+
+    server.tool(
+        name="lint_tours",
+        description=(
+            "Lint tours against the actual workspace (missing files, "
+            "out-of-range lines, non-matching or ambiguous patterns, broken "
+            "nextTour links, duplicate isPrimary). Structured findings; "
+            "same checks as `codetour-cli lint`."
+        ),
+    )(lint_tours_impl)
+
+    server.tool(
+        name="migrate_tour",
+        description=(
+            "Migrate a tour (or all out-of-date tours) toward HEAD via the "
+            "CLI's own pipeline. DEFAULTS TO dry_run=true — pass "
+            "dry_run=false to actually write. Confident step updates are "
+            "applied (byte-preserving edits); low-confidence steps land in a "
+            "review report (paths returned in `reports`). Note: `threshold` "
+            "confidence only takes 5 exact values — values in (0.5, 0.95) "
+            "behave like the default; see that repo's ADR-0016 before tuning."
+        ),
+    )(migrate_tour_impl)
+
+    server.tool(
+        name="read_review_report",
+        description=(
+            "Parse a MIGRATION-REVIEW-*.md report into structured step "
+            "reviews: per step, its checkbox state, tentative file/line, "
+            "confidence, and any edited description. Read this, judge each "
+            "proposed location against the step's original intent, then use "
+            "apply_review."
+        ),
+    )(read_review_report_impl)
+
+    server.tool(
+        name="apply_review",
+        description=(
+            "Apply corrections from a review report to the tour file "
+            "(byte-preserving edits, backup created). Applies checkbox-"
+            "checked steps; `auto_approve_above` (0.0-1.0) additionally "
+            "applies UNCHECKED steps at/above that confidence — but steps "
+            "marked for deletion are NEVER auto-approved (destructive stays "
+            "behind an explicit checkbox). Confidence takes 5 exact values "
+            "(ADR-0016). `approve_warned_descriptions` maps to the CLI's "
+            "--yes for description-edit warnings; when false, warned edits "
+            "are skipped (the CLI prompt's own default)."
+        ),
+    )(apply_review_impl)
+
+    return server
+
+
+def main() -> None:
+    try:
+        import mcp  # noqa: F401
+    except ImportError as exc:
+        missing = getattr(exc, "name", None) or str(exc)
+        print(_INSTALL_HINT.format(missing=missing), file=sys.stderr)
+        raise SystemExit(1)
+
+    build_server().run()
+
+
+if __name__ == "__main__":
+    main()

codetour_cli-0.3.0/src/codetour_cli.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: codetour-cli
+Version: 0.3.0
+Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
+Author: Jérémie Lumbroso
+License: MIT
+Project-URL: Homepage, https://github.com/jlumbroso/codetour-cli
+Project-URL: Repository, https://github.com/jlumbroso/codetour-cli
+Keywords: codetour,code-tour,vscode,git,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: gitpython
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog
+Requires-Dist: rich
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: json-source-edit<2,>=1.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# CodeTour CLI
+
+[![Tests](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml/badge.svg)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
+[![Coverage ≥60%](https://img.shields.io/badge/coverage-%E2%89%A560%25-yellowgreen)](https://github.com/jlumbroso/codetour-cli/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/codetour-cli)](https://pypi.org/project/codetour-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codetour-cli)](https://pypi.org/project/codetour-cli/)
+[![Downloads](https://static.pepy.tech/badge/codetour-cli)](https://pepy.tech/projects/codetour-cli)
+[![License](https://img.shields.io/github/license/jlumbroso/codetour-cli)](https://github.com/jlumbroso/codetour-cli/blob/main/LICENSE)
+
+**Algorithmic maintenance of [CodeTour](https://github.com/microsoft/codetour) files: keep `.tour` walkthroughs accurate as the code they narrate evolves.**
+
+> **Unofficial companion tool.** `codetour-cli` is an independent,
+> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
+> the VS Code extension by Jonathan Carter (Microsoft). It is not
+> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
+> project. It exists to *serve* CodeTour and its users — keeping `.tour`
+> files accurate as the code they walk through evolves.
+
+---
+
+## The problem
+
+A CodeTour step pinned to `src/auth.py:42` is correct the day it's written. Twenty commits later, line 42 is something else entirely — and every tour in the repository is silently lying. Tours are the best onboarding artifact a codebase can have, *if* someone keeps them true. Nobody keeps them true by hand.
+
+`codetour-cli` tracks each step across the commits between a tour's pinned `ref` and `HEAD` (git hunk mapping plus content heuristics), applies high-confidence line updates automatically with **byte-preserving surgical edits** (your diff shows the step change, not a rewritten file — via [`json-source-edit`](https://pypi.org/project/json-source-edit/)), and routes everything it isn't sure about to a review report designed to be worked by humans *and* AI agents alike.
+
+## Install
+
+```bash
+pip install codetour-cli        # Python ≥ 3.10
+```
+
+## Quickstart
+
+```bash
+codetour-cli status                  # which tours lag HEAD?
+codetour-cli migrate --dry-run       # preview: what would move, what needs review
+codetour-cli migrate                 # apply confident updates; write review report
+codetour-cli lint                    # ground-truth check tours against the workspace
+```
+
+## The maintenance loop
+
+```
+author tour ──► lint ──► commit, pin `ref`
+     ▲                        │
+     │               ...code evolves...
+     │                        │
+     │                   status  (tour lags HEAD?)
+     │                        │
+apply-review ◄── review report ◄── migrate [--dry-run]
+(checked steps            (auto-applies confident updates;
+ written back)             low-confidence → the report)
+```
+
+Steps the migration can't confidently place land in `MIGRATION-REVIEW-{tour}-{commit}.md`: each entry carries the step's original description (its *intent*), old → new location, why confidence dropped, and the actual code now at the proposed location. Check the boxes you approve — or correct the locations inline — then:
+
+```bash
+codetour-cli apply-review MIGRATION-REVIEW-mytour-abc12345.md
+```
+
+**The report is deliberately dual-audience**: an AI agent can read it, judge each proposed location against the step's stated intent, mark the checkboxes, and apply — the same workflow, no human bottleneck for the easy calls. (A companion [Claude skill](https://github.com/jlumbroso/codetour-skill/releases) teaches agents both tour authoring and this maintenance loop.)
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Set up `.codetour-cli.yml` configuration |
+| `status` | Health of every tour: current vs. lagging HEAD |
+| `check [tour]` | Validate tour structure without migrating |
+| `lint [paths]` | Step-level checks against the workspace: missing files, out-of-range lines, non-matching or ambiguous patterns, broken `nextTour` links (`--format json`, `--strict`) |
+| `migrate [tour]` | Track steps to HEAD; apply confident updates; report the rest |
+| `apply-review <report>` | Write checked corrections back to the tour file |
+| `undo [tour]` | Restore from the `.tour.backup` files migrate creates |
+
+**Flags worth knowing** (`migrate`): `--threshold X` — the auto-apply confidence bar (note: confidence takes 5 exact values, not a smooth dial; see `docs/adr/0016-*.md`); `--clean-reviews` — drop stale review reports from earlier target commits; `--context-lines N` — code context in reports (default 7, config `review.context_lines`). (`apply-review`): `--auto-approve-above X` — also apply *unchecked* steps at or above that confidence; steps marked for deletion are **never** auto-approved.
+
+## MCP server
+
+For agents on MCP-capable surfaces, the same operations are exposed as structured tools:
+
+```bash
+pip install "codetour-cli[mcp]"
+codetour-mcp                       # stdio MCP server
+```
+
+Five tools — `tour_status`, `lint_tours`, `migrate_tour` (defaults to dry-run; a model-facing tool must not mutate by default), `read_review_report`, `apply_review` — each a thin wrapper calling the exact functions the CLI verbs call, with identical semantics (including: deletion-marked steps are never auto-approved). Register it e.g. in `.mcp.json`:
+
+```json
+{ "mcpServers": { "codetour": { "command": "codetour-mcp" } } }
+```
+
+## Design record
+
+This tool is developed with the [ADRs4AI](https://github.com/jlumbroso) methodology — every architectural decision, including the ones that were later reversed, lives in `docs/adr/` as a first-class deliberation record: the byte-preserving editing contract, the confidence quantization study, the review-workflow design, and the retirement of ideas that eight months of shipped reality outvoted.
+
+## License
+
+[MIT](LICENSE) — like CodeTour itself.

{codetour_cli-0.2.0 → codetour_cli-0.3.0}/src/codetour_cli.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/codetour_cli/description_validator.py
 src/codetour_cli/detection.py
 src/codetour_cli/discovery.py
 src/codetour_cli/lint.py
+src/codetour_cli/mcp_server.py
 src/codetour_cli/review_parser.py
 src/codetour_cli/schema_models.py
 src/codetour_cli.egg-info/PKG-INFO
@@ -37,6 +38,7 @@ tests/test_integration.py
 tests/test_lint.py
 tests/test_lint_cli.py
 tests/test_logging_setup.py
+tests/test_mcp_server.py
 tests/test_pattern_validation.py
 tests/test_post_migration_lint.py
 tests/test_review_roundtrip.py

{codetour_cli-0.2.0 → codetour_cli-0.3.0}/src/codetour_cli.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 codetour-cli = codetour_cli.cli:main
+codetour-mcp = codetour_cli.mcp_server:main

{codetour_cli-0.2.0 → codetour_cli-0.3.0}/src/codetour_cli.egg-info/requires.txt

@@ -14,3 +14,6 @@ pytest-cov
 black
 ruff
 mypy
+
+[mcp]
+mcp>=1.2

codetour_cli-0.3.0/tests/test_mcp_server.py

@@ -0,0 +1,253 @@
+"""Tests for the MCP server (ADR-0017, v0.3.0).
+
+The tool implementations are deliberately SDK-free plain functions, so
+everything except the stdio smoke test runs without the [mcp] extra --
+and everything runs against REAL machinery (real git repos, real tour
+files, the real command functions), never mocks: the wrapper-not-fork
+constraint means the thing worth testing is that the wrappers drive the
+same behavior the CLI does.
+"""
+
+import json
+import subprocess
+import sys
+
+import pytest
+
+from codetour_cli.mcp_server import (
+    apply_review_impl,
+    lint_tours_impl,
+    migrate_tour_impl,
+    read_review_report_impl,
+    tour_status_impl,
+)
+
+
+def _init_git_repo(path):
+    subprocess.run(["git", "init", "-q"], cwd=path, check=True)
+    subprocess.run(["git", "config", "user.email", "test@example.com"], cwd=path, check=True)
+    subprocess.run(["git", "config", "user.name", "Test"], cwd=path, check=True)
+
+
+def _review_report(tour_name, entries):
+    """Same shape the apply-review integration tests use, plus a `checked`
+    knob so auto-approve-above has genuinely unchecked steps to promote."""
+    steps_md = []
+    for e in entries:
+        checked = "[x] Reviewed" if e.get("checked", True) else "[ ] Not reviewed"
+        block = f"""### Step {e['step_number']}: placeholder → placeholder ({e.get('confidence', 80)}% confidence)
+
+---
+
+#### Review Status
+
+- **Status**: {checked}
+- **Tentative file**: `{e['tentative_file']}`
+- **Tentative line**: `{e['tentative_line']}`
+- **Confidence**: {e.get('confidence', 80)}%
+- **Modified Description**: [ ]
+
+---
+"""
+        steps_md.append(block)
+
+    return f"""---
+schema_version: '1.0'
+---
+
+# Migration Review Report
+
+- **Generated**: 2026-08-30 00:00:00
+- **Source commit**: abc12345
+- **Target commit**: def67890
+- **Mode**: live
+- **Tour**: {tour_name}
+- **Total steps**: {len(entries)}
+
+## Steps Needing Review
+
+""" + "\n".join(steps_md)
+
+
+TOUR_JSON = """{
+  "$schema": "https://aka.ms/codetour-schema",
+  "title": "Rust Basics",
+  "steps": [
+    {
+      "file": "src/main.rs",
+      "line": 3,
+      "description": "Entry point"
+    },
+    {
+      "file": "src/lib.rs",
+      "line": 2,
+      "description": "Library definition"
+    }
+  ]
+}
+"""
+
+
+@pytest.fixture
+def repo_with_tour(tmp_path, monkeypatch):
+    _init_git_repo(tmp_path)
+    (tmp_path / "src").mkdir()
+    (tmp_path / "src" / "main.rs").write_text("fn a() {}\nfn b() {}\nfn main() {}\n", encoding="utf-8")
+    (tmp_path / "src" / "lib.rs").write_text("mod a;\npub fn lib() {}\n", encoding="utf-8")
+    tours_dir = tmp_path / ".tours"
+    tours_dir.mkdir()
+    tour_path = tours_dir / "rust-basics.tour"
+    tour_path.write_text(TOUR_JSON, encoding="utf-8")
+    subprocess.run(["git", "add", "."], cwd=tmp_path, check=True)
+    subprocess.run(["git", "commit", "-q", "-m", "initial"], cwd=tmp_path, check=True)
+    monkeypatch.chdir(tmp_path)
+    return tmp_path, tour_path
+
+
+class TestTourStatus:
+    def test_structured_status_for_real_repo(self, repo_with_tour):
+        tmp_path, _ = repo_with_tour
+        result = tour_status_impl()
+        assert result["repo_path"] == str(tmp_path)
+        assert len(result["tours"]) == 1
+        t = result["tours"][0]
+        assert t["title"] == "Rust Basics"
+        assert t["steps"] == 2
+        assert isinstance(t["commits_behind"], int)
+        assert isinstance(t["up_to_date"], bool)
+        assert t["source_commit"]
+
+
+class TestLintTours:
+    def test_reports_real_problems(self, repo_with_tour):
+        tmp_path, tour_path = repo_with_tour
+        # A real defect a user would ship: a step pointing at a missing file.
+        broken = TOUR_JSON.replace("src/lib.rs", "src/gone.rs")
+        tour_path.write_text(broken, encoding="utf-8")
+        result = lint_tours_impl()
+        assert result["tours_checked"] == 1
+        assert result["errors"] >= 1
+        assert result["clean"] is False
+        assert any("gone.rs" in str(f.get("message", "")) for f in result["findings"])
+
+    def test_clean_tour_is_clean(self, repo_with_tour):
+        result = lint_tours_impl()
+        assert result["errors"] == 0
+        assert result["clean"] is True
+
+
+class TestReadReviewReport:
+    def test_parses_structured(self, repo_with_tour, tmp_path):
+        report = tmp_path / "MIGRATION-REVIEW-rust-basics-def67890.md"
+        report.write_text(
+            _review_report("rust-basics.tour", [
+                {"step_number": 1, "tentative_file": "src/main.rs",
+                 "tentative_line": "2", "confidence": 50, "checked": False},
+            ]),
+            encoding="utf-8",
+        )
+        result = read_review_report_impl(str(report))
+        assert result["tour_name"] == "rust-basics.tour"
+        assert result["target_commit"] == "def67890"
+        (r,) = result["step_reviews"]
+        assert r["step_number"] == 1
+        assert r["status_checked"] is False
+        assert r["confidence"] == 50
+
+
+class TestApplyReview:
+    def test_applies_checked_step_to_real_tour(self, repo_with_tour, tmp_path):
+        _, tour_path = repo_with_tour
+        report = tmp_path / "MIGRATION-REVIEW-rust-basics-def67890.md"
+        report.write_text(
+            _review_report("rust-basics.tour", [
+                {"step_number": 2, "tentative_file": "src/lib.rs",
+                 "tentative_line": "1", "checked": True},
+            ]),
+            encoding="utf-8",
+        )
+        result = apply_review_impl(str(report))
+        assert result["exit_code"] == 0
+        data = json.loads(tour_path.read_text(encoding="utf-8"))
+        assert data["steps"][1]["line"] == 1
+        assert data["steps"][0]["line"] == 3  # untouched neighbor
+
+    def test_auto_approve_above_promotes_unchecked_high_confidence(self, repo_with_tour, tmp_path):
+        _, tour_path = repo_with_tour
+        report = tmp_path / "MIGRATION-REVIEW-rust-basics-def67890.md"
+        report.write_text(
+            _review_report("rust-basics.tour", [
+                {"step_number": 1, "tentative_file": "src/main.rs",
+                 "tentative_line": "1", "confidence": 90, "checked": False},
+                {"step_number": 2, "tentative_file": "src/lib.rs",
+                 "tentative_line": "1", "confidence": 50, "checked": False},
+            ]),
+            encoding="utf-8",
+        )
+        result = apply_review_impl(str(report), auto_approve_above=0.8)
+        assert result["exit_code"] == 0
+        data = json.loads(tour_path.read_text(encoding="utf-8"))
+        assert data["steps"][0]["line"] == 1   # 90% ≥ 80%: promoted, applied
+        assert data["steps"][1]["line"] == 2   # 50% < 80%: untouched
+
+    def test_without_flag_unchecked_steps_do_nothing(self, repo_with_tour, tmp_path):
+        _, tour_path = repo_with_tour
+        before = tour_path.read_bytes()
+        report = tmp_path / "MIGRATION-REVIEW-rust-basics-def67890.md"
+        report.write_text(
+            _review_report("rust-basics.tour", [
+                {"step_number": 1, "tentative_file": "src/main.rs",
+                 "tentative_line": "1", "confidence": 90, "checked": False},
+            ]),
+            encoding="utf-8",
+        )
+        result = apply_review_impl(str(report))
+        assert result["exit_code"] == 0
+        assert tour_path.read_bytes() == before
+
+
+class TestMigrateTour:
+    def test_dry_run_is_the_default_and_mutates_nothing(self, repo_with_tour):
+        _, tour_path = repo_with_tour
+        before = tour_path.read_bytes()
+        result = migrate_tour_impl()
+        assert result["dry_run"] is True
+        assert result["exit_code"] in (0, 1)
+        assert tour_path.read_bytes() == before
+        assert result["output"]  # the CLI's own narration, captured
+
+
+class TestStdioServer:
+    def test_smoke_initialize_and_tools_list(self):
+        # A real (minimal) MCP client over stdio: the v2 SDK enforces the
+        # session lifecycle, so batch-piping all messages races the
+        # initialize handshake and tools/list gets dropped — write, read
+        # the response, then proceed, like an actual client.
+        pytest.importorskip("mcp")
+        proc = subprocess.Popen(
+            [sys.executable, "-m", "codetour_cli.mcp_server"],
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE, text=True,
+        )
+        try:
+            def send(msg):
+                proc.stdin.write(json.dumps(msg) + "\n")
+                proc.stdin.flush()
+
+            send({"jsonrpc": "2.0", "id": 1, "method": "initialize",
+                  "params": {"protocolVersion": "2025-06-18", "capabilities": {},
+                             "clientInfo": {"name": "smoke", "version": "0"}}})
+            init_resp = json.loads(proc.stdout.readline())
+            assert init_resp["id"] == 1
+            assert init_resp["result"]["serverInfo"]["name"] == "codetour-cli"
+
+            send({"jsonrpc": "2.0", "method": "notifications/initialized"})
+            send({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+            tools_resp = json.loads(proc.stdout.readline())
+            assert tools_resp["id"] == 2
+            names = {t["name"] for t in tools_resp["result"]["tools"]}
+            assert names == {"tour_status", "lint_tours", "migrate_tour",
+                             "read_review_report", "apply_review"}
+        finally:
+            proc.kill()
+            proc.wait(timeout=10)

codetour_cli-0.2.0/PKG-INFO

@@ -1,47 +0,0 @@
-Metadata-Version: 2.4
-Name: codetour-cli
-Version: 0.2.0
-Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
-Author: Jérémie Lumbroso
-License: MIT
-Project-URL: Homepage, https://github.com/jlumbroso/codetour-cli
-Project-URL: Repository, https://github.com/jlumbroso/codetour-cli
-Keywords: codetour,code-tour,vscode,git,cli
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Topic :: Software Development :: Version Control :: Git
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: gitpython
-Requires-Dist: pydantic>=2.0
-Requires-Dist: structlog
-Requires-Dist: rich
-Requires-Dist: python-dotenv
-Requires-Dist: pyyaml
-Requires-Dist: click>=8.0
-Requires-Dist: jinja2>=3.0
-Requires-Dist: json-source-edit<2,>=1.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Dynamic: license-file
-
-# CodeTour CLI
-
-A CLI to reliably migrate CodeTours in the background, and prevent drift.
-
-> **Unofficial companion tool.** `codetour-cli` is an independent,
-> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
-> the VS Code extension by Jonathan Carter (Microsoft). It is not
-> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
-> project. It exists to *serve* CodeTour and its users — keeping `.tour`
-> files accurate as the code they walk through evolves.

codetour_cli-0.2.0/README.md

@@ -1,10 +0,0 @@
-# CodeTour CLI
-
-A CLI to reliably migrate CodeTours in the background, and prevent drift.
-
-> **Unofficial companion tool.** `codetour-cli` is an independent,
-> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
-> the VS Code extension by Jonathan Carter (Microsoft). It is not
-> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
-> project. It exists to *serve* CodeTour and its users — keeping `.tour`
-> files accurate as the code they walk through evolves.

codetour_cli-0.2.0/src/codetour_cli.egg-info/PKG-INFO

@@ -1,47 +0,0 @@
-Metadata-Version: 2.4
-Name: codetour-cli
-Version: 0.2.0
-Summary: Algorithmic maintenance of CodeTour files — an unofficial companion CLI for the CodeTour VS Code extension
-Author: Jérémie Lumbroso
-License: MIT
-Project-URL: Homepage, https://github.com/jlumbroso/codetour-cli
-Project-URL: Repository, https://github.com/jlumbroso/codetour-cli
-Keywords: codetour,code-tour,vscode,git,cli
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Topic :: Software Development :: Version Control :: Git
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: gitpython
-Requires-Dist: pydantic>=2.0
-Requires-Dist: structlog
-Requires-Dist: rich
-Requires-Dist: python-dotenv
-Requires-Dist: pyyaml
-Requires-Dist: click>=8.0
-Requires-Dist: jinja2>=3.0
-Requires-Dist: json-source-edit<2,>=1.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Dynamic: license-file
-
-# CodeTour CLI
-
-A CLI to reliably migrate CodeTours in the background, and prevent drift.
-
-> **Unofficial companion tool.** `codetour-cli` is an independent,
-> unofficial companion to [CodeTour](https://github.com/microsoft/codetour),
-> the VS Code extension by Jonathan Carter (Microsoft). It is not
-> affiliated with, endorsed by, or maintained by Microsoft or the CodeTour
-> project. It exists to *serve* CodeTour and its users — keeping `.tour`
-> files accurate as the code they walk through evolves.