uncoded 3.0.0__tar.gz → 3.0.1__tar.gz

{uncoded-3.0.0 → uncoded-3.0.1}/.agents/skills/uncoded-code-navigation/SKILL.md

@@ -31,8 +31,8 @@ tools don't.
 
 ## How to execute the rule
 
-The index has two parts: a namespace map and per-file stubs. Follow this
-sequence.
+The index has two parts: a namespace map and per-file stubs. Start with the map
+and add detail only when the task needs it.
 
 **Step 1: Orient. Read the namespace map first.** If the map is missing, run the
 repository's configured `uncoded sync` command. Then, before answering the user,
@@ -55,18 +55,18 @@ src/foo/bar.py      →  .uncoded/stubs/src/foo/bar.pyi
 tests/test_foo.py   →  .uncoded/stubs/tests/test_foo.pyi
 ```
 
-Read the stub for every file you intend to touch or reference, including tests.
-The stub contains imports, every signature with types, module-level assignments,
-and class attributes. That is 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.
+The stub contains imports, parameter names and annotations, return types,
+module-level assignments, and class attributes. It omits parameter defaults,
+decorators, docstrings, and function bodies. Read source when the task depends
+on an omitted detail or needs exact code. 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 `uncoded body` to read a symbol's body. Use `uncoded refs`
 to find every reference to a symbol. Use `Edit` (with `uncoded body`'s output as
-`old_string`) to change a symbol. With the map and stub loaded, you have the
-exact `relative_path` and `name_path` each tool needs. Use `ClassName/method`
-for a method and `function_name` for a top-level function. Per task:
+`old_string`) to change a symbol. Use the exact `relative_path` and `name_path`
+from the map. Use `ClassName/method` for a method and `function_name` for a
+top-level function. Per task:
 
 - **Read a symbol's body.** `uvx uncoded body <name_path> --in <relative_path>`
   prints the symbol's source text to stdout, byte-identical to disk. Returns

{uncoded-3.0.0 → uncoded-3.0.1}/.claude/skills/uncoded-code-navigation/SKILL.md

@@ -31,8 +31,8 @@ tools don't.
 
 ## How to execute the rule
 
-The index has two parts: a namespace map and per-file stubs. Follow this
-sequence.
+The index has two parts: a namespace map and per-file stubs. Start with the map
+and add detail only when the task needs it.
 
 **Step 1: Orient. Read the namespace map first.** If the map is missing, run the
 repository's configured `uncoded sync` command. Then, before answering the user,
@@ -55,18 +55,18 @@ src/foo/bar.py      →  .uncoded/stubs/src/foo/bar.pyi
 tests/test_foo.py   →  .uncoded/stubs/tests/test_foo.pyi
 ```
 
-Read the stub for every file you intend to touch or reference, including tests.
-The stub contains imports, every signature with types, module-level assignments,
-and class attributes. That is 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.
+The stub contains imports, parameter names and annotations, return types,
+module-level assignments, and class attributes. It omits parameter defaults,
+decorators, docstrings, and function bodies. Read source when the task depends
+on an omitted detail or needs exact code. 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 `uncoded body` to read a symbol's body. Use `uncoded refs`
 to find every reference to a symbol. Use `Edit` (with `uncoded body`'s output as
-`old_string`) to change a symbol. With the map and stub loaded, you have the
-exact `relative_path` and `name_path` each tool needs. Use `ClassName/method`
-for a method and `function_name` for a top-level function. Per task:
+`old_string`) to change a symbol. Use the exact `relative_path` and `name_path`
+from the map. Use `ClassName/method` for a method and `function_name` for a
+top-level function. Per task:
 
 - **Read a symbol's body.** `uvx uncoded body <name_path> --in <relative_path>`
   prints the symbol's source text to stdout, byte-identical to disk. Returns

{uncoded-3.0.0 → uncoded-3.0.1}/.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
           fetch-depth: 0
       - uses: astral-sh/setup-uv@v6
       - run: uv python install 3.12
-      - run: uv sync --extra dev
+      - run: uv sync
       - run: uv run pre-commit run --all-files
 
   test:
@@ -29,7 +29,7 @@ jobs:
           fetch-depth: 0
       - uses: astral-sh/setup-uv@v6
       - run: uv python install ${{ matrix.python-version }}
-      - run: uv sync --extra dev
+      - run: uv sync
       - run: uv run pytest -v -m "integration or not integration"
         env:
           PYTHONWARNDEFAULTENCODING: "1"

uncoded-3.0.1/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Docs
+
+# The site is already built in strict mode by the pull request checks. This
+# workflow repeats that build from main and publishes its output.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - run: uv sync --locked
+      - run: uv run mkdocs build
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

