docsync 0.1.0__py3-none-any.whl

docsync/__init__.py

@@ -0,0 +1,5 @@
+from docsync.commands.cascade import find_affected_docs
+from docsync.commands.check import check_refs
+from docsync.core.parser import parse_doc
+
+__all__ = ["parse_doc", "check_refs", "find_affected_docs"]

docsync/cli.py

@@ -0,0 +1,50 @@
+import argparse
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from docsync.commands import cascade, check, init, sync, tree
+
+VERSION = version("docsync")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Keep docs in sync with code")
+    parser.add_argument("-v", "--version", action="version", version=f"docsync {VERSION}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    check_parser = subparsers.add_parser("check", help="validate all refs exist")
+    check_parser.add_argument("path", type=Path, help="docs directory to check")
+
+    cascade_parser = subparsers.add_parser("cascade", help="list docs affected by git diff")
+    cascade_parser.add_argument("commit", help="commit ref (e.g., HEAD~1, abc123)")
+    cascade_parser.add_argument("--docs", type=Path, default=Path("docs"), help="docs directory")
+
+    sync_parser = subparsers.add_parser("sync", help="generate prompt for AI to fix docs")
+    sync_parser.add_argument("path", type=Path, help="docs directory")
+    sync_parser.add_argument("--incremental", action="store_true", help="only include changed docs")
+    sync_parser.add_argument("--json", action="store_true", help="output as JSON instead of text")
+    sync_parser.add_argument("--parallel", action="store_true", help="ignore dependencies, sync all at once")
+    sync_parser.add_argument("--update-lock", action="store_true", help="update lock.json with current commit")
+
+    tree_parser = subparsers.add_parser("tree", help="show doc dependency tree")
+    tree_parser.add_argument("path", type=Path, help="docs directory")
+
+    subparsers.add_parser("init", help="create .docsync/ folder")
+
+    args = parser.parse_args()
+
+    if args.command == "check":
+        sys.exit(check.run(args.path))
+    elif args.command == "cascade":
+        sys.exit(cascade.run(args.commit, args.docs))
+    elif args.command == "sync":
+        sys.exit(sync.run(args.path, args.incremental, args.json, args.parallel, args.update_lock))
+    elif args.command == "tree":
+        sys.exit(tree.run(args.path))
+    elif args.command == "init":
+        sys.exit(init.run())
+
+
+if __name__ == "__main__":
+    main()

docsync/commands/cascade.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import subprocess
+from collections import defaultdict
+from pathlib import Path
+from typing import NamedTuple
+
+from docsync.core.config import Config, find_repo_root
+from docsync.core.parser import parse_doc
+
+
+class CascadeResult(NamedTuple):
+    affected_docs: list[Path]
+    direct_hits: list[Path]
+    cascade_hits: list[Path]
+    circular_refs: list[tuple[Path, Path]]
+
+
+def find_affected_docs(
+    docs_path: Path, commit_ref: str, config: Config, repo_root: Path | None = None
+) -> CascadeResult:
+    if repo_root is None:
+        repo_root = find_repo_root(docs_path)
+    changed_files = _get_changed_files(commit_ref, repo_root)
+    if not changed_files:
+        return CascadeResult([], [], [], [])
+    source_to_docs, doc_to_docs = _build_indexes(docs_path, repo_root)
+    direct_hits = _find_direct_hits(changed_files, source_to_docs)
+    cascade_hits, circular_refs = _cascade(direct_hits, doc_to_docs, config.cascade_depth_limit)
+    all_affected = list(set(direct_hits) | set(cascade_hits))
+    return CascadeResult(
+        affected_docs=all_affected, direct_hits=direct_hits, cascade_hits=cascade_hits, circular_refs=circular_refs
+    )
+
+
+def _get_changed_files(commit_ref: str, repo_root: Path) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", commit_ref], capture_output=True, text=True, check=True, cwd=repo_root
+        )
+        return [f.strip() for f in result.stdout.splitlines() if f.strip()]
+    except subprocess.CalledProcessError:
+        return []
+
+
+def _build_indexes(docs_path: Path, repo_root: Path) -> tuple[dict[str, list[Path]], dict[Path, list[Path]]]:
+    source_to_docs: dict[str, list[Path]] = defaultdict(list)
+    doc_to_docs: dict[Path, list[Path]] = defaultdict(list)
+    doc_files = list(docs_path.rglob("*.md"))
+    for doc_file in doc_files:
+        try:
+            parsed = parse_doc(doc_file)
+        except Exception:
+            continue
+        for ref in parsed.related_sources:
+            source_to_docs[ref.path].append(doc_file)
+        for ref in parsed.related_docs:
+            ref_path = repo_root / ref.path
+            if ref_path.exists():
+                doc_to_docs[ref_path].append(doc_file)
+    return source_to_docs, doc_to_docs
+
+
+def _find_direct_hits(changed_files: list[str], source_to_docs: dict[str, list[Path]]) -> list[Path]:
+    hits = []
+    for changed in changed_files:
+        if changed in source_to_docs:
+            hits.extend(source_to_docs[changed])
+        for source_ref, docs in source_to_docs.items():
+            if source_ref.endswith("/") and changed.startswith(source_ref):
+                hits.extend(docs)
+    return list(set(hits))
+
+
+def _cascade(
+    initial_docs: list[Path], doc_to_docs: dict[Path, list[Path]], depth_limit: int | None
+) -> tuple[list[Path], list[tuple[Path, Path]]]:
+    cascade_hits = []
+    circular_refs = []
+    visited = set(initial_docs)
+    current_level = set(initial_docs)
+    depth = 0
+    while current_level:
+        if depth_limit is not None and depth >= depth_limit:
+            break
+        next_level = set()
+        for doc in current_level:
+            for referencing_doc in doc_to_docs.get(doc, []):
+                if referencing_doc in visited:
+                    if referencing_doc not in initial_docs:
+                        circular_refs.append((doc, referencing_doc))
+                    continue
+                visited.add(referencing_doc)
+                cascade_hits.append(referencing_doc)
+                next_level.add(referencing_doc)
+        current_level = next_level
+        depth += 1
+    return cascade_hits, circular_refs
+
+
+def run(commit_ref: str, docs_path: Path) -> int:
+    from docsync.core.config import load_config
+
+    config = load_config()
+    result = find_affected_docs(docs_path, commit_ref, config)
+    if not result.affected_docs:
+        print("No docs affected")
+        return 0
+    print(f"Direct hits ({len(result.direct_hits)}):")
+    for doc in result.direct_hits:
+        print(f"  {doc}")
+    if result.cascade_hits:
+        print(f"\nCascade hits ({len(result.cascade_hits)}):")
+        for doc in result.cascade_hits:
+            print(f"  {doc}")
+    if result.circular_refs:
+        print("\nWarning: circular refs detected:")
+        for src, dst in result.circular_refs:
+            print(f"  {src} <-> {dst}")
+    return 0

