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, checks its settings, resolves the project directory, checks roots, and renders the file init writes. |
cli.py |
Dispatches the configured work. |
extract.py |
Extracts the imports and symbols of parseable Python files, with their signatures and assignments. |
namespace_map.py |
Renders the Python hierarchy as YAML. |
stubs.py |
Renders the 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. |
The code index and the documentation index are independent. Removing every root of one kind removes that part of the index, and its skills, on the next sync.
The skill sources ship as Markdown files in the package. skill.py renders them
into installed 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.
Layers¶
The modules form three layers, and each module imports only from the layers below it.
cli.pyis the top layer. It reads the configuration and calls the layer below for each command.- The middle layer holds one module for each generated file or tool. None of them imports another.
- The foundation holds every other module. These modules can import one another.
An import-linter contract in pyproject.toml lists the modules in each layer
and checks the imports. A new module fails the check until the import-linter
contract places it in a layer.
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 find the project directory in the same way, and resolve their
--in paths from the current working directory. An --in file must also be
inside the project directory after resolving symbolic links. refs gives ty the
project directory as its workspace.