Weaveback — project index

Weaveback is a literate-programming toolchain written in Rust. Source files are authored as annotated documents (AsciiDoc or Markdown); weaveback expands macro calls and extracts named code chunks to produce final source files.

This page is the top-level navigation hub. Every literate AsciiDoc source in the project is listed below with a short description. Generated HTML pages also carry per-page module cross-reference data (imports, imported-by, public symbols) rendered in the Module cross-references panel at the bottom of each page.

Overview

The two core passes can run independently, or via the split front-end tools:

# Build/tangle directly
wb-tangle source.adoc --gen src/

# Separate passes
weaveback-macro source.adoc --output expanded.adoc
weaveback-tangle expanded.adoc --gen src/

Crate overview

Table 1. Workspace crates
Crate	Purpose
weaveback-macro	Macro expansion engine — lexer, parser, AST, evaluator, scripting back-ends
weaveback-tangle	Noweb chunk extractor, safe file writer, SQLite source-map database
split CLI overview	Public command surface: `wb-tangle`, `wb-query`, `wb-serve`, and `wb-mcp`
markup prelude	`¤`-sigil document macros for markup-portable code blocks, diagrams, links
two-pass markup migration	Migration plan from direct `.adoc` sources to `.wvb` sources with AsciiDoc and Markdown projections
weaveback-docgen	Renders all `.adoc` to HTML with dark theme, PlantUML, Rust xref graph
weaveback-core	Shared constants, configuration, and path resolution logic
weaveback-lsp	Language Server Protocol (LSP) client for Rust, Nim, and Python
weaveback Python agent bridge	Literate design and scaffold for the PyO3 + Pydantic agent stack

Project-level literate sources

These documents generate workspace files and cross-cutting scaffolding outside the main Rust crates.

Table 2. project adoc files
Document	Generates
root project files	`Cargo.toml`, `justfile`, `.gitignore`, `weaveback.toml`, and other root files
Python agent bridge	`crates/weaveback-agent-core/`, `crates/weaveback-py/`, and `python/`
CLI option-spec experiment	`scripts/option_spec/` prototype for multi-projection CLI metadata
complexity reduction plan	Cleanup plan for reducing source/generated drift and oversized modules
split CLI specification	`docs/cli.adoc` (generated cross-binary CLI reference)

Split CLI literate sources

The public CLI now lives in four focused binaries.

Table 3. split CLI adoc files
Document	Generates
wb-tangle	`crates/wb-tangle/src/main.rs`
wb-query	`crates/wb-query/src/main.rs`
wb-serve	`crates/wb-serve/src/main.rs`
wb-mcp	`crates/wb-mcp/src/main.rs`

Planning Notes

Some project constraints and future directions are still exploratory. These notes are meant to preserve them without pretending they are settled.

weaveback-tangle literate sources

Start with weaveback_tangle.adoc for the module map and error hierarchy, then follow the dependency order: noweb → safe_writer → db. The CLI main.rs is the thin shell around Clip.

Table 4. weaveback-tangle adoc files
Document	Generates
weaveback-tangle crate index	`crates/weaveback-tangle/src/lib.rs`
chunk parser and expander	`crates/weaveback-tangle/src/noweb.rs`
safe file writer	`crates/weaveback-tangle/src/safe_writer.rs`
persistent database	`crates/weaveback-tangle/src/db.rs`
CLI binary	`crates/weaveback-tangle/src/main.rs`
tests	`crates/weaveback-tangle/src/tests/` (4 files)
Cargo manifest	`crates/weaveback-tangle/Cargo.toml`

weaveback-macro literate sources

Table 5. weaveback-macro adoc files
Document	Generates
weaveback-macro crate index	`crates/weaveback-macro/src/lib.rs`
shared types	`crates/weaveback-macro/src/types.rs`
line index	`crates/weaveback-macro/src/line_index.rs`
lexer	`crates/weaveback-macro/src/lexer/mod.rs` `crates/weaveback-macro/src/lexer/tests.rs`
parser	`crates/weaveback-macro/src/parser/mod.rs`
AST	`crates/weaveback-macro/src/ast/mod.rs` `crates/weaveback-macro/src/ast/serialization.rs` `crates/weaveback-macro/src/ast/tests.rs`
evaluator index	`crates/weaveback-macro/src/evaluator/mod.rs` `crates/weaveback-macro/src/evaluator/errors.rs` `crates/weaveback-macro/src/evaluator/lexer_parser.rs`
evaluator state	`crates/weaveback-macro/src/evaluator/state.rs`
evaluator output sinks	`crates/weaveback-macro/src/evaluator/output.rs`
evaluator core	`crates/weaveback-macro/src/evaluator/core.rs`
evaluator builtins	`crates/weaveback-macro/src/evaluator/builtins.rs` `crates/weaveback-macro/src/evaluator/case_conversion.rs` `crates/weaveback-macro/src/evaluator/source_utils.rs`
script back-ends	`crates/weaveback-macro/src/evaluator/monty_eval.rs`
public eval API	`crates/weaveback-macro/src/evaluator/eval_api.rs`
evaluator tests index tests-macros tests-control tests-case tests-scripting tests-output	`crates/weaveback-macro/src/evaluator/tests/` (21 files)
macro_api	`crates/weaveback-macro/src/macro_api.rs`
CLI binary	`crates/weaveback-macro/src/bin/weaveback-macro.rs`
Cargo manifest	`crates/weaveback-macro/Cargo.toml`

weaveback-core literate sources

Table 6. weaveback-core adoc files
Document	Generates
weaveback-core index	`crates/weaveback-core/src/lib.rs`
Cargo manifest	`crates/weaveback-core/Cargo.toml`

weaveback-lsp literate sources

Table 7. weaveback-lsp adoc files
Document	Generates
weaveback-lsp index	`crates/weaveback-lsp/src/lib.rs`
Cargo manifest	`crates/weaveback-lsp/Cargo.toml`

weaveback-docgen literate sources

Renders .adoc files to dark-themed HTML with PlantUML diagrams, literate chunk IDs, and cross-reference panels.

Table 8. weaveback-docgen adoc files
Document	Generates
weaveback-docgen index	`crates/weaveback-docgen/src/main.rs` + `lib.rs`
acdc renderer	`crates/weaveback-docgen/src/render.rs`
HTML post-processor	`crates/weaveback-docgen/src/inject.rs`
cross-reference engine	`crates/weaveback-docgen/src/xref.rs`
literate index builder	`crates/weaveback-docgen/src/literate_index.rs`
PlantUML integration	`crates/weaveback-docgen/src/plantuml.rs`
Cargo manifest	`crates/weaveback-docgen/Cargo.toml`

Project configuration

Root-level project files — workspace manifest, justfile, tangle config, toolchain pin, and editor/IDE settings — all generated from a single literate source.

Table 9. Project configuration adoc files
Document	Generates
project.adoc	`Cargo.toml`, `justfile`, `weaveback.toml`, `.gitignore`, `rust-toolchain.toml`, `.mcp.json`, `.vscode/settings.json`, `Containerfile`, `flake.nix` (snapshot)
workflows.adoc	`.github/workflows/ci.yml`, `pages.yml`, `release.yml`

Packaging and distribution

Table 10. Packaging adoc files
Document	Generates
packaging.adoc	`packaging/update_release.py` — downloads release assets, writes AUR PKGBUILD and `flake.nix`

Scripts and UI

Table 11. Scripts adoc files
Document	Generates
scripts.adoc	`scripts/install.py`, `scripts/gliner_experiment.py`, `scripts/weaveback-graph/` Python package
serve-ui.adoc	TypeScript/CSS browser UI for the `wb-serve` documentation server (`src/`, `package.json`, `tsconfig.json`)

Examples

Each example sub-project has a config.adoc capturing its build and tooling files.

Table 12. Example adoc files
Document	Generates
events/config.adoc	`examples/events/justfile`, `meson.build`, `.gitignore`
hello-world/config.adoc	`examples/hello-world/justfile`, `.gitignore`
c_enum/config.adoc	`examples/c_enum/.gitignore`
nim-adoc/config.adoc	`examples/nim-adoc/meson.build`, `.gitignore`
nim-adoc/scripts/gen_docs.adoc	`examples/nim-adoc/scripts/gen_docs.py`
graph-prototype/config.adoc	`examples/graph-prototype/Cargo.toml`

Platform tooling and test fixtures

Table 13. Platform tooling adoc files
Document	Generates
windows.adoc	`windows/verify.ps1`, `windows/verification.wsb` — Windows sandbox verification scripts
test-data.adoc	`test-data/test-c-project/Taskfile` — test fixture for the C project integration tests

Architecture and design

New here? Start with why.adoc — the intent, tradeoffs, and design rationale behind every major decision. Then read architecture.adoc for the structural detail.

See architecture.adoc for a detailed discussion of:

The literate-programming model and toolchain pipeline
Backpropagation (`apply-back`) tool design
MCP server interface and agent tools
Semantic LSP bridge (Go to Definition, Find References)
Macro tracing and the source-map schema
Build-system integration (--depfile, --stamp)