docsync/commands/check.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator
+
+from docsync.core.config import Config, find_repo_root
+from docsync.core.parser import RefEntry, parse_doc
+
+
+@dataclass
+class RefError:
+    doc_path: Path
+    ref: RefEntry
+    message: str
+
+
+@dataclass
+class CheckResult:
+    doc_path: Path
+    errors: list[RefError] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return len(self.errors) == 0
+
+
+def check_refs(docs_path: Path, config: Config, repo_root: Path | None = None) -> Iterator[CheckResult]:
+    docs_path = docs_path.resolve()
+    if repo_root is None:
+        repo_root = find_repo_root(docs_path)
+    doc_files = list(docs_path.rglob("*.md"))
+    for doc_file in doc_files:
+        if _is_ignored(doc_file, config.ignored_paths, repo_root):
+            continue
+        yield _check_single_doc(doc_file, repo_root)
+
+
+def _check_single_doc(doc_path: Path, repo_root: Path) -> CheckResult:
+    result = CheckResult(doc_path=doc_path)
+    try:
+        parsed = parse_doc(doc_path)
+    except Exception as e:
+        result.errors.append(
+            RefError(
+                doc_path=doc_path,
+                ref=RefEntry(path="", description="", line_number=0),
+                message=f"failed to parse doc: {e}",
+            )
+        )
+        return result
+    for ref in parsed.related_docs:
+        ref_path = repo_root / ref.path
+        if not ref_path.exists():
+            result.errors.append(RefError(doc_path=doc_path, ref=ref, message=f"related doc not found: {ref.path}"))
+    for ref in parsed.related_sources:
+        ref_path = repo_root / ref.path
+        if not ref_path.exists() and not _glob_matches(ref.path, repo_root):
+            result.errors.append(RefError(doc_path=doc_path, ref=ref, message=f"related source not found: {ref.path}"))
+    return result
+
+
+def _glob_matches(pattern: str, repo_root: Path) -> bool:
+    if "*" in pattern or "?" in pattern:
+        matches = list(repo_root.glob(pattern))
+        return len(matches) > 0
+    return False
+
+
+def _is_ignored(path: Path, ignored_patterns: list[str], repo_root: Path) -> bool:
+    rel_path = str(path.relative_to(repo_root))
+    for pattern in ignored_patterns:
+        if fnmatch.fnmatch(rel_path, pattern):
+            return True
+    return False
+
+
+def run(docs_path: Path) -> int:
+    from docsync.core.config import load_config
+
+    config = load_config()
+    has_errors = False
+    for result in check_refs(docs_path, config):
+        if not result.ok:
+            has_errors = True
+            for error in result.errors:
+                print(f"{result.doc_path}:{error.ref.line_number}: {error.message}")
+    if has_errors:
+        return 1
+    print("All refs valid")
+    return 0

