codegraph-engine 2.2.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

codegraph/change_impact.py

@@ -0,0 +1,337 @@
+"""Deep Change Impact Analysis Engine.
+
+Extends existing Git impact analysis by tracing complete downstream chains:
+    changed symbol
+        ↓
+    callers (direct & transitive)
+        ↓
+    callees
+        ↓
+    routes & endpoints
+        ↓
+    tests & test suites
+        ↓
+    DB readers & writers
+        ↓
+    downstream package dependencies
+
+Every item carries explicit evidence, relationship type, source location,
+and confidence/epistemic state (FACT, POSSIBLE, UNKNOWN).
+"""
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from codegraph.graph.traversal import find_callees, find_callers, find_related_tests
+from codegraph.monorepo import detect_workspace
+from codegraph.structural_diff import compare_revisions
+
+
+@dataclass
+class ImpactedEntity:
+    name: str
+    kind: str  # "CALLER" | "CALLEE" | "ROUTE" | "TEST" | "DB_WRITER" | "DB_READER" | "PACKAGE"
+    file: str
+    line: int | None
+    relationship: str  # "CALLS" | "HANDLED_BY" | "TESTS" | "WRITES_TABLE" | "READS_TABLE" | "DEPENDS_ON"
+    depth: int
+    confidence: str  # "FACT" | "POSSIBLE" | "UNKNOWN"
+    reason: str
+    evidence: str
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "file": self.file,
+            "line": self.line,
+            "relationship": self.relationship,
+            "depth": self.depth,
+            "confidence": self.confidence,
+            "reason": self.reason,
+            "evidence": self.evidence,
+        }
+
+
+@dataclass
+class DeepImpactReport:
+    base_ref: str
+    head_ref: str
+    changed_files: list[str] = field(default_factory=list)
+    changed_symbols: list[dict[str, Any]] = field(default_factory=list)
+    direct_callers: list[ImpactedEntity] = field(default_factory=list)
+    transitive_callers: list[ImpactedEntity] = field(default_factory=list)
+    affected_callees: list[ImpactedEntity] = field(default_factory=list)
+    affected_routes: list[ImpactedEntity] = field(default_factory=list)
+    affected_tests: list[ImpactedEntity] = field(default_factory=list)
+    db_readers: list[ImpactedEntity] = field(default_factory=list)
+    db_writers: list[ImpactedEntity] = field(default_factory=list)
+    affected_packages: list[str] = field(default_factory=list)
+    total_impacted_count: int = 0
+    blast_radius_score: float = 0.0  # 0.0 - 100.0 scale
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "base_ref": self.base_ref,
+            "head_ref": self.head_ref,
+            "changed_files": self.changed_files,
+            "changed_symbols": self.changed_symbols,
+            "direct_callers": [c.as_dict() for c in self.direct_callers],
+            "transitive_callers": [c.as_dict() for c in self.transitive_callers],
+            "affected_callees": [c.as_dict() for c in self.affected_callees],
+            "affected_routes": [r.as_dict() for r in self.affected_routes],
+            "affected_tests": [t.as_dict() for t in self.affected_tests],
+            "db_readers": [d.as_dict() for d in self.db_readers],
+            "db_writers": [d.as_dict() for d in self.db_writers],
+            "affected_packages": self.affected_packages,
+            "total_impacted_count": self.total_impacted_count,
+            "blast_radius_score": self.blast_radius_score,
+        }
+
+
+def get_deep_change_impact(
+    repository: Path,
+    con: sqlite3.Connection,
+    base: str = "HEAD~1",
+    head: str = "HEAD",
+    max_depth: int = 2,
+    max_results: int = 50,
+) -> DeepImpactReport:
+    """Analyze full blast radius of git revision changes across AST, routes, tests, DB, and packages."""
+    # Fast path: identical refs have zero changes
+    if base == head and head != "WORKING_TREE":
+        return DeepImpactReport(base_ref=base, head_ref=head)
+
+    diff_report = compare_revisions(repository, base=base, head=head, con=con)
+
+    changed_symbols_list: list[dict[str, Any]] = [
+        s.as_dict() for s in (diff_report.changed_symbols + diff_report.added_symbols + diff_report.removed_symbols)
+    ]
+    changed_files = diff_report.modified_files + diff_report.added_files + diff_report.deleted_files
+
+    if not changed_symbols_list and not changed_files:
+        return DeepImpactReport(base_ref=base, head_ref=head)
+
+    direct_callers: list[ImpactedEntity] = []
+    transitive_callers: list[ImpactedEntity] = []
+    affected_callees: list[ImpactedEntity] = []
+    affected_routes: list[ImpactedEntity] = []
+    affected_tests: list[ImpactedEntity] = []
+    db_readers: list[ImpactedEntity] = []
+    db_writers: list[ImpactedEntity] = []
+
+    seen_keys: set[str] = set()
+    processed_symbols: set[str] = set()
+    processed_transitive: set[str] = set()
+
+    for s_info in changed_symbols_list[:max_results]:
+        s_name = s_info["name"]
+        s_path = s_info["path"]
+
+        if not s_name or s_name in processed_symbols:
+            continue
+        processed_symbols.add(s_name)
+
+        # 1. Direct callers (1-hop)
+        raw_callers = find_callers(con, s_name, max_results=max_results)
+        for c in raw_callers:
+            c_name = c.get("caller") or c.get("symbol") or ""
+            c_file = c.get("file") or ""
+            c_line = c.get("line")
+            c_key = f"CALLER:1:{c_file}:{c_name}"
+            if c_key not in seen_keys:
+                seen_keys.add(c_key)
+                direct_callers.append(
+                    ImpactedEntity(
+                        name=c_name,
+                        kind="CALLER",
+                        file=c_file,
+                        line=c_line,
+                        relationship="CALLS",
+                        depth=1,
+                        confidence="FACT",
+                        reason=f"Invokes modified symbol {s_name}",
+                        evidence=f"{c_file}:{c_line} -> {s_name}",
+                    )
+                )
+
+                # 2. Transitive callers (2-hop) if max_depth >= 2
+                if max_depth >= 2 and c_name and c_name not in processed_transitive:
+                    processed_transitive.add(c_name)
+                    raw_trans = find_callers(con, c_name, max_results=10)
+                    for tc in raw_trans:
+                        tc_name = tc.get("caller") or tc.get("symbol") or ""
+                        tc_file = tc.get("file") or ""
+                        tc_line = tc.get("line")
+                        tc_key = f"CALLER:2:{tc_file}:{tc_name}"
+                        if tc_key not in seen_keys and tc_name != s_name:
+                            seen_keys.add(tc_key)
+                            transitive_callers.append(
+                                ImpactedEntity(
+                                    name=tc_name,
+                                    kind="CALLER",
+                                    file=tc_file,
+                                    line=tc_line,
+                                    relationship="CALLS",
+                                    depth=2,
+                                    confidence="FACT",
+                                    reason=f"Transitively invokes {s_name} via {c_name}",
+                                    evidence=f"{tc_file}:{tc_line} -> {c_name} -> {s_name}",
+                                )
+                            )
+
+        # 3. Direct callees
+        raw_callees = find_callees(con, s_name, max_results=max_results)
+        for ce in raw_callees:
+            ce_name = ce.get("callee") or ce.get("symbol") or ""
+            ce_file = ce.get("file") or ""
+            ce_line = ce.get("line")
+            ce_key = f"CALLEE:{ce_file}:{ce_name}"
+            if ce_key not in seen_keys:
+                seen_keys.add(ce_key)
+                affected_callees.append(
+                    ImpactedEntity(
+                        name=ce_name,
+                        kind="CALLEE",
+                        file=ce_file,
+                        line=ce_line,
+                        relationship="CALLED_BY",
+                        depth=1,
+                        confidence="FACT",
+                        reason=f"Called by modified symbol {s_name}",
+                        evidence=f"{s_path} -> {ce_name}",
+                    )
+                )
+
+        # 4. Route impact: does this symbol handle an endpoint or get called by a route?
+        try:
+            route_rows = con.execute(
+                "SELECT path, method, handler_name, file FROM routes WHERE handler_name=? OR symbol=?",
+                (s_name, s_name),
+            ).fetchall()
+            for rr in route_rows:
+                r_key = f"ROUTE:{rr[0]}:{rr[1]}"
+                if r_key not in seen_keys:
+                    seen_keys.add(r_key)
+                    affected_routes.append(
+                        ImpactedEntity(
+                            name=f"{rr[1]} {rr[0]}",
+                            kind="ROUTE",
+                            file=rr[3],
+                            line=None,
+                            relationship="ROUTES_TO",
+                            depth=1,
+                            confidence="FACT",
+                            reason=f"Endpoint handled by changed symbol {s_name}",
+                            evidence=f"Route {rr[1]} {rr[0]} -> {s_name}",
+                        )
+                    )
+        except (sqlite3.OperationalError, sqlite3.DatabaseError):
+            pass
+
+        # 5. Tests targeting this symbol
+        tests = find_related_tests(con, s_name, max_results=20)
+        for t in tests:
+            t_name = str(t.get("symbol") or t.get("test") or "")
+            t_file = str(t.get("file") or "")
+            t_line_raw = t.get("line")
+            t_line = int(t_line_raw) if isinstance(t_line_raw, (int, str)) and str(t_line_raw).isdigit() else None
+            t_key = f"TEST:{t_file}:{t_name}"
+            if t_key not in seen_keys:
+                seen_keys.add(t_key)
+                affected_tests.append(
+                    ImpactedEntity(
+                        name=t_name,
+                        kind="TEST",
+                        file=t_file,
+                        line=t_line,
+                        relationship="TESTS",
+                        depth=1,
+                        confidence="FACT",
+                        reason=f"Test targets modified symbol {s_name}",
+                        evidence=f"{t_file}:{t_line} tests {s_name}",
+                    )
+                )
+
+        # 6. Database readers and writers
+        try:
+            db_rows = con.execute(
+                "SELECT table_name, operation, file, line FROM database_queries WHERE symbol=? OR caller_symbol=?",
+                (s_name, s_name),
+            ).fetchall()
+            for dr in db_rows:
+                tbl, op, f_path, l_num = dr[0], dr[1], dr[2], dr[3]
+                is_mutating = op.upper() in ("INSERT", "UPDATE", "DELETE", "DROP", "ALTER")
+                kind = "DB_WRITER" if is_mutating else "DB_READER"
+                rel = "WRITES_TABLE" if is_mutating else "READS_TABLE"
+                db_key = f"{kind}:{tbl}:{op}:{s_name}"
+                if db_key not in seen_keys:
+                    seen_keys.add(db_key)
+                    entity = ImpactedEntity(
+                        name=f"{op} {tbl}",
+                        kind=kind,
+                        file=f_path or s_path,
+                        line=l_num,
+                        relationship=rel,
+                        depth=1,
+                        confidence="FACT",
+                        reason=f"{s_name} executes {op} on {tbl}",
+                        evidence=f"{s_name} -> {op} {tbl} ({f_path}:{l_num})",
+                    )
+                    if is_mutating:
+                        db_writers.append(entity)
+                    else:
+                        db_readers.append(entity)
+        except (sqlite3.OperationalError, sqlite3.DatabaseError):
+            pass
+
+    # 7. Monorepo package impact
+    ws = detect_workspace(repository, con=con)
+    affected_packages: set[str] = set()
+    for p in changed_files:
+        pkg = ws.get_package_for_file(p)
+        if pkg:
+            affected_packages.add(pkg.package_id)
+            for dep in ws.get_dependent_packages(pkg.package_id):
+                affected_packages.add(dep.package_id)
+
+    total_count = (
+        len(direct_callers)
+        + len(transitive_callers)
+        + len(affected_callees)
+        + len(affected_routes)
+        + len(affected_tests)
+        + len(db_readers)
+        + len(db_writers)
+    )
+
+    # Blast radius score calculation: 0 - 100
+    # Factors: number of direct callers, routes impacted, db writers impacted, package boundaries crossed
+    score = min(
+        100.0,
+        (len(direct_callers) * 3.5)
+        + (len(transitive_callers) * 1.5)
+        + (len(affected_routes) * 8.0)
+        + (len(db_writers) * 6.0)
+        + (len(affected_packages) * 5.0),
+    )
+
+    return DeepImpactReport(
+        base_ref=base,
+        head_ref=head,
+        changed_files=changed_files,
+        changed_symbols=changed_symbols_list,
+        direct_callers=direct_callers[:max_results],
+        transitive_callers=transitive_callers[:max_results],
+        affected_callees=affected_callees[:max_results],
+        affected_routes=affected_routes,
+        affected_tests=affected_tests[:max_results],
+        db_readers=db_readers,
+        db_writers=db_writers,
+        affected_packages=sorted(affected_packages),
+        total_impacted_count=total_count,
+        blast_radius_score=round(score, 1),
+    )

