omphalos 1.1.1__py3-none-any.whl

omphalos/cache.py

@@ -0,0 +1,58 @@
+# omphalos/cache.py
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+CACHE_FILE = ".omphcache"
+# Increment this number when the cache data structure changes to invalidate old caches.
+# v3: symbols stored as structured dicts (kind/name/line/doc/label/children)
+# v4: function/method symbols gained optional `calls` and `raises` lists
+# v5: calls exclude signature/decorator/defaults and collapse chained callees
+CACHE_VERSION = 5
+
+def calculate_sha256(content: bytes) -> str:
+    """Calculate the SHA-256 checksum of raw file bytes for change detection."""
+    return hashlib.sha256(content).hexdigest()
+
+def load_cache(root_dir: Path) -> dict:
+    """Load symbol cache from .omphcache.
+
+    Returns an empty dict if the cache file does not exist, fails to parse,
+    or has an incompatible cache version.
+    """
+    cache_path = root_dir / CACHE_FILE
+    if not cache_path.exists():
+        return {}
+    try:
+        raw = json.loads(cache_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError, OSError):
+        return {}
+    # Discard cache created with a different schema version
+    if not isinstance(raw, dict) or raw.get("version") != CACHE_VERSION:
+        return {}
+    files = raw.get("files")
+    return files if isinstance(files, dict) else {}
+
+def save_cache(root_dir: Path, cache: dict):
+    """Save symbol cache to .omphcache atomically.
+
+    Writes to a temporary file first and replaces the target file via os.replace
+    to prevent file corruption if interrupted.
+    """
+    cache_path = root_dir / CACHE_FILE
+    payload = {"version": CACHE_VERSION, "files": cache}
+    fd, tmp_name = tempfile.mkstemp(
+        dir=cache_path.parent, prefix=f"{CACHE_FILE}.", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2, ensure_ascii=False)
+        os.replace(tmp_name, cache_path)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise

omphalos/cli.py

@@ -0,0 +1,181 @@
+# omphalos/cli.py
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+import typer
+
+from omphalos.cache import calculate_sha256, load_cache, save_cache
+from omphalos.ignore import (
+    IGNORE_FILE,
+    NotAGitRepoError,
+    collect_files,
+    collect_git_files,
+    ensure_ignore_file,
+    load_ignore_spec,
+)
+from omphalos.parser import SUPPORTED_EXTENSIONS, extract_symbols
+from omphalos.render import render_json, render_markdown
+
+INDEX_FILE = "INDEX.md"
+FORMATS = ("markdown", "json")
+
+app = typer.Typer(
+    add_completion=False,
+)
+
+
+def _package_version() -> str:
+    """Read the installed package version (single source of truth: pyproject.toml)."""
+    try:
+        return version("omphalos")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+def _version_callback(value: bool):
+    """Callback for --version flag to print the version and exit immediately."""
+    if value:
+        typer.echo(f"omph {_package_version()} (omphalos)")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True,
+        help="Show version and exit.",
+    )
+):
+    """Omphalos - Codebase symbol indexer for LLMs.
+
+    Quick start:
+
+      omph scan                  Scan repository and generate INDEX.md
+
+      omph scan --check          Verify index is up to date (exit 1 if stale)
+
+      omph scan --git-only       Scan only files tracked by Git
+
+      omph scan --format json    Export index as JSON
+
+      omph init                  Create a default .omphignore file
+
+    For full options of each command, run: omph COMMAND --help
+    """
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+@app.command()
+def init(
+    target_dir: str = typer.Argument(".", help="Target directory to initialize")
+):
+    """Create a default .omphignore file if not present in the target directory."""
+    root = Path(target_dir).resolve()
+    created = ensure_ignore_file(root)
+    if created:
+        typer.echo(f"Created {created.name}")
+    else:
+        typer.echo(f"Ignore file already exists ({IGNORE_FILE}).")
+
+
+@app.command()
+def scan(
+    target_dir: str = typer.Argument(".", help="Target directory to scan"),
+    output: Path = typer.Option(
+        None, "--output", "-o",
+        help=f"Index output path (default: {INDEX_FILE} in the target directory)",
+    ),
+    fmt: str = typer.Option(
+        "markdown", "--format", help=f"Output format: {' or '.join(FORMATS)}"
+    ),
+    no_cache: bool = typer.Option(
+        False, "--no-cache", help="Ignore cached symbols and re-parse every file"
+    ),
+    check: bool = typer.Option(
+        False, "--check",
+        help="Verify the index is up to date without writing; exit 1 if stale",
+    ),
+    git_only: bool = typer.Option(
+        False, "--git-only", help="Only scan files tracked by git (requires a git repository)"
+    ),
+):
+    """Scan multi-language codebase files and generate a symbol index with line numbers and docstrings."""
+    root = Path(target_dir).resolve()
+    if fmt not in FORMATS:
+        typer.echo(f"error: invalid --format '{fmt}' (choose from {', '.join(FORMATS)})", err=True)
+        raise typer.Exit(2)
+
+    if not check:
+        created = ensure_ignore_file(root)
+        if created:
+            typer.echo(f"Created default {created.name}")
+
+    spec = load_ignore_spec(root)
+
+    try:
+        if git_only:
+            target_files = collect_git_files(root, spec, SUPPORTED_EXTENSIONS)
+        else:
+            target_files = collect_files(root, spec, SUPPORTED_EXTENSIONS)
+    except NotAGitRepoError as e:
+        typer.echo(f"error: --git-only requires a git repository ({e})", err=True)
+        raise typer.Exit(1) from e
+
+    cache = {} if no_cache else load_cache(root)
+    new_cache = {}
+    files_data: dict[str, dict] = {}
+    failed = 0
+
+    with typer.progressbar(target_files, label="Indexing", file=sys.stderr) as progress:
+        for file_path in progress:
+            rel_posix = file_path.relative_to(root).as_posix()
+            try:
+                content = file_path.read_bytes()
+            except OSError as e:
+                typer.echo(f"error: cannot read {rel_posix}: {e}", err=True)
+                failed += 1
+                continue
+
+            file_hash = calculate_sha256(content)
+            # Check whether cached symbol data is reusable
+            cached = cache.get(rel_posix)
+            if cached and cached.get("hash") == file_hash and isinstance(cached.get("data"), dict):
+                data = cached["data"]
+            else:
+                data = extract_symbols(file_path, content)
+
+            new_cache[rel_posix] = {"hash": file_hash, "data": data}
+            files_data[rel_posix] = data
+
+            if data.get("error"):
+                typer.echo(f"error: cannot parse {rel_posix}: {data['error']}", err=True)
+                failed += 1
+
+    renderer = render_json if fmt == "json" else render_markdown
+    rendered = renderer(files_data)
+    index_path = output if output else root / INDEX_FILE
+
+    if check:
+        existing = index_path.read_text(encoding="utf-8") if index_path.exists() else None
+        if existing == rendered:
+            typer.echo("Index is up to date.")
+        else:
+            typer.echo(f"Index is out of date: {index_path}", err=True)
+            raise typer.Exit(1)
+        return
+
+    # Write index file and persist updated cache
+    index_path.write_text(rendered, encoding="utf-8")
+    save_cache(root, new_cache)
+    summary = f"Updated {index_path.name} successfully ({len(target_files)} files scanned)."
+    if failed:
+        summary = f"Updated {index_path.name} ({len(target_files)} files scanned, {failed} failed)."
+    typer.echo(summary)
+
+
+if __name__ == "__main__":
+    app()