docsync/commands/init.py

@@ -0,0 +1,9 @@
+from pathlib import Path
+
+from docsync.core.config import init_docsync
+
+
+def run() -> int:
+    docsync_dir = init_docsync(Path.cwd())
+    print(f"Created {docsync_dir}/")
+    return 0

docsync/commands/sync.py

@@ -0,0 +1,172 @@
+import fnmatch
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from docsync.core.config import Config, find_repo_root
+from docsync.core.constants import DOCSYNC_DIR, SYNC_FILENAME, SYNCS_DIR, load_default_prompt
+from docsync.core.parser import parse_doc
+
+
+def generate_validation_report(docs_path: Path, config: Config, incremental: bool = False) -> dict[str, Any]:
+    docs_path = docs_path.resolve()
+    repo_root = find_repo_root(docs_path)
+    doc_files = list(docs_path.rglob("*.md"))
+    metadata: dict[str, Any] = {"incremental": incremental}
+    if incremental:
+        from docsync.commands.cascade import find_affected_docs
+        from docsync.core.lock import load_lock
+
+        lock = load_lock(repo_root)
+        if lock.last_analyzed_commit:
+            result = find_affected_docs(docs_path, lock.last_analyzed_commit, config, repo_root)
+            affected_set = set(result.affected_docs)
+            doc_files = [f for f in doc_files if f in affected_set]
+            metadata["since_commit"] = lock.last_analyzed_commit
+        else:
+            metadata["since_commit"] = None
+    docs = []
+    for doc_file in doc_files:
+        if _is_ignored(doc_file, config.ignored_paths, repo_root):
+            continue
+        parsed = parse_doc(doc_file)
+        rel_path = str(doc_file.relative_to(repo_root))
+        docs.append(
+            {
+                "path": rel_path,
+                "related_docs": [ref.path for ref in parsed.related_docs],
+                "related_sources": [ref.path for ref in parsed.related_sources],
+            }
+        )
+    return {
+        "repo_root": str(repo_root),
+        "metadata": metadata,
+        "docs": docs,
+    }
+
+
+def _is_ignored(path: Path, ignored_patterns: list[str], repo_root: Path) -> bool:
+    rel_path = str(path.relative_to(repo_root))
+    for pattern in ignored_patterns:
+        if fnmatch.fnmatch(rel_path, pattern):
+            return True
+    return False
+
+
+def print_validation_report(docs_path: Path, config: Config, incremental: bool = False) -> str:
+    report = generate_validation_report(docs_path, config, incremental)
+    return json.dumps(report, indent=2)
+
+
+def _load_prompt_template(repo_root: Path, parallel: bool) -> str:
+    prompt_path = repo_root / DOCSYNC_DIR / SYNC_FILENAME
+    if prompt_path.exists():
+        return prompt_path.read_text()
+    return load_default_prompt(parallel)
+
+
+def _format_docs_list(docs: list[dict[str, Any]]) -> str:
+    lines = []
+    for i, doc in enumerate(docs, 1):
+        lines.append(f"{i}. {doc['path']}")
+        if doc["related_sources"]:
+            sources = ", ".join(doc["related_sources"])
+            lines.append(f"   sources: {sources}")
+        if doc["related_docs"]:
+            related = ", ".join(doc["related_docs"])
+            lines.append(f"   related docs: {related}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _format_phases(levels: list[list[dict[str, Any]]]) -> str:
+    lines = []
+    for i, level_docs in enumerate(levels):
+        if not level_docs:
+            continue
+        if i == 0:
+            lines.append("Phase 1 - Independent (launch parallel):")
+        else:
+            lines.append(f"\nPhase {i + 1} - Level {i} (after phase {i} completes):")
+        for doc in level_docs:
+            lines.append(f"  {doc['path']}")
+            if doc["related_sources"]:
+                sources = ", ".join(doc["related_sources"])
+                lines.append(f"    sources: {sources}")
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _get_syncs_dir() -> str:
+    timestamp = datetime.now().strftime("%Y-%m-%dT%H-%M-%S")
+    return f".docsync/{SYNCS_DIR}/{timestamp}"
+
+
+def _build_sync_levels(docs: list[dict[str, Any]], repo_root: Path) -> list[list[dict[str, Any]]]:
+    doc_paths = {repo_root / d["path"] for d in docs}
+    doc_by_path = {repo_root / d["path"]: d for d in docs}
+    deps: dict[Path, list[Path]] = {}
+    for d in docs:
+        path = repo_root / d["path"]
+        deps[path] = [repo_root / rd for rd in d["related_docs"] if (repo_root / rd) in doc_paths]
+    assigned: dict[Path, int] = {}
+
+    def get_level(doc: Path, visiting: set[Path]) -> int:
+        if doc in assigned:
+            return assigned[doc]
+        if doc in visiting:
+            return 0
+        if not deps.get(doc):
+            assigned[doc] = 0
+            return 0
+        visiting.add(doc)
+        max_dep = max((get_level(dep, visiting) for dep in deps[doc]), default=-1)
+        visiting.remove(doc)
+        level = max_dep + 1
+        assigned[doc] = level
+        return level
+
+    for path in doc_paths:
+        get_level(path, set())
+    max_level = max(assigned.values()) if assigned else 0
+    levels: list[list[dict[str, Any]]] = [[] for _ in range(max_level + 1)]
+    for path, level in assigned.items():
+        levels[level].append(doc_by_path[path])
+    return [level for level in levels if level]
+
+
+def generate_sync_prompt(docs_path: Path, config: Config, incremental: bool = False, parallel: bool = False) -> str:
+    report = generate_validation_report(docs_path, config, incremental)
+    docs = report["docs"]
+    if not docs:
+        return "No docs to sync."
+    repo_root = Path(report["repo_root"])
+    syncs_dir = _get_syncs_dir()
+    template = _load_prompt_template(repo_root, parallel)
+
+    if parallel:
+        docs_list = _format_docs_list(docs)
+        return template.format(count=len(docs), docs_list=docs_list, syncs_dir=syncs_dir)
+    else:
+        levels = _build_sync_levels(docs, repo_root)
+        phases = _format_phases(levels)
+        return template.format(count=len(docs), phases=phases, syncs_dir=syncs_dir)
+
+
+def run(docs_path: Path, incremental: bool, as_json: bool, parallel: bool, update_lock: bool = False) -> int:
+    from docsync.core.config import find_repo_root, load_config
+    from docsync.core.lock import Lock, get_current_commit, save_lock
+
+    config = load_config()
+    if as_json:
+        print(print_validation_report(docs_path, config, incremental))
+    else:
+        print(generate_sync_prompt(docs_path, config, incremental, parallel))
+    if update_lock:
+        repo_root = find_repo_root(docs_path)
+        commit = get_current_commit()
+        if commit:
+            lock = Lock({"last_analyzed_commit": commit})
+            save_lock(lock, repo_root)
+    return 0

docsync/commands/tree.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+from typing import NamedTuple
+
+from docsync.core.config import Config, find_repo_root
+from docsync.core.parser import parse_doc
+
+
+class DependencyTree(NamedTuple):
+    levels: list[list[Path]]
+    circular: list[tuple[Path, Path]]
+    doc_deps: dict[Path, list[Path]]
+
+
+def build_dependency_tree(docs_path: Path, config: Config, repo_root: Path | None = None) -> DependencyTree:
+    if repo_root is None:
+        repo_root = find_repo_root(docs_path)
+    doc_deps = _build_doc_dependencies(docs_path, repo_root)
+    levels, circular = _compute_levels(doc_deps)
+    return DependencyTree(levels=levels, circular=circular, doc_deps=doc_deps)
+
+
+def _build_doc_dependencies(docs_path: Path, repo_root: Path) -> dict[Path, list[Path]]:
+    doc_deps: dict[Path, list[Path]] = defaultdict(list)
+    doc_files = list(docs_path.rglob("*.md"))
+    for doc_file in doc_files:
+        try:
+            parsed = parse_doc(doc_file)
+        except Exception:
+            continue
+        for ref in parsed.related_docs:
+            ref_path = repo_root / ref.path
+            if ref_path.exists():
+                doc_deps[doc_file].append(ref_path)
+        if doc_file not in doc_deps:
+            doc_deps[doc_file] = []
+    return dict(doc_deps)
+
+
+def _compute_levels(doc_deps: dict[Path, list[Path]]) -> tuple[list[list[Path]], list[tuple[Path, Path]]]:
+    all_docs = set(doc_deps.keys())
+    assigned: dict[Path, int] = {}
+    circular: list[tuple[Path, Path]] = []
+
+    def get_level(doc: Path, visiting: set[Path]) -> int:
+        if doc in assigned:
+            return assigned[doc]
+        if doc in visiting:
+            return -1
+        if doc not in doc_deps:
+            assigned[doc] = 0
+            return 0
+        deps = doc_deps[doc]
+        if not deps:
+            assigned[doc] = 0
+            return 0
+        visiting.add(doc)
+        max_dep_level = -1
+        for dep in deps:
+            dep_level = get_level(dep, visiting)
+            if dep_level == -1:
+                circular.append((doc, dep))
+                continue
+            max_dep_level = max(max_dep_level, dep_level)
+        visiting.remove(doc)
+        level = max_dep_level + 1 if max_dep_level >= 0 else 0
+        assigned[doc] = level
+        return level
+
+    for doc in all_docs:
+        get_level(doc, set())
+
+    max_level = max(assigned.values()) if assigned else 0
+    levels: list[list[Path]] = [[] for _ in range(max_level + 1)]
+    for doc, level in assigned.items():
+        levels[level].append(doc)
+
+    for level_docs in levels:
+        level_docs.sort()
+
+    return levels, circular
+
+
+def format_tree(tree: DependencyTree, repo_root: Path) -> str:
+    lines = []
+    for i, level_docs in enumerate(tree.levels):
+        if not level_docs:
+            continue
+        if i == 0:
+            lines.append(f"Level 0 - Independent ({len(level_docs)}):")
+        else:
+            lines.append(f"\nLevel {i} ({len(level_docs)}):")
+        for doc in level_docs:
+            rel_path = doc.relative_to(repo_root)
+            deps = tree.doc_deps.get(doc, [])
+            if deps:
+                dep_names = ", ".join(str(d.relative_to(repo_root)) for d in deps)
+                lines.append(f"  {rel_path}")
+                lines.append(f"    └── depends on: {dep_names}")
+            else:
+                lines.append(f"  {rel_path}")
+    if tree.circular:
+        lines.append("\nCircular dependencies (warning):")
+        for src, dst in tree.circular:
+            src_rel = src.relative_to(repo_root)
+            dst_rel = dst.relative_to(repo_root)
+            lines.append(f"  {src_rel} <-> {dst_rel}")
+    return "\n".join(lines)
+
+
+def run(docs_path: Path) -> int:
+    from docsync.core.config import load_config
+
+    config = load_config()
+    docs_path = docs_path.resolve()
+    repo_root = find_repo_root(docs_path)
+    tree = build_dependency_tree(docs_path, config, repo_root)
+    print(format_tree(tree, repo_root))
+    return 0

docsync/core/config.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from docsync.core.constants import CONFIG_FILENAME, DEFAULT_CONFIG, DOCSYNC_DIR, SYNCS_DIR
+
+
+class ConfigError(Exception):
+    pass
+
+
+class Config:
+    def __init__(self, data: dict[str, Any]):
+        self.ignored_paths: list[str] = data.get("ignored_paths", DEFAULT_CONFIG["ignored_paths"])
+        self.cascade_depth_limit: int | None = data.get("cascade_depth_limit", DEFAULT_CONFIG["cascade_depth_limit"])
+
+
+def validate_config(data: dict[str, Any], config_path: Path | None = None) -> list[str]:
+    errors = []
+    valid_keys = {"ignored_paths", "cascade_depth_limit"}
+    for key in data:
+        if key not in valid_keys:
+            errors.append(f"unknown key: {key}")
+    if "ignored_paths" in data:
+        if not isinstance(data["ignored_paths"], list):
+            errors.append("ignored_paths must be a list")
+        elif not all(isinstance(p, str) for p in data["ignored_paths"]):
+            errors.append("ignored_paths must contain only strings")
+    if "cascade_depth_limit" in data:
+        val = data["cascade_depth_limit"]
+        if val is not None and not isinstance(val, int):
+            errors.append("cascade_depth_limit must be null or integer")
+    return errors
+
+
+def load_config(start_path: Path | None = None, validate: bool = True) -> Config:
+    config_path = find_config(start_path or Path.cwd())
+    if config_path is None:
+        return Config({})
+    with open(config_path) as f:
+        data = json.load(f)
+    if validate:
+        errors = validate_config(data, config_path)
+        if errors:
+            raise ConfigError(f"{config_path}: {', '.join(errors)}")
+    return Config(data)
+
+
+def find_config(start_path: Path) -> Path | None:
+    current = start_path.resolve()
+    while current != current.parent:
+        config_path = current / DOCSYNC_DIR / CONFIG_FILENAME
+        if config_path.exists():
+            return config_path
+        current = current.parent
+    return None
+
+
+def find_docsync_dir(start_path: Path) -> Path | None:
+    current = start_path.resolve()
+    while current != current.parent:
+        docsync_dir = current / DOCSYNC_DIR
+        if docsync_dir.exists():
+            return docsync_dir
+        current = current.parent
+    return None
+
+
+def find_repo_root(start_path: Path) -> Path:
+    current = start_path.resolve()
+    while current != current.parent:
+        if (current / ".git").exists():
+            return current
+        current = current.parent
+    return start_path.resolve()
+
+
+def init_docsync(target_dir: Path) -> Path:
+    docsync_dir = target_dir / DOCSYNC_DIR
+    docsync_dir.mkdir(exist_ok=True)
+    config_path = docsync_dir / CONFIG_FILENAME
+    with open(config_path, "w") as f:
+        json.dump(DEFAULT_CONFIG, f, indent=2)
+    syncs_dir = docsync_dir / SYNCS_DIR
+    syncs_dir.mkdir(exist_ok=True)
+    gitignore_path = syncs_dir / ".gitignore"
+    with open(gitignore_path, "w") as f:
+        f.write("*\n!.gitignore\n")
+    return docsync_dir

docsync/core/constants.py

@@ -0,0 +1,26 @@
+import re
+from pathlib import Path
+
+RELATED_DOCS_PATTERN = re.compile(r"^related docs:\s*$", re.MULTILINE | re.IGNORECASE)
+RELATED_SOURCES_PATTERN = re.compile(r"^related sources:\s*$", re.MULTILINE | re.IGNORECASE)
+LIST_ITEM_PATTERN = re.compile(r"^-\s+(\S+)\s+-\s+(.+)$")
+
+DOCSYNC_DIR = ".docsync"
+CONFIG_FILENAME = "config.json"
+LOCK_FILENAME = "lock.json"
+SYNC_FILENAME = "sync.md"
+SYNCS_DIR = "syncs"
+
+PROMPTS_DIR = Path(__file__).parent.parent / "prompts"
+
+DEFAULT_CONFIG = {
+    "ignored_paths": [],
+    "cascade_depth_limit": None,
+}
+
+DEFAULT_LOCK = {"last_analyzed_commit": None, "last_run": None, "docs_validated": []}
+
+
+def load_default_prompt(parallel: bool = False) -> str:
+    filename = "sync-parallel.md" if parallel else "sync.md"
+    return (PROMPTS_DIR / filename).read_text()

docsync/core/lock.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from docsync.core.constants import DOCSYNC_DIR, LOCK_FILENAME
+
+
+class Lock:
+    def __init__(self, data: dict[str, Any]):
+        self.last_analyzed_commit: str | None = data.get("last_analyzed_commit")
+        self.last_run: str | None = data.get("last_run")
+        self.docs_validated: list[str] = data.get("docs_validated", [])
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "last_analyzed_commit": self.last_analyzed_commit,
+            "last_run": self.last_run,
+            "docs_validated": self.docs_validated,
+        }
+
+
+def load_lock(start_path: Path | None = None) -> Lock:
+    lock_path = find_lock(start_path or Path.cwd())
+    if lock_path is None:
+        return Lock({})
+    with open(lock_path) as f:
+        data = json.load(f)
+    return Lock(data)
+
+
+def find_lock(start_path: Path) -> Path | None:
+    current = start_path.resolve()
+    while current != current.parent:
+        lock_path = current / DOCSYNC_DIR / LOCK_FILENAME
+        if lock_path.exists():
+            return lock_path
+        current = current.parent
+    return None
+
+
+def save_lock(lock: Lock, repo_root: Path) -> Path:
+    docsync_dir = repo_root / DOCSYNC_DIR
+    docsync_dir.mkdir(exist_ok=True)
+    lock_path = docsync_dir / LOCK_FILENAME
+    lock.last_run = datetime.now(timezone.utc).isoformat()
+    with open(lock_path, "w") as f:
+        json.dump(lock.to_dict(), f, indent=2)
+    return lock_path
+
+
+def get_current_commit() -> str | None:
+    try:
+        result = subprocess.run(["git", "rev-parse", "HEAD"], capture_output=True, text=True, check=True)
+        return result.stdout.strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return None

