weaveback — combined tool

Runs macro expansion and chunk extraction in one pass.

weaveback [OPTIONS] <INPUTS>...      # explicit files
weaveback [OPTIONS] --dir <DIR>      # auto-discover driver files

Options

Flag Default Description

--input-dir <PATH>

.

Base directory prepended to every input path

--special <CHAR>

%

Macro invocation character

--include <PATHS>

.

Include search paths for %include/%import (colon-separated on Unix)

--gen <PATH>

gen

Base directory for generated output files

--open-delim <STR>

<[

Chunk-open delimiter

--close-delim <STR>

]>

Chunk-close delimiter

--chunk-end <STR>

@

End-of-chunk marker

--comment-markers <STR>

#,//

Comment prefixes recognised before chunk delimiters (comma-separated)

--formatter <EXT=CMD>

Run a formatter after writing each file, e.g. rs=rustfmt; repeatable

--dump-expanded

off

Print macro-expanded text to stderr before noweb processing

--dir <DIR>

Auto-discover driver files; mutually exclusive with positional inputs

--ext <EXT>

md

File extension to scan in --dir mode; repeatable

--depfile <PATH>

Write a Makefile depfile listing every source file read

--stamp <PATH>

Touch this file on success (build-system stamp)

--db <PATH>

weaveback.db

Path to the source-map database

--allow-env

off

Enable %env(NAME) (disabled by default to protect secrets)

--allow-home

off

Allow @file ~/… chunks to write outside the gen/ sandbox

--dry-run

off

Print output paths without writing anything

Directory mode

--dir scans a directory tree recursively for files matching --ext, determines which are drivers (top-level files) vs fragments (included by another file), and processes each driver. No changes needed when new files are added.

weaveback --dir src --include . --gen src
weaveback --dir src --ext adoc --include . --gen src
weaveback --dir src --ext md --ext adoc --include . --gen src

--dump-expanded is the first thing to check when a chunk can’t be found or expands unexpectedly — it prints the macro-expanded intermediate text that weaveback-tangle receives.

Build-system integration

--depfile and --stamp together let a single build rule cover an entire directory of literate sources:

custom_target('gen',
  output  : ['gen.stamp'],
  depfile : 'gen.d',
  command : [weaveback,
             '--dir',     meson.current_source_dir() / 'src',
             '--ext',     'adoc',
             '--include', meson.current_source_dir(),
             '--stamp',   '@OUTPUT0@',
             '--depfile', '@DEPFILE@'],
)
Note

List only the stamp in output, never the .d file. Ninja consumes the depfile internally; declaring it as an output makes ninja think it is always missing and reruns the target on every build.

Subcommands

weaveback where <file> <line>        # trace output line to its noweb chunk
weaveback trace <file> <line>        # full two-level trace (noweb + macro)
weaveback apply-back [OPTIONS]       # propagate gen/ edits to literate source
weaveback impact <chunk>             # show transitive impact of a chunk change
weaveback graph [OPTIONS]            # export dependency graph as DOT (Graphviz)
weaveback lsp <command> [ARGS]       # semantic language server operations
weaveback mcp                        # start MCP server for IDE/agent integration

apply-back

When you edit a file in gen/ directly, the next weaveback run refuses to overwrite it (ModifiedExternally). apply-back closes the loop: it diffs the modified gen/ file against the stored baseline, traces each changed line back to its literate source, and patches the source file.

weaveback apply-back                     # process all modified gen/ files
weaveback apply-back src/foo.c           # process one specific file
weaveback apply-back --dry-run           # show patches without writing
weaveback --gen path/to/gen apply-back   # use non-default gen/ directory

Macro-generated content (%def, %rhaidef bodies) is traced back through the two-level source map to the original definition or call-site argument and patched automatically where unambiguous.

apply-back supports size-changing edits (insertions and deletions) by attributing new lines to the chunk of the preceding or succeeding line.

impact

Shows every chunk and output file transitively affected if a given chunk changes. Outputs a JSON object.

weaveback impact my-config-chunk

graph

Exports the chunk-dependency graph in DOT (Graphviz) format for visualization.

weaveback graph | dot -Tsvg -o deps.svg
weaveback graph --chunk my-module | dot -Tpng -o my-module.png

lsp

Provides semantic navigation and intelligence by bridging language-specific LSPs (like rust-analyzer) with Weaveback source maps.

weaveback lsp definition gen/main.rs 100 8
weaveback lsp references gen/main.rs 100 8
Command Description

