{"id":47677738,"url":"https://github.com/giannifer7/weaveback","last_synced_at":"2026-04-14T07:06:42.397Z","repository":{"id":273431807,"uuid":"919143811","full_name":"giannifer7/weaveback","owner":"giannifer7","description":"Bidirectional literate programming toolchain (noweb, macros, source tracing)","archived":false,"fork":false,"pushed_at":"2026-04-04T14:11:34.000Z","size":9470,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-04T17:07:17.606Z","etag":null,"topics":["code-generation","developer-tools","literate-programming","macros","noweb","rust"],"latest_commit_sha":null,"homepage":"https://github.com/giannifer7/weaveback","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/giannifer7.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-0BSD","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-19T20:08:18.000Z","updated_at":"2026-04-04T14:09:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"782958b8-fc61-4f90-8c59-80f6f60a9006","html_url":"https://github.com/giannifer7/weaveback","commit_stats":null,"previous_names":["giannifer7/azadi","giannifer7/weaveback"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/giannifer7/weaveback","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giannifer7%2Fweaveback","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giannifer7%2Fweaveback/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giannifer7%2Fweaveback/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giannifer7%2Fweaveback/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giannifer7","download_url":"https://codeload.github.com/giannifer7/weaveback/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giannifer7%2Fweaveback/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31483380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","developer-tools","literate-programming","macros","noweb","rust"],"created_at":"2026-04-02T13:37:46.852Z","updated_at":"2026-04-14T07:06:42.389Z","avatar_url":"https://github.com/giannifer7.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Weaveback\n\nlink:https://giannifer7.github.io/weaveback/[Documentation]\n| link:https://giannifer7.github.io/weaveback/crates/weaveback-tangle/src/weaveback_tangle.html[weaveback-tangle source]\n| link:https://giannifer7.github.io/weaveback/crates/weaveback-macro/src/weaveback_macro.html#literate-sources[weaveback-macro source]\n\nWeaveback is a bidirectional literate programming toolchain.\n\nWrite your source code inside AsciiDoc (or any text file), assemble named\nchunks, and let the tool write the real files — then trace any generated\nline back to its origin, or propagate edits back to the source.\n\n[source,sh]\n----\nweaveback source.adoc --gen src\n----\n\n---\n\n== Why this exists now\n\nCoding agents made code generation cheap.  They did not make judgment cheap.\n\nThat changes the value proposition of literate programming.  The hard part is\nno longer typing boilerplate; it is preserving *intent*, keeping distant but\nrelated fragments in sync, and making generated or agent-modified code\nreviewable by a human.\n\nWeaveback is useful only if it helps with that higher-level problem:\n\n- keeping related code fragments synchronized across distance\n- tracing generated code back to the rationale that produced it\n- propagating edits without losing the source of truth\n- giving humans enough context to validate agent-produced changes\n\nAs code templates, many classic \"design patterns\" are cheaper than ever for an\nagent to emit.  As a vocabulary for *why* a structure exists, they still\nmatter.\n\nIf the tool does not reduce cognitive load and improve auditability, it is just\ncleverness.  If it carries the why together with the code strongly enough that\npeople can still reason about large systems, it earns its keep.\n\n---\n\n== What makes Weaveback different\n\nTraditional literate programming is one-way: source → generated code.\nEdits to generated files must be propagated back manually, and over time\nthe two representations drift.\n\nWeaveback closes the loop.\nEvery generated line knows where it came from and can be traced precisely.\nEdits can propagate back to the source.\n\n- *Trace* any generated line back to its source: `weaveback where`\n- *Propagate* edits from generated files back to the document: `weaveback apply-back`\n\nThe source remains the single source of truth — without becoming a dead end.\n\n---\n\n== A simple example\n\nStart from generated code:\n\n[source,rust]\n----\n// src/events.rs — generated\npub enum PluginEvent {\n    PluginLoad,\n    PluginUnload,\n}\n----\n\nTrace a line back to its origin:\n\n[source,sh]\n----\nweaveback where src/events.rs:2\n----\n\n→ opens the exact chunk in the literate source.\n\n---\n\nOr edit the generated file directly:\n\n[source,rust]\n----\n// src/events.rs — after your edit\npub enum PluginEvent {\n    PluginLoaded,\n    PluginUnloaded,\n}\n----\n\nPropagate the change back:\n\n[source,sh]\n----\nweaveback apply-back\n----\n\n→ the literate source is updated, preserving consistency.\n\n---\n\n== Language-agnostic fan-out\n\nA single document can define data once and fan it out to multiple files in\nmultiple languages simultaneously.\n\nAdd one entry; every target stays in sync.\n\nThe example below defines plugin events in AsciiDoc and generates\na C header, a Rust module, and a SQL seed file from the same source definition.\n\n[source,adoc]\n----\n%def(event, id, ns, name, description, %{\n// \u003c[c enum arms]\u003e=\nEVT_%to_screaming_case(%(ns))_%to_screaming_case(%(name)) = %(id),\n// @\n// \u003c[rust enum arms]\u003e=\n%to_pascal_case(%(ns))%to_pascal_case(%(name)),\n// @\n// \u003c[sql rows]\u003e=\nINSERT INTO audit_event_types (id, name, description)\n    VALUES (%(id), '%(ns).%(name)', '%(description)')\n    ON CONFLICT (name) DO NOTHING;\n// @\n%})\n\n%event(0, plugin, load,   \"Plugin loaded into host\")\n%event(1, plugin, unload, \"Plugin removed from host\")\n----\n\nAll outputs remain consistent because they originate from the same structured source.\n\n---\n\n== Macro language\n\nThe macro system is intentionally simple.\n\nBuilt-ins — case conversion, `%if`, `%equal` — cover common patterns\nwhile keeping expansions predictable and traceable.\n\nMacros enable:\n- parameterized code generation\n- structured reuse\n- multi-language fan-out\n\nwithout introducing a full programming language.\n\n---\n\n== Escape hatches\n\nWhen the built-in macros are not enough, one scripted extension is available.\n\n- *`%pydef`* — macro body runs in a sandboxed Python interpreter (monty), compiled into the binary. No Python installation required.\n\nThe tradeoff: code produced inside scripted macros cannot be mapped back by\n`weaveback trace`. Use them for isolated calculations or string manipulation,\nnot as a primary structuring mechanism.\n\n---\n\n== Agent and IDE integration\n\nWeaveback exposes a set of operations via MCP:\n\n- *Source Tracing*: trace a generated line to its exact source chunk.\n- *Semantic Intelligence*: \"Go to Definition\" and \"Find References\" using LSP (Rust, Nim, Python).\n- *Literate Diagnostics*: see compiler errors and hover info directly in the source document.\n- *Contextual Understanding*: retrieve full chunk context (code, prose, dependencies).\n- *Verified Editing*: apply surgical, oracle-verified edits to source files.\n\nThis enables a workflow closer to:\n\ntrace → understand → modify → verify\n\nrather than blind generation.\n\n---\n\n== Live documentation server\n\n`weaveback serve` starts a local HTTP server with live reload, inline chunk\nediting, and an AI assistant panel that receives full chunk context: source\nbody, surrounding prose and design notes, dependency bodies.\n\nimage::docs/ai-panel.png[AI assistant panel,width=700]\n\n---\n\n== Install\n\n*Installer script* (Linux, macOS, Windows — downloads and installs the binary):\n\n[source,sh]\n----\npython3 scripts/install.py             # core\npython3 scripts/install.py --diagrams  # + PlantUML support\n----\n\n*Arch Linux:* `paru -S weaveback-bin`\n\n*Nix:* `nix profile install github:giannifer7/weaveback`\n\n*Quick binary only (musl, any Linux):*\n\n[source,sh]\n----\ncurl -sL https://github.com/giannifer7/weaveback/releases/latest/download/weaveback-musl \\\n     -o ~/.local/bin/weaveback \u0026\u0026 chmod +x ~/.local/bin/weaveback\n----\n\n→ link:docs/install.adoc[Full installation guide]\n\n---\n\n== Quick start\n\n[source,sh]\n----\ncd examples/events\nweaveback events.adoc --gen .\n----\n\n---\n\n== Status\n\nExperimental. This is an ongoing exploration of bidirectional literate\nprogramming and structured agent integration.\n\nNot production-ready. The focus is on the design, not completeness.\n\n---\n\n== Documentation\n\n[cols=\"1,3\",options=\"header\"]\n|===\n| Document | Contents\n\n| link:docs/cli.adoc[CLI reference]\n| All flags and options\n\n| link:docs/macros.adoc[Macro language]\n| `%def`, `%if`, `%pydef`\n\n| link:docs/noweb.adoc[Chunk syntax]\n| `@file`, named chunks, composition\n\n| link:docs/tracing.adoc[Source tracing]\n| `trace`, `apply-back`, MCP workflow\n\n| link:docs/architecture.adoc[Architecture]\n| Pipeline, source maps, server design\n\n| link:project/agent-python.adoc[Python Agent Bridge]\n| PyO3 + Pydantic agent design and scaffold\n\n| link:docs/install.adoc[Installation]\n| Platforms and binaries\n|===\n\n---\n\n== License\n\n0BSD OR MIT OR Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiannifer7%2Fweaveback","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiannifer7%2Fweaveback","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiannifer7%2Fweaveback/lists"}