docsync/core/parser.py

@@ -0,0 +1,47 @@
+import re
+from pathlib import Path
+from typing import NamedTuple
+
+RELATED_DOCS_HEADER = re.compile(r"^related docs:\s*$", re.MULTILINE | re.IGNORECASE)
+RELATED_SOURCES_HEADER = re.compile(r"^related sources:\s*$", re.MULTILINE | re.IGNORECASE)
+LIST_ITEM = re.compile(r"^-\s+(\S+(?:\s+\S+)*?)\s+-\s+(.+)$")
+
+
+class RefEntry(NamedTuple):
+    path: str
+    description: str
+    line_number: int
+
+
+class ParsedDoc(NamedTuple):
+    related_docs: list[RefEntry]
+    related_sources: list[RefEntry]
+
+
+def parse_doc(filepath: Path) -> ParsedDoc:
+    content = filepath.read_text()
+    lines = content.splitlines()
+    related_docs = _extract_section(lines, RELATED_DOCS_HEADER)
+    related_sources = _extract_section(lines, RELATED_SOURCES_HEADER)
+    return ParsedDoc(related_docs=related_docs, related_sources=related_sources)
+
+
+def _extract_section(lines: list[str], header_pattern: re.Pattern) -> list[RefEntry]:
+    entries = []
+    in_section = False
+    for i, line in enumerate(lines, start=1):
+        if header_pattern.match(line):
+            in_section = True
+            continue
+        if in_section:
+            if not line.strip():
+                continue
+            if line.startswith("-"):
+                match = LIST_ITEM.match(line)
+                if match:
+                    entries.append(
+                        RefEntry(path=match.group(1).strip(), description=match.group(2).strip(), line_number=i)
+                    )
+            else:
+                break
+    return entries

