rylox 0.0.1__py3-none-any.whl

rylox/__init__.py

@@ -0,0 +1,3 @@
+"""Rylox — local, deterministic repository context engine."""
+
+__version__ = "0.0.1"

rylox/cache.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from rylox.chunking import Chunk
+from rylox.errors import IndexCorruptError, IndexNotFoundError
+
+CACHE_DIRNAME = ".rylox"
+INDEX_FILENAME = "index.json"
+SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class CachedChunk:
+    path: str
+    kind: str
+    name: str
+    start_line: int
+    end_line: int
+    parent_class: Optional[str]
+    docstring: Optional[str]
+    content: str
+
+    @classmethod
+    def from_chunk(cls, chunk: Chunk) -> CachedChunk:
+        return cls(
+            path=chunk.path.as_posix(),
+            kind=chunk.kind,
+            name=chunk.name,
+            start_line=chunk.start_line,
+            end_line=chunk.end_line,
+            parent_class=chunk.parent_class,
+            docstring=chunk.docstring,
+            content=chunk.content,
+        )
+
+    def to_chunk(self) -> Chunk:
+        return Chunk(
+            path=Path(self.path),
+            kind=self.kind,  # type: ignore[arg-type]
+            name=self.name,
+            start_line=self.start_line,
+            end_line=self.end_line,
+            parent_class=self.parent_class,
+            docstring=self.docstring,
+            content=self.content,
+        )
+
+
+@dataclass
+class FileEntry:
+    hash: str
+    chunks: list[CachedChunk] = field(default_factory=list)
+
+
+@dataclass
+class IndexManifest:
+    schema_version: int = SCHEMA_VERSION
+    files: dict[str, FileEntry] = field(default_factory=dict)
+
+
+def cache_dir(repo: Path) -> Path:
+    return repo / CACHE_DIRNAME
+
+
+def index_path(repo: Path) -> Path:
+    return cache_dir(repo) / INDEX_FILENAME
+
+
+def ensure_cache_dir(repo: Path) -> Path:
+    directory = cache_dir(repo)
+    directory.mkdir(parents=True, exist_ok=True)
+    gitignore = directory / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n", encoding="utf-8")
+    return directory
+
+
+def save_index(repo: Path, manifest: IndexManifest) -> None:
+    ensure_cache_dir(repo)
+    target = index_path(repo)
+    payload = _serialize(manifest)
+
+    fd, tmp_name = tempfile.mkstemp(dir=str(target.parent), prefix=".index-", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+        os.replace(tmp_name, target)
+    except Exception:
+        if os.path.exists(tmp_name):
+            os.remove(tmp_name)
+        raise
+
+
+def load_index(repo: Path) -> IndexManifest:
+    target = index_path(repo)
+    if not target.exists():
+        raise IndexNotFoundError(
+            f"no index found at {target}. Run `rylox index` first."
+        )
+
+    try:
+        raw = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise IndexCorruptError(f"{target} is unreadable or corrupt: {exc}") from exc
+
+    try:
+        return _deserialize(raw)
+    except (KeyError, TypeError, ValueError) as exc:
+        raise IndexCorruptError(f"{target} has an unexpected structure: {exc}") from exc
+
+
+def load_or_empty(repo: Path) -> IndexManifest:
+    try:
+        return load_index(repo)
+    except IndexNotFoundError:
+        return IndexManifest()
+
+
+def _serialize(manifest: IndexManifest) -> dict[str, Any]:
+    return {
+        "schema_version": manifest.schema_version,
+        "files": {
+            relpath: {
+                "hash": entry.hash,
+                "chunks": [asdict(c) for c in entry.chunks],
+            }
+            for relpath, entry in manifest.files.items()
+        },
+    }
+
+
+def _deserialize(raw: dict[str, Any]) -> IndexManifest:
+    schema_version = raw["schema_version"]
+    if schema_version != SCHEMA_VERSION:
+        raise IndexCorruptError(
+            f"index schema_version {schema_version} is not supported "
+            f"(expected {SCHEMA_VERSION}); run `rylox clean` and re-index."
+        )
+
+    files: dict[str, FileEntry] = {}
+    for relpath, entry_raw in raw["files"].items():
+        chunks = [CachedChunk(**c) for c in entry_raw["chunks"]]
+        files[relpath] = FileEntry(hash=entry_raw["hash"], chunks=chunks)
+
+    return IndexManifest(schema_version=schema_version, files=files)

rylox/chunking.py

@@ -0,0 +1,216 @@
+"""Python chunking via tree-sitter (spec §2).
+
+Scope for this module, deliberately narrow:
+  - integrate tree-sitter-python and parse .py source into an AST
+  - chunk at function / method / class granularity (never file, never line)
+  - store per-chunk metadata: file path, line range, parent class, docstring,
+    source text
+  - skip a file tree-sitter can't parse without crashing the whole run
+
+Explicitly NOT in this module yet (later phases): content hashing for
+incremental re-index, the `.rylox/` cache, and CLI wiring for `rylox index`.
+`parse_source` and `parse_file` below are self-contained and testable without
+any of that machinery existing yet.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Optional
+
+import tree_sitter_python as tspython
+from tree_sitter import Language, Node, Parser
+
+_PY_LANGUAGE = Language(tspython.language(), "python")
+
+# One parser instance, reused across calls. tree_sitter.Parser holds no
+# per-parse mutable state worth avoiding reuse over, so constructing a new
+# one on every parse_source() call was pure overhead.
+_PARSER = Parser()
+_PARSER.set_language(_PY_LANGUAGE)
+
+ChunkKind = Literal["function", "method", "class"]
+
+
+@dataclass(frozen=True)
+class Chunk:
+    """One retrievable unit of code, per spec §2's chunk metadata list."""
+
+    path: Path
+    kind: ChunkKind
+    name: str
+    start_line: int  # 1-indexed, inclusive. Includes decorator lines, if any.
+    end_line: int  # 1-indexed, inclusive
+    parent_class: Optional[str]
+    docstring: Optional[str]
+    content: str  # exact source text of the chunk, decorators included
+
+
+@dataclass
+class ParseResult:
+    """Outcome of parsing one file: either chunks, or a recorded error.
+
+    `error` being set means the file was skipped, not that the whole
+    operation failed (spec §12: malformed files are logged and skipped,
+    never fatal for the whole `index` run). Callers should check `error`
+    and continue on to the next file rather than propagating an exception.
+    """
+
+    chunks: list[Chunk]
+    error: Optional[str] = None
+
+
+def parse_source(source: str, path: Path) -> list[Chunk]:
+    """Parse Python source text into function/method/class chunks.
+
+    Pure function, no filesystem access — this is what makes chunking
+    behavior directly unit-testable against hand-written source strings,
+    independent of `parse_file`'s I/O and error handling.
+    """
+    tree = _PARSER.parse(source.encode("utf-8"))
+    lines = source.splitlines()
+    chunks: list[Chunk] = []
+    _walk(tree.root_node, path, lines, parent_class=None, chunks=chunks)
+    return chunks
+
+
+def parse_file(path: Path) -> ParseResult:
+    """Read and parse a single .py file. Never raises — malformed or
+    unreadable files come back as a ParseResult with `error` set and an
+    empty chunk list, per spec §12.
+    """
+    try:
+        source = path.read_text(encoding="utf-8-sig")
+    except (OSError, UnicodeDecodeError) as exc:
+        return ParseResult(chunks=[], error=f"{path}: could not read file ({exc})")
+
+    try:
+        chunks = parse_source(source, path)
+    except Exception as exc:  # noqa: BLE001 — deliberately broad: any parser
+        # failure must degrade to "skip this file", never crash the whole
+        # index run (spec §12). Narrowing this to tree_sitter's specific
+        # exception types would risk missing a case and defeating the point.
+        return ParseResult(chunks=[], error=f"{path}: failed to parse ({exc})")
+
+    return ParseResult(chunks=chunks, error=None)
+
+
+def _walk(
+    node: Node,
+    path: Path,
+    lines: list[str],
+    *,
+    parent_class: Optional[str],
+    chunks: list[Chunk],
+) -> None:
+    for child in node.children:
+        # Decorated definitions (@foo\ndef bar(): ...) wrap the real
+        # function_definition/class_definition in a decorated_definition
+        # node. Unwrap it, but keep the *outer* node's start point so the
+        # decorator line(s) are included in the chunk's span — the
+        # decorator is semantically part of the unit being chunked.
+        target = child
+        span_start = child
+        if child.type == "decorated_definition":
+            inner = child.child_by_field_name("definition")
+            if inner is None:
+                _walk(child, path, lines, parent_class=parent_class, chunks=chunks)
+                continue
+            target = inner
+            span_start = child
+
+        if target.type == "class_definition":
+            name = _node_name(target)
+            chunks.append(
+                Chunk(
+                    path=path,
+                    kind="class",
+                    name=name,
+                    start_line=span_start.start_point[0] + 1,
+                    end_line=target.end_point[0] + 1,
+                    parent_class=parent_class,
+                    docstring=_docstring(target, lines),
+                    content=_content(span_start, lines),
+                )
+            )
+            # Recurse with this class as the new parent_class, so nested
+            # function_definitions/class_definitions inside it are chunked
+            # as methods/nested classes respectively.
+            _walk(target, path, lines, parent_class=name, chunks=chunks)
+
+        elif target.type == "function_definition":
+            name = _node_name(target)
+            chunks.append(
+                Chunk(
+                    path=path,
+                    kind="method" if parent_class is not None else "function",
+                    name=name,
+                    start_line=span_start.start_point[0] + 1,
+                    end_line=target.end_point[0] + 1,
+                    parent_class=parent_class,
+                    docstring=_docstring(target, lines),
+                    content=_content(span_start, lines),
+                )
+            )
+            # Recurse without a parent_class: a function nested inside
+            # another function is chunked as its own top-level-style
+            # "function" (v0.1 doesn't track function-in-function nesting).
+            _walk(target, path, lines, parent_class=None, chunks=chunks)
+
+        else:
+            _walk(child, path, lines, parent_class=parent_class, chunks=chunks)
+
+
+def _content(span_start: Node, lines: list[str]) -> str:
+    """Exact source text of the chunk's span (decorator lines included, if any).
+
+    Safe for both plain definitions and decorated_definition wrappers: a
+    decorator can only add lines *before* the def/class line, never after,
+    so span_start.end_point always matches the inner definition's end.
+    """
+    start = span_start.start_point[0]
+    end = span_start.end_point[0]
+    return "\n".join(lines[start : end + 1])
+
+
+def _node_name(def_node: Node) -> str:
+    name_node = def_node.child_by_field_name("name")
+    if name_node is None:
+        return "<anonymous>"
+    return name_node.text.decode("utf-8")
+
+
+def _docstring(def_node: Node, lines: list[str]) -> Optional[str]:
+    """Extract a def/class's own docstring: the first statement in its body,
+    if that statement is a bare string expression.
+    """
+    body = def_node.child_by_field_name("body")
+    if body is None or body.child_count == 0:
+        return None
+
+    first_statement = body.children[0]
+    if first_statement.type != "expression_statement":
+        return None
+    if first_statement.child_count == 0:
+        return None
+
+    string_node = first_statement.children[0]
+    if string_node.type != "string":
+        return None
+
+    raw = string_node.text.decode("utf-8")
+    return _strip_string_literal(raw)
+
+
+def _strip_string_literal(raw: str) -> str:
+    """Strip Python string-literal quoting/prefixes to get the docstring body."""
+    text = raw.strip()
+    for prefix in ("u", "U", "r", "R", "b", "B", "rb", "Rb", "rB", "RB", "br", "Br", "bR", "BR"):
+        if text.startswith(prefix) and text[len(prefix) :].startswith(('"', "'")):
+            text = text[len(prefix) :]
+            break
+    for quote in ('"""', "'''", '"', "'"):
+        if text.startswith(quote) and text.endswith(quote) and len(text) >= 2 * len(quote):
+            return text[len(quote) : -len(quote)].strip()
+    return text.strip()

rylox/cli.py

@@ -0,0 +1,119 @@
+"""Rylox CLI — exactly four commands (spec §9). No fifth command in v0.1.
+
+Phase 1 goal: lock in the *interface* (command names, options, exit codes,
+error presentation) before any real logic exists. Every command below is a
+stub that returns a clearly-labeled "not implemented" result rather than
+doing nothing silently — that way `rylox --help` and each subcommand's
+`--help` are already correct and testable, and later phases fill bodies in
+without touching signatures.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from rylox import __version__
+from rylox.errors import RyloxError
+
+app = typer.Typer(
+    name="rylox",
+    help=(
+        "Local repository context engine — turns a repo + task into a "
+        "token-budgeted markdown package."
+    ),
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"rylox {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the Rylox version and exit.",
+    ),
+) -> None:
+    """Rylox: build the best local repository context assembler."""
+
+
+@app.command()
+def index(
+    repo: Path = typer.Option(
+        Path("."), "--repo", exists=True, file_okay=False, help="Repository root to index."
+    ),
+) -> None:
+    """Build or incrementally update the local `.rylox/` index."""
+    _not_implemented("index")
+
+
+@app.command()
+def context(
+    task: str = typer.Argument(..., help="The task/question to build context for."),
+    max_tokens: int = typer.Option(
+        16000, "--max-tokens", min=1, help="Hard token budget for the assembled context."
+    ),
+    output_format: str = typer.Option(
+        "markdown",
+        "--format",
+        help="Output format. Only 'markdown' is supported in v0.1.",
+    ),
+    repo: Path = typer.Option(
+        Path("."), "--repo", exists=True, file_okay=False, help="Repository root."
+    ),
+) -> None:
+    """Assemble a token-budgeted, relationship-aware context package for TASK."""
+    if output_format != "markdown":
+        raise typer.BadParameter("Only --format markdown is supported in v0.1.")
+    _not_implemented("context")
+
+
+@app.command()
+def clean(
+    repo: Path = typer.Option(
+        Path("."), "--repo", exists=True, file_okay=False, help="Repository root."
+    ),
+) -> None:
+    """Delete the `.rylox/` cache and start fresh."""
+    _not_implemented("clean")
+
+
+@app.command()
+def doctor() -> None:
+    """Run environment/health checks and report each pass/fail individually."""
+    _not_implemented("doctor")
+
+
+def _not_implemented(command: str) -> None:
+    """Placeholder body for Phase 1 stubs.
+
+    Deliberately visible and non-zero-exit rather than a silent no-op, so
+    running any command today tells you honestly that it's unbuilt instead
+    of pretending to succeed.
+    """
+    typer.echo(f"rylox {command}: not implemented yet (Phase 1 skeleton)", err=True)
+    raise typer.Exit(code=1)
+
+
+def run() -> None:
+    """Entry point wrapper: turn RyloxError into a clean message + exit code."""
+    try:
+        app()
+    except RyloxError as err:
+        typer.echo(f"error: {err.message}", err=True)
+        raise typer.Exit(code=err.exit_code) from err
+
+
+if __name__ == "__main__":
+    run()