uncoded 0.5.0__py3-none-any.whl

uncoded/__init__.py

@@ -0,0 +1,5 @@
+"""Uncoded."""
+
+from importlib.metadata import version
+
+__version__ = version("uncoded")

uncoded/cli.py

@@ -0,0 +1,103 @@
+"""CLI entry point for uncoded."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from uncoded.config import read_instruction_files, read_source_roots
+from uncoded.extract import walk_source
+from uncoded.instruction_files import sync_instruction_file
+from uncoded.namespace_map import build_map, render_map
+from uncoded.serena_setup import setup_serena
+from uncoded.skill import sync_skill
+from uncoded.stubs import build_stubs
+from uncoded.sync import sync_file
+
+DEFAULT_MAP_OUTPUT = Path(".uncoded/namespace.yaml")
+
+
+def _sync(*, check: bool = False) -> int:
+    """Sync (or verify) the namespace map, stub files, and instruction-file sections.
+
+    When ``check=True``, the on-disk tree is not mutated: each step reports
+    whether it would write. Returns 1 if any step reports a prospective
+    change (so CI can gate on a stale index), 0 if the tree is already in
+    sync. In apply mode, returns 0 on success or 1 on configuration error.
+    """
+    try:
+        source_roots = [r.resolve() for r in read_source_roots()]
+    except (FileNotFoundError, KeyError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+    for root in source_roots:
+        if not root.is_dir():
+            print(f"Error: {root} is not a directory", file=sys.stderr)
+            return 1
+
+    changes = 0
+
+    modules = [m for root in source_roots for m in walk_source(root)]
+    map_content = render_map(build_map(modules))
+    if sync_file(DEFAULT_MAP_OUTPUT, map_content, check=check):
+        changes += 1
+
+    for root in source_roots:
+        changes += build_stubs(root, check=check)
+
+    for path in read_instruction_files():
+        if sync_instruction_file(path, check=check):
+            changes += 1
+
+    if sync_skill(check=check):
+        changes += 1
+
+    if check:
+        if changes:
+            print(f"Index out of date: {changes} file(s) would change.")
+            return 1
+        print("Index is up to date.")
+        return 0
+    return 0
+
+
+def main() -> int:
+    """Dispatch the uncoded CLI.
+
+    Three subcommands: ``sync`` builds or refreshes the navigation index;
+    ``check`` verifies the index matches what a rebuild would produce
+    (exits non-zero on drift, useful in CI); ``setup-serena`` generates
+    MCP and Claude Code config for the recommended Serena + ty LSP
+    integration.
+    """
+    parser = argparse.ArgumentParser(
+        prog="uncoded",
+        description="Build a navigation index for AI coding agents.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser(
+        "sync",
+        help=(
+            "Build or refresh the namespace map, stub files, and "
+            "instruction-file sections."
+        ),
+    )
+    subparsers.add_parser(
+        "check",
+        help=(
+            "Verify the index is up to date without writing. Exits non-zero "
+            "if any file would change. Useful in CI."
+        ),
+    )
+    subparsers.add_parser(
+        "setup-serena",
+        help=(
+            "Write .mcp.json, .serena/project.yml, and .claude/settings.json "
+            "for the recommended Serena + ty LSP integration."
+        ),
+    )
+    args = parser.parse_args()
+
+    if args.command == "setup-serena":
+        return setup_serena()
+    return _sync(check=args.command == "check")

uncoded/config.py

@@ -0,0 +1,62 @@
+"""Read uncoded configuration from pyproject.toml."""
+
+import tomllib
+from pathlib import Path
+
+from uncoded.instruction_files import DEFAULT_INSTRUCTION_FILES
+
+
+def find_pyproject_toml() -> Path | None:
+    """Search for pyproject.toml starting from cwd, walking up."""
+    current = Path.cwd()
+    while True:
+        candidate = current / "pyproject.toml"
+        if candidate.exists():
+            return candidate
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def read_source_roots() -> list[Path]:
+    """Read source roots from [tool.uncoded] source-roots in pyproject.toml."""
+    toml_path = find_pyproject_toml()
+    if toml_path is None:
+        raise FileNotFoundError(
+            "No pyproject.toml found. Add [tool.uncoded] source-roots to configure."
+        )
+
+    with toml_path.open("rb") as f:
+        data = tomllib.load(f)
+
+    try:
+        roots = data["tool"]["uncoded"]["source-roots"]
+    except KeyError:
+        raise KeyError(
+            "No [tool.uncoded] source-roots found in pyproject.toml."
+        ) from None
+
+    return [Path(r) for r in roots]
+
+
+def read_instruction_files() -> list[Path]:
+    """Read instruction files from [tool.uncoded] instruction-files in pyproject.toml.
+
+    Falls back to ``DEFAULT_INSTRUCTION_FILES`` if the key is absent or no
+    ``pyproject.toml`` is found, so that ``uncoded`` works on a fresh repo
+    without explicit configuration.
+    """
+    toml_path = find_pyproject_toml()
+    if toml_path is None:
+        return list(DEFAULT_INSTRUCTION_FILES)
+
+    with toml_path.open("rb") as f:
+        data = tomllib.load(f)
+
+    try:
+        files = data["tool"]["uncoded"]["instruction-files"]
+    except KeyError:
+        return list(DEFAULT_INSTRUCTION_FILES)
+
+    return [Path(f) for f in files]

uncoded/extract.py

@@ -0,0 +1,137 @@
+"""Extract symbols from Python source files using the AST."""
+
+import ast
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class ClassInfo:
+    """A class with its attributes and methods."""
+
+    name: str
+    attributes: list[str] = field(default_factory=list)
+    methods: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ModuleInfo:
+    """Symbols found in a single Python module."""
+
+    rel_path: str
+    constants: list[str] = field(default_factory=list)
+    classes: list[ClassInfo] = field(default_factory=list)
+    functions: list[str] = field(default_factory=list)
+
+
+def _property_kind(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> str | None:
+    """Classify a method by its property-related decorators.
+
+    Returns "property" for @property, "setter" for @<name>.setter,
+    "deleter" for @<name>.deleter, or None for a plain method.
+    """
+    for d in node.decorator_list:
+        if isinstance(d, ast.Name) and d.id == "property":
+            return "property"
+        if isinstance(d, ast.Attribute) and d.attr in ("setter", "deleter"):
+            return d.attr
+    return None
+
+
+def _assign_target_name(node: ast.Assign | ast.AnnAssign) -> str | None:
+    """Return the single-name target of an assignment, or None if not a simple name."""
+    if isinstance(node, ast.AnnAssign):
+        target = node.target
+        return target.id if isinstance(target, ast.Name) else None
+    if len(node.targets) != 1:
+        return None
+    target = node.targets[0]
+    return target.id if isinstance(target, ast.Name) else None
+
+
+def extract_module(source: str, rel_path: str) -> ModuleInfo:
+    """Parse Python source and extract classes, functions, and constants."""
+    tree = ast.parse(source)
+
+    constants: list[str] = []
+    classes: list[ClassInfo] = []
+    functions: list[str] = []
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            attributes: list[str] = []
+            methods: list[str] = []
+            for n in ast.iter_child_nodes(node):
+                if isinstance(n, (ast.AnnAssign, ast.Assign)):
+                    name = _assign_target_name(n)
+                    if name:
+                        attributes.append(name)
+                elif isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    kind = _property_kind(n)
+                    if kind == "setter" or kind == "deleter":
+                        continue
+                    if kind == "property":
+                        attributes.append(n.name)
+                    else:
+                        methods.append(n.name)
+            classes.append(
+                ClassInfo(name=node.name, attributes=attributes, methods=methods)
+            )
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions.append(node.name)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+            name = _assign_target_name(node)
+            if name:
+                constants.append(name)
+        elif isinstance(node, ast.TypeAlias) and isinstance(node.name, ast.Name):
+            constants.append(node.name.id)
+
+    return ModuleInfo(
+        rel_path=rel_path,
+        constants=constants,
+        classes=classes,
+        functions=functions,
+    )
+
+
+def iter_source_files(
+    source_root: Path, base: Path | None = None
+) -> Iterator[tuple[str, str]]:
+    """Yield (source_text, rel_path) for every Python file under *source_root*.
+
+    Paths are relative to *base* (defaults to cwd).
+    """
+    if base is None:
+        base = Path.cwd()
+
+    source_root = source_root.resolve()
+    base = base.resolve()
+
+    for py_file in sorted(source_root.rglob("*.py")):
+        rel_path = str(py_file.relative_to(base))
+        yield py_file.read_text(), rel_path
+
+
+def walk_source(source_root: Path, base: Path | None = None) -> list[ModuleInfo]:
+    """Walk a source root and extract symbols from all Python files.
+
+    Paths in the returned ModuleInfo are relative to *base* (defaults to
+    cwd), so they can be used directly to open files from the repo root.
+
+    Skips files with no symbols and files with syntax errors.
+    """
+    modules: list[ModuleInfo] = []
+
+    for source, rel_path in iter_source_files(source_root, base):
+        try:
+            module = extract_module(source, rel_path)
+        except SyntaxError:
+            continue
+
+        if module.classes or module.functions or module.constants:
+            modules.append(module)
+
+    return modules

uncoded/instruction_files.py

@@ -0,0 +1,133 @@
+"""Maintain the uncoded navigation section in agent instruction files.
+
+Different coding agents read different instruction files from a repo's root.
+Claude Code reads ``CLAUDE.md``; an emerging cross-agent convention uses
+``AGENTS.md``. Until the ecosystem converges, a project that wants to support
+both populations needs both files, with the same navigation guidance in each.
+This module owns a delimited section in any such file and keeps it in sync.
+"""
+
+from pathlib import Path
+
+from uncoded.sync import sync_file
+
+MARKER_START = "<!-- uncoded:start -->"
+MARKER_END = "<!-- uncoded:end -->"
+
+DEFAULT_INSTRUCTION_FILES = [Path("CLAUDE.md"), Path("AGENTS.md")]
+
+_SECTION_BODY = """\
+## How to read and edit code in this codebase
+
+This repo uses [uncoded](https://github.com/alimanfoo/uncoded) to maintain
+a symbol index over its source code, designed for AI agents to navigate
+deterministically rather than by grep-and-skim. For source navigation, use
+the index — grep-and-skim produces a noisier, slower version of what the
+index already lists in full. (For free-text search elsewhere —
+Markdown, configs, commit messages — grep remains the right tool. The index
+is about source.)
+
+**Step 1 — Orient. Do this now, before anything else.** Your first action
+in this session — before answering the user, before any other tool call —
+is to read the namespace map in full:
+
+```
+Read .uncoded/namespace.yaml
+```
+
+Do this once, immediately, at session start — not "eventually" or "when
+a code question comes up." Without the map loaded, design and navigation
+answers will come from pretrained guesses rather than the code actually
+here. The map lists every symbol in the codebase — directories, files,
+classes, methods, functions — in source order.
+
+**Step 2 — Understand.** Before reading any `.py` source file in this repo,
+read its `.pyi` stub first. Stub paths mirror source paths under
+`.uncoded/stubs/`:
+
+```
+src/foo/bar.py      →  .uncoded/stubs/src/foo/bar.pyi
+tests/test_foo.py   →  .uncoded/stubs/tests/test_foo.pyi
+```
+
+This applies to every file you intend to touch or reference — including
+tests. The stub is sufficient for most navigation: it contains imports,
+every signature with types, module-level assignments, class attributes,
+and first-sentence docstrings. Skipping to source means reading many
+lines to learn what the stub would have told you in one. If no stub
+exists at the expected path, the file has no symbols indexed — in that
+narrow case, read source directly.
+
+**Step 3 — Read source through Serena.** When you need source beyond
+what the stub shows, use Serena to read exactly the symbol body. The
+namespace map and stub give you the exact `relative_path` and `name_path`
+Serena needs — e.g. `ClassName/method` for a method,
+`function_name` for a top-level function.
+
+Stubs intentionally do not carry source line ranges: line numbers churn
+when nearby code moves, creating noisy generated diffs and teaching
+agents to trust stale coordinates. Let uncoded provide the stable map
+and signatures; let Serena resolve the current source body.
+
+**For symbol-level operations — use Serena.** Where Serena's MCP tools
+are available (`mcp__serena__*` in the tool list), prefer them over
+Read / Edit / grep for anything that operates on a symbol as a unit.
+
+- **Read one symbol body.** `find_symbol` with `include_body=True`
+  returns exactly the symbol — no offset arithmetic, no risk of reading
+  too much. Stay on stubs for a wider sweep; use Serena when you need
+  implementation detail.
+- **Find callers, or check whether a symbol is dead.**
+  `find_referencing_symbols` returns every reference resolved by the
+  language server. Do not grep for the name — grep hits comments,
+  strings, attribute lookups on unrelated types, and re-exports.
+- **Rename.** `rename_symbol` updates every reference across the
+  codebase in one call. Multi-file find-and-replace misses imports
+  and re-exports and racks up false positives.
+- **Edit a whole symbol.** `replace_symbol_body`,
+  `insert_before_symbol`, and `insert_after_symbol` operate on the
+  symbol as a unit. Immune to the Edit tool's "string not unique"
+  failure mode, never accidentally modify a similarly-named
+  neighbour, and keep surrounding indentation consistent.
+- **Delete a symbol.** `safe_delete_symbol` checks for live
+  references before removing — dead code goes cleanly, live code
+  stays put.
+
+Reach for Read + Edit when Serena does not fit: free-text files
+(Markdown, YAML, configs), partial-line edits inside a function body
+after you have retrieved it, environments where Serena is unavailable,
+or the rare stub-less Python file that needs exploratory reading."""
+
+SECTION = f"{MARKER_START}\n{_SECTION_BODY}\n{MARKER_END}\n"
+
+
+def generate_section() -> str:
+    """Return the full delimited uncoded section for an instruction file."""
+    return SECTION
+
+
+def _replace_or_append(existing: str, section: str) -> str:
+    """Replace the delimited section in existing text, or append it if absent."""
+    start = existing.find(MARKER_START)
+    end = existing.find(MARKER_END)
+    if start != -1 and end != -1 and start < end:
+        before = existing[:start]
+        after = existing[end + len(MARKER_END) :].lstrip("\n")
+        return before + section + after
+    stripped = existing.rstrip("\n")
+    prefix = stripped + "\n\n" if stripped else ""
+    return prefix + section
+
+
+def sync_instruction_file(path: Path, *, check: bool = False) -> bool:
+    """Write or update the uncoded navigation section in an instruction file.
+
+    When ``check=True``, reports a prospective change without touching disk.
+    Returns ``True`` if a write was (or would be) performed.
+    """
+    section = generate_section()
+    if not path.exists():
+        return sync_file(path, section, check=check)
+    existing = path.read_text()
+    updated = _replace_or_append(existing, section)
+    return sync_file(path, updated, check=check)

uncoded/namespace_map.py

@@ -0,0 +1,84 @@
+"""Generate a YAML namespace map from extracted symbols."""
+
+from pathlib import Path
+
+import yaml
+
+from uncoded.extract import ModuleInfo
+
+HEADER = """\
+# Symbol index of this codebase, for agent navigation.
+# Generated by uncoded — do not edit; regeneration overwrites.
+#
+# Pure key hierarchy (no lists, no values); indent to zoom in.
+# Directory keys end with "/". Entries within a file or class appear
+# in source order.
+#
+# For signatures and types, see stubs:
+#   src/foo/bar.py  →  .uncoded/stubs/src/foo/bar.pyi
+"""
+
+
+class _CleanDumper(yaml.SafeDumper):
+    """YAML dumper that indents list items and suppresses 'null' values."""
+
+    def increase_indent(self, flow=False, indentless=False):
+        """Force list items to be indented relative to their parent key."""
+        return super().increase_indent(flow, False)
+
+
+# Render None as empty rather than "null" so leaf symbols appear as just "name:"
+_CleanDumper.add_representer(
+    type(None),
+    lambda dumper, _: dumper.represent_scalar("tag:yaml.org,2002:null", ""),
+)
+
+
+def build_map(modules: list[ModuleInfo]) -> dict:
+    """Build a nested dict representing the namespace.
+
+    Keys are repo-relative paths. Directory keys have a trailing slash.
+    Symbols sit directly under their file key.
+    """
+    root: dict = {}
+
+    for module in modules:
+        parts = Path(module.rel_path).parts
+        current = root
+
+        # Create intermediate directory entries
+        for dir_part in parts[:-1]:
+            key = dir_part + "/"
+            if key not in current:
+                current[key] = {}
+            current = current[key]
+
+        # Build the file entry — symbols directly under the file key.
+        # Classes with methods map to their method list.
+        # Classes without methods, bare functions, and constants map to None.
+        file_entry: dict = {}
+
+        for const in module.constants:
+            file_entry[const] = None
+
+        for cls in module.classes:
+            members = cls.attributes + cls.methods
+            file_entry[cls.name] = {m: None for m in members} if members else None
+
+        for func in module.functions:
+            file_entry[func] = None
+
+        current[parts[-1]] = file_entry
+
+    return root
+
+
+def render_map(namespace: dict) -> str:
+    """Render a namespace map dict as a YAML string with an explanatory header."""
+    body = yaml.dump(
+        namespace,
+        Dumper=_CleanDumper,
+        default_flow_style=False,
+        sort_keys=False,
+    )
+    return HEADER + "\n" + body