codegraph/cli.py

@@ -1313,5 +1313,243 @@ def uninit(
         cli_echo(report.format_human())
 
 
+@app.command("git-state")
+def git_state_cmd(
+    path: Annotated[Path | None, typer.Argument(help="Repository path (default: current directory)")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    sync: Annotated[bool, typer.Option("--sync", help="Incrementally synchronize affected graph state if dirty/stale")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON format")] = False,
+) -> None:
+    """Track current Git branch, HEAD, indexed commit, working-tree modifications, and freshness states (CLEAN, DIRTY, STALE, REINDEXING, ERROR)."""
+    from codegraph.git_state import get_git_state, incremental_git_sync
+
+    repo = _resolve_repo(path, repository)
+    indexer = _indexer(repo)
+
+    if sync:
+        with indexer.session() as con:
+            res = incremental_git_sync(repo, con=con)
+            if json_output:
+                cli_echo(json.dumps(res.as_dict(), indent=2), json_mode=True)
+            else:
+                cli_echo(f"Incremental Sync: {res.status.upper()} ({res.duration_ms:.1f}ms) - {res.detail}")
+            return
+
+    with indexer.session() as con:
+        rep = get_git_state(repo, con=con)
+
+    if json_output:
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(f"Git Repository: {repo}")
+        cli_echo(f"Branch:         {rep.branch or 'N/A'}")
+        cli_echo(f"Current HEAD:   {rep.current_head[:8] if rep.current_head else 'N/A'}")
+        cli_echo(f"Indexed HEAD:   {rep.indexed_head[:8] if rep.indexed_head else 'Not indexed'}")
+        cli_echo(f"Freshness:      {rep.freshness.value}")
+        cli_echo(f"Status Detail:  {rep.detail}")
+        if rep.working_tree.is_dirty:
+            cli_echo("\nWorking Tree Changes:")
+            if rep.working_tree.modified_files:
+                cli_echo(f"  Modified:   {len(rep.working_tree.modified_files)} files ({', '.join(rep.working_tree.modified_files[:3])}...)")
+            if rep.working_tree.staged_files:
+                cli_echo(f"  Staged:     {len(rep.working_tree.staged_files)} files ({', '.join(rep.working_tree.staged_files[:3])}...)")
+            if rep.working_tree.untracked_files:
+                cli_echo(f"  Untracked:  {len(rep.working_tree.untracked_files)} files ({', '.join(rep.working_tree.untracked_files[:3])}...)")
+            if rep.working_tree.deleted_files:
+                cli_echo(f"  Deleted:    {len(rep.working_tree.deleted_files)} files")
+
+
+@app.command("git-diff")
+def git_diff_cmd(
+    base: Annotated[str, typer.Argument(help="Base Git ref or commit (default: HEAD~1)")] = "HEAD~1",
+    head: Annotated[str, typer.Argument(help="Head Git ref, commit, or branch (default: HEAD)")] = "HEAD",
+    path: Annotated[Path | None, typer.Option("--path", "-p", help="Repository path")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    branch_comparison: Annotated[bool, typer.Option("--branch", "-b", help="Perform hierarchical branch architecture comparison")] = False,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON format")] = False,
+) -> None:
+    """Compute structural AST-level difference between Git revisions, commits, or branches."""
+    repo = _resolve_repo(path, repository)
+    indexer = _indexer(repo)
+
+    if branch_comparison:
+        from codegraph.branch_comparison import compare_branch_architecture
+        with indexer.session() as con:
+            b_rep = compare_branch_architecture(repo, base_branch=base, head_branch=head, con=con)
+        if json_output:
+            cli_echo(json.dumps(b_rep.as_dict(), indent=2), json_mode=True)
+        else:
+            cli_echo(f"Branch Architecture Comparison: {base} -> {head}")
+            cli_echo(f"Packages: {b_rep.total_packages} | Symbols: {b_rep.total_symbols} (~{b_rep.estimated_tokens} tokens)")
+            for pkg in b_rep.packages:
+                cli_echo(f"\nPackage: {pkg.package_id}")
+                for mod in pkg.modules:
+                    cli_echo(f"  Module: {mod.module} ({mod.file_path})")
+                    for s in mod.symbols:
+                        cli_echo(f"    [{s.change_type}] {s.kind} {s.name}")
+                        for rel in s.relationships:
+                            cli_echo(f"      -> {rel}")
+        return
+
+    from codegraph.structural_diff import compare_revisions
+    with indexer.session() as con:
+        s_rep = compare_revisions(repo, base=base, head=head, con=con)
+
+    if json_output:
+        cli_echo(json.dumps(s_rep.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(f"Structural Diff: {base} -> {head}")
+        cli_echo(f"Files Changed:   {s_rep.total_file_changes} (Added: {len(s_rep.added_files)}, Modified: {len(s_rep.modified_files)}, Deleted: {len(s_rep.deleted_files)}, Renamed: {len(s_rep.renamed_files)})")
+        cli_echo(f"Symbols Changed: {s_rep.total_symbol_changes} (Added: {len(s_rep.added_symbols)}, Modified: {len(s_rep.changed_symbols)}, Removed: {len(s_rep.removed_symbols)})")
+        if s_rep.changed_routes:
+            cli_echo(f"Changed Routes:  {len(s_rep.changed_routes)}")
+            for r in s_rep.changed_routes:
+                cli_echo(f"  [{r.change_type}] {r.method} {r.path} -> {r.handler}")
+        if s_rep.affected_tests:
+            cli_echo(f"Affected Tests:  {len(s_rep.affected_tests)} ({', '.join(s_rep.affected_tests[:5])})")
+
+
+@app.command("git-impact")
+def git_impact_cmd(
+    base: Annotated[str, typer.Argument(help="Base Git ref (default: HEAD~1)")] = "HEAD~1",
+    head: Annotated[str, typer.Argument(help="Head Git ref (default: HEAD)")] = "HEAD",
+    depth: Annotated[int, typer.Option("--depth", "-d", help="Max caller traversal depth")] = 2,
+    max_results: Annotated[int, typer.Option("--max-results", "-m", help="Max items per category")] = 30,
+    tree: Annotated[bool, typer.Option("--tree", "-t", help="Display visual impact tree")] = False,
+    path: Annotated[Path | None, typer.Option("--path", "-p", help="Repository path")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON format")] = False,
+) -> None:
+    """Compute deep downstream change impact across callers, callees, framework routes, tests, and DB."""
+    from codegraph.change_impact import get_deep_change_impact
+
+    repo = _resolve_repo(path, repository)
+    indexer = _indexer(repo)
+
+    with indexer.session() as con:
+        imp = get_deep_change_impact(repo, con, base=base, head=head, max_depth=depth, max_results=max_results)
+
+    if json_output:
+        cli_echo(json.dumps(imp.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(f"Deep Change Impact Analysis: {base} -> {head}")
+        cli_echo(f"Blast Radius Score:   {imp.blast_radius_score} / 100")
+        cli_echo(f"Total Impacted Items: {imp.total_impacted_count}")
+        cli_echo(f"Direct Callers:       {len(imp.direct_callers)}")
+        cli_echo(f"Transitive Callers:   {len(imp.transitive_callers)}")
+        cli_echo(f"Affected Routes:      {len(imp.affected_routes)}")
+        cli_echo(f"Covering Tests:       {len(imp.affected_tests)}")
+        cli_echo(f"DB Writers:           {len(imp.db_writers)}")
+        cli_echo(f"Monorepo Packages:    {len(imp.affected_packages)}")
+
+        if tree or imp.total_impacted_count > 0:
+            cli_echo("\nImpact Tree:")
+            for s in imp.changed_symbols[:10]:
+                cli_echo(f"  └── 📄 [{s.get('change_type', 'MODIFIED')}] {s.get('path', '')}::{s.get('name', '')}")
+            for c in imp.direct_callers[:8]:
+                cli_echo(f"      ├── 📞 CALLER: {c.file}::{c.name} (depth 1)")
+            for r in imp.affected_routes[:5]:
+                cli_echo(f"      ├── 🌐 ROUTE: {r.name} -> {r.file}")
+            for t in imp.affected_tests[:5]:
+                cli_echo(f"      ├── 🧪 TEST: {t.file}::{t.name}")
+            for db in imp.db_writers[:5]:
+                cli_echo(f"      └── 💾 DB: {db.relationship} {db.name} in {db.file}")
+
+
+@app.command("git-conflicts")
+def git_conflicts_cmd(
+    base: Annotated[str, typer.Argument(help="Base Git branch (default: main)")] = "main",
+    head: Annotated[str, typer.Argument(help="Head Git branch (default: HEAD)")] = "HEAD",
+    path: Annotated[Path | None, typer.Option("--path", "-p", help="Repository path")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON format")] = False,
+) -> None:
+    """Detect semantic and contract merge conflicts between branches (calling deleted symbols, broken call signatures, or missing route handlers)."""
+    from codegraph.semantic_conflicts import detect_semantic_conflicts
+
+    repo = _resolve_repo(path, repository)
+    indexer = _indexer(repo)
+
+    with indexer.session() as con:
+        rep = detect_semantic_conflicts(repo, base_branch=base, head_branch=head, con=con)
+
+    if json_output:
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(f"Semantic Conflict Analysis: {base} <-> {head}")
+        cli_echo(f"Status:          {'⚠️ CONFLICTS DETECTED' if rep.has_conflicts else '✅ CLEAN (0 conflicts)'}")
+        cli_echo(f"Total Conflicts: {rep.total_conflicts}")
+        cli_echo(f"Summary:         {rep.summary}")
+        if rep.conflicts:
+            cli_echo("\nDetected Semantic Conflicts:")
+            for c in rep.conflicts:
+                cli_echo(f"\n  [{c.severity.value}] {c.conflict_type.value}: {c.symbol}")
+                cli_echo(f"    Description: {c.description}")
+                cli_echo(f"    Base ({base}): {c.base_file} ({c.base_evidence})")
+                cli_echo(f"    Head ({head}): {c.head_file} ({c.head_evidence})")
+
+
+@app.command("check-freshness")
+def check_freshness_cli_cmd(
+    task: Annotated[str, typer.Argument(help="Task prompt to verify context freshness for")] = "",
+    path: Annotated[Path | None, typer.Option("--path", "-p", help="Repository path")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON format")] = False,
+) -> None:
+    """Validate whether compiled context remains VALID, PARTIALLY_STALE, or STALE against repository changes."""
+    from codegraph.context import get_context
+    from codegraph.context_freshness import check_context_freshness
+
+    repo = _resolve_repo(path, repository)
+    indexer = _indexer(repo)
+
+    with indexer.session() as con:
+        # Generate baseline context if task provided
+        ctx = get_context(con, repo, task or "general repository overview", mode="FAST")
+        rep = check_context_freshness(ctx, repo, con=con)
+
+    if json_output:
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(f"Context Freshness Status: {rep.status.value}")
+        cli_echo(f"Reason:                  {rep.reason}")
+        cli_echo(f"Recommended Action:      {rep.recommended_action}")
+        if rep.changed_relevant_files:
+            cli_echo(f"Changed Relevant Files:  {', '.join(rep.changed_relevant_files)}")
+        if rep.unrelated_changed_files:
+            cli_echo(f"Unrelated Changed Files: {len(rep.unrelated_changed_files)} file(s)")
+
+
+@app.command("symbol-history")
+def symbol_history_cli_cmd(
+    symbol: Annotated[str, typer.Argument(help="Symbol name to trace across Git history")],
+    file_path: Annotated[str | None, typer.Option("--file", "-f", help="File path where symbol is located")] = None,
+    max_commits: Annotated[int, typer.Option("--max-commits", "-m", help="Max commits to inspect")] = 15,
+    path: Annotated[Path | None, typer.Option("--path", "-p", help="Repository path")] = None,
+    repository: Annotated[Path | None, typer.Option("--repository", "-r", "--repo", help="Repository path")] = None,
+    json_output: Annotated[bool, typer.Option("--json", help="Output JSON format")] = False,
+) -> None:
+    """Trace deterministic symbol evolution across Git history: introduced, modified, moved, renamed, or deleted."""
+    from codegraph.symbol_history import trace_symbol_history
+
+    repo = _resolve_repo(path, repository)
+    indexer = _indexer(repo)
+
+    with indexer.session() as con:
+        rep = trace_symbol_history(repo, symbol=symbol, path=file_path, con=con, max_commits=max_commits)
+
+    if json_output:
+        cli_echo(json.dumps(rep.as_dict(), indent=2), json_mode=True)
+    else:
+        cli_echo(f"Symbol History: {symbol}")
+        cli_echo(f"Status:         {rep.status} ({rep.detail})")
+        for ev in rep.events:
+            cli_echo(f"\n  [{ev.event_type}] Commit {ev.commit_sha[:8]} on {ev.date} by {ev.author}")
+            cli_echo(f"    Message:  {ev.message}")
+            cli_echo(f"    Location: {ev.path}")
+            cli_echo(f"    Evidence: {ev.evidence} (confidence: {ev.confidence})")
+
+
+
 if __name__ == "__main__":
     app()