codetruth 0.2.0__py3-none-any.whl

codetruth/__init__.py

@@ -0,0 +1,16 @@
+"""CodeTruth — a verification layer that lets AI agents safely delete code.
+
+    from codetruth import scan, check_deletion_safety, track
+"""
+from .api import check_deletion_safety, plan_deletion, scan
+from .core.models import (Action, Edge, EvidenceRecord, RiskLevel, Status,
+                          Symbol)
+from .runtime import track
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "scan", "check_deletion_safety", "plan_deletion", "track",
+    "Status", "RiskLevel", "Action", "Symbol", "Edge", "EvidenceRecord",
+    "__version__",
+]

codetruth/api.py

@@ -0,0 +1,102 @@
+"""Programmatic API — what the MCP server and scripts call.
+
+    from codetruth import scan, check_deletion_safety, plan_deletion
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .core.deletion import build_deletion_plan
+from .core.plugin import get_plugin
+from .core.scanner import ScanResult, scan_repo
+
+
+def scan(repo_path: str | Path, language: str = "python",
+         treat_public_as_api: Optional[bool] = None,
+         runtime_log: Optional[str | Path] = None,
+         use_cache: bool = True,
+         reachability: str = "default") -> ScanResult:
+    """Run all four layers over a repository and return the evidence set.
+
+    treat_public_as_api: True (conservative, the default when neither the
+    caller nor .codetruth.toml says otherwise) caps unreferenced public
+    symbols at `likely_dead` because a library's consumers are invisible.
+    False for application code; None defers to `app_mode` in .codetruth.toml.
+
+    reachability: "default", or "strict" to detect useless clumps — code
+    that is internally connected but never reached from any real entry point
+    (route, CLI command, __main__, test, declared entrypoint). Strict-mode
+    findings surface in the review queue with cluster grouping.
+
+    use_cache=True reuses a persisted result (<repo>/.codetruth/index.json)
+    when no source or config file has changed since the last scan.
+    """
+    return scan_repo(repo_path, language=language,
+                     treat_public_as_api=treat_public_as_api,
+                     runtime_log=runtime_log, use_cache=use_cache,
+                     reachability=reachability)
+
+
+def check_deletion_safety(repo_path: str | Path, symbol: str,
+                          result: Optional[ScanResult] = None,
+                          **scan_kwargs) -> dict:
+    """The agent-facing question: 'may I delete this symbol?'
+
+    Returns the evidence record(s) for the symbol, or candidate matches if
+    the name is ambiguous. The agent should only act on `safe_to_delete`.
+    """
+    if result is None:
+        result = scan(repo_path, **scan_kwargs)
+    matches = result.find(symbol)
+    if not matches:
+        return {
+            "found": False, "symbol": symbol,
+            "message": "Symbol not found in the scanned repository. "
+                       "Do NOT delete based on this response — verify the "
+                       "symbol id (format: 'pkg.module:Qual.name').",
+        }
+    if len(matches) > 1:
+        return {
+            "found": True, "ambiguous": True, "symbol": symbol,
+            "message": f"{len(matches)} symbols match — re-query with an exact id.",
+            "candidates": [m.to_dict() for m in matches[:20]],
+        }
+    record = matches[0]
+    return {"found": True, "ambiguous": False, "record": record.to_dict()}
+
+
+def plan_deletion(repo_path: str | Path, symbol: str,
+                  language: str = "python",
+                  result: Optional[ScanResult] = None,
+                  **scan_kwargs) -> dict:
+    """Advisory plan for removing one symbol: exact span, orphaned imports,
+    __all__ entry. Works for any status — the response carries the verdict so
+    the reader knows whether acting on the plan is advised. CodeTruth never
+    applies the plan.
+    """
+    safety = check_deletion_safety(repo_path, symbol, result=result,
+                                   **scan_kwargs)
+    if not safety.get("found") or safety.get("ambiguous"):
+        return safety
+
+    record = safety["record"]
+    if record.get("deletion_plan"):
+        plan = record["deletion_plan"]
+    else:
+        repo = Path(repo_path).resolve()
+        plugin = get_plugin(language)
+        modules, _warnings = plugin.extract(repo)
+        sym = next((s for m in modules for s in m.symbols
+                    if s.id == record["symbol"]), None)
+        plan = build_deletion_plan(repo, sym) if sym is not None else None
+
+    return {
+        "found": True, "symbol": record["symbol"],
+        "status": record["status"],
+        "recommended_action": record["recommended_action"],
+        "plan": plan,
+        "warning": None if record["status"] == "safe_to_delete" else
+                   f"status is {record['status']} — this plan is informational; "
+                   "review is required before anyone acts on it",
+    }

codetruth/cli.py

@@ -0,0 +1,183 @@
+"""Human/script CLI.
+
+    codetruth scan ./repo [--json out.json] [--status likely_dead] [--app-mode]
+    codetruth scan ./repo --strict --min-rank 0.5 --group
+    codetruth scan ./repo --ci                 # exit 1 if safe_to_delete found
+    codetruth scan ./repo --html report.html
+    codetruth check ./repo pkg.module:symbol
+    codetruth plan ./repo pkg.module:symbol
+    codetruth mcp
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import defaultdict
+
+from .api import check_deletion_safety, plan_deletion, scan
+from .core.models import Status
+from .core.report import write_html_report
+
+STATUS_ICON = {
+    Status.SAFE_TO_DELETE: "[SAFE]  ",
+    Status.LIKELY_DEAD: "[DEAD?] ",
+    Status.UNCERTAIN_DYNAMIC_RISK: "[RISK]  ",
+    Status.DEFINITELY_USED: "[USED]  ",
+}
+
+
+def _print_record(r, verbose: bool, indent: str = "") -> None:
+    print(f"{indent}{STATUS_ICON[r.status]}{r.rank_score:.2f}  {r.symbol}  "
+          f"({r.file}:{r.line})")
+    if verbose:
+        for e in r.evidence_for_deletion:
+            print(f"{indent}    + {e}")
+        for e in r.evidence_against_deletion:
+            print(f"{indent}    - {e}")
+
+
+def _cmd_scan(args) -> int:
+    result = scan(args.repo, language=args.language,
+                  treat_public_as_api=False if args.app_mode else None,
+                  runtime_log=args.runtime_log, use_cache=not args.no_cache,
+                  reachability="strict" if args.strict else "default")
+    summary = result.summary()
+
+    if args.json:
+        result.save(args.json)
+        print(f"Wrote full evidence to {args.json}")
+    if args.html:
+        write_html_report(result, args.html)
+        print(f"Wrote HTML report to {args.html}")
+
+    records = result.candidates()
+    if args.status:
+        records = [r for r in records if r.status.value == args.status]
+    if args.min_rank is not None:
+        records = [r for r in records if r.rank_score >= args.min_rank]
+
+    shown = records[: args.limit]
+    if args.group:
+        by_file: dict[str, list] = defaultdict(list)
+        for r in shown:
+            by_file[r.file].append(r)
+        for file in sorted(by_file):
+            print(f"\n{file}")
+            for r in by_file[file]:
+                _print_record(r, args.verbose, indent="  ")
+    else:
+        for r in shown:
+            _print_record(r, args.verbose)
+    if len(records) > args.limit:
+        print(f"... {len(records) - args.limit} more (raise --limit or use --json)")
+
+    c = summary["status_counts"]
+    print(f"\n{summary['symbols']} symbols, {summary['edges']} edges | "
+          f"safe_to_delete: {c['safe_to_delete']}  "
+          f"likely_dead: {c['likely_dead']}  "
+          f"uncertain: {c['uncertain_dynamic_risk']}  "
+          f"used: {c['definitely_used']}")
+    if result.warnings:
+        print(f"warnings: {len(result.warnings)} (parse failures)")
+
+    if args.ci:
+        # Report-gate: fail the build when provably-dead code exists so a
+        # human looks. Never deletes anything — advisory, as always.
+        n = c["safe_to_delete"]
+        if n:
+            print(f"\nCI gate: {n} safe_to_delete symbol(s) found — failing "
+                  "(review and remove, or mark as an entrypoint).",
+                  file=sys.stderr)
+            return 1
+    return 0
+
+
+def _cmd_check(args) -> int:
+    response = check_deletion_safety(
+        args.repo, args.symbol,
+        treat_public_as_api=False if args.app_mode else None)
+    print(json.dumps(response, indent=2))
+    return 0
+
+
+def _cmd_plan(args) -> int:
+    response = plan_deletion(
+        args.repo, args.symbol,
+        treat_public_as_api=False if args.app_mode else None)
+    print(json.dumps(response, indent=2))
+    return 0
+
+
+def _cmd_mcp(_args) -> int:
+    try:
+        from .mcp_server import main as mcp_main
+    except ImportError:
+        print("The MCP server requires the 'mcp' package: pip install codetruth[mcp]",
+              file=sys.stderr)
+        return 1
+    mcp_main()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="codetruth",
+        description="Deletion-safety evidence for code symbols. "
+                    "A risk assessor, not an oracle: only act on safe_to_delete.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scan = sub.add_parser("scan", help="scan a repository")
+    p_scan.add_argument("repo")
+    p_scan.add_argument("--language", "-l", default="python",
+                        choices=["python", "javascript", "typescript"],
+                        help="language plugin (javascript needs "
+                             "`pip install codetruth[javascript]`)")
+    p_scan.add_argument("--json", help="write full evidence JSON to this file")
+    p_scan.add_argument("--status", choices=[s.value for s in Status])
+    p_scan.add_argument("--limit", type=int, default=50)
+    p_scan.add_argument("--verbose", "-v", action="store_true",
+                        help="print evidence lines per symbol")
+    p_scan.add_argument("--app-mode", action="store_true",
+                        help="treat public symbols as internal (application, "
+                             "not library) — allows safe_to_delete on them")
+    p_scan.add_argument("--runtime-log", help="path to a runtime.jsonl trace")
+    p_scan.add_argument("--no-cache", action="store_true",
+                        help="ignore the persisted .codetruth/index.json result")
+    p_scan.add_argument("--strict", action="store_true",
+                        help="strict reachability: flag code not reachable "
+                             "from any real entry point (detects internally-"
+                             "connected but orphaned clumps)")
+    p_scan.add_argument("--min-rank", type=float, default=None,
+                        help="only show candidates with rank_score >= this "
+                             "(0-1); trims the noisy tail of the review queue")
+    p_scan.add_argument("--group", action="store_true",
+                        help="group the output by file")
+    p_scan.add_argument("--html", help="write a standalone HTML report here")
+    p_scan.add_argument("--ci", action="store_true",
+                        help="exit non-zero if any safe_to_delete code exists "
+                             "(a dead-code report gate; never deletes)")
+    p_scan.set_defaults(func=_cmd_scan)
+
+    p_check = sub.add_parser("check", help="check one symbol's deletion safety")
+    p_check.add_argument("repo")
+    p_check.add_argument("symbol", help="e.g. pkg.module:function_name")
+    p_check.add_argument("--app-mode", action="store_true")
+    p_check.set_defaults(func=_cmd_check)
+
+    p_plan = sub.add_parser(
+        "plan", help="advisory deletion plan for one symbol (never applied)")
+    p_plan.add_argument("repo")
+    p_plan.add_argument("symbol", help="e.g. pkg.module:function_name")
+    p_plan.add_argument("--app-mode", action="store_true")
+    p_plan.set_defaults(func=_cmd_plan)
+
+    p_mcp = sub.add_parser("mcp", help="run the MCP server (stdio)")
+    p_mcp.set_defaults(func=_cmd_mcp)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codetruth/core/cache.py

