Prepare 0.0.2 Release: sf agency enhancements, parser fixes and 10x faster parsing

[jlantz]

This pull request introduces significant improvements and restructuring to the CI and release workflows, along with the addition of a comprehensive CHANGELOG.md. The changes focus on streamlining build and release processes, improving multi-platform support, and making publishing to npm and other registries more robust and consistent.

Salesforce CLI Plugin Enhancements

• New commands agents list and agents select for filtering which agents get scanned
• New commands impact and `paths
• query command changed to path based queries or dot for direct AST querying

Rust Parser and Graph Enhancements

• 10x faster, benches ~5.9MB/s for single files, faster in parallel
• Added support for object variables
• Added support for ... placeholder values

CI Workflow Enhancements:

• Added dedicated build jobs for the SF plugin (sf-plugin-build) and Zed extension (zed-build), enabling targeted builds for these components with proper WASM and Node.js environment setup. [1] [2]
• Removed the umbrella test job and updated dependencies for coverage and completion jobs to reflect the new build structure. [1] [2] [3]

Release Workflow Improvements:

• Unified and simplified WASM build jobs, replacing separate parser and graph builds with a single job, and introduced a Zed extension build job for release artifacts.
• Improved npm publishing logic to support pre-releases and stable releases, including dynamic npm tags and waiting for WASM package availability before publishing the SF plugin. [1] F4f30113L29R29, [2] [3]
• Updated platform matrix and build steps for LSP and VS Code extension packaging, removing unused targets and switching to the correct marketplace token. [1] [2] [3] [4]

Documentation:

• Added a new CHANGELOG.md following Keep a Changelog and Semantic Versioning, documenting all notable changes, new features, and API adjustments across releases.

Other Notable Changes:

• Improved artifact packaging for releases, including zipped WASM and Zed extension artifacts.
• Renamed jobs and commands for clarity and consistency, e.g., tree-sitter npm publish and SF plugin npm publish.

These updates provide a more maintainable and extensible workflow for building, testing, and releasing all components of the project.

---

References:
[1] [2] [3] [4] [5] [6] [7] F4f30113L29R29, [8] [9] [10] [11] [12] [13] [14] [15] [16]

[github-actions]

📊 Benchmark Results

⚠️ Benchmarks could not run in this CI environment.

The benchmark runner was unable to execute cargo bench due to sandbox execution restrictions in the workflow environment. Additionally, git submodule update --init --recursive was blocked, so the agent-script-recipes submodule input files were not available.

---

What failed

Step	Result
git submodule update --init --recursive	❌ Permission denied (sandbox policy)
cargo bench --bench parse_recipes	❌ Permission denied (sandbox policy)

---

How to reproduce locally

To run the benchmarks and compare against main, run the following on your machine:

# 1. Initialize submodule (required for recipe input files)
git submodule update --init --recursive

# 2. Establish baseline on main
git fetch origin main
git stash
git checkout origin/main -- .
cargo bench --bench parse_recipes -- --save-baseline main

# 3. Restore PR branch and compare
git checkout -
cargo bench --bench parse_recipes -- --baseline main

The PR description claims ~10x faster parsing (~5.9 MB/s for single files, faster in parallel). Results will be printed by Criterion with statistically significant changes highlighted.

Requires: git submodule update --init to populate agent-script-recipes/ with .agent files.

Generated by Benchmark Regression Checker for issue #25

[github-actions]

Breaking Change Analysis

Files checked: src/ast.rs, src/lib.rs, src/error.rs, Cargo.toml

---

Rust Crate (busbar-sf-agentscript) — ✅ No Breaking Changes

None of the core public API files (src/ast.rs, src/lib.rs, src/error.rs) were modified in this PR. The Rust crate's public API is unchanged.

Cargo.toml changes:

• Version bump: 0.0.1 → 0.0.2 — expected for a 0.x release cycle
• rayon = "1.10" added to dev-dependencies (benchmarks only) — not a public API change
• rust-version remains "1.88" — no MSRV change

---

SF CLI Plugin (@muselab/sf-plugin-busbar-agency) — ⚠️ Breaking Changes for Plugin Users

This PR bumps the plugin from 0.0.1 to 0.0.2 and introduces several breaking changes to the CLI interface that downstream users and scripts must account for:

Change	Why it breaks
sf agency query topic (name) removed	Replaced by sf agency query /topics/(name) (positional arg syntax)
sf agency query variable (name) removed	Replaced by sf agency query /variables/(name)
sf agency query action (name) removed	Replaced by sf agency query /actions/(name)
sf agency query --path (dot-notation) flag removed	Query path is now a positional argument; --path now means directory scan
sf agency parse JSON output format changed	Was raw AST object; now { file, ast } — any JSON consumer parsing the output must update
sf agency impact --dir renamed to --path	Scripts using --dir will fail
npm package renamed	busbar-sf-agentscript → @muselab/busbar-sf-agentscript — any package.json referencing the old name must be updated

These are all in the SF CLI plugin, which is separately versioned and consumed. The CHANGELOG correctly documents all of these under Changed and Removed for 0.0.2. Since the project is pre-1.0 (0.x), breaking changes are permitted but communication is important.

Suggestion: These changes are already well-documented in CHANGELOG.md. No code changes needed, but consider whether any migration notes or deprecation warnings would help users of the old subcommand syntax.

Generated by Breaking Change Checker for issue #25

[codecov-commenter]

Codecov Report

❌ Patch coverage is 61.34969% with 189 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/parser/instructions.rs	35.15%	142 Missing ⚠️
src/graph/builder.rs	38.98%	36 Missing ⚠️
src/graph/error.rs	0.00%	5 Missing ⚠️
src/parser/connections.rs	93.75%	2 Missing ⚠️
src/graph/export.rs	0.00%	1 Missing ⚠️
src/lexer.rs	98.59%	1 Missing ⚠️
src/parser/mod.rs	92.85%	1 Missing ⚠️
src/serializer.rs	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

📊 Benchmark Results

⚠️ Benchmarks could not be executed in this workflow run.

The benchmark runner encountered a sandbox restriction that prevented executing build tools (cargo, git, rustup). This is a CI environment limitation, not a code issue.

What failed

cargo bench --bench parse_recipes
# Error: Permission denied (seccomp filter blocked process execution)
```