{uncoded-3.0.0 → uncoded-3.0.1}/.pre-commit-config.yaml

@@ -48,6 +48,12 @@ repos:
         args: ["--write"]
         files: \.md$
         exclude: ^(CLAUDE\.md|(\.claude|\.agents)/skills/.*)$
+      - id: mkdocs
+        name: build documentation
+        entry: uv run mkdocs build
+        language: system
+        always_run: true
+        pass_filenames: false
       - id: uncoded
         name: uncoded
         entry: uv run uncoded sync

{uncoded-3.0.0 → uncoded-3.0.1}/AGENTS.md

@@ -73,16 +73,11 @@ Clone and install dev dependencies:
 ```sh
 git clone https://github.com/alimanfoo/uncoded
 cd uncoded
-uv sync --extra dev
+uv sync
 uv run uncoded sync
 uv run pre-commit install
 ```
 
-Run `uv sync --extra dev` before the first pre-commit run in a clean checkout.
-The ty hook type-checks `src` and `tests`. The test modules import dev-only
-packages such as pytest and hypothesis. Without the dev extras in the venv, ty
-cannot resolve those imports and reports spurious errors.
-
 This repo uses uncoded on itself. The pre-commit hook runs `uv run uncoded sync`
 on each commit. The local `.uncoded/` index is ignored. If the hook modifies a
 tracked generated skill file, the commit fails. Re-stage the skill file and