omphalos/ignore.py

@@ -0,0 +1,168 @@
+# omphalos/ignore.py
+import os
+import subprocess
+from collections.abc import Container
+from pathlib import Path
+
+import pathspec
+
+DEFAULT_IGNORES = [
+    ".git/",
+    ".omphcache",
+    ".omphalos_cache.json",
+    "INDEX.md",
+    ".omphalos_index",
+    ".omphignore",
+    ".omphalos_ignore",
+    "__pycache__/",
+    ".pytest_cache/",
+    ".mypy_cache/",
+    ".ruff_cache/",
+    "node_modules/",
+    ".venv/",
+    "venv/",
+    "dist/",
+    "build/",
+    "*.lock",
+    "*.min.js",
+]
+
+IGNORE_TEMPLATE = """# .omphignore
+# Files and directories to ignore when scanning codebase symbols.
+# Uses gitignore pattern syntax.
+
+# Version control & environments
+.git/
+.venv/
+venv/
+node_modules/
+
+# Cache & build outputs
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# Omphalos cache & output
+.omphcache
+INDEX.md
+
+# Locks & minified files
+*.lock
+*.min.js
+"""
+
+IGNORE_FILE = ".omphignore"
+
+def ensure_ignore_file(root_dir: Path) -> Path | None:
+    """Create a default .omphignore file if it does not already exist.
+
+    Returns:
+        Path of the newly created ignore file, or None if it already exists.
+    """
+    target = root_dir / IGNORE_FILE
+    if target.exists():
+        return None
+
+    target.write_text(IGNORE_TEMPLATE.strip() + "\n", encoding="utf-8")
+    return target
+
+def load_ignore_spec(root_dir: Path) -> pathspec.PathSpec:
+    """Load and merge all ignore rules into a unified PathSpec.
+
+    Precedence order:
+    1. DEFAULT_IGNORES (e.g., .git, venv, caches)
+    2. Rules from .gitignore (if present)
+    3. Rules from .omphignore (and legacy .omphalos_ignore if present)
+
+    Returns:
+        GitIgnoreSpec matcher for filtering paths.
+    """
+    patterns = list(DEFAULT_IGNORES)
+
+    # Order matters: ignore files come after .gitignore to allow overriding with negation patterns
+    for filename in [".gitignore", ".omphalos_ignore", IGNORE_FILE]:
+        ignore_file = root_dir / filename
+        if ignore_file.exists():
+            patterns.extend(ignore_file.read_text(encoding="utf-8").splitlines())
+
+    # Use GitIgnoreSpec for git-compliant semantics (negation, directory matching)
+    return pathspec.GitIgnoreSpec.from_lines("gitignore", patterns)
+
+
+def collect_files(
+    root_dir: Path, spec: pathspec.PathSpec, supported_extensions: Container[str]
+) -> list[Path]:
+    """Recursively collect supported files, pruning directories matched by ignore spec.
+
+    Note: Directories matching ignore rules are pruned immediately during os.walk,
+    matching git behavior (negation patterns cannot re-include files within an
+    ignored directory).
+    """
+    target_files: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root_dir):
+        rel_dir = Path(dirpath).relative_to(root_dir)
+        dirnames[:] = [
+            d for d in dirnames
+            if not spec.match_file(f"{(rel_dir / d).as_posix()}/")
+        ]
+        for f in filenames:
+            p = Path(f)
+            if p.suffix.lower() in supported_extensions:
+                rel_file = (rel_dir / f).as_posix()
+                if not spec.match_file(rel_file):
+                    target_files.append(root_dir / rel_file)
+
+    target_files.sort()
+    return target_files
+
+
+class NotAGitRepoError(Exception):
+    pass
+
+
+def collect_git_files(
+    root_dir: Path, spec: pathspec.PathSpec, supported_extensions: Container[str]
+) -> list[Path]:
+    """Collect only files tracked by Git (via git ls-files), filtered by spec and extension.
+
+    Args:
+        root_dir: Root directory of the Git repository.
+        spec: PathSpec ignore filter.
+        supported_extensions: Collection of supported file extensions.
+
+    Returns:
+        List of matching file Paths that exist in the working tree.
+
+    Raises:
+        NotAGitRepoError: If root_dir is not inside a git repository or git binary is missing.
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "ls-files", "-z"], cwd=root_dir,
+            capture_output=True, check=False,
+        )
+    except FileNotFoundError as e:
+        raise NotAGitRepoError("git command not found") from e
+    if proc.returncode != 0:
+        msg = proc.stderr.decode("utf-8", errors="replace").strip()
+        raise NotAGitRepoError(msg or "not a git repository")
+
+    target_files: list[Path] = []
+    for chunk in proc.stdout.split(b"\0"):
+        if not chunk:
+            continue
+        rel = chunk.decode("utf-8", errors="replace").replace("\\", "/")
+        p = Path(rel)
+        if p.suffix.lower() not in supported_extensions:
+            continue
+        if not (root_dir / p).is_file():
+            continue  # Present in git index but deleted from working tree
+        if not spec.match_file(rel):
+            target_files.append(root_dir / p)
+
+    target_files.sort()
+    return target_files

omphalos/parser.py

@@ -0,0 +1,519 @@
+# omphalos/parser.py
+from pathlib import Path
+from typing import Any
+
+import tree_sitter as ts
+import tree_sitter_go as tsgo
+import tree_sitter_javascript as tsjs
+import tree_sitter_python as tspython
+import tree_sitter_rust as tsrust
+import tree_sitter_typescript as tsts
+
+# Initialize Languages
+_LANG_PYTHON = ts.Language(tspython.language())
+_LANG_TS = ts.Language(tsts.language_typescript())
+_LANG_TSX = ts.Language(tsts.language_tsx())
+_LANG_JS = ts.Language(tsjs.language())
+_LANG_GO = ts.Language(tsgo.language())
+_LANG_RUST = ts.Language(tsrust.language())
+
+# Parsers
+_PARSER_PYTHON = ts.Parser(_LANG_PYTHON)
+_PARSER_TS = ts.Parser(_LANG_TS)
+_PARSER_TSX = ts.Parser(_LANG_TSX)
+_PARSER_JS = ts.Parser(_LANG_JS)
+_PARSER_GO = ts.Parser(_LANG_GO)
+_PARSER_RUST = ts.Parser(_LANG_RUST)
+
+SUPPORTED_EXTENSIONS = {
+    ".py": "python",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "tsx",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".go": "go",
+    ".rs": "rust",
+}
+
+
+def _text(node: ts.Node) -> str:
+    """Decode Tree-sitter AST node text bytes to a UTF-8 string."""
+    return (node.text or b"").decode("utf-8", errors="replace")
+
+
+def _mk_symbol(kind: str, name: str, node: ts.Node, label: str, doc: str = "") -> dict[str, Any]:
+    """Create a standardized symbol schema dictionary.
+
+    Args:
+        kind: Type of symbol (e.g., function, class, method, struct, interface).
+        name: Identifier name of the symbol.
+        node: Originating Tree-sitter AST node for extracting 1-indexed start line.
+        label: Human/LLM-readable display label.
+        doc: First-line summary or docstring (if available).
+    """
+    return {
+        "kind": kind,
+        "name": name,
+        "label": label,
+        "line": node.start_point[0] + 1,
+        "doc": doc,
+        "exported": False,
+        "children": [],
+    }
+
+
+def _prev_comment_block(node: ts.Node) -> list[ts.Node]:
+    """Return contiguous comment nodes immediately preceding the node (in top-to-bottom order).
+
+    Note: Certain grammars (like Rust) include the trailing newline in line_comment,
+    causing end_point to fall on the next line. We strip trailing newlines before checking contiguity.
+    """
+    def content_end_row(c: ts.Node) -> int:
+        text = c.text or b""
+        return c.end_point[0] - (len(text) - len(text.rstrip(b"\r\n")))
+
+    block = []
+    cur = node.prev_named_sibling
+    row = node.start_point[0]
+    while cur is not None and cur.type in ("comment", "line_comment") and content_end_row(cur) == row - 1:
+        block.append(cur)
+        row = cur.start_point[0]
+        cur = cur.prev_named_sibling
+    block.reverse()
+    return block
+
+
+def _get_py_docstring(node: ts.Node) -> str:
+    """Extract the first line of a Python function or class docstring, if present."""
+    body = node.child_by_field_name("body")
+    if body and len(body.named_children) > 0:
+        first = body.named_children[0]
+        if first.type == "expression_statement" and len(first.named_children) > 0:
+            str_node = first.named_children[0]
+            if str_node.type == "string":
+                # Intentional charset strip: remove repeated quotes (""" or ''') and surrounding whitespace
+                raw = _text(str_node).strip("\"' \n\r\t")  # noqa: B005
+                return raw.splitlines()[0].strip() if raw else ""
+    return ""
+
+
+def _go_doc(node: ts.Node) -> str:
+    """Go doc comment: first line of comment block attached above declaration (skipping //go: directives)."""
+    for c in _prev_comment_block(node):
+        t = _text(c).strip()
+        if t.startswith("//go:"):
+            continue
+        return t.removeprefix("//").strip()
+    return ""
+
+
+def _rust_doc(node: ts.Node) -> str:
+    """Rust doc comment: first line of /// comment block attached above an item."""
+    for c in _prev_comment_block(node):
+        t = _text(c).strip()
+        if t.startswith("///"):
+            line = t.removeprefix("///").strip()
+            if line:
+                return line
+    return ""
+
+
+def _ts_doc(node: ts.Node) -> str:
+    """JSDoc comment: first line containing content within a /** ... */ block attached above declaration."""
+    for c in _prev_comment_block(node):
+        t = _text(c).strip()
+        if not t.startswith("/**"):
+            continue
+        for raw in t.splitlines():
+            line = raw.strip().removeprefix("/**").removeprefix("*").removesuffix("*/").strip()
+            if line:
+                return line
+    return ""
+
+
+def _unwrap_decorated(node: ts.Node) -> ts.Node:
+    """Unwrap core definition node (function/class) from a Python decorated_definition."""
+    if node.type == "decorated_definition":
+        for child in node.named_children:
+            if child.type in ("function_definition", "async_function_definition", "class_definition"):
+                return child
+    return node
+
+
+# Node-type rules for internal logic extraction, per language family:
+# {call-like node type: field name holding the callee expression}
+_CALL_FIELDS = {
+    "python": {"call": "function"},
+    "ts_js": {"call_expression": "function", "new_expression": "constructor"},
+    "go": {"call_expression": "function"},
+    "rust": {"call_expression": "function"},
+}
+# Statement types that propagate errors outward (Go/Rust use return values instead)
+_RAISE_NODES = {"python": "raise_statement", "ts_js": "throw_statement"}
+
+
+def _raise_target(node: ts.Node) -> str:
+    """Extract the exception type from a raise/throw statement.
+
+    Covers `raise X`, `raise X(...)`, `throw new X(...)`, and bare identifier re-throws.
+    """
+    if not node.named_children:
+        return ""
+    first = node.named_children[0]
+    if first.type in ("call", "call_expression"):
+        callee = first.child_by_field_name("function")
+        return _text(callee) if callee else ""
+    if first.type == "new_expression":
+        ctor = first.child_by_field_name("constructor")
+        return _text(ctor) if ctor else ""
+    if first.type in ("identifier", "scoped_identifier", "scoped_type_identifier"):
+        return _text(first)
+    return ""
+
+
+def _is_simple_chain(node: ts.Node) -> bool:
+    """True ถ้า node เป็นโซ่ identifier เรียบ ๆ เช่น `self`, `log`, `file_path.relative_to`
+
+    ใช้แยกว่า callee ควรแสดงเต็ม (`self._flush`) หรือย่อเหลือ property ปลาย
+    เมื่อ object ต้นทางเป็นนิพจน์ซับซ้อน (`(a / b).as_posix`, `f(x).strip`)
+    """
+    if node.type in ("identifier", "type_identifier", "self", "this", "super",
+                     "field_identifier", "property_identifier"):
+        return True
+    kids = node.named_children
+    if node.type in ("attribute", "member_expression", "selector_expression", "field_expression",
+                     "scoped_identifier", "scoped_type_identifier") and kids:
+        return _is_simple_chain(kids[0])
+    return False
+
+
+def _callee_name(callee: ts.Node) -> str:
+    """Compact callee name: dotted chain เต็มถ้าต้นทางเรียบ, ไม่งั้นเหลือเฉพาะชื่อปลาย"""
+    kids = callee.named_children
+    if len(kids) < 2 or _is_simple_chain(kids[0]):
+        return _text(callee)
+    return _text(kids[-1])
+
+
+def _collect_logic(node: ts.Node, family: str) -> tuple[list[str], list[str]]:
+    """Collect deduplicated internal call targets and raised exception types of a function body.
+
+    Only names are recorded (not arguments) to keep the index compact yet signal-dense.
+    Raise/throw subtrees are not descended into: the raised expression is an error type,
+    not a call target, and would otherwise appear in both lists.
+    """
+    call_fields = _CALL_FIELDS[family]
+    raise_type = _RAISE_NODES.get(family)
+    calls: list[str] = []
+    raises: list[str] = []
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if raise_type and n.type == raise_type:
+            name = _raise_target(n)
+            if name and name not in raises:
+                raises.append(name)
+            continue
+        field = call_fields.get(n.type)
+        if field:
+            callee = n.child_by_field_name(field)
+            if callee:
+                name = _callee_name(callee)
+                if name and name not in calls:
+                    calls.append(name)
+        stack.extend(reversed(n.named_children))
+    return calls, raises
+
+
+def _annotate_logic(sym: dict[str, Any], node: ts.Node, family: str, force: bool = False):
+    """Attach `calls`/`raises` to function-like symbols (keys added only when non-empty).
+
+    Scans only the function *body*: calls appearing in signatures, decorators,
+    or parameter defaults are declaration-time expressions, not runtime logic.
+    """
+    if not force and sym["kind"] not in ("function", "method"):
+        return
+    body = node.child_by_field_name("body") or node
+    calls, raises = _collect_logic(body, family)
+    if calls:
+        sym["calls"] = calls
+    if raises:
+        sym["raises"] = raises
+
+
+def _extract_python(root_node: ts.Node) -> list[dict[str, Any]]:
+    """Extract all symbols from a Python AST (classes, methods, functions)."""
+    symbols = []
+    for raw_node in root_node.children:
+        node = _unwrap_decorated(raw_node)
+        if node.type == "class_definition":
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                cls = _mk_symbol("class", name, node, f"class `{name}`", _get_py_docstring(node))
+
+                body = node.child_by_field_name("body")
+                for child_raw in (body.named_children if body else []):
+                    child = _unwrap_decorated(child_raw)
+                    if child.type in ("function_definition", "async_function_definition"):
+                        m_name_node = child.child_by_field_name("name")
+                        if m_name_node:
+                            m_name = _text(m_name_node)
+                            m = _mk_symbol("method", m_name, child, f"`{m_name}()`", _get_py_docstring(child))
+                            _annotate_logic(m, child, "python")
+                            cls["children"].append(m)
+                symbols.append(cls)
+
+        elif node.type in ("function_definition", "async_function_definition"):
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                fn = _mk_symbol("function", name, node, f"`{name}()`", _get_py_docstring(node))
+                _annotate_logic(fn, node, "python")
+                symbols.append(fn)
+
+    return symbols
+
+
+def _ts_symbol(target: ts.Node, doc_node: ts.Node, exported: bool) -> dict[str, Any] | None:
+    """Extract a structured symbol dictionary from a TypeScript/JavaScript declaration node."""
+    prefix = "export " if exported else ""
+
+    if target.type == "interface_declaration":
+        name_node = target.child_by_field_name("name")
+        if name_node:
+            return _mk_symbol("interface", _text(name_node), target,
+                              f"{prefix}interface `{_text(name_node)}`", _ts_doc(doc_node))
+
+    elif target.type == "type_alias_declaration":
+        name_node = target.child_by_field_name("name")
+        if name_node:
+            return _mk_symbol("type", _text(name_node), target,
+                              f"{prefix}type `{_text(name_node)}`", _ts_doc(doc_node))
+
+    elif target.type == "function_declaration":
+        name_node = target.child_by_field_name("name")
+        if name_node:
+            fn = _mk_symbol("function", _text(name_node), target,
+                            f"{prefix}function `{_text(name_node)}()`", _ts_doc(doc_node))
+            _annotate_logic(fn, target, "ts_js")
+            return fn
+
+    elif target.type == "class_declaration":
+        name_node = target.child_by_field_name("name")
+        if name_node:
+            cls = _mk_symbol("class", _text(name_node), target,
+                             f"{prefix}class `{_text(name_node)}`", _ts_doc(doc_node))
+            body = target.child_by_field_name("body")
+            if body:
+                for item in body.named_children:
+                    if item.type == "method_definition":
+                        m_name_node = item.child_by_field_name("name")
+                        if m_name_node:
+                            m = _mk_symbol(
+                                "method", _text(m_name_node), item, f"`{_text(m_name_node)}()`", _ts_doc(item))
+                            _annotate_logic(m, item, "ts_js")
+                            cls["children"].append(m)
+            return cls
+
+    elif target.type == "lexical_declaration":
+        kind_word = _text(target.children[0]) if target.children else "const"
+        kind = "constant" if kind_word == "const" else "variable"
+        for decl in target.named_children:
+            if decl.type == "variable_declarator":
+                name_node = decl.child_by_field_name("name")
+                value_node = decl.child_by_field_name("value")
+                if name_node:
+                    name = _text(name_node)
+                    is_fn = value_node and value_node.type in ("arrow_function", "function_expression")
+                    suffix = "()" if is_fn else ""
+                    sym = _mk_symbol(kind, name, target, f"{prefix}{kind_word} `{name}{suffix}`", _ts_doc(doc_node))
+                    if is_fn and value_node:
+                        # Arrow/function-expression constants behave as functions: collect their logic
+                        _annotate_logic(sym, value_node, "ts_js", force=True)
+                    return sym
+
+    return None
+
+
+def _extract_ts_js(root_node: ts.Node) -> list[dict[str, Any]]:
+    """Extract symbols from TypeScript and JavaScript ASTs (functions, classes, interfaces, types, exports)."""
+    symbols = []
+    for node in root_node.children:
+        exported = False
+        target = node
+
+        if node.type == "export_statement":
+            exported = True
+            named = [c for c in node.named_children if c.type not in ("comment",)]
+            if named:
+                target = named[0]
+
+        # Doc comment is attached above export_statement (or declaration itself if not exported)
+        sym = _ts_symbol(target, node, exported)
+        if sym:
+            sym["exported"] = exported
+            symbols.append(sym)
+
+    return symbols
+
+
+def _extract_go(root_node: ts.Node) -> list[dict[str, Any]]:
+    """Extract symbols from Go AST (types, structs, interfaces, functions, methods with receivers)."""
+    symbols = []
+    for node in root_node.children:
+        if node.type == "type_declaration":
+            specs = [c for c in node.named_children if c.type == "type_spec"]
+            for spec in specs:
+                name_node = spec.child_by_field_name("name")
+                type_val = spec.child_by_field_name("type")
+                if not name_node or type_val is None:
+                    continue
+                t_kind = {"struct_type": "struct", "interface_type": "interface"}.get(type_val.type, "type")
+                suffix = {"struct": " (struct)", "interface": " (interface)"}.get(t_kind, "")
+                name = _text(name_node)
+                # Grouped type block: doc comment sits above type_spec; single type: above type_declaration
+                doc = _go_doc(spec)
+                if not doc and len(specs) == 1:
+                    doc = _go_doc(node)
+                symbols.append(_mk_symbol(t_kind, name, spec, f"type `{name}`{suffix}", doc))
+
+        elif node.type == "function_declaration":
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                fn = _mk_symbol("function", name, node, f"func `{name}()`", _go_doc(node))
+                _annotate_logic(fn, node, "go")
+                symbols.append(fn)
+
+        elif node.type == "method_declaration":
+            recv = node.child_by_field_name("receiver")
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                recv_str = _text(recv) if recv else ""
+                m = _mk_symbol("method", name, node, f"func `{recv_str} {name}()`", _go_doc(node))
+                _annotate_logic(m, node, "go")
+                symbols.append(m)
+
+    return symbols
+
+
+def _rust_vis(node: ts.Node) -> str:
+    """Extract visibility modifier string (e.g., 'pub') from a Rust item node."""
+    for c in node.children:
+        if c.type == "visibility_modifier":
+            return _text(c)
+    return ""
+
+
+def _extract_rust(root_node: ts.Node) -> list[dict[str, Any]]:
+    """Extract symbols from Rust AST (structs, enums, traits, functions, and impl blocks)."""
+    symbols = []
+    for node in root_node.children:
+        vis = _rust_vis(node)
+        vis_str = f"{vis} " if vis else ""
+
+        if node.type == "struct_item":
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                symbols.append(_mk_symbol("struct", name, node, f"{vis_str}struct `{name}`", _rust_doc(node)))
+
+        elif node.type == "enum_item":
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                symbols.append(_mk_symbol("enum", name, node, f"{vis_str}enum `{name}`", _rust_doc(node)))
+
+        elif node.type == "trait_item":
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                symbols.append(_mk_symbol("trait", name, node, f"{vis_str}trait `{name}`", _rust_doc(node)))
+
+        elif node.type == "function_item":
+            name_node = node.child_by_field_name("name")
+            if name_node:
+                name = _text(name_node)
+                fn = _mk_symbol("function", name, node, f"{vis_str}fn `{name}()`", _rust_doc(node))
+                _annotate_logic(fn, node, "rust")
+                symbols.append(fn)
+
+        elif node.type == "impl_item":
+            trait_node = node.child_by_field_name("trait")
+            type_node = node.child_by_field_name("type")
+            impl_header = ""
+            if trait_node and type_node:
+                impl_header = f"{_text(trait_node)} for {_text(type_node)}"
+            elif type_node:
+                impl_header = _text(type_node)
+
+            if impl_header:
+                impl = _mk_symbol("impl", impl_header, node, f"impl `{impl_header}`", _rust_doc(node))
+                body = node.child_by_field_name("body")
+                if body:
+                    for item in body.named_children:
+                        if item.type == "function_item":
+                            m_vis = _rust_vis(item)
+                            m_vis_str = f"{m_vis} " if m_vis else ""
+                            m_name_node = item.child_by_field_name("name")
+                            if m_name_node:
+                                m_name = _text(m_name_node)
+                                m = _mk_symbol(
+                                    "method", m_name, item, f"`{m_vis_str}fn {m_name}()`", _rust_doc(item))
+                                _annotate_logic(m, item, "rust")
+                                impl["children"].append(m)
+                symbols.append(impl)
+
+    return symbols
+
+
+def extract_symbols(file_path: Path, content: bytes | None = None) -> dict[str, Any]:
+    """Parse file content using the appropriate Tree-sitter language grammar and extract code symbols.
+
+    Args:
+        file_path: Path to the target source file (used for extension detection and reading content if not given).
+        content: Optional raw bytes content of the file.
+
+    Returns:
+        Dictionary containing extracted symbols or an error message if parsing fails.
+    """
+    ext = file_path.suffix.lower()
+    lang_type = SUPPORTED_EXTENSIONS.get(ext)
+    if not lang_type:
+        return {"symbols": []}
+
+    if content is None:
+        try:
+            content = file_path.read_bytes()
+        except Exception as e:
+            return {"error": str(e), "symbols": []}
+
+    try:
+        if lang_type == "python":
+            tree = _PARSER_PYTHON.parse(content)
+            symbols = _extract_python(tree.root_node)
+        elif lang_type == "typescript":
+            tree = _PARSER_TS.parse(content)
+            symbols = _extract_ts_js(tree.root_node)
+        elif lang_type == "tsx":
+            tree = _PARSER_TSX.parse(content)
+            symbols = _extract_ts_js(tree.root_node)
+        elif lang_type == "javascript":
+            tree = _PARSER_JS.parse(content)
+            symbols = _extract_ts_js(tree.root_node)
+        elif lang_type == "go":
+            tree = _PARSER_GO.parse(content)
+            symbols = _extract_go(tree.root_node)
+        elif lang_type == "rust":
+            tree = _PARSER_RUST.parse(content)
+            symbols = _extract_rust(tree.root_node)
+        else:
+            symbols = []
+    except Exception as e:
+        return {"error": str(e), "symbols": []}
+
+    return {"symbols": symbols}

omphalos/render.py

@@ -0,0 +1,69 @@
+# omphalos/render.py
+"""Render structured symbol data (from parser/cache) into target output formats."""
+import json
+from typing import Any
+
+
+def render_markdown(files_data: dict[str, dict[str, Any]]) -> str:
+    """Render structured symbol data into Markdown format for LLM context or human reading.
+
+    Args:
+        files_data: Symbol mapping keyed by relative file paths.
+
+    Returns:
+        Formatted Markdown index grouping symbols under file headers.
+    """
+    lines = ["# Codebase Symbol Index\n"]
+    for path, data in files_data.items():
+        symbols = data.get("symbols", [])
+        if not symbols:
+            continue
+        lines.append(f"## {path}")
+        _render_md_symbols(symbols, depth=0, lines=lines)
+        lines.append("")
+    return "\n".join(lines)
+
+
+def _render_md_symbols(symbols: list[dict[str, Any]], depth: int, lines: list[str]):
+    """Recursively render symbols as nested Markdown bullet points.
+
+    Includes label, @line number, docstring summary, and nested child symbols
+    (such as methods within classes or trait implementations).
+    """
+    for sym in symbols:
+        text = f"{'  ' * depth}- {sym['label']}"
+        if sym.get("line"):
+            text += f" @{sym['line']}"
+        if sym.get("doc"):
+            text += f": {sym['doc']}"
+        # Internal logic detail: deduplicated call targets and raised exceptions (inline, keeps tree flat)
+        detail = []
+        if sym.get("calls"):
+            detail.append("calls: " + ", ".join(f"`{c}`" for c in sym["calls"]))
+        if sym.get("raises"):
+            detail.append("raises: " + ", ".join(f"`{r}`" for r in sym["raises"]))
+        if detail:
+            text += f" ({'; '.join(detail)})"
+        lines.append(text)
+        _render_md_symbols(sym.get("children", []), depth + 1, lines)
+
+
+def render_json(files_data: dict[str, dict[str, Any]]) -> str:
+    """Render structured symbol data into a JSON string for programmatic consumption.
+
+    Args:
+        files_data: Symbol mapping keyed by relative file paths.
+
+    Returns:
+        Indented JSON string conforming to the Omphalos schema format.
+    """
+    payload = {
+        "tool": "omphalos",
+        "format_version": 1,
+        "files": {
+            path: {"symbols": data.get("symbols", [])}
+            for path, data in files_data.items()
+            if data.get("symbols")
+        },
+    }
+    return json.dumps(payload, indent=2, ensure_ascii=False)

omphalos-1.1.1.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.3
+Name: omphalos
+Version: 1.1.1
+Summary: Codebase symbol index for LLMs
+Keywords: llm,indexer,tree-sitter,ast,codebase,symbols,agent
+Author: snui1s
+Author-email: snui1s <snailsqz@gmail.com>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: typer>=0.12.0
+Requires-Dist: pathspec>=1.1
+Requires-Dist: tree-sitter>=0.24.0
+Requires-Dist: tree-sitter-python>=0.25.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter-javascript>=0.25.0
+Requires-Dist: tree-sitter-go>=0.25.0
+Requires-Dist: tree-sitter-rust>=0.24.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/snui1s/Omphalos
+Project-URL: Repository, https://github.com/snui1s/Omphalos
+Project-URL: Issues, https://github.com/snui1s/Omphalos/issues
+Project-URL: Changelog, https://github.com/snui1s/Omphalos/releases
+Description-Content-Type: text/markdown
+
+# Omphalos
+
+[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
+[![CI](https://github.com/snui1s/Omphalos/actions/workflows/ci.yml/badge.svg)](https://github.com/snui1s/Omphalos/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Codebase symbol indexer for LLMs.
+
+Omphalos generates a compact, high-signal symbol map (`INDEX.md`) of your repository. It provides large language models and developers with an instant architectural overview and precise symbol locations—minimizing token usage and eliminating the need to read entire source files just to find declarations.
+
+## Table of Contents
+
+- [Omphalos](#omphalos)
+  - [Table of Contents](#table-of-contents)
+  - [Background](#background)
+  - [Install](#install)
+  - [Usage](#usage)
+    - [Quick Start](#quick-start)
+    - [CLI Reference](#cli-reference)
+    - [LLM / Agent Integration](#llm--agent-integration)
+  - [Development](#development)
+  - [Related Efforts](#related-efforts)
+  - [Maintainers](#maintainers)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+## Background
+
+When providing a full codebase as context to Large Language Models (LLMs) or AI coding agents, feeding entire file contents quickly exhausts the model's context window, degrades reasoning performance, and incurs high token costs.
+
+In practice, an agent rarely needs the implementation bodies of every file at once; it only needs an accurate structural index: what functions, classes, interfaces, and methods exist, where they are defined, and what their docstrings say.
+
+Omphalos was created to solve this problem:
+
+1. **Multi-language AST Parsing**: Uses Tree-sitter for deterministic parsing across Python, TypeScript/JavaScript, Go, and Rust.
+2. **Precise Line Numbers (`@<line>`)**: Symbols indicate exact declaration line numbers so agents can inspect or slice specific ranges on demand.
+3. **Internal Logic Hints**: Function-like symbols list their deduplicated call targets (`calls`) and raised exception types (`raises`), giving agents a control-flow preview without opening the file.
+4. **Atomic Incremental Cache**: Tracks SHA-256 content hashes to re-parse only changed files, guaranteeing rapid re-indexes.
+5. **CI/CD Integration**: Supports `--check` mode to ensure codebase indexes stay synchronized with changes.
+
+## Install
+
+### Using [uv](https://github.com/astral-sh/uv) (Recommended)
+
+Run directly without installing:
+
+```sh
+$ uvx --from git+https://github.com/snui1s/Omphalos.git omph scan
+```
+
+Or install as a standalone CLI tool:
+
+```sh
+$ uv tool install git+https://github.com/snui1s/Omphalos.git
+```
+
+### Using pip
+
+```sh
+$ pip install git+https://github.com/snui1s/Omphalos.git
+```
+
+### Using npm / npx
+
+Run directly via npx:
+
+```sh
+$ npx omphalos scan
+```
+
+Or install globally:
+
+```sh
+$ npm install -g omphalos
+```
+
+### From Source
+
+```sh
+$ git clone https://github.com/snui1s/Omphalos.git
+$ cd Omphalos
+$ uv sync
+```
+
+## Usage
+
+### Quick Start
+
+1. **Initialize Ignore File** (creates default `.omphignore`):
+
+```sh
+$ omph init
+```
+
+2. **Generate the Symbol Index**:
+
+```sh
+$ omph scan
+```
+
+This generates `INDEX.md` in the root directory:
+
+```markdown
+# Codebase Symbol Index
+
+## src/omphalos/cache.py
+
+- `calculate_sha256()` @15: Calculate the SHA-256 checksum of raw file bytes for change detection. (calls: `hexdigest`, `hashlib.sha256`)
+- `save_cache()` @38: Save symbol cache to .omphcache atomically. (calls: `tempfile.mkstemp`, `os.fdopen`, `json.dump`, `os.replace`, `os.unlink`)
+
+## src/omphalos/cli.py
+
+- `_version_callback()` @33: Callback for --version flag to print the version and exit immediately. (calls: `typer.echo`, `_package_version`; raises: `typer.Exit`)
+
+## tests/fixtures/sample.ts
+
+- export interface `UserProfile` @1
+- export type `AuthToken` @6
+- export function `verifyToken()` @8
+- export class `SessionManager` @18
+  - `createSession()` @19
+```
+
+3. **Instruct AI Agents via `AGENTS.md`**:
+
+Create or add to `AGENTS.md` (or `CLAUDE.md` / `.cursorrules`) at the root of your repository so AI agents read `INDEX.md` before exploring code:
+
+```markdown
+# Agent Guidelines
+
+## Codebase Navigation & Exploration
+
+Before searching, running grep, or opening entire source files across the codebase:
+
+1. **Always read [`INDEX.md`](INDEX.md) first.** It provides an instant symbol map of the entire repository with exact line numbers.
+2. Use the symbols, line locations (`@<line>`), and internal logic hints (`calls:`, `raises:`) in [`INDEX.md`](INDEX.md) to pinpoint definitions directly.
+3. Inspect or slice-read only the specific line ranges or files needed for the task, rather than loading entire files into context.
+```
+
+### CLI Reference
+
+```sh
+$ omph scan [DIRECTORY] [OPTIONS]
+```
+
+The binary is installed as `omph`; the full name `omphalos` is also available as an alias.
+
+| Option           | Flag               | Description                                                               |
+| ---------------- | ------------------ | ------------------------------------------------------------------------- |
+| `--output`, `-o` | `PATH`             | Custom path for index output (default: `INDEX.md`).                       |
+| `--format`       | `markdown \| json` | Output format (default: `markdown`).                                      |
+| `--check`        | flag               | Verify index is up to date without writing. Exits with code `1` if stale. |
+| `--git-only`     | flag               | Scan only files tracked by Git (`git ls-files`).                          |
+| `--no-cache`     | flag               | Bypass cache and re-parse all files.                                      |
+| `--version`      | flag               | Show version and exit.                                                    |
+| `--help`         | flag               | Show help message.                                                        |
+
+### LLM / Agent Integration
+
+- **Automatic Agent Discovery via `AGENTS.md`**: Coding agents (Antigravity, Cursor, Claude Code, GitHub Copilot) automatically load `AGENTS.md` at conversation start. By telling the agent to consult `INDEX.md` first, the agent pinpoints definitions immediately without burning tokens on repository-wide grep searches.
+- **Surgical Inspection**: Because each symbol includes `@<line>`, an LLM can request precise lines via tools (e.g. `head -n 50` or view tool slice) rather than ingesting entire files.
+- **Machine-Readable Formats**: Use `--format json` to integrate with custom RAG systems or agent tools:
+
+```sh
+$ omph scan --format json -o index.json
+```
+
+## Development
+
+```sh
+# Install development dependencies
+$ uv sync --dev
+
+# Run tests
+$ uv run pytest
+
+# Run linter and type checker
+$ uv run ruff check .
+$ uv run mypy src
+```
+
+## Related Efforts
+
+- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) - Fast, incremental parsing system used under the hood.
+- [Universal Ctags](https://ctags.io/) - Traditional code indexing system.
+- [Repomix](https://github.com/yamadashy/repomix) - Repository packager for AI context.
+
+## Contributing
+
+Feel free to dive in! [Open an issue](https://github.com/snui1s/Omphalos/issues/new) or submit a Pull Request.
+
+Omphalos follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct.
+
+## License
+
+[MIT](LICENSE) © 2026 snui1s

omphalos-1.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+omphalos/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+omphalos/cache.py,sha256=iZ9qNQFST5Yl6UDkw94WZiaEX5tqpFZufNfgGqDjkAY,2059
+omphalos/cli.py,sha256=0h0gxowXlBifbWhmBKjbC6DaRaQwdpPna5KAsKvmBcs,5913
+omphalos/ignore.py,sha256=qzxNjoBgbW7huxkEA7AlPHn1jmlAaR14ekWmtoz6_eU,4792
+omphalos/parser.py,sha256=CUjoUBWhNPfi6Z4x1jVZiHig88jedfsrt_Ry9N-yn9c,21295
+omphalos/render.py,sha256=bwRZbpO6DdNbLkDWruL84aOy_R-72DMRaM9iIdp2WgQ,2437
+omphalos-1.1.1.dist-info/WHEEL,sha256=4OL6Foqnnp3xRY5wMkjgc25_i5YJC6dKsC6LPcjqEoU,80
+omphalos-1.1.1.dist-info/entry_points.txt,sha256=i2JZB6H1rM4_ujOCeCyRjfkmkG6nx4PNnQ917-cseJs,71
+omphalos-1.1.1.dist-info/METADATA,sha256=61lrsgjZiHEqyKKrX7DUHECmR7HPvyyXm4sX7aq5Pyc,8998
+omphalos-1.1.1.dist-info/RECORD,,

omphalos-1.1.1.dist-info/WHEEL

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

omphalos-1.1.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+omph = omphalos.cli:app
+omphalos = omphalos.cli:app
+