docsync/prompts/sync-parallel.md

@@ -0,0 +1,21 @@
+Sync {count} docs by launching PARALLEL agents (one per doc).
+
+Each agent will:
+1. Read the doc + all related sources
+2. Fix any outdated/incorrect content directly in the doc
+3. Write a report to {syncs_dir}
+
+Report format ({syncs_dir}/{{doc-name}}.md):
+```markdown
+## Changes made
+- what was fixed
+
+## Why it was wrong
+- explanation referencing the source code
+```
+
+IMPORTANT: Launch ALL agents in a SINGLE message for parallel execution.
+
+Docs to sync:
+
+{docs_list}

docsync/prompts/sync.md

@@ -0,0 +1,17 @@
+Sync {count} docs by launching agents in phases (respecting dependencies).
+
+Each agent will:
+1. Read the doc + all related sources
+2. Fix any outdated/incorrect content directly in the doc
+3. Write a report to {syncs_dir}
+
+Report format ({syncs_dir}/{{doc-name}}.md):
+```markdown
+## Changes made
+- what was fixed
+
+## Why it was wrong
+- explanation referencing the source code
+```
+
+{phases}

docsync-0.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: docsync
+Version: 0.1.0
+Summary: Auto-validate and update docs in large codebases
+License-File: LICENSE
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: bump2version>=1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: towncrier>=23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Overview
+
+CLI tool that keeps documentation in sync with code in large codebases. Detects which docs are affected by code changes and generates reports for AI validation.
+
+```
+  src/booking/handler.ts changed
+            │
+            v
+  ┌─────────────────────────┐
+  │ docsync cascade HEAD~1  │
+  └───────────┬─────────────┘
+              │
+              v
+  ┌─────────────────────────┐      ┌─────────────────────────┐
+  │ Direct hits:            │      │ docs/bookings.md        │
+  │  - docs/bookings.md     │ ──>  │                         │
+  └─────────────────────────┘      │ related sources:        │
+              │                    │  - src/booking/  <───── │ ← matched!
+              v                    └─────────────────────────┘
+  ┌─────────────────────────┐
+  │ Cascade hits:           │      docs/bookings.md references
+  │  - docs/payments.md     │ ──>  docs/payments.md, so it
+  └─────────────────────────┘      might need review too
+```
+
+<details>
+<summary>How it works</summary>
+
+Each doc ends with metadata sections:
+
+```markdown
+# Booking System
+
+How bookings work...
+
+---
+
+related docs:
+- docs/payments.md - payment integration
+
+related sources:
+- src/booking/           - booking module
+- src/booking/commands/  - command handlers
+```
+
+When `src/booking/handler.ts` changes:
+
+```
+docsync cascade HEAD~1
+
+Direct hits (1):
+  docs/bookings.md       <- references src/booking/
+
+Cascade hits (1):
+  docs/payments.md       <- referenced BY docs/bookings.md
+```
+
+The cascade propagates: if `bookings.md` might be outdated, then `payments.md` (which references it) might also need review.
+
+</details>
+
+## Motivation
+
+In large codebases, docs get outdated because:
+1. No one remembers which docs need updating when a file changes
+2. AI agents don't know which files to read to validate each doc
+
+docsync solves this by adding "hints" to each doc - `related sources:` tells any AI exactly what to read.
+
+## Features
+
+- check   - validates all referenced paths exist
+- cascade - finds docs affected by code changes (with directory matching)
+- sync    - generates prompt for AI to fix docs (ordered by deps)
+- tree    - shows doc dependency tree
+
+## Quickstart
+
+### 1. Install
+
+```bash
+pipx install docsync
+```
+
+### 2. Add metadata to your docs
+
+Each doc needs two sections at the end (after a `---` separator):
+
+```markdown
+# My Feature
+
+Documentation content here...
+
+---
+
+related docs:
+- docs/other-feature.md - brief description
+
+related sources:
+- src/feature/           - main module
+- src/feature/utils.ts   - helper functions
+```
+
+### 3. Initialize config (optional)
+
+```bash
+docsync init    # creates .docsync/ folder
+```
+
+<details>
+<summary>Config options</summary>
+
+```
+.docsync/
+├── config.json   # required
+├── sync.md       # optional - custom prompt template
+├── lock.json     # optional - tracks last synced commit
+└── syncs/        # ignored - AI writes sync reports here
+```
+
+config.json:
+```json
+{
+  "ignored_paths": ["**/migrations/**", "**/*.test.ts"],
+  "cascade_depth_limit": null
+}
+```
+
+sync.md (custom template):
+```markdown
+Sync {count} docs. Write reports to {syncs_dir}/
+
+{phases}
+```
+
+Placeholders: `{count}`, `{phases}`, `{docs_list}`, `{syncs_dir}`
+
+</details>
+
+### 4. Validate your setup
+
+```bash
+docsync check docs/    # ensures all paths exist
+```
+
+### 5. Use it
+
+```bash
+docsync cascade HEAD~5 --docs docs/    # docs affected by last 5 commits
+docsync sync docs/ | pbcopy            # generate AI prompt
+claude "$(docsync sync docs/)"         # or pipe directly to AI
+```
+
+## Commands
+
+```bash
+docsync check <path>                   # validate refs exist
+docsync cascade <commit> --docs <dir>  # list affected docs
+docsync sync <path>                    # generate prompt (ordered by deps)
+docsync sync <path> --parallel         # ignore deps, all at once
+docsync sync <path> --incremental      # only include changed docs
+docsync sync <path> --update-lock      # update lock.json after sync
+docsync sync <path> --json             # output as JSON for scripts
+docsync tree <path>                    # show doc dependency tree
+docsync init                           # create .docsync/ folder
+docsync --version                      # show version
+```
+
+### AI Sync
+
+The `sync` command generates a prompt for AI to fix docs in phases (respecting dependencies):
+
+```
+Sync 5 docs by launching agents in phases (respecting dependencies).
+
+Each agent will:
+1. Read the doc + all related sources
+2. Fix any outdated/incorrect content directly in the doc
+3. Write a report to .docsync/syncs/2024-01-15T10-30-00/
+
+Phase 1 - Independent (launch parallel):
+  docs/utils.md
+  docs/config.md
+
+Phase 2 - Level 1 (after phase 1 completes):
+  docs/auth.md
+    sources: src/auth/
+
+Phase 3 - Level 2 (after phase 2 completes):
+  docs/login.md
+    sources: src/login/
+```
+
+Use `--parallel` to ignore dependencies and sync all at once.
+
+## Development
+
+```bash
+make install        # create venv + install
+make check          # lint
+make test           # run tests
+docsync check docs/ # practical test
+```