uncoded-3.0.1/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: uncoded
+Version: 3.0.1
+Summary: Symbol index with associated code reading tools for AI coding agent navigation
+Project-URL: Homepage, https://github.com/alimanfoo/uncoded
+Project-URL: Repository, https://github.com/alimanfoo/uncoded
+Author-email: Alistair Miles <alimanfoo@googlemail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# uncoded
+
+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. The result is plausible-looking output built on a hallucinated
+understanding of the code.
+
+**uncoded** builds a static navigation index that gives coding agents
+progressively deeper views of a codebase. Agents start with the namespace map,
+read compact stubs when they need parameters and types, and retrieve only the
+symbol bodies that they need. Each view adds detail without making the agent
+read whole source files.
+
+The `uncoded body` command retrieves symbol bodies, and `uncoded refs` finds
+every reference to a symbol. References cover callers, dead-symbol checks, and
+the full set of sites to update before a rename.
+
+Read the [documentation](https://alimanfoo.github.io/uncoded/) for installation,
+configuration, command reference, upgrades, and contributor guidance.

uncoded-3.0.1/README.md

@@ -0,0 +1,19 @@
+# uncoded
+
+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. The result is plausible-looking output built on a hallucinated
+understanding of the code.
+
+**uncoded** builds a static navigation index that gives coding agents
+progressively deeper views of a codebase. Agents start with the namespace map,
+read compact stubs when they need parameters and types, and retrieve only the
+symbol bodies that they need. Each view adds detail without making the agent
+read whole source files.
+
+The `uncoded body` command retrieves symbol bodies, and `uncoded refs` finds
+every reference to a symbol. References cover callers, dead-symbol checks, and
+the full set of sites to update before a rename.
+
+Read the [documentation](https://alimanfoo.github.io/uncoded/) for installation,
+configuration, command reference, upgrades, and contributor guidance.

uncoded-3.0.1/docs/agent-workflow.md

@@ -0,0 +1,73 @@
+# Agent workflow
+
+The generated skills tell your agent when to load the index, read source, and
+check references. Once you have [set up the repository](getting-started.md), the
+agent follows this workflow during a coding task.
+
+## Start a task
+
+The agent loads `.uncoded/namespace.yaml` in full to learn the Python symbols
+that exist. For a documentation task, it loads `.uncoded/docs.yaml` to find the
+relevant file and heading.
+
+Navigation skills load once per session. Their instructions apply throughout the
+session.
+
+## Read code
+
+The agent adds detail only when the task needs it. This progressive disclosure
+keeps broad work on compact views and limits source reads to the implementations
+that matter.
+
+1. The namespace map shows every indexed symbol and its file. It is often enough
+   for questions about structure or where a feature lives.
+2. The file's stub under `.uncoded/stubs/` adds imports, parameter names and
+   annotations, return types, constants, and attributes. It omits parameter
+   defaults, decorators, docstrings, and function bodies. It is often enough for
+   questions about names and types.
+3. `uncoded body` returns one symbol's exact source when the task needs it:
+
+```sh
+uvx uncoded body greet --in src/greetings.py
+```
+
+This example assumes `greet` is defined in `src/greetings.py`. For a method, use
+`ClassName/method_name`. See [the command reference](commands.md#body) for
+supported symbols and paths.
+
+A file with no indexed symbols has no stub, so the agent reads the file
+directly. Free text and patterns still belong in a text search.
+
+## Change a symbol
+
+Before renaming, changing a signature, or deleting a symbol, the agent checks
+its references:
+
+```sh
+uvx uncoded refs greet --in src/greetings.py
+```
+
+The results identify the sites to inspect and update. After changing indexed
+Python or Markdown files, the agent runs `uncoded sync` before navigating again.
+
+## Review consistency
+
+With `source-roots` configured, uncoded also generates a consistency review
+skill. It looks for concrete disagreements between names, signatures,
+docstrings, and behavior. Every finding must quote both conflicting claims and
+show that they describe the same concept.
+
+Invoke it with `$uncoded-consistency-review` in Codex or
+`/uncoded-consistency-review` in Claude Code.
+
+## Know the limits
+
+The code index describes static Python structure. It does not run imports or
+resolve runtime registration. Files that cannot be parsed or decoded are skipped
+with a warning.
+
+The documentation index records headings that begin with `#`. It excludes
+underlined headings and headings inside fenced code blocks. Read documentation
+sections directly; `body` and `refs` operate on Python symbols.
+
+Keep using tests and type checks to verify changes.

uncoded-3.0.1/docs/architecture.md

@@ -0,0 +1,43 @@
+# Architecture
+
+uncoded builds static code and documentation indexes. The CLI reads the
+configuration, validates roots, and coordinates extraction and file writes.
+
+## Sync pipeline
+
+| Module             | Responsibility                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------------- |
+| `config.py`        | Finds the nearest configuration and resolves the project root.                            |
+| `cli.py`           | Validates roots and dispatches the configured work.                                       |
+| `extract.py`       | Extracts symbols from parseable Python files.                                             |
+| `namespace_map.py` | Renders the Python hierarchy as YAML.                                                     |
+| `stubs.py`         | Extracts imports, signatures, and assignments into a mirrored `.pyi` tree.                |
+| `docs_map.py`      | Extracts Markdown headings and renders their hierarchy as YAML.                           |
+| `skill.py`         | Writes navigation and consistency review skills to both agent directories.                |
+| `sync.py`          | Writes and removes files only when needed; reports changes without writing in check mode. |
+
+Code and documentation indexes are independent. Removing a root type removes its
+generated index and skills on the next sync.
+
+The skill instructions ship as Markdown package resources. `skill.py` renders
+them into repository skill files. `markers.py` defines the provenance marker
+shared by every generated output.
+
+## Symbol tools
+
+`resolver.py` locates a named Python symbol in the abstract syntax tree and
+records its source position. `body.py` uses that location to return the original
+source text.
+
+`refs.py` sends the position to a one-shot `ty` language server, then sorts and
+formats the returned references. `ty` resolves the references; uncoded provides
+the command and output format.
+
+## Path boundary
+
+`sync` and `check` anchor all generated files at the configuration file's parent
+directory. Every configured root must remain inside that directory after
+resolving symbolic links.
+
+`body` and `refs` resolve their `--in` paths from the current working directory.
+They can operate without a project configuration.

uncoded-3.0.1/docs/commands.md

@@ -0,0 +1,85 @@
+# Commands
+
+Run uncoded with `uvx uncoded`. Contributors use `uv run uncoded` to run the
+code in their checkout.
+
+| To…                                   | Use                                     |
+| ------------------------------------- | --------------------------------------- |
+| Build or refresh the index and skills | `uvx uncoded sync`                      |
+| Check generated files without writing | `uvx uncoded check`                     |
+| Read a Python symbol's source         | `uvx uncoded body <symbol> --in <file>` |
+| Find references to a Python symbol    | `uvx uncoded refs <symbol> --in <file>` |
+
+## `sync`
+
+```sh
+uvx uncoded sync
+```
+
+Builds or refreshes every configured index and navigation skill. Output lists
+files created, updated, or removed. Running it from a subdirectory produces
+output at the same project root.
+
+Files that cannot be parsed or decoded are skipped with a warning. Invalid
+configuration or roots cause exit status `1`.
+
+## `check`
+
+```sh
+uvx uncoded check
+```
+
+Runs the same pipeline as `sync` without changing files.
+
+| Status | Meaning                                                                        |
+| ------ | ------------------------------------------------------------------------------ |
+| `0`    | All generated files match a fresh build.                                       |
+| `1`    | A file would be created, updated, or removed, or the configuration is invalid. |
+
+Run `sync` first in a fresh checkout. The local index is not committed.
+
+## `body`
+
+```sh
+uvx uncoded body greet --in src/greetings.py
+uvx uncoded body Greeter/greet --in src/greetings.py
+```
+
+Prints the named symbol's source to standard output, exactly as written in the
+file. These examples assume a `greet` function or a `Greeter.greet` method in
+`src/greetings.py`.
+
+Use one name for a top-level function, class, module assignment, or Python 3.12
+`type` alias. Use `Class/member` for a method or class attribute. Deeper paths
+and empty segments are unsupported.
+
+The `--in` path is relative to your current directory, not the configuration
+file. No project configuration is required.
+
+## `refs`
+
+```sh
+uvx uncoded refs greet --in src/greetings.py
+uvx uncoded refs Greeter/greet --in src/greetings.py
+```
+
+Finds references to the symbol. Names and `--in` paths follow the same rules as
+`body`. Each result is printed as:
+
+```text
+path:line:column
+```
+
+Positions are one-based. Results are sorted by path and position. Paths within
+the current directory are relative; other paths are absolute. Empty output with
+exit status `0` means no references were found.
+
+Reference resolution uses the pinned `ty` language server through `uvx`. The
+first call may download it. `uvx` must be on `PATH`.
+
+## Lookup errors
+
+`body` and `refs` exit with status `1` if the source cannot be read or parsed,
+the symbol is missing, or its name path is unsupported. A reference lookup also
+fails if the language server fails. Missing required arguments exit with status
+`2`.

uncoded-3.0.1/docs/configuration.md

@@ -0,0 +1,57 @@
+# Configuration
+
+Use one configuration file in your repository root. Choose the directories
+containing Python code and the files or directories containing Markdown docs.
+
+## Choose a configuration file
+
+For a standalone configuration, use `.uncoded.toml`:
+
+```toml title=".uncoded.toml"
+source-roots = ["src", "tests"]
+doc-roots = ["README.md", "docs"]
+```
+
+To keep the settings in `pyproject.toml`, add a section there instead:
+
+```toml title="pyproject.toml"
+[tool.uncoded]
+source-roots = ["src", "tests"]
+doc-roots = ["README.md", "docs"]
+```
+
+Both formats work in Python and non-Python repositories. At least one root list
+must be non-empty. You can configure either type on its own.
+
+## Settings
+
+| Setting        | Accepted paths                        | Indexed content                |
+| -------------- | ------------------------------------- | ------------------------------ |
+| `source-roots` | Directories                           | Python symbols and signatures. |
+| `doc-roots`    | Directories or individual `.md` files | Markdown headings.             |
+
+Every path is relative to the configuration file's directory and must exist.
+Paths that resolve outside that directory are rejected, including through
+symbolic links.
+
+uncoded searches upwards from the current directory and uses the nearest
+configuration. In one directory, `.uncoded.toml` takes precedence over a
+`pyproject.toml` without `[tool.uncoded]`. If both files configure uncoded, the
+command fails. Keep the settings in one file.
+
+## Generated files
+
+| Output                                        | When generated         | Commit it? |
+| --------------------------------------------- | ---------------------- | ---------- |
+| `.uncoded/namespace.yaml`                     | `source-roots` is set. | No.        |
+| `.uncoded/stubs/`                             | `source-roots` is set. | No.        |
+| `.uncoded/docs.yaml`                          | `doc-roots` is set.    | No.        |
+| Code navigation and consistency review skills | `source-roots` is set. | Yes.       |
+| Documentation navigation skill                | `doc-roots` is set.    | Yes.       |
+
+The index's generated `.gitignore` keeps `.uncoded/` out of Git. Skills are
+written to both `.agents/skills/` and `.claude/skills/`.
+
+When you remove a root type and run `sync`, uncoded removes that type's index
+and skills. Every generated file has a provenance marker. Change generated files
+by running `sync`, rather than editing them by hand.

uncoded-3.0.1/docs/contributing.md

@@ -0,0 +1,73 @@
+# Contributing
+
+Use Python 3.12 or later and [uv](https://docs.astral.sh/uv/).
+
+## Set up a checkout
+
+```sh
+git clone https://github.com/alimanfoo/uncoded
+cd uncoded
+uv sync
+uv run uncoded sync
+uv run pre-commit install
+```
+
+The development dependency group includes tests, linting, type checking,
+documentation, and pre-commit tools. The local index is ignored by Git, so build
+it before navigating the checkout.
+
+On Windows, enable symbolic links before cloning:
+
+```sh
+git config --global core.symlinks true
+```
+
+This lets Git check out `CLAUDE.md` as the symbolic link to `AGENTS.md`.
+
+## Run the tests
+
+```sh
+uv run python -X warn_default_encoding -m pytest -q --tb=short
+```
+
+The suite requires complete branch coverage. The Python option enables
+`EncodingWarning`, which the test configuration turns into an error.
+
+For a focused run without the repository-wide coverage gate:
+
+```sh
+uv run python -X warn_default_encoding -m pytest -q --tb=short tests/test_stubs.py --no-cov
+```
+
+## Run the checks
+
+```sh
+uv run pre-commit run --all-files
+```
+
+The suite runs formatters, linters, type and complexity checks, the strict
+documentation build, and `uncoded sync`. If a hook changes files, stage the
+changes and run the suite again. Never commit with `--no-verify`.
+
+## Edit the docs
+
+```sh
+uv run mkdocs serve
+```
+
+Preview the site at `http://127.0.0.1:8000/`. Run `uv run mkdocs build` to check
+links, anchors, and navigation. The strict build treats warnings as errors.
+
+## Change indexed content
+
+After editing Python code or indexed Markdown, run `uv run uncoded sync` before
+navigating again. Commit any changed generated skill files with the sources that
+produced them. Read
+[AGENTS.md](https://github.com/alimanfoo/uncoded/blob/main/AGENTS.md) for the
+code and testing conventions.
+
+## Release
+
+Publish a GitHub release from its version tag. `.github/workflows/publish.yml`
+builds the source distribution and wheel and uploads them with PyPI Trusted
+Publishing. The repository does not store a PyPI token.

uncoded-3.0.1/docs/getting-started.md

@@ -0,0 +1,83 @@
+# Get started
+
+Set up uncoded in your repository, then ask your agent to use the index. You
+need [uv](https://docs.astral.sh/uv/getting-started/installation/). `uvx` runs
+uncoded on demand; there is no separate install step.
+
+<span id="install-uv"></span> <span id="choose-a-configuration-file"></span>
+
+## 1. Choose what to index
+
+Create `.uncoded.toml` in your repository root:
+
+```toml title=".uncoded.toml"
+source-roots = ["src", "tests"]
+doc-roots = ["README.md", "docs"]
+```
+
+Replace these paths with directories and files that exist in your repository.
+`source-roots` indexes Python files. `doc-roots` indexes Markdown headings.
+Remove either line if you only need the other index.
+
+<span id="build-the-index"></span>
+
+## 2. Build the index
+
+Run from your repository root:
+
+```sh
+uvx uncoded sync
+```
+
+The command prints the files it creates. With both root types configured, you
+will find:
+
+| Output                                  | Purpose                                                 |
+| --------------------------------------- | ------------------------------------------------------- |
+| `.uncoded/namespace.yaml`               | Lists Python symbols and their locations.               |
+| `.uncoded/stubs/`                       | Records imports, signatures, constants, and attributes. |
+| `.uncoded/docs.yaml`                    | Lists Markdown files and headings.                      |
+| `.agents/skills/` and `.claude/skills/` | Give agents the navigation instructions.                |
+
+Commit the generated skill files. The `.uncoded/` index stays local and is
+ignored by Git.
+
+<span id="tell-agents-to-use-the-skills"></span>
+
+## 3. Tell your agent to use it
+
+Add these instructions to your repository's `AGENTS.md` or `CLAUDE.md`:
+
+```text title="Agent instructions"
+## Before you start
+
+- Load the `uncoded-code-navigation` skill once per session, before searching, reading or editing any code.
+- Load the `uncoded-doc-navigation` skill once per session, before searching, reading or editing any docs.
+```
+
+Keep only the lines for the root types you configured.
+
+## 4. Try a task
+
+Start a new agent session in the repository and ask:
+
+```text title="Example prompt"
+Explain this repository using the uncoded navigation skills.
+Read the index first, then show me one function or documentation section
+that explains how the project works.
+```
+
+For Python code, the agent should move from `.uncoded/namespace.yaml` to a
+matching stub and then to `uncoded body` as it needs more detail. The agent can
+stop after the map or stub when that view answers the question. For
+documentation, it should load `.uncoded/docs.yaml` and read the relevant
+section.
+
+<span id="keep-the-index-current"></span>
+
+When you change indexed code or docs, run `uvx uncoded sync` again before
+navigating. [Keep the index current](keeping-current.md) explains how to
+automate this with pre-commit.
+
+See [Configuration](configuration.md) to use `pyproject.toml` or change the
+indexed paths.