codebase-index 1.6.0__py3-none-any.whl

codebase_index/output/markdown.py

@@ -0,0 +1,316 @@
+"""Compact Markdown renderer for SearchResponse and dict payloads."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..models import ImpactResponse, RefsResponse, SearchResponse, SymbolResponse
+
+
+def render(resp: SearchResponse | dict) -> str:
+    if isinstance(resp, dict):
+        return _render_dict(resp)
+    return _render_search_response(resp)
+
+
+def _render_dict(payload: dict) -> str:
+    lines: list[str] = []
+    lines.append(f"**Query:** {payload['query']}  ")
+    lines.append(
+        f"**Intent:** `{payload['intent']}` · **Confidence:** {payload['confidence']}\n"
+    )
+
+    if payload["results"]:
+        lines.append("| # | Path | Lines | Reason |")
+        lines.append("|---|------|-------|--------|")
+        for r in payload["results"]:
+            lines.append(
+                f"| {r['rank']} | `{r['path']}` | {r['line_start']}-{r['line_end']} "
+                f"| {r.get('reason', '')} |"
+            )
+        lines.append("")
+        for r in payload["results"]:
+            if r.get("snippet"):
+                lines.append(f"`{r['path']}:{r['line_start']}-{r['line_end']}`")
+                lines.append("```")
+                lines.append(r["snippet"])
+                lines.append("```")
+
+    if payload["recommended_reads"]:
+        lines.append("\n**Recommended reads:**")
+        for rr in payload["recommended_reads"]:
+            lines.append(f"- `{rr['path']}:{rr['line_start']}-{rr['line_end']}`")
+
+    fb = payload.get("fallback_suggestions", {}).get("ripgrep")
+    if fb:
+        lines.append("\n**Fallback (low confidence) — try:**")
+        for cmd in fb:
+            lines.append(f"- `{cmd}`")
+
+    pg = payload.get("pagination")
+    if pg:
+        shown = f"results {pg['offset'] + 1}–{pg['offset'] + len(payload['results'])}"
+        if pg.get("has_more"):
+            lines.append(f"\n_Showing {shown}; more available — `--offset {pg['next_offset']}`._")
+        else:
+            lines.append(f"\n_Showing {shown} (end of results)._")
+
+    return "\n".join(lines)
+
+
+def _render_search_response(resp: SearchResponse) -> str:
+    lines: list[str] = []
+    freshness = "fresh" if not resp.index.stale else "STALE"
+    if not resp.index.exists:
+        freshness = "NO INDEX"
+    lines.append(
+        f"**query:** {resp.query}  |  **intent:** {resp.intent}  |  "
+        f"**confidence:** {resp.confidence}  |  **index:** {freshness}"
+    )
+    lines.append("")
+
+    if resp.results:
+        lines.append("| # | path | lines | reason |")
+        lines.append("|---|------|-------|--------|")
+        for result in resp.results:
+            symbols = f" `{','.join(result.symbols)}`" if result.symbols else ""
+            lines.append(
+                f"| {result.rank} | `{result.path}`{symbols} | "
+                f"{result.line_start}-{result.line_end} | {result.reason} |"
+            )
+        lines.append("")
+        for result in resp.results:
+            if result.snippet:
+                lines.append(f"`{result.path}:{result.line_start}-{result.line_end}`")
+                lines.append("```")
+                lines.append(result.snippet)
+                lines.append("```")
+        lines.append("")
+    else:
+        lines.append("_No index matches._")
+        lines.append("")
+
+    if resp.recommended_reads:
+        lines.append("**recommended reads:**")
+        for read in resp.recommended_reads:
+            lines.append(f"- `{read.path}:{read.line_start}-{read.line_end}`")
+        lines.append("")
+
+    if resp.fallback_suggestions:
+        lines.append("**fallback:**")
+        for commands in resp.fallback_suggestions.values():
+            for command in commands:
+                lines.append(f"- `{command}`")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_symbols(resp: SymbolResponse) -> str:
+    lines = [_header(resp.query, resp.index.exists, resp.index.stale)]
+    lines.append("")
+    if not resp.symbols:
+        lines.append("_No symbol definitions found._")
+        return "\n".join(lines).rstrip() + "\n"
+
+    lines.append("| name | kind | path | lines | signature |")
+    lines.append("|------|------|------|-------|-----------|")
+    for symbol in resp.symbols:
+        display = symbol.qualified or symbol.name
+        signature = symbol.signature or ""
+        lines.append(
+            f"| `{display}` | {symbol.kind} | `{symbol.path}` | "
+            f"{symbol.line_start}-{symbol.line_end} | `{signature}` |"
+        )
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _coverage_line(coverage) -> Optional[str]:
+    if coverage is not None and getattr(coverage, "partial", False):
+        return f"\n> ⚠️ Partial graph coverage: {coverage.reason}"
+    return None
+
+
+# Audit-trail glyphs: an exact edge needs no annotation; inferred/ambiguous ones
+# warn the reader that the link is a heuristic or could not be pinned down.
+_CONF_MARK = {"extracted": "", "inferred": "~ inferred", "ambiguous": "? ambiguous"}
+
+
+def _conf_mark(confidence: Optional[str]) -> str:
+    return _CONF_MARK.get(confidence or "extracted", confidence or "")
+
+
+def render_refs(resp: RefsResponse) -> str:
+    lines = [_header(resp.query, resp.index.exists, resp.index.stale)]
+    lines.append("")
+    note = _coverage_line(resp.coverage)
+    if not resp.sites:
+        lines.append("_No references found._")
+        if note:
+            lines.append(note)
+        return "\n".join(lines).rstrip() + "\n"
+
+    lines.append("| kind | path | line | confidence |")
+    lines.append("|------|------|------|------------|")
+    for site in resp.sites:
+        lines.append(
+            f"| {site.kind} | `{site.path}` | {site.line} | {_conf_mark(site.confidence) or 'exact'} |"
+        )
+    if note:
+        lines.append(note)
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _node_label(ref: dict) -> str:
+    name = ref.get("name")
+    path = ref.get("path") or ""
+    return f"`{name}` ({path})" if name and ref.get("kind") == "symbol" else f"`{path}`"
+
+
+def render_path(payload: dict) -> str:
+    """Render a path between two nodes as an arrow chain annotated with edge types."""
+    head = f"**path:** `{payload['src']}` → `{payload['dst']}`"
+    if not payload.get("found"):
+        return f"{head}\n\n_{payload.get('reason', 'No path found.')}_\n"
+
+    lines = [f"{head}  ·  **{payload.get('hops', 0)} hop(s)**", ""]
+    nodes = payload.get("nodes", [])
+    steps = payload.get("steps", [])
+    # Render as: A  --edge(conf)-->  B  --edge-->  C
+    if nodes:
+        lines.append(_node_label(nodes[0]))
+        for step, nxt in zip(steps, nodes[1:]):
+            mark = _conf_mark(step.get("confidence"))
+            edge = f"{step['edge_type']}{' ' + mark if mark else ''}"
+            arrow = "→" if step.get("direction") == "out" else "←"
+            lines.append(f"  {arrow} _{edge}_ {arrow}")
+            lines.append(_node_label(nxt))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_describe(payload: dict) -> str:
+    """Render a symbol node card: definition, centrality, callers, callees."""
+    head = f"**describe:** `{payload['query']}`"
+    if not payload.get("found"):
+        return f"{head}\n\n_{payload.get('reason', 'Not found.')}_\n"
+
+    p = payload.get("primary", {})
+    god = f" · god node #{p['god_rank']}" if p.get("god_rank") else ""
+    lines = [
+        f"{head}  ·  module `{p.get('module', '?')}`  ·  "
+        f"in {p.get('in_degree', 0)} / out {p.get('out_degree', 0)}{god}",
+        "",
+    ]
+
+    defs = payload.get("definitions", [])
+    if defs:
+        lines.append("**definition(s):**")
+        for d in defs:
+            sig = f" — `{d['signature']}`" if d.get("signature") else ""
+            lines.append(f"- {d['kind']} `{d.get('qualified') or d['name']}` "
+                         f"at `{d['path']}:{d['line_start']}`{sig}")
+        lines.append("")
+
+    callers = payload.get("callers", [])
+    if callers:
+        lines.append(f"**callers ({len(callers)}):**")
+        for c in callers[:20]:
+            mark = _conf_mark(c.get("confidence"))
+            lines.append(f"- `{c['path']}:{c['line']}`{' · ' + mark if mark else ''}")
+        lines.append("")
+
+    callees = payload.get("callees", [])
+    if callees:
+        lines.append(f"**callees ({len(callees)}):**")
+        for c in callees[:20]:
+            mark = _conf_mark(c.get("confidence"))
+            lines.append(f"- {_node_label(c)} _{c.get('edge_type', '')}_"
+                         f"{' · ' + mark if mark else ''}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_architecture(payload: dict) -> str:
+    """Render the architecture overview: modules, god nodes, surprising links, questions."""
+    if not payload.get("available", False):
+        reason = payload.get("reason", "No architecture analysis available.")
+        return f"_{reason}_\n"
+
+    idx = payload.get("index", {})
+    freshness = "fresh" if not idx.get("stale") else "STALE"
+    lines = [
+        f"**Architecture overview**  |  **index:** {freshness}  |  "
+        f"{payload.get('node_count', 0)} nodes · {payload.get('edge_count', 0)} edges · "
+        f"{payload.get('community_count', 0)} modules · modularity {payload.get('modularity', 0)}",
+        "",
+    ]
+
+    communities = payload.get("communities", [])
+    if communities:
+        lines.append("### Modules")
+        lines.append("| # | module | size | key nodes |")
+        lines.append("|---|--------|------|-----------|")
+        for c in communities:
+            tops = ", ".join(f"`{t['name']}`" for t in c.get("top_nodes", [])[:4])
+            lines.append(f"| {c['id']} | {c['label']} | {c['size']} | {tops} |")
+        lines.append("")
+
+    gods = payload.get("god_nodes", [])
+    if gods:
+        lines.append("### God nodes (most-connected)")
+        lines.append("| node | kind | degree | location |")
+        lines.append("|------|------|--------|----------|")
+        for g in gods:
+            loc = g.get("path") or ""
+            lines.append(f"| `{g['name']}` | {g['kind']} | {g['degree']} | `{loc}` |")
+        lines.append("")
+
+    surprising = payload.get("surprising", [])
+    if surprising:
+        lines.append("### Surprising connections (cross-module bridges)")
+        for s in surprising:
+            fr, to = s["from"], s["to"]
+            lines.append(
+                f"- `{fr['name']}` ({fr.get('path') or '?'}) ↔ "
+                f"`{to['name']}` ({to.get('path') or '?'}) — {s['edge_count']} edge(s)"
+            )
+        lines.append("")
+
+    questions = payload.get("questions", [])
+    if questions:
+        lines.append("### Suggested questions")
+        for q in questions:
+            lines.append(f"- {q}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _header(query: str, exists: bool, stale: bool) -> str:
+    freshness = "fresh" if not stale else "STALE"
+    if not exists:
+        freshness = "NO INDEX"
+    return f"**query:** {query}  |  **index:** {freshness}"
+
+
+def render_impact(resp: ImpactResponse) -> str:
+    header = (f"**impact:** `{resp.target}`  ·  **direction:** {resp.direction}  ·  "
+              f"**depth:** {resp.depth}  ·  **affected files:** {len(resp.files)}")
+    lines = [header, ""]
+    note = _coverage_line(resp.coverage)
+    if not resp.nodes:
+        body = ["_No impact found (target unknown or no edges)._"]
+        if note:
+            body.append(note)
+        return "\n".join(lines + body + [""]).rstrip() + "\n"
+    lines.append("| dist | via | kind | node | location |")
+    lines.append("|------|-----|------|------|----------|")
+    for n in sorted(resp.nodes, key=lambda x: (x.distance, x.path, x.line_start or 0)):
+        loc = f"{n.path}:{n.line_start}" if n.line_start else n.path
+        node_name = f"`{n.name}`" if n.name else "—"
+        mark = _conf_mark(n.via_confidence)
+        via = f"{n.via_edge or ''} {mark}".strip()
+        lines.append(f"| {n.distance} | {via} | {n.kind} | {node_name} | `{loc}` |")
+    if note:
+        lines.append(note)
+    return "\n".join(lines).rstrip() + "\n"

codebase_index/output/redact.py

@@ -0,0 +1,31 @@
+"""Conservative output-time secret redaction."""
+
+from __future__ import annotations
+
+import re
+
+_PRIVATE_KEY_RE = re.compile(
+    r"-----BEGIN ([A-Z ]*PRIVATE KEY)-----.*?-----END \1-----",
+    re.DOTALL,
+)
+_AWS_ACCESS_KEY_RE = re.compile(r"\bAKIA[0-9A-Z]{16}\b")
+_ASSIGNED_SECRET_RE = re.compile(
+    r"(?i)\b(api[_-]?key|access[_-]?token|secret|token|password)\b"
+    r"(\s*[:=]\s*)"
+    r"([\"']?)[A-Za-z0-9_./+=:-]{16,}\3"
+)
+
+
+def redact_snippet(text: str) -> str:
+    text = _PRIVATE_KEY_RE.sub(_redact_private_key, text)
+    text = _AWS_ACCESS_KEY_RE.sub("<<redacted:aws_access_key>>", text)
+    return _ASSIGNED_SECRET_RE.sub(
+        lambda m: f"{m.group(1)}{m.group(2)}<<redacted:secret>>", text
+    )
+
+
+def _redact_private_key(match: re.Match[str]) -> str:
+    return "\n".join(
+        "<<redacted:private_key>>" if line and not line.startswith("-----") else line
+        for line in match.group(0).splitlines()
+    )

codebase_index/parsers/__init__.py

@@ -0,0 +1,9 @@
+"""Parsers turn an eligible file into chunks + symbols.
+
+base.py         : Parser protocol -> parse(path, text) -> (list[Chunk], list[Symbol]).
+treesitter.py   : AST-based symbol extraction using tree-sitter grammars.
+line_chunker.py : fallback line-window chunking for unsupported / unparseable files.
+languages.py    : grammar registry + per-language node->symbol-kind maps + import/call queries.
+
+Selection: treesitter when a grammar exists for the detected language, else line_chunker.
+"""

codebase_index/parsers/base.py

@@ -0,0 +1,47 @@
+"""Shared parser types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional, Protocol
+
+
+@dataclass
+class Chunk:
+    line_start: int
+    line_end: int
+    content: str
+    token_est: int
+    kind: str = "window"
+    symbol_index: Optional[int] = None
+
+
+@dataclass
+class Symbol:
+    name: str
+    kind: str
+    line_start: int
+    line_end: int
+    qualified: Optional[str] = None
+    signature: Optional[str] = None
+    parent_index: Optional[int] = None
+    docstring: Optional[str] = None
+
+
+@dataclass
+class Edge:
+    edge_type: str
+    callee_name: str
+    line: int
+    src_symbol_index: Optional[int] = None
+
+
+@dataclass
+class ParseResult:
+    chunks: list[Chunk] = field(default_factory=list)
+    symbols: list[Symbol] = field(default_factory=list)
+    edges: list[Edge] = field(default_factory=list)
+
+
+class Parser(Protocol):
+    def parse(self, text: str) -> ParseResult: ...

codebase_index/parsers/languages.py

@@ -0,0 +1,290 @@
+"""Per-language tree-sitter specs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+CONTAINER_KINDS = {"class", "interface", "enum", "struct", "trait", "impl", "record"}
+
+
+_PY_IMPORTS = """
+    (import_from_statement module_name: (dotted_name) @import.module)
+    (import_statement name: (dotted_name) @import.module)
+    (class_definition superclasses: (argument_list (identifier) @extends.base))
+"""
+
+_JS_IMPORTS = """
+    (import_statement source: (string (string_fragment) @import.module))
+    (class_declaration (class_heritage (identifier) @extends.base))
+"""
+
+_TS_IMPORTS = """
+    (import_statement source: (string (string_fragment) @import.module))
+    (class_declaration (class_heritage
+        (extends_clause value: (identifier) @extends.base)))
+    (class_declaration (class_heritage
+        (implements_clause (type_identifier) @implements.iface)))
+"""
+
+
+@dataclass(frozen=True)
+class LangSpec:
+    name: str
+    ts_name: str
+    defs_query: str
+    calls_query: str
+    imports_query: str = ""
+
+
+_PYTHON = LangSpec(
+    name="python",
+    ts_name="python",
+    defs_query="""
+        (function_definition name: (identifier) @name) @def.function
+        (class_definition    name: (identifier) @name) @def.class
+    """,
+    calls_query="""
+        (call function: (identifier) @callee)
+        (call function: (attribute attribute: (identifier) @callee))
+    """,
+    imports_query=_PY_IMPORTS,
+)
+
+_JS_DEFS = """
+    (function_declaration name: (identifier) @name) @def.function
+    (class_declaration    name: (identifier) @name) @def.class
+    (method_definition    name: (property_identifier) @name) @def.method
+    (variable_declarator  name: (identifier) @name value: (arrow_function)) @def.function
+    (variable_declarator  name: (identifier) @name value: (function_expression)) @def.function
+"""
+_JS_CALLS = """
+    (call_expression function: (identifier) @callee)
+    (call_expression function: (member_expression property: (property_identifier) @callee))
+"""
+
+_JAVASCRIPT = LangSpec(
+    name="javascript",
+    ts_name="javascript",
+    defs_query=_JS_DEFS,
+    calls_query=_JS_CALLS,
+    imports_query=_JS_IMPORTS,
+)
+
+_TS_DEFS = """
+    (function_declaration name: (identifier) @name) @def.function
+    (class_declaration    name: (type_identifier) @name) @def.class
+    (method_definition    name: (property_identifier) @name) @def.method
+    (variable_declarator  name: (identifier) @name value: (arrow_function)) @def.function
+    (interface_declaration name: (type_identifier) @name) @def.interface
+    (enum_declaration      name: (identifier) @name) @def.enum
+    (type_alias_declaration name: (type_identifier) @name) @def.type
+"""
+
+_TYPESCRIPT = LangSpec(
+    name="typescript",
+    ts_name="typescript",
+    defs_query=_TS_DEFS,
+    calls_query=_JS_CALLS,
+    imports_query=_TS_IMPORTS,
+)
+
+# --- Tier A: compiled / back-end languages ------------------------------------------------------
+# NOTE: symbol extraction is driven by treesitter._definition_kind (node-type mapping), not by
+# defs_query. These queries are kept as compile-checked documentation of the relevant node types
+# and to power graph edges (imports_query). See tests/test_languages.py.
+
+_JAVA = LangSpec(
+    name="java",
+    ts_name="java",
+    defs_query="""
+        (class_declaration name: (identifier) @name) @def.class
+        (interface_declaration name: (identifier) @name) @def.interface
+        (enum_declaration name: (identifier) @name) @def.enum
+        (record_declaration name: (identifier) @name) @def.record
+        (method_declaration name: (identifier) @name) @def.method
+        (constructor_declaration name: (identifier) @name) @def.method
+    """,
+    calls_query="(method_invocation name: (identifier) @callee)",
+    imports_query="""
+        (import_declaration (scoped_identifier) @import.module)
+        (superclass (type_identifier) @extends.base)
+        (super_interfaces (type_list (type_identifier) @implements.iface))
+    """,
+)
+
+_GO = LangSpec(
+    name="go",
+    ts_name="go",
+    defs_query="""
+        (function_declaration name: (identifier) @name) @def.function
+        (method_declaration name: (field_identifier) @name) @def.method
+        (type_spec name: (type_identifier) @name) @def.type
+    """,
+    calls_query="(call_expression function: (identifier) @callee)",
+    imports_query="(import_spec (interpreted_string_literal) @import.module)",
+)
+
+_RUST = LangSpec(
+    name="rust",
+    ts_name="rust",
+    defs_query="""
+        (function_item name: (identifier) @name) @def.function
+        (struct_item name: (type_identifier) @name) @def.struct
+        (enum_item name: (type_identifier) @name) @def.enum
+        (trait_item name: (type_identifier) @name) @def.trait
+        (impl_item type: (type_identifier) @name) @def.impl
+        (mod_item name: (identifier) @name) @def.module
+    """,
+    calls_query="(call_expression function: (identifier) @callee)",
+    imports_query="""
+        (use_declaration (scoped_identifier) @import.module)
+        (use_declaration (identifier) @import.module)
+        (use_declaration (use_as_clause) @import.module)
+        (use_declaration (scoped_use_list) @import.module)
+    """,
+)
+
+_C = LangSpec(
+    name="c",
+    ts_name="c",
+    defs_query="""
+        (function_definition
+            declarator: (function_declarator declarator: (identifier) @name)) @def.function
+        (struct_specifier name: (type_identifier) @name) @def.struct
+    """,
+    calls_query="(call_expression function: (identifier) @callee)",
+    imports_query="""
+        (preproc_include path: (system_lib_string) @import.module)
+        (preproc_include path: (string_literal) @import.module)
+    """,
+)
+
+_CPP = LangSpec(
+    name="cpp",
+    ts_name="cpp",
+    defs_query="""
+        (function_definition
+            declarator: (function_declarator declarator: (identifier) @name)) @def.function
+        (class_specifier name: (type_identifier) @name) @def.class
+        (struct_specifier name: (type_identifier) @name) @def.struct
+        (namespace_definition name: (namespace_identifier) @name) @def.module
+    """,
+    calls_query="(call_expression function: (identifier) @callee)",
+    imports_query="""
+        (preproc_include path: (system_lib_string) @import.module)
+        (preproc_include path: (string_literal) @import.module)
+        (base_class_clause (type_identifier) @extends.base)
+    """,
+)
+
+_CSHARP = LangSpec(
+    name="csharp",
+    ts_name="csharp",
+    defs_query="""
+        (class_declaration name: (identifier) @name) @def.class
+        (interface_declaration name: (identifier) @name) @def.interface
+        (struct_declaration name: (identifier) @name) @def.struct
+        (enum_declaration name: (identifier) @name) @def.enum
+        (method_declaration name: (identifier) @name) @def.method
+        (constructor_declaration name: (identifier) @name) @def.method
+    """,
+    calls_query="(invocation_expression function: (identifier) @callee)",
+    imports_query="""
+        (using_directive (identifier) @import.module)
+        (using_directive (qualified_name) @import.module)
+        (base_list (identifier) @extends.base)
+    """,
+)
+
+_RUBY = LangSpec(
+    name="ruby",
+    ts_name="ruby",
+    defs_query="""
+        (class name: (constant) @name) @def.class
+        (module name: (constant) @name) @def.module
+        (method name: (identifier) @name) @def.method
+    """,
+    calls_query="(call method: (identifier) @callee)",
+    imports_query="(superclass (constant) @extends.base)",
+)
+
+_PHP = LangSpec(
+    name="php",
+    ts_name="php",
+    defs_query="""
+        (class_declaration name: (name) @name) @def.class
+        (interface_declaration name: (name) @name) @def.interface
+        (trait_declaration name: (name) @name) @def.trait
+        (method_declaration name: (name) @name) @def.method
+        (function_definition name: (name) @name) @def.function
+    """,
+    calls_query="(function_call_expression function: (name) @callee)",
+    imports_query="""
+        (namespace_use_declaration (namespace_use_clause (qualified_name) @import.module))
+        (base_clause (name) @extends.base)
+        (class_interface_clause (name) @implements.iface)
+    """,
+)
+
+_KOTLIN = LangSpec(
+    name="kotlin",
+    ts_name="kotlin",
+    defs_query="""
+        (class_declaration (type_identifier) @name) @def.class
+        (object_declaration (type_identifier) @name) @def.class
+        (function_declaration (simple_identifier) @name) @def.function
+    """,
+    calls_query="(call_expression (simple_identifier) @callee)",
+    imports_query="(import_header (identifier) @import.module)",
+)
+
+LANGS: dict[str, LangSpec] = {
+    s.name: s
+    for s in (
+        _PYTHON,
+        _JAVASCRIPT,
+        _TYPESCRIPT,
+        _JAVA,
+        _GO,
+        _RUST,
+        _C,
+        _CPP,
+        _CSHARP,
+        _RUBY,
+        _PHP,
+        _KOTLIN,
+    )
+}
+
+
+def has_grammar(lang: Optional[str]) -> bool:
+    """True if a tree-sitter grammar is loadable for `lang` (Tier B eligibility)."""
+    if not lang:
+        return False
+    try:
+        from tree_sitter_language_pack import get_language
+
+        return get_language(lang) is not None
+    except Exception:
+        return False
+
+
+def is_supported(lang: Optional[str]) -> bool:
+    """A language is supported if it has a Tier-A spec OR a loadable Tier-B grammar."""
+    if lang in LANGS:
+        return True
+    return has_grammar(lang)
+
+
+def spec_for(lang: Optional[str]) -> Optional[LangSpec]:
+    return LANGS.get(lang) if lang else None
+
+
+def has_full_graph(lang: Optional[str]) -> bool:
+    """True if `lang` has a Tier-A spec (full import/inheritance edges for refs/impact).
+
+    Tier-B languages (a loadable grammar but no hand-tuned spec) yield symbols and
+    best-effort call sites only, so their dependency graph is partial.
+    """
+    return spec_for(lang) is not None