docsync-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+docsync/__init__.py,sha256=ukKr35GuAF_rKmKQJNTKfsz9HEmZ87kt0Qz8RL-hYGE,205
+docsync/cli.py,sha256=l4g5VUtgiF9kyq6XNNe6mhKwI3NlS01X-5gq4kkbgkk,2184
+docsync/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docsync/commands/cascade.py,sha256=vjM84402_KD1_ljR6qmLRgDbmihYI-46zhudgxDiHks,4403
+docsync/commands/check.py,sha256=DYOKMhB6lzO3YpzMCw69ulYRKCMLoH0nhhAdMtAyWd0,2819
+docsync/commands/init.py,sha256=9zLQVgiYjd7X-cXZ0jQ3023_HOic0EST8xTuMxZ9THk,184
+docsync/commands/sync.py,sha256=WnChiBqoQxp2dGsIMx7Gb-xtI1fB2yO4UyHN90tnjkc,6365
+docsync/commands/tree.py,sha256=IqiFbGzZrQyys5wPlU9T35s_94qfMOQTdx8lYha303E,4041
+docsync/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docsync/core/config.py,sha256=GBMP41Aum4gS0LH4p8VLIrGq6HfdaM92oLuF-sAHY8U,3046
+docsync/core/constants.py,sha256=nXS35iNPIxW3vnFOJu6fWiGcNRiz-1v919I9n_wzKtM,796
+docsync/core/lock.py,sha256=4Fzs_8nfcIVyCZ3hSmNdjVxkfJ2hXz48eOfLTBr0MRQ,1855
+docsync/core/parser.py,sha256=rmnlZfhuWjVGa_XCZvHwAnNCANr6vx--xr1tS6O_fW8,1505
+docsync/prompts/sync-parallel.md,sha256=6LJ8BrvzJwEmvkDiyt3sAQtlRJrmDmR93hi8DYIqLko,469
+docsync/prompts/sync.md,sha256=nBaAPwNK9LU8c3EXSkfCL1hIDvJZ5ijfxZwB9DDOEa0,390
+docsync-0.1.0.dist-info/METADATA,sha256=wPOvVF-wPhMRR_7fH7PEC2UfonsDXxUOP_EMvjx-EGk,5944
+docsync-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+docsync-0.1.0.dist-info/entry_points.txt,sha256=Mk67DbEgbGkQmp5NRqOgivotQv1R3RcaD4ncUlZXabk,45
+docsync-0.1.0.dist-info/licenses/LICENSE,sha256=njaGk8b8NcBMEtm31x6Vt9w5HYU3kMPZNHN2DidK2TU,1069
+docsync-0.1.0.dist-info/RECORD,,

docsync-0.1.0.dist-info/WHEEL

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

docsync-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docsync = docsync.cli:main

docsync-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lucas Vieira
+
+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.