chore: add execute command to cli

.github/workflows/ci.yml

@@ -38,6 +38,7 @@ jobs:
             cli:
               - '.github/workflows/ci.yml'
               - 'acdc-cli/**'
+              - 'acdc-execute/**'
               - 'acdc-parser/**'
               - 'converters/**'
               - 'Cargo.toml'
@@ -82,7 +83,9 @@ jobs:
           version: 0.16.0
       - uses: Swatinem/rust-cache@v2
       - name: Run clippy
-        run: cargo clippy --all-targets --all-features -- --deny clippy::pedantic
+        run: cargo clippy --all-targets --all-features -- --deny clippy::pedantic --deny clippy::todo
+      - name: Run clippy (execute library)
+        run: cargo clippy -p acdc-execute --all-targets --all-features -- --deny clippy::pedantic --deny clippy::todo
       - name: Install wasm32 target
         run: rustup target add wasm32-unknown-unknown
       - name: Run clippy (WASM editor)
@@ -153,8 +156,12 @@ jobs:
           version: 0.16.0
       - uses: Swatinem/rust-cache@v2
       - uses: taiki-e/install-action@nextest
-      - name: Run CLI tests
-        run: cargo nextest run -p acdc-cli --all-features --verbose --no-tests warn --test-threads 1 # we've added this until https://github.com/nextest-rs/nextest/pull/3553 gets merged
+      - name: Run CLI and execute library tests
+        run: cargo nextest run -p acdc-cli -p acdc-execute --all-features --verbose --no-tests warn --test-threads 1 # we've added this until https://github.com/nextest-rs/nextest/pull/3553 gets merged
+      - name: Run execute-only tests
+        run: cargo nextest run -p acdc-cli -p acdc-execute --no-default-features --features execute --verbose --test-threads 1
+      - name: Test execute with parser-only substitution features
+        run: cargo nextest run -p acdc-execute --no-default-features --features acdc-parser/pre-spec-subs -E 'test(substitution_follows_the_parser_feature_even_when_features_are_unified)' --verbose
       - name: Smoke-test backend-only CLI builds
         shell: bash
         run: |
@@ -164,6 +171,7 @@ jobs:
       - name: Smoke-test tool-only CLI builds
         shell: bash
         run: |
+          cargo run -p acdc-cli --no-default-features --features execute -- execute --help
           cargo run -p acdc-cli --no-default-features --features inspect -- inspect --help
           cargo run -p acdc-cli --no-default-features --features lint -- lint --help
           cargo run -p acdc-cli --no-default-features --features tck -- tck --help
@@ -220,3 +228,5 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - name: Run doc tests
         run: cargo test --doc --all-features --verbose
+      - name: Run execute library doc tests
+        run: cargo test --doc -p acdc-execute --all-features --verbose

Cargo.toml