Additionally, the `agent-script-recipes` submodule was not initialized (empty directory), which would also prevent recipe-based benchmarks from producing meaningful results:

```
git submodule update --init --recursive
# Error: network access blocked

How to reproduce benchmarks locally

# 1. Initialize the submodule
git submodule update --init --recursive

# 2. Run benchmarks on main (save baseline)
git stash
git checkout origin/main -- .
cargo bench --bench parse_recipes -- --save-baseline main

# 3. Restore PR branch and compare
git checkout -
cargo bench --bench parse_recipes -- --baseline main

The PR description notes ~10x faster parsing (~5.9 MB/s for single files, faster in parallel). Once the benchmark runner has proper build tool access and the submodule is available, a comparison against main can confirm those numbers statistically.

Generated by Benchmark Regression Checker for issue #25

[github-actions]

Breaking Change Analysis — PR #25

Files checked: src/ast.rs, src/lib.rs, src/error.rs, Cargo.toml

---

⚠️ Breaking Change Found

File	Change	Why It Breaks
src/ast.rs	Added Expr::SlotFill variant to pub enum Expr	Expr is not #[non_exhaustive], so any downstream code with an exhaustive match on Expr will fail to compile with "non-exhaustive patterns: SlotFill not covered"

Detail:

// Before (0.0.1)
pub enum Expr {
    // ...
    None,
    List(Vec(Spanned(Expr))),
    // ...
}

// After (0.0.2) — new variant added
pub enum Expr {
    // ...
    None,
    SlotFill,   // ← NEW: breaks exhaustive match arms
    List(Vec(Spanned(Expr))),
    // ...
}

Any downstream crate that matches Expr exhaustively will fail to compile after upgrading.

---

✅ No Breaking Changes

File	Status
src/lib.rs	Unchanged
src/error.rs	Unchanged
Cargo.toml – rust-version	Unchanged (1.88)
Cargo.toml – feature flags	Unchanged (default, graph, wasm)

---

💡 Recommendation

Since Expr is expected to grow with the language, consider annotating it with #[non_exhaustive]:

#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Expr {
    // ...
}

This is a one-time opt-in that allows future variant additions without breaking downstream matchers. Downstream users would need to add a wildcard arm (_ => ...), but only once.

The version bump to 0.0.2 correctly signals this breaking change per the 0.x pre-release convention. The breaking-change label is already applied to this PR ✓

Generated by Breaking Change Checker for issue #25

[github-actions]

🔍 Breaking Change Analysis

Files checked: src/ast.rs, src/lib.rs, src/error.rs, Cargo.toml

⚠️ Breaking Changes Found

Two exhaustive pub enum types receive new variants in this PR. Neither enum is marked #[non_exhaustive], so downstream code that exhaustively matches on these types will fail to compile after upgrading.

---

1. Expr::SlotFill — new variant in pub enum Expr (src/ast.rs)

// Added:
+    /// Slot-fill token: `...`
+    SlotFill,
```

`pub enum Expr` has no `#[non_exhaustive]` attribute. Any downstream crate with a `match expr { ... }` that covers all variants (or uses a wildcard-free match) will get:

```
error[E0004]: non-exhaustive patterns: `Expr::SlotFill` not covered

Suggested remediation: Add #[non_exhaustive] to pub enum Expr in src/ast.rs, or accept the compile-time break and document it in CHANGELOG.md (which it appears has already been done).

---

2. ValidationError::InvalidPropertyAccess — new variant in pub enum ValidationError (src/graph/error.rs)

// Added:
+    InvalidPropertyAccess {
+        reference: String,
+        variable: String,
+        variable_type: String,
+        span: Span,
+    },

pub enum ValidationError also has no #[non_exhaustive] attribute, producing the same downstream compile error for exhaustive matches.

Suggested remediation: Add #[non_exhaustive] to pub enum ValidationError, or document the break.

---

✅ No Breaking Changes

• src/lib.rs — no changes
• src/error.rs (crate root) — no changes
• Cargo.toml — version bumped 0.0.1 → 0.0.2 (expected), rust-version unchanged at 1.88, no feature flags removed

---

Summary

Item	Type	Breaking?
Expr::SlotFill added	New exhaustive enum variant	✅ Yes
ValidationError::InvalidPropertyAccess added	New exhaustive enum variant	✅ Yes
rust-version	Unchanged (1.88)	No
Cargo.toml feature flags	None removed	No

Since this is a 0.x release, breaking changes are permitted but should be documented. The breaking-change label has already been applied to this PR. Consider adding #[non_exhaustive] to both enums going forward to prevent this class of break in future minor releases.

Generated by Breaking Change Checker for issue #25

[github-actions]

📊 Benchmark Results

⚠️ Benchmark execution failed — the workflow environment does not permit running cargo bench (executable permission restrictions in the sandbox).

This PR modifies parser and graph code:

• src/graph/builder.rs, src/graph/error.rs, src/graph/export.rs, src/graph/validation.rs
• src/parser/connections.rs, src/parser/expressions.rs, src/parser/instructions.rs, src/parser/mod.rs, src/parser/reasoning.rs, src/parser/topics.rs

Benchmarks were intended to run comparing PR branch vs main using cargo bench --baseline main.

How to reproduce locally

# Initialize recipe submodule
git submodule update --init --recursive

# Save baseline from main
git stash
git checkout origin/main -- .
cargo bench --bench parse_recipes -- --save-baseline main

# Restore PR branch and compare
git checkout -
cargo bench --bench parse_recipes -- --baseline main

Note: Recipe files from the agent-script-recipes submodule are required for the benchmarks to produce meaningful results.

Generated by Benchmark Regression Checker for issue #25

[github-actions]

🔍 Breaking Change Analysis

Files checked: src/ast.rs, src/graph/error.rs, src/error.rs, Cargo.toml

---

⚠️ Breaking Change Found

pub enum Expr — new variant SlotFill added (src/ast.rs)

// Added in this PR:
/// Slot-fill token: `...`
SlotFill,
```

`pub enum Expr` is **not** marked `#[non_exhaustive]`. Any downstream code with an exhaustive `match` on `Expr` will fail to compile after this upgrade:

```
error[E0004]: non-exhaustive patterns: `Expr::SlotFill` not covered

Why it's breaking: Rust requires exhaustive match arms for non-#[non_exhaustive] enums. Downstream crates that match on Expr (e.g., in custom serializers, analyzers, or linters built on top of this library) must add a new arm or use a catch-all _ => to compile.

Suggested mitigation: Add #[non_exhaustive] to pub enum Expr so that future variant additions don't require downstream changes:

#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum Expr {
    // ...
}

Since this project is pre-1.0 (0.x), breaking changes are allowed — this one is clearly communicated by the version bump (0.0.1 → 0.0.2) and the breaking-change label already applied to this PR. ✅

---

✅ Not Breaking

Item	Reason
pub enum Expr::Object	Already existed in the base branch — not new
pub enum ValidationError::InvalidPropertyAccess	Already existed in the base branch — not new
Internal parser refactoring (instructions.rs, reasoning.rs, topics.rs)	Private/pub(crate) changes only
rayon dev-dependency added	Dev/bench dependency, not public API
rust-version in Cargo.toml	Unchanged — still 1.88
Changes in crates/lsp/	publish = false, excluded
SF CLI plugin changes (plugin-agency/)	TypeScript package, separate from Rust crate API

---

Summary

One Rust public API breaking change: Expr::SlotFill added to non-#[non_exhaustive] pub enum Expr. The breaking-change label is already present on this PR. Consider adding #[non_exhaustive] to Expr to protect against this class of break in all future releases.

Generated by Breaking Change Checker for issue #25

[github-actions]

📊 Benchmark Results

⚠️ Benchmarks could not run in this environment

The benchmark workflow was unable to execute cargo bench --bench parse_recipes due to sandbox restrictions in the CI environment — both cargo/rustup execution and git submodule update were blocked.

Additionally, the agent-script-recipes submodule is not initialized in this checkout, which is required for the benchmarks to have input files.

---

How to reproduce locally

# 1. Clone and initialize submodules
git clone https://github.com/composable-delivery/busbar-sf-agentscript
cd busbar-sf-agentscript
git submodule update --init --recursive

# 2. Run benchmarks on main (baseline)
git checkout main
cargo bench --bench parse_recipes -- --save-baseline main

# 3. Switch to the PR branch and compare
git checkout sf-plugin
cargo bench --bench parse_recipes -- --baseline main

Results are saved to target/criterion/ and can be viewed with critcmp:

cargo install critcmp
critcmp main $(git rev-parse --short HEAD)

---

Note: This PR claims ~10x faster parsing (~5.9 MB/s for single files). Running the benchmarks above will confirm the improvement with statistical confidence (Criterion p-values).

Generated by Benchmark Regression Checker for issue #25