uncoded 0.5.0__tar.gz → 0.6.0__tar.gz

uncoded-0.6.0/AGENTS.md

@@ -0,0 +1,155 @@
+# uncoded
+
+## Problem
+
+AI coding agents navigate codebases poorly. They grep for guessed keywords,
+skim the first few lines of files, and fill gaps from pretraining rather than
+reading the actual code. System prompts encourage this with "make reasonable
+assumptions." The result is plausible-looking output built on a hallucinated
+understanding of code that's sitting right there, unread.
+
+## Approach
+
+A static, pre-computed index gives agents a top-down view of a codebase.
+The agent loads the index at the start of a task, sees the full vocabulary
+of the code, and navigates deterministically to what it needs — no guessing,
+no grep.
+
+Two-level index:
+
+1. **Namespace map** (`.uncoded/namespace.yaml`) — a hierarchical YAML file
+   listing all symbols: directories, files, classes (with attributes
+   and methods), and functions. Covers both source and tests. Loaded into
+   context before any task begins. Gives the agent a world view.
+
+2. **Stub files** (`.uncoded/stubs/`) — one `.pyi` per source file, with
+   imports, full signatures (parameter names, types, return types),
+   first-sentence docstrings, module constants, and class attributes.
+
+## Commands
+
+This project uses [uv](https://docs.astral.sh/uv/). Run commands via
+`uv run` so they execute inside the project environment without needing
+an activated venv.
+
+```
+# Generate (or update) the namespace map, stub files, and CLAUDE.md section
+uv run uncoded sync
+
+# Run tests
+uv run pytest
+```
+
+<!-- uncoded:start -->
+## 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, with
+[Serena](https://github.com/oraios/serena) providing language-server-backed
+tools over that index. The point of this scaffolding is one rule.
+
+### The rule
+
+**If your search term is the name of a Python symbol — a class, function,
+method, attribute, or module-level constant — use the index. If it's a
+pattern, regex, or free-text phrase, use grep.**
+
+This applies to every tool call where you are trying to find code, not
+just the first one in the session. The pretrained reflex for "find X" is
+grep, and that reflex is wrong here. `grep -rn 'WriteResult'` to locate a
+class is the rule firing — that is `find_symbol`. `grep -rn 'function_name'`
+to check whether something has callers before a refactor is the rule
+firing — that is `find_referencing_symbols`. `grep` then `Edit` to delete
+dead code is the rule firing — that is `safe_delete_symbol`. The grep
+version of any of these is noisier and less complete: grep misses
+re-exports, and adds false positives from comments, strings, and unrelated
+attribute lookups on other types. The language server does not.
+
+### How to execute the rule
+
+The index has two parts (a namespace map and per-file stubs) and three
+steps (orient, understand, act).
+
+**Step 1 — Orient. Read the namespace map first.** Before answering the
+user, before any other tool call:
+
+```
+Read .uncoded/namespace.yaml
+```
+
+This lists every symbol in the codebase — directories, files, classes,
+methods, functions — in source order. Without it loaded, "find X"
+answers come from pretrained guesses about what a project like this
+*probably* contains, rather than what is actually here. Read it once,
+in full, at session start.
+
+**Step 2 — Understand. Read the `.pyi` stub before any `.py` source.**
+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
+```
+
+Every file you intend to touch or reference, including tests. The stub
+contains imports, every signature with types, module-level assignments,
+class attributes, and first-sentence docstrings — enough for most
+navigation. Skipping straight 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 — Act. Use Serena to find, read, rename, edit, and delete symbols.**
+With the map and stub loaded, you have the exact `relative_path` and
+`name_path` each Serena tool needs (`ClassName/method` for a method,
+`function_name` for a top-level function). Per task:
+
+- **Find a symbol's definition, or read its body.** `find_symbol` —
+  with `include_body=True` when you need implementation detail the
+  stub does not show. Returns exactly the symbol; no offset arithmetic,
+  no risk of reading too much. Stay on stubs for a wider sweep.
+
+- **Find callers, or check whether a symbol is dead.**
+  `find_referencing_symbols`. Returns every reference resolved by the
+  language server — every import, every call site, every re-export.
+  Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the
+  next move depends on the answer being complete, grep cannot give
+  you that.
+
+- **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 substring false positives.
+
+- **Edit a symbol as a unit.** `replace_symbol_body`,
+  `insert_before_symbol`, `insert_after_symbol`. Immune to the Edit
+  tool's "string not unique" failure mode, never modify a similarly
+  named neighbour, and keep surrounding indentation consistent.
+
+- **Delete a symbol.** `safe_delete_symbol` — not Edit, and not Edit
+  after a manual reference check. The tool fuses two operations: it
+  finds every reference, refuses to delete if any are live, and
+  removes the symbol cleanly only when it is truly dead. The two-step
+  version (find references with grep or `find_referencing_symbols`,
+  then Edit) can drift — the reference check goes stale the moment
+  any file changes between the calls. Whenever the task is "remove
+  this symbol," regardless of how dead it looks, this is the tool.
+
+### Where Read, Edit, and grep are still the right tools
+
+The rule is about source navigation by symbol name. Outside that, the
+non-Serena tools stay correct:
+
+- Free-text or pattern search outside source: Markdown, YAML, TOML,
+  configs, commit messages, notebook JSON, fixture data.
+- Pattern search across signatures (regex over type annotations,
+  decorator usage, alias declarations) — these are not symbol-name
+  lookups even though they sit inside source.
+- Partial-line edits inside a symbol body, once you have retrieved it
+  through Serena.
+- Environments where Serena is unavailable, or the rare stub-less
+  Python file that needs exploratory reading.
+
+The dispatch test is the search term: a symbol name → Serena; a regex
+or free-text phrase → grep.
+<!-- uncoded:end -->

uncoded-0.6.0/CLAUDE.md

@@ -0,0 +1,155 @@
+# uncoded
+
+## Problem
+
+AI coding agents navigate codebases poorly. They grep for guessed keywords,
+skim the first few lines of files, and fill gaps from pretraining rather than
+reading the actual code. System prompts encourage this with "make reasonable
+assumptions." The result is plausible-looking output built on a hallucinated
+understanding of code that's sitting right there, unread.
+
+## Approach
+
+A static, pre-computed index gives agents a top-down view of a codebase.
+The agent loads the index at the start of a task, sees the full vocabulary
+of the code, and navigates deterministically to what it needs — no guessing,
+no grep.
+
+Two-level index:
+
+1. **Namespace map** (`.uncoded/namespace.yaml`) — a hierarchical YAML file
+   listing all symbols: directories, files, classes (with attributes
+   and methods), and functions. Covers both source and tests. Loaded into
+   context before any task begins. Gives the agent a world view.
+
+2. **Stub files** (`.uncoded/stubs/`) — one `.pyi` per source file, with
+   imports, full signatures (parameter names, types, return types),
+   first-sentence docstrings, module constants, and class attributes.
+
+## Commands
+
+This project uses [uv](https://docs.astral.sh/uv/). Run commands via
+`uv run` so they execute inside the project environment without needing
+an activated venv.
+
+```
+# Generate (or update) the namespace map, stub files, and CLAUDE.md section
+uv run uncoded sync
+
+# Run tests
+uv run pytest
+```
+
+<!-- uncoded:start -->
+## 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, with
+[Serena](https://github.com/oraios/serena) providing language-server-backed
+tools over that index. The point of this scaffolding is one rule.
+
+### The rule
+
+**If your search term is the name of a Python symbol — a class, function,
+method, attribute, or module-level constant — use the index. If it's a
+pattern, regex, or free-text phrase, use grep.**
+
+This applies to every tool call where you are trying to find code, not
+just the first one in the session. The pretrained reflex for "find X" is
+grep, and that reflex is wrong here. `grep -rn 'WriteResult'` to locate a
+class is the rule firing — that is `find_symbol`. `grep -rn 'function_name'`
+to check whether something has callers before a refactor is the rule
+firing — that is `find_referencing_symbols`. `grep` then `Edit` to delete
+dead code is the rule firing — that is `safe_delete_symbol`. The grep
+version of any of these is noisier and less complete: grep misses
+re-exports, and adds false positives from comments, strings, and unrelated
+attribute lookups on other types. The language server does not.
+
+### How to execute the rule
+
+The index has two parts (a namespace map and per-file stubs) and three
+steps (orient, understand, act).
+
+**Step 1 — Orient. Read the namespace map first.** Before answering the
+user, before any other tool call:
+
+```
+Read .uncoded/namespace.yaml
+```
+
+This lists every symbol in the codebase — directories, files, classes,
+methods, functions — in source order. Without it loaded, "find X"
+answers come from pretrained guesses about what a project like this
+*probably* contains, rather than what is actually here. Read it once,
+in full, at session start.
+
+**Step 2 — Understand. Read the `.pyi` stub before any `.py` source.**
+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
+```
+
+Every file you intend to touch or reference, including tests. The stub
+contains imports, every signature with types, module-level assignments,
+class attributes, and first-sentence docstrings — enough for most
+navigation. Skipping straight 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 — Act. Use Serena to find, read, rename, edit, and delete symbols.**
+With the map and stub loaded, you have the exact `relative_path` and
+`name_path` each Serena tool needs (`ClassName/method` for a method,
+`function_name` for a top-level function). Per task:
+
+- **Find a symbol's definition, or read its body.** `find_symbol` —
+  with `include_body=True` when you need implementation detail the
+  stub does not show. Returns exactly the symbol; no offset arithmetic,
+  no risk of reading too much. Stay on stubs for a wider sweep.
+
+- **Find callers, or check whether a symbol is dead.**
+  `find_referencing_symbols`. Returns every reference resolved by the
+  language server — every import, every call site, every re-export.
+  Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the
+  next move depends on the answer being complete, grep cannot give
+  you that.
+
+- **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 substring false positives.
+
+- **Edit a symbol as a unit.** `replace_symbol_body`,
+  `insert_before_symbol`, `insert_after_symbol`. Immune to the Edit
+  tool's "string not unique" failure mode, never modify a similarly
+  named neighbour, and keep surrounding indentation consistent.
+
+- **Delete a symbol.** `safe_delete_symbol` — not Edit, and not Edit
+  after a manual reference check. The tool fuses two operations: it
+  finds every reference, refuses to delete if any are live, and
+  removes the symbol cleanly only when it is truly dead. The two-step
+  version (find references with grep or `find_referencing_symbols`,
+  then Edit) can drift — the reference check goes stale the moment
+  any file changes between the calls. Whenever the task is "remove
+  this symbol," regardless of how dead it looks, this is the tool.
+
+### Where Read, Edit, and grep are still the right tools
+
+The rule is about source navigation by symbol name. Outside that, the
+non-Serena tools stay correct:
+
+- Free-text or pattern search outside source: Markdown, YAML, TOML,
+  configs, commit messages, notebook JSON, fixture data.
+- Pattern search across signatures (regex over type annotations,
+  decorator usage, alias declarations) — these are not symbol-name
+  lookups even though they sit inside source.
+- Partial-line edits inside a symbol body, once you have retrieved it
+  through Serena.
+- Environments where Serena is unavailable, or the rare stub-less
+  Python file that needs exploratory reading.
+
+The dispatch test is the search term: a symbol name → Serena; a regex
+or free-text phrase → grep.
+<!-- uncoded:end -->

{uncoded-0.5.0 → uncoded-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uncoded
-Version: 0.5.0
+Version: 0.6.0
 Summary: Static symbol indexes for AI-assisted code navigation
 Project-URL: Homepage, https://github.com/alimanfoo/uncoded
 Project-URL: Repository, https://github.com/alimanfoo/uncoded

uncoded-0.6.0/src/uncoded/instruction_files.py

@@ -0,0 +1,164 @@
+"""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, with
+[Serena](https://github.com/oraios/serena) providing language-server-backed
+tools over that index. The point of this scaffolding is one rule.
+
+### The rule
+
+**If your search term is the name of a Python symbol — a class, function,
+method, attribute, or module-level constant — use the index. If it's a
+pattern, regex, or free-text phrase, use grep.**
+
+This applies to every tool call where you are trying to find code, not
+just the first one in the session. The pretrained reflex for "find X" is
+grep, and that reflex is wrong here. `grep -rn 'WriteResult'` to locate a
+class is the rule firing — that is `find_symbol`. `grep -rn 'function_name'`
+to check whether something has callers before a refactor is the rule
+firing — that is `find_referencing_symbols`. `grep` then `Edit` to delete
+dead code is the rule firing — that is `safe_delete_symbol`. The grep
+version of any of these is noisier and less complete: grep misses
+re-exports, and adds false positives from comments, strings, and unrelated
+attribute lookups on other types. The language server does not.
+
+### How to execute the rule
+
+The index has two parts (a namespace map and per-file stubs) and three
+steps (orient, understand, act).
+
+**Step 1 — Orient. Read the namespace map first.** Before answering the
+user, before any other tool call:
+
+```
+Read .uncoded/namespace.yaml
+```
+
+This lists every symbol in the codebase — directories, files, classes,
+methods, functions — in source order. Without it loaded, "find X"
+answers come from pretrained guesses about what a project like this
+*probably* contains, rather than what is actually here. Read it once,
+in full, at session start.
+
+**Step 2 — Understand. Read the `.pyi` stub before any `.py` source.**
+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
+```
+
+Every file you intend to touch or reference, including tests. The stub
+contains imports, every signature with types, module-level assignments,
+class attributes, and first-sentence docstrings — enough for most
+navigation. Skipping straight 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 — Act. Use Serena to find, read, rename, edit, and delete symbols.**
+With the map and stub loaded, you have the exact `relative_path` and
+`name_path` each Serena tool needs (`ClassName/method` for a method,
+`function_name` for a top-level function). Per task:
+
+- **Find a symbol's definition, or read its body.** `find_symbol` —
+  with `include_body=True` when you need implementation detail the
+  stub does not show. Returns exactly the symbol; no offset arithmetic,
+  no risk of reading too much. Stay on stubs for a wider sweep.
+
+- **Find callers, or check whether a symbol is dead.**
+  `find_referencing_symbols`. Returns every reference resolved by the
+  language server — every import, every call site, every re-export.
+  Grep on the name misses re-exports and adds false positives from
+  comments, strings, and attribute lookups on other types. If the
+  next move depends on the answer being complete, grep cannot give
+  you that.
+
+- **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 substring false positives.
+
+- **Edit a symbol as a unit.** `replace_symbol_body`,
+  `insert_before_symbol`, `insert_after_symbol`. Immune to the Edit
+  tool's "string not unique" failure mode, never modify a similarly
+  named neighbour, and keep surrounding indentation consistent.
+
+- **Delete a symbol.** `safe_delete_symbol` — not Edit, and not Edit
+  after a manual reference check. The tool fuses two operations: it
+  finds every reference, refuses to delete if any are live, and
+  removes the symbol cleanly only when it is truly dead. The two-step
+  version (find references with grep or `find_referencing_symbols`,
+  then Edit) can drift — the reference check goes stale the moment
+  any file changes between the calls. Whenever the task is "remove
+  this symbol," regardless of how dead it looks, this is the tool.
+
+### Where Read, Edit, and grep are still the right tools
+
+The rule is about source navigation by symbol name. Outside that, the
+non-Serena tools stay correct:
+
+- Free-text or pattern search outside source: Markdown, YAML, TOML,
+  configs, commit messages, notebook JSON, fixture data.
+- Pattern search across signatures (regex over type annotations,
+  decorator usage, alias declarations) — these are not symbol-name
+  lookups even though they sit inside source.
+- Partial-line edits inside a symbol body, once you have retrieved it
+  through Serena.
+- Environments where Serena is unavailable, or the rare stub-less
+  Python file that needs exploratory reading.
+
+The dispatch test is the search term: a symbol name → Serena; a regex
+or free-text phrase → grep."""
+
+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-0.5.0/AGENTS.md

@@ -1,124 +0,0 @@
-# uncoded
-
-## Problem
-
-AI coding agents navigate codebases poorly. They grep for guessed keywords,
-skim the first few lines of files, and fill gaps from pretraining rather than
-reading the actual code. System prompts encourage this with "make reasonable
-assumptions." The result is plausible-looking output built on a hallucinated
-understanding of code that's sitting right there, unread.
-
-## Approach
-
-A static, pre-computed index gives agents a top-down view of a codebase.
-The agent loads the index at the start of a task, sees the full vocabulary
-of the code, and navigates deterministically to what it needs — no guessing,
-no grep.
-
-Two-level index:
-
-1. **Namespace map** (`.uncoded/namespace.yaml`) — a hierarchical YAML file
-   listing all symbols: directories, files, classes (with attributes
-   and methods), and functions. Covers both source and tests. Loaded into
-   context before any task begins. Gives the agent a world view.
-
-2. **Stub files** (`.uncoded/stubs/`) — one `.pyi` per source file, with
-   imports, full signatures (parameter names, types, return types),
-   first-sentence docstrings, module constants, and class attributes.
-
-## Commands
-
-This project uses [uv](https://docs.astral.sh/uv/). Run commands via
-`uv run` so they execute inside the project environment without needing
-an activated venv.
-
-```
-# Generate (or update) the namespace map, stub files, and CLAUDE.md section
-uv run uncoded sync
-
-# Run tests
-uv run pytest
-```
-
-<!-- uncoded:start -->
-## 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.
-<!-- uncoded:end -->

uncoded-0.5.0/CLAUDE.md

@@ -1,124 +0,0 @@
-# uncoded
-
-## Problem
-
-AI coding agents navigate codebases poorly. They grep for guessed keywords,
-skim the first few lines of files, and fill gaps from pretraining rather than
-reading the actual code. System prompts encourage this with "make reasonable
-assumptions." The result is plausible-looking output built on a hallucinated
-understanding of code that's sitting right there, unread.
-
-## Approach
-
-A static, pre-computed index gives agents a top-down view of a codebase.
-The agent loads the index at the start of a task, sees the full vocabulary
-of the code, and navigates deterministically to what it needs — no guessing,
-no grep.
-
-Two-level index:
-
-1. **Namespace map** (`.uncoded/namespace.yaml`) — a hierarchical YAML file
-   listing all symbols: directories, files, classes (with attributes
-   and methods), and functions. Covers both source and tests. Loaded into
-   context before any task begins. Gives the agent a world view.
-
-2. **Stub files** (`.uncoded/stubs/`) — one `.pyi` per source file, with
-   imports, full signatures (parameter names, types, return types),
-   first-sentence docstrings, module constants, and class attributes.
-
-## Commands
-
-This project uses [uv](https://docs.astral.sh/uv/). Run commands via
-`uv run` so they execute inside the project environment without needing
-an activated venv.
-
-```
-# Generate (or update) the namespace map, stub files, and CLAUDE.md section
-uv run uncoded sync
-
-# Run tests
-uv run pytest
-```
-
-<!-- uncoded:start -->
-## 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.
-<!-- uncoded:end -->

uncoded-0.5.0/src/uncoded/instruction_files.py

@@ -1,133 +0,0 @@
-"""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)