@@ -2,6 +2,7 @@
 members = [
   "acdc-cli",
   "acdc-editor-wasm",
+  "acdc-execute",
   "acdc-lint",
   "acdc-lsp",
   "acdc-parser",
@@ -43,6 +44,8 @@ acdc-converters-manpage = { path = "converters/manpage", default-features = fals
 acdc-converters-markdown = { path = "converters/markdown" }
 acdc-converters-pdf = { path = "converters/pdf", default-features = false }
 acdc-converters-terminal = { path = "converters/terminal", default-features = false }
+acdc-editor-wasm = { path = "acdc-editor-wasm" }
+acdc-execute = { path = "acdc-execute", default-features = false }
 acdc-lint = { path = "acdc-lint", default-features = false }
 acdc-parser = { path = "acdc-parser", default-features = false }
 base64 = "0.23"
@@ -54,6 +57,7 @@ image = { version = "0.25", default-features = false, features = ["png", "jpeg",
 libghostty-vt = { git = "https://github.com/Uzaaft/libghostty-rs", rev = "5988a0b78b4aa804d1c12e66bbfe662bd97d81c0" }
 lopdf = "0.45"
 mockito = "1"
+petgraph = { version = "0.8", default-features = false, features = ["std"] }
 pretty_assertions = "1.4"
 rayon = "1.11"
 relative-path = "2.0.1"

acdc-cli/CHANGELOG.md

@@ -7,8 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- `execute --list` now prints one bullet per command with labeled ids,
+  interpreters, enclosing section titles, direct dependencies, and optional
+  descriptions. Commands outside sections omit the section title. Quoted
+  values escape control characters so each command stays on one line.
+
 ### Fixed
 
+- Warning batches read each referenced source file once, reducing repeated I/O
+  for documents with many warnings, including commands that use `subs=attributes`.
 - `lint -D one-sentence-per-line` now rejects description-list values with
   multiple sentences on one line or a sentence split across lines, including
   values written after the term's delimiter.
@@ -98,6 +107,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   page sizes can use portrait or landscape output, `pdf-page-size` accepts
   custom dimensions, `pdf-page-margin` sets per-document margins, and `--strict` makes
   unresolved PDF images or logos fail instead of falling back with a warning.
+- Builds with the `execute` feature run listing and source blocks marked with
+  the `command` role. Use `--id` or `--id-regex` to select commands and their
+  dependencies, `--dry-run` to inspect scripts, and `--list` to see descriptions.
+  `interpreter=` overrides the source language; `--cwd` and repeated `--env`
+  options configure child processes.
+- Command execution preserves literal script text after includes and conditionals;
+  `subs=attributes` or `subs=+attributes` expands document attributes from each
+  command's source position without shell quoting or removing callouts. Missing
+  enabled attributes and incomplete command input fail before any process starts.
+  Dry-run shows the prepared script. Builds without `pre-spec-subs` reject explicit
+  `subs` settings. Failed commands block dependents while independent commands
+  continue; `--exit-on-failure`
+  stops sooner. Source diagnostics identify commands in included files.
 - The `terminal-emulator` build feature renders `[terminal]` session blocks
   through `libghostty-vt` on the `--backend terminal` path. Requires a Zig
   toolchain to build the bundled library, which is statically linked so the

acdc-cli/Cargo.toml

@@ -17,6 +17,7 @@ doc = false
 
 [dependencies]
 acdc-converters-core.workspace = true
+acdc-execute = { workspace = true, optional = true }
 acdc-converters-html = { workspace = true, optional = true }
 acdc-lint = { workspace = true, optional = true }
 acdc-parser.workspace = true
@@ -30,6 +31,7 @@ crossterm.workspace = true
 miette = { version = "7", features = ["derive", "fancy"] }
 open = "5"
 rayon.workspace = true
+regex = { version = "1", optional = true }
 serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
@@ -52,6 +54,7 @@ pre-spec-subs = [
     "acdc-converters-manpage?/pre-spec-subs",
     "acdc-converters-pdf?/pre-spec-subs",
     "acdc-converters-terminal?/pre-spec-subs",
+    "acdc-execute?/pre-spec-subs",
     "acdc-lint?/pre-spec-subs",
 ]
 
@@ -81,16 +84,17 @@ terminal-emulator = [
 ]
 
 # Development tools
+execute = ["dep:acdc-execute", "dep:regex"]  # Run command blocks from AsciiDoc documents
 inspect = []  # AST inspection tool for debugging parser output
 tck = []      # Technology Compatibility Kit for spec compliance testing
 
 # Compatibility features
-setext = ["acdc-parser/setext", "acdc-lint?/setext"]  # Enable Setext-style (underlined) header parsing
-network = ["acdc-parser/network", "acdc-lint?/network", "acdc-converters-pdf?/network"]  # Enable remote include parsing and remote PDF images
+setext = ["acdc-parser/setext", "acdc-execute?/setext", "acdc-lint?/setext"]  # Enable Setext-style (underlined) header parsing
+network = ["acdc-parser/network", "acdc-execute?/network", "acdc-lint?/network", "acdc-converters-pdf?/network"]  # Enable remote include parsing and remote PDF images
 
 # Feature groups for convenience
 all-backends = ["html", "manpage", "markdown", "pdf", "terminal"]  # Enable all output converters
-dev-tools = ["inspect"]              # Enable development utilities
+dev-tools = ["execute", "inspect"]   # Enable development utilities
 test-tools = ["tck"]                 # Enable testing and compliance tools
 
 [lints.rust]