witan-code 0.2.0__py3-none-any.whl

witan_code/queries_ts/python.scm

@@ -0,0 +1,29 @@
+; Python symbol extraction.
+; Capture names drive Symbol kind + edge construction in indexer.py.
+
+(function_definition
+  name: (identifier) @symbol.function)
+
+(class_definition
+  name: (identifier) @symbol.class)
+
+; Base classes — used for best-effort Inherits edges.
+(class_definition
+  superclasses: (argument_list (identifier) @inherit.base))
+
+; Imports — used for import-aware name resolution.
+(import_statement
+  name: (dotted_name (identifier) @import.name))
+
+(import_from_statement
+  name: (dotted_name (identifier) @import.name))
+
+(import_from_statement
+  name: (aliased_import (dotted_name (identifier) @import.name)))
+
+; Calls — best-effort Calls/References edges.
+(call
+  function: (identifier) @call.name)
+
+(call
+  function: (attribute attribute: (identifier) @call.name))

witan_code/queries_ts/sql.scm

@@ -0,0 +1,20 @@
+; SQL symbol extraction.
+;
+; dbt-style models are usually a bare `select` wrapped in Jinja ({{ }} / {% %})
+; that this grammar can't parse (each templated span becomes an isolated
+; ERROR node; the surrounding SQL still parses). Those files rarely contain a
+; CREATE statement — the CTEs inside the query are the only reliably
+; navigable structure, so they're captured alongside the CREATE-statement
+; definitions more common in migrations/raw SQL.
+
+(create_table
+  (object_reference) @symbol.table)
+
+(create_view
+  (object_reference) @symbol.table)
+
+(create_function
+  (object_reference) @symbol.function)
+
+(cte
+  (identifier) @symbol.cte)

witan_code/queries_ts/typescript.scm

@@ -0,0 +1,51 @@
+; TypeScript / JavaScript / JSX / TSX symbol extraction. All JS and TS variants
+; are parsed with the tsx grammar (a superset), so this single query covers them.
+
+(function_declaration
+  name: (identifier) @symbol.function)
+
+(generator_function_declaration
+  name: (identifier) @symbol.function)
+
+(class_declaration
+  name: (type_identifier) @symbol.class)
+
+(method_definition
+  name: (property_identifier) @symbol.method)
+
+; const Foo = () => {...} / const Foo = function () {...}
+(variable_declarator
+  name: (identifier) @symbol.function
+  value: [(arrow_function) (function_expression)])
+
+; class fields holding arrows: render = () => {...}
+(public_field_definition
+  name: (property_identifier) @symbol.method
+  value: (arrow_function))
+
+(interface_declaration
+  name: (type_identifier) @symbol.interface)
+
+(type_alias_declaration
+  name: (type_identifier) @symbol.type)
+
+(enum_declaration
+  name: (identifier) @symbol.enum)
+
+; extends Base — best-effort Inherits.
+(class_declaration
+  (class_heritage (extends_clause (identifier) @inherit.base)))
+
+; imports — best-effort resolution.
+(import_statement
+  (import_clause (identifier) @import.name))
+
+(import_statement
+  (import_clause (named_imports (import_specifier name: (identifier) @import.name))))
+
+; calls
+(call_expression
+  function: (identifier) @call.name)
+
+(call_expression
+  function: (member_expression property: (property_identifier) @call.name))

witan_code/queries_ts/yaml.scm

@@ -0,0 +1,5 @@
+; YAML symbol extraction. Each mapping key becomes a Symbol; nested keys get a
+; dotted qualified path (e.g. jobs.build.steps) so large configs are navigable.
+
+(block_mapping_pair
+  key: (flow_node) @symbol.key)

witan_code/repo.py