definition

Find symbol definition and map back to .adoc

references

Find all references and map back to .adoc
Flag Default Description

--lsp-cmd <CMD>

(auto)

Manual override for LSP command (e.g. nimlsp)

--lsp-lang <ID>

(auto)

Manual override for language ID (e.g. nim)

serve

Starts a local HTTP server at http://127.0.0.1:<port>/ that serves docs/html/, pushes live-reload events to connected browsers when HTML files change, and provides the inline chunk editor for literate source files.

weaveback serve                          # default port 7779
weaveback serve --port 8080             # custom port
weaveback serve --html /other/dir       # serve a different directory
Flag Default Description

--port <N>

7779

TCP port to listen on

--html <PATH>

<root>/docs/html

Directory to serve

--open-delim <STR>

<[

Chunk-open delimiter for the tangle oracle

--close-delim <STR>

]>

Chunk-close delimiter for the tangle oracle

--chunk-end <STR>

@@

Chunk-end marker for the tangle oracle

--comment-markers <STR>

//

Comment prefixes for the oracle (comma-separated)

--ai-backend <MODE>

claude-cli

AI backend for /__ai: claude-cli, anthropic, gemini, ollama, or openai

--ai-model <STR>

(default)

AI model name (e.g. gemini-1.5-pro, llama3, gpt-4o)

--ai-endpoint <URL>

(default)

Base URL for ollama or openai backends

The tangle-oracle flags must match the delimiters used by the project being served. They are only needed if you use non-default chunk syntax and intend to use the /__apply inline editor endpoint.

AI Backend Modes

claude-cli (default)

Shells out to claude -p --output-format stream-json, using the authenticated Claude Code session already on the machine — no extra credentials required.

anthropic

Calls the Anthropic Messages API directly. Requires the ANTHROPIC_API_KEY environment variable.

gemini

Calls the Google Gemini API. Requires the GOOGLE_API_KEY environment variable.

ollama

Calls a local Ollama instance. Uses --ai-endpoint (default: http://localhost:11434) and --ai-model (default: llama3).

openai

Calls an OpenAI-compatible API. Requires OPENAI_API_KEY (unless using a local provider) and --ai-endpoint.

See architecture.adoc for the full design, HTTP endpoint reference, and inline editor documentation.

weaveback-macro — macro expander only

weaveback-macro [OPTIONS] <INPUTS>...
weaveback-macro [OPTIONS] --dir <DIR>
Flag Default Description

--output <PATH>

-

Output file (- for stdout)

--special <CHAR>

%

Macro invocation character

--include <PATHS>

.

Include search paths

--pathsep <STR>

: / ;

Path separator (platform default)

--input-dir <PATH>

.

Base directory prepended to each input path

--allow-env

off

Enable %env(NAME)

--dir <DIR>

Auto-discover driver files

--ext <EXT>

md

File extension to scan in --dir mode; repeatable

weaveback-tangle — chunk extractor only

weaveback-tangle [OPTIONS] <FILES>...
weaveback-tangle [OPTIONS] -              # read from stdin
Flag Default Description

--gen <PATH>

gen

Base directory for generated output files

--output <PATH>

stdout

Output for --chunks extraction

--chunks <NAMES>

Comma-separated chunk names to extract to stdout

--open-delim <STR>

<[

Chunk-open delimiter

--close-delim <STR>

]>

Chunk-close delimiter

--chunk-end <STR>

@

End-of-chunk marker

--comment-markers <STR>

#,//

Comment prefixes (comma-separated)

--formatter <EXT=CMD>

Run a formatter after writing each file

--allow-home

off

Allow @file ~/… chunks to write outside the gen/ sandbox

--dry-run

off

Print output paths without writing anything

weaveback-docgen — documentation generator

Renders AsciiDoc sources to HTML, post-processes them with chunk IDs and a literate-source index, and optionally injects cross-reference data.

weaveback-docgen [OPTIONS]
Flag Default Description

--out-dir <PATH>

docs/html

Directory for rendered HTML output

--theme-dir <PATH>

Directory with docinfo.html templates

--special <CHAR>

De-duplicate CHAR (repeatable)

--xref-cmd <CMD>

External command for cross-reference analysis

--no-xref

off

Skip cross-reference analysis entirely

--ai-xref

off

Use LSP (rust-analyzer) for precise semantic links

See architecture.adoc for the full documentation pipeline details.