@@ -0,0 +1,104 @@
+"""Phase-5 performance: a persistent scan cache keyed by file fingerprints.
+
+A scan is deterministic given the repo's source + config bytes, so we can
+skip it entirely when nothing has changed since the last run. The cache lives
+at <repo>/.codetruth/index.json and survives process restarts — which the
+MCP server's in-memory TTL cache does not.
+
+Invalidation is whole-repo and mtime+size based: if any tracked file's
+(mtime_ns, size) differs from what produced the cached result, the cache
+misses and a full rescan runs. We deliberately do NOT patch the graph
+incrementally per changed file — edges cross files, and a stale edge could
+turn a used symbol into a false safe_to_delete, the one error class the tool
+exists to prevent. Correctness first; the cache only ever short-circuits an
+exact, verified match.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from .models import EvidenceRecord
+
+if TYPE_CHECKING:
+    from .scanner import ScanResult
+
+# Bump on ANY change to classification, ranking, or the record schema — a
+# cached result from older logic must never be served by newer code.
+CACHE_VERSION = 3
+CACHE_DIRNAME = ".codetruth"
+CACHE_FILENAME = "index.json"
+
+
+def _cache_path(repo: Path) -> Path:
+    return repo / CACHE_DIRNAME / CACHE_FILENAME
+
+
+def fingerprint(repo: Path, source_files: list[Path]) -> dict[str, list[int]]:
+    """{rel_path: [mtime_ns, size]} for every file whose bytes affect a scan."""
+    fp: dict[str, list[int]] = {}
+    for path in source_files:
+        try:
+            st = path.stat()
+        except OSError:
+            continue
+        rel = path.relative_to(repo).as_posix()
+        fp[rel] = [st.st_mtime_ns, st.st_size]
+    return fp
+
+
+def load(repo: Path, language: str, treat_public_as_api: bool,
+         current_fp: dict[str, list[int]],
+         reachability: str = "default") -> Optional["ScanResult"]:
+    """Return a cached ScanResult iff it matches the current inputs exactly."""
+    from .scanner import ScanResult  # local import: avoid a cycle
+
+    path = _cache_path(repo)
+    if not path.is_file():
+        return None
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+    if (doc.get("version") != CACHE_VERSION
+            or doc.get("language") != language
+            or doc.get("treat_public_as_api") != treat_public_as_api
+            or doc.get("reachability", "default") != reachability
+            or doc.get("fingerprint") != current_fp):
+        return None
+
+    try:
+        records = [EvidenceRecord.from_dict(r) for r in doc["records"]]
+        return ScanResult(
+            repo_path=str(repo), language=language, records=records,
+            symbol_count=doc["symbol_count"], edge_count=doc["edge_count"],
+            warnings=list(doc.get("warnings", [])),
+        )
+    except (KeyError, ValueError):
+        return None  # schema drift — treat as a miss and rescan
+
+
+def save(repo: Path, result: "ScanResult", language: str,
+         treat_public_as_api: bool, current_fp: dict[str, list[int]],
+         reachability: str = "default") -> None:
+    doc = {
+        "version": CACHE_VERSION,
+        "language": language,
+        "treat_public_as_api": treat_public_as_api,
+        "reachability": reachability,
+        "fingerprint": current_fp,
+        "symbol_count": result.symbol_count,
+        "edge_count": result.edge_count,
+        "warnings": result.warnings,
+        "records": [r.to_dict() for r in result.records],
+    }
+    path = _cache_path(repo)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(doc), encoding="utf-8")
+        tmp.replace(path)  # atomic on POSIX and Windows
+    except OSError:
+        pass  # a read-only repo just means no persistent cache; not fatal

codetruth/core/config.py

@@ -0,0 +1,74 @@
+"""Repo-level configuration: let users teach the scanner about usage it
+cannot see, and scope what it looks at.
+
+`.codetruth.toml` at the repository root:
+
+    [codetruth]
+    app_mode = true                # public symbols are internal (application)
+    entrypoints = [                # externally-reached symbols (cron, RPC, ...)
+        "jobs.nightly:run",
+        "services.handlers.*",
+    ]
+    ignore_paths = [               # not scanned at all
+        "migrations/",
+        "vendor/**",
+    ]
+
+Inline suppression: a `# codetruth: keep` comment on (or directly above) a
+definition marks it as an entry point.
+"""
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+try:
+    import tomllib  # Python 3.11+
+except ImportError:  # pragma: no cover - Python 3.10
+    try:
+        import tomli as tomllib
+    except ImportError:
+        tomllib = None
+
+CONFIG_FILENAME = ".codetruth.toml"
+
+
+@dataclass
+class RepoConfig:
+    app_mode: Optional[bool] = None
+    entrypoints: list[str] = field(default_factory=list)
+    ignore_paths: list[str] = field(default_factory=list)
+
+    def is_ignored(self, rel_path: str) -> bool:
+        rel = rel_path.replace("\\", "/")
+        for pat in self.ignore_paths:
+            pat = pat.replace("\\", "/")
+            base = pat.rstrip("/*")
+            if fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(rel, base + "/*") \
+                    or rel == base or rel.startswith(base + "/"):
+                return True
+        return False
+
+    def is_declared_entrypoint(self, symbol_id: str) -> bool:
+        dotted = symbol_id.replace(":", ".")
+        return any(fnmatch.fnmatch(symbol_id, pat)
+                   or fnmatch.fnmatch(dotted, pat.replace(":", "."))
+                   for pat in self.entrypoints)
+
+
+def load_config(repo: Path) -> RepoConfig:
+    path = repo / CONFIG_FILENAME
+    if tomllib is None or not path.is_file():
+        return RepoConfig()
+    try:
+        doc = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return RepoConfig()
+    section = doc.get("codetruth", doc)  # tolerate a bare top-level table
+    return RepoConfig(
+        app_mode=section.get("app_mode"),
+        entrypoints=[str(x) for x in section.get("entrypoints", [])],
+        ignore_paths=[str(x) for x in section.get("ignore_paths", [])],
+    )

codetruth/core/deletion.py

@@ -0,0 +1,165 @@
+"""Advisory deletion plans: *describe* exactly what removing a symbol would
+involve — the tool never applies any of it (advisory-only by design).
+
+A plan answers the three questions a reviewer has to work out by hand:
+1. What is the exact span to remove (decorators through end of block,
+   including trailing blank lines)?
+2. Which imports in the same file become orphaned — their only remaining
+   user is the symbol being removed?
+3. Does anything else reference the name administratively (an `__all__`
+   entry) that would need cleanup?
+"""
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Optional
+
+from .models import Symbol, SymbolType
+
+
+def build_deletion_plan(repo: Path, sym: Symbol) -> Optional[dict]:
+    """Compute an advisory plan for one symbol. Returns None when the file
+    can't be parsed or the definition can't be located (never raises)."""
+    if sym.type is SymbolType.MODULE:
+        return {
+            "symbol": sym.id, "file": sym.file, "kind": "module",
+            "note": "whole-file removal candidate — review the module, then "
+                    "remove the file and any references to the module name",
+        }
+    try:
+        source = (repo / sym.file).read_text(encoding="utf-8", errors="replace")
+        tree = ast.parse(source)
+    except (OSError, SyntaxError, ValueError):
+        return None
+
+    node = _locate(tree, sym.qualname)
+    if node is None:
+        return None
+
+    lines = source.splitlines()
+    start = node.lineno
+    if getattr(node, "decorator_list", None):
+        start = min(d.lineno for d in node.decorator_list)
+    end = node.end_lineno or node.lineno
+    # Consume trailing blank lines so the removal leaves no gap.
+    end_with_blanks = end
+    while end_with_blanks < len(lines) and not lines[end_with_blanks].strip():
+        end_with_blanks += 1
+
+    plan = {
+        "symbol": sym.id,
+        "file": sym.file,
+        "kind": sym.type.value,
+        "span": {"start_line": start, "end_line": end},
+        "span_with_trailing_blanks": {"start_line": start,
+                                      "end_line": end_with_blanks},
+        "orphaned_imports": _orphaned_imports(tree, start, end),
+        "note": "advisory only — CodeTruth never applies deletions",
+    }
+
+    dunder_all = _all_entry_line(tree, sym.name)
+    if dunder_all is not None:
+        plan["dunder_all_entry"] = {
+            "file": sym.file, "line": dunder_all,
+            "note": f"remove '{sym.name}' from __all__",
+        }
+    return plan
+
+
+def _locate(tree: ast.Module, qualname: str) -> Optional[ast.AST]:
+    """Walk the def/class nesting to the node matching a dotted qualname.
+    Variables resolve to their (first) assignment statement."""
+    parts = qualname.split(".")
+    body = tree.body
+    node: Optional[ast.AST] = None
+    for i, part in enumerate(parts):
+        node = _find_in_body(body, part)
+        if node is None:
+            return None
+        if i < len(parts) - 1:
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef,
+                                     ast.ClassDef)):
+                return None
+            body = node.body
+    return node
+
+
+def _find_in_body(body, name: str) -> Optional[ast.AST]:
+    for stmt in body:
+        if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef,
+                             ast.ClassDef)) and stmt.name == name:
+            return stmt
+        if isinstance(stmt, ast.Assign):
+            for t in stmt.targets:
+                if isinstance(t, ast.Name) and t.id == name:
+                    return stmt
+        if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name) \
+                and stmt.target.id == name:
+            return stmt
+        if isinstance(stmt, (ast.If, ast.Try, ast.With)):
+            blocks = [getattr(stmt, "body", [])] + \
+                     [getattr(stmt, "orelse", [])] + \
+                     [getattr(stmt, "finalbody", [])] + \
+                     [h.body for h in getattr(stmt, "handlers", [])]
+            for blk in blocks:
+                found = _find_in_body(blk, name)
+                if found is not None:
+                    return found
+    return None
+
+
+def _orphaned_imports(tree: ast.Module, start: int, end: int) -> list[dict]:
+    """Imports whose bound name is used ONLY inside the [start, end] span —
+    they become dead once the span is removed."""
+    # bound name -> import statement line
+    bound: dict[str, int] = {}
+    import_lines: set[int] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            import_lines.add(node.lineno)
+            for alias in node.names:
+                bound[alias.asname or alias.name.split(".")[0]] = node.lineno
+        elif isinstance(node, ast.ImportFrom):
+            import_lines.add(node.lineno)
+            for alias in node.names:
+                if alias.name != "*":
+                    bound[alias.asname or alias.name] = node.lineno
+
+    if not bound:
+        return []
+
+    # name -> line numbers of every load-context usage outside import stmts
+    usages: dict[str, list[int]] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load) \
+                and node.lineno not in import_lines:
+            usages.setdefault(node.id, []).append(node.lineno)
+        elif isinstance(node, ast.Attribute):
+            root = node
+            while isinstance(root, ast.Attribute):
+                root = root.value
+            if isinstance(root, ast.Name) and root.lineno not in import_lines:
+                usages.setdefault(root.id, []).append(root.lineno)
+
+    orphaned = []
+    for name, imp_line in sorted(bound.items(), key=lambda kv: kv[1]):
+        lines = usages.get(name, [])
+        inside = [ln for ln in lines if start <= ln <= end]
+        outside = [ln for ln in lines if not (start <= ln <= end)]
+        if inside and not outside:
+            orphaned.append({"name": name, "import_line": imp_line,
+                             "note": "only used by the symbol being removed"})
+    return orphaned
+
+
+def _all_entry_line(tree: ast.Module, name: str) -> Optional[int]:
+    for stmt in tree.body:
+        if isinstance(stmt, ast.Assign):
+            for t in stmt.targets:
+                if isinstance(t, ast.Name) and t.id == "__all__":
+                    if isinstance(stmt.value, (ast.List, ast.Tuple)):
+                        for e in stmt.value.elts:
+                            if isinstance(e, ast.Constant) and e.value == name:
+                                return stmt.lineno
+    return None