@@ -0,0 +1,282 @@
+import configparser
+import os
+import re
+import subprocess
+from pathlib import Path
+
+
+def detect(override: str | None = None, start: Path | None = None) -> str | None:
+    """
+    Return a canonical repo key (HTTPS URI) for ``start`` (or the cwd).
+
+    Resolution order:
+      1. ``override`` parameter (explicit caller value)
+      2. ``WITAN_REPO`` environment variable
+      3. ``git remote get-url origin`` (handles worktrees and multi-valued
+         config keys that ``configparser`` rejects)
+      4. ``origin`` remote URL parsed from the nearest ``.git/config``
+      5. directory name of the git root (fallback when no remote)
+      6. ``None`` — no repo context available
+    """
+    if override is not None:
+        return override or None
+
+    if env_repo := os.environ.get("WITAN_REPO"):
+        return env_repo
+
+    base = start or Path.cwd()
+
+    if url := _git_origin(base):
+        return _normalise(url)
+
+    git_config_path = _find_git_config(base)
+    if git_config_path is None:
+        return None
+
+    if slug := _parse_origin(git_config_path):
+        return slug
+
+    # No origin remote — fall back to the repo root directory name.
+    return git_config_path.parent.parent.name
+
+
+def _git_origin(start: Path) -> str | None:
+    """Resolve the ``origin`` remote URL via git itself.
+
+    git is the only correct parser of its own config: it resolves git worktrees
+    (where ``.git`` is a file) and tolerates multi-valued keys (e.g. several
+    ``fetch =`` lines) that Python's ``configparser`` rejects.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(start), "remote", "get-url", "origin"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _find_git_config(start: Path) -> Path | None:
+    """Walk up from ``start`` until a .git/config is found."""
+    for directory in [start, *start.parents]:
+        candidate = directory / ".git" / "config"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _parse_origin(git_config: Path) -> str | None:
+    """Parse .git/config and return the normalised ``origin`` remote URL."""
+    parser = configparser.RawConfigParser()
+    try:
+        parser.read(git_config)
+    except configparser.Error:
+        return None
+
+    section = 'remote "origin"'
+    if not parser.has_option(section, "url"):
+        return None
+
+    return _normalise(parser.get(section, "url"))
+
+
+def _normalise(url: str) -> str:
+    """
+    Normalise a git remote URL to its canonical HTTPS project URI.
+
+    Must match ``witan/repo.py::_normalise`` so the repo key — used
+    in symbol ids (``repo#path::Name``) and the Layer-1 ``symbol_refs`` that point
+    at them — is identical across both stores.
+
+    Examples
+    --------
+    git@github.com:mitodl/ol-django.git  →  https://github.com/mitodl/ol-django
+    https://github.com/mitodl/ol-django  →  https://github.com/mitodl/ol-django
+    """
+    url = re.sub(r"\.git$", "", url.strip()).rstrip("/")
+
+    if m := re.match(r"(?:ssh://)?[^@]+@([^:/]+)[:/](.+)", url):
+        return f"https://{m.group(1)}/{m.group(2)}"
+
+    if m := re.match(r"https?://(?:[^@/]+@)?([^/]+)/(.+)", url):
+        return f"https://{m.group(1)}/{m.group(2)}"
+
+    return url
+
+
+# Omnigraph scratch branch for detached-HEAD checkouts: never index a detached
+# state onto main (it would overwrite the shared view with an arbitrary commit).
+DETACHED_BRANCH = "_detached"
+
+_DEFAULT_BRANCHES = frozenset({"main", "master"})
+
+
+def sanitize_branch(name: str) -> str:
+    """Make a git branch name safe as an omnigraph branch name."""
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("_") or DETACHED_BRANCH
+
+
+def branch_store_name(name: str) -> str:
+    """Omnigraph branch name for a NON-DEFAULT git branch.
+
+    Omnigraph reserves ``main`` for the store's default branch, so a feature
+    branch literally named ``main`` (possible when the repo's default is
+    ``master``) maps to ``_main``. sanitize_branch strips leading
+    underscores, so no other git branch can produce a ``_``-prefixed name —
+    the underscore namespace (``_main``, ``_detached``) is collision-free.
+    """
+    sanitized = sanitize_branch(name)
+    return "_main" if sanitized == "main" else sanitized
+
+
+def current_branch(start: Path | None = None) -> str | None:
+    """Current git branch name for ``start`` (or the cwd).
+
+    Returns ``"HEAD"`` for a detached checkout (git's own convention) and
+    ``None`` outside a git repository or when git is unavailable.
+    """
+    base = start or Path.cwd()
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(base), "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def _origin_default_branch(base: Path) -> str | None:
+    """Short name of origin's HEAD branch (``main``), if resolvable locally."""
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(base),
+                "symbolic-ref",
+                "--short",
+                "refs/remotes/origin/HEAD",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    ref = result.stdout.strip()
+    return (ref.partition("/")[2] or None) if ref else None
+
+
+def _default_branch(base: Path) -> str | None:
+    """The repo's default branch: origin HEAD, else main/master by presence.
+
+    The local fallback prefers ``main`` over ``master`` when both exist so
+    the choice is deterministic; whichever loses maps to its own store branch
+    (collision-free either way). Returns None when no default is
+    recognizable — then every branch gets its own store branch and nothing
+    claims the store's main.
+    """
+    if default := _origin_default_branch(base):
+        return default
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(base), "branch", "--list", *_DEFAULT_BRANCHES],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    present = {line.lstrip("*+ ").strip() for line in result.stdout.splitlines()}
+    for name in ("main", "master"):
+        if name in present:
+            return name
+    return None
+
+
+def store_branch(start: Path | None = None) -> str | None:
+    """Omnigraph branch for the checkout at ``start``: ``None`` = store main.
+
+    The repo's default branch maps to the store's main branch; any other
+    branch maps through ``branch_store_name`` (so a non-default branch named
+    ``main`` gets ``_main``, never colliding with the store's default); a
+    detached HEAD maps to the ``_detached`` scratch branch.
+    """
+    base = start or Path.cwd()
+    branch = current_branch(base)
+    if branch is None:
+        return None
+    if branch == "HEAD":
+        return DETACHED_BRANCH
+    if branch == _default_branch(base):
+        return None
+    return branch_store_name(branch)
+
+
+def local_branches(start: Path | None = None) -> frozenset[str] | None:
+    """Store-branch names of all local git branches, or None when git fails.
+
+    Uses the same mapping as ``store_branch`` (``branch_store_name``) so
+    ``branches --prune`` compares like with like — a git branch named
+    ``main`` yields ``_main`` here, protecting its store branch from pruning.
+    """
+    base = start or Path.cwd()
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(base),
+                "for-each-ref",
+                "--format=%(refname:short)",
+                "refs/heads",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    return frozenset(
+        branch_store_name(line) for line in result.stdout.splitlines() if line.strip()
+    )
+
+
+def root(start: Path | None = None) -> Path | None:
+    """Return the git repository root for ``start`` (or the cwd).
+
+    Prefers ``git rev-parse --show-toplevel`` so worktrees and submodules (where
+    ``.git`` is a file, not a directory) resolve correctly; falls back to walking
+    for ``.git/config`` when the git binary is unavailable.
+    """
+    base = start or Path.cwd()
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(base), "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return Path(result.stdout.strip())
+    except OSError:
+        pass
+
+    git_config = _find_git_config(base)
+    if git_config is None:
+        return None
+    return git_config.parent.parent

witan_code/schema/bridge-schema.pg

@@ -0,0 +1,82 @@
+// Cross-Repo Context Bridge (Layer 2.5) — shared LOCAL store (_bridge.omni).
+//
+// One flat node per interface binding. Cross-repo linkages are computed by
+// GROUPING bindings on (kind, key_norm) where roles/repos differ — there are
+// NO link edges. An anchor-node + edge model would force every repo touching a
+// shared contract (e.g. env_var DATABASE_URL) to upsert the same node, maxing
+// write contention on a store with many concurrent writers (every repo's index
+// run + every PostToolUse reindex hook). Flat bindings are each scoped to their
+// own repo+file, so concurrent writers never touch the same row.
+//
+// Local-only and re-derivable, like the per-repo Layer-2 stores; never synced.
+//
+// Id convention:
+//   InterfaceBinding.slug = repo|file|kind|key_norm|role|symbol_id
+//     e.g. https://github.com/mitodl/mit-learn|main/settings.py|env_var|
+//          MITOL_APP_BASE_URL|consumer|...settings.py::<module>
+
+node InterfaceBinding {
+    slug: String @key
+    kind: enum(env_var, package, service, endpoint) @index
+    key: String @index            // raw as written (METHOD path, pkg name, env NAME)
+    key_norm: String @index       // normalized join key (collapsed path params, …)
+    role: enum(provider, consumer, shared) @index
+    repo: String @index           // canonical HTTPS repo URI (join key to Layer 2)
+    file: String @index           // repo-relative source path of the binding
+    repo_file: String @index      // "repo|file" — single-field key for per-file delete
+                                  // (delete `where` takes one condition, no compound `and`)
+    sub_kind: String?             // service anchor variant: repo | image | name
+    symbol_id: String?            // enclosing Symbol id (repo#path::Qn) when applicable
+    line: I32?
+    language: String?
+    framework: String?            // django | drf | pulumi | npm | nextjs | …
+    generic: String?              // "1" for stoplisted generic keys (DEBUG, PORT, …)
+    confidence: F32?              // 0.0–1.0 endpoint-consumer trust score (phantom
+                                  // suppression); null/absent treated as 1.0 by readers
+    symbol: String? @index        // canonical symbol string (docs/SYMBOL_FORMAT.md):
+                                  // {scheme}:{manager}:{package}:{version}:{descriptor}
+                                  // Stage-2 precise join key; "."-fields = unresolved
+    indexed_at: DateTime
+}
+
+// Per-repo symbol table (Stage 1 artifact — docs/SYMBOL_TABLE.md): one row per
+// (repo, role, symbol), aggregated from that repo's InterfaceBinding rows on
+// every bridge write. role=exported is the repo's public contract surface;
+// role=external is an unresolved reference to another repo's contract (a
+// RANGER-style import placeholder, redirected at read time by Stage 2 — no
+// cross-repo edges are ever written). Rows are repo-scoped, so concurrent
+// writers never touch the same row (same argument as InterfaceBinding).
+node RepoSymbol {
+    slug: String @key             // repo|role|symbol
+    repo: String @index           // canonical HTTPS repo URI
+    role: enum(exported, external) @index
+    symbol: String @index         // full canonical string (docs/SYMBOL_FORMAT.md)
+    scheme: String @index         // http | env | pkg | svc
+    descriptor: String @index     // precise Stage-2 join key (with scheme)
+    key_norm: String @index       // coarse join key — descriptor minus the
+                                  // method for http (consumer methods are "*")
+    manager: String?              // "." = unknown
+    package: String?              // "." = unresolved (typical for external)
+    version: String?
+    kind: String                  // binding kind: env_var | package | service | endpoint
+    n_refs: I32                   // occurrence count in this repo
+    confidence: F32?              // max occurrence confidence; 1.0 for exported
+    file: String?                 // exemplar occurrence (deterministic: min file/line)
+    line: I32?
+    indexed_at: DateTime
+}
+
+// One row per indexed repo: its declared (or fallback) package identity from
+// witan-code.toml (docs/PACKAGE_MAP.md). Overwritten on each full-repo index
+// (merge by slug). Qualifies provider symbols and backs the
+// known_provider_package confidence heuristic.
+node PackageMap {
+    slug: String @key             // canonical repo URI
+    repo: String @index
+    name: String @index           // canonical package name
+    manager: String               // pypi | npm | "."
+    version: String               // "main" = trunk-tracking
+    provides: String?             // JSON array of extra "manager:name" identities
+    declared: String?             // "1" when read from witan-code.toml (vs fallback)
+    indexed_at: DateTime
+}

witan_code/schema/code-schema.pg

@@ -0,0 +1,51 @@
+// Code Graph (Layer 2) — per-repo tree-sitter-derived symbol graph.
+//
+// One store per repository, kept LOCAL only (never synced to team S3).
+// Composes with witan (Layer 1) via soft symbol-ID references:
+// Layer-1 nodes store symbol ids of the form `repo#path::Qualified.Name`,
+// which resolve here without a hard cross-store edge.
+//
+// Id conventions:
+//   CodeFile.slug  = repo#relative/path.py
+//   Symbol.slug    = repo#relative/path.py::QualifiedName
+//                  e.g. github.com/mitodl/repo#app/svc.py::Service.run
+
+node CodeFile {
+    slug: String @key
+    repo: String @index
+    path: String @index
+    language: String @index
+    content_hash: String
+    indexed_at: DateTime
+}
+
+node Symbol {
+    slug: String @key
+    repo: String @index
+    file_id: String @index
+    name: String @index
+    qualified_name: String @index
+    kind: enum(function, method, class, module, variable, interface, type, enum, key, table, cte, block) @index
+    start_line: I32
+    end_line: I32
+    signature: String?
+    docstring: String?
+    decorators: [String]?      // @decorators on the def (framework semantics: routes, tasks, fixtures, …)
+    indexed_at: DateTime
+}
+
+// Defines: a file defines a symbol (top-level or nested).
+edge Defines: CodeFile -> Symbol
+
+// Contains: lexical nesting (class Contains method, module Contains class).
+edge Contains: Symbol -> Symbol
+
+// Calls / References: HEURISTIC name-resolved usage edges (best-effort).
+edge Calls: Symbol -> Symbol
+edge References: Symbol -> Symbol
+
+// Imports: a file imports a symbol (best-effort module/name resolution).
+edge Imports: CodeFile -> Symbol
+
+// Inherits: a class inherits from a base class (best-effort resolution).
+edge Inherits: Symbol -> Symbol