Merge pull request #239 from acgetchell/fix/benchmark-docs

fix: complete benchmark CI and improve documentation navigation

Author: acgetchell

.github/workflows/benchmarks.yml

@@ -58,7 +58,9 @@ env:
 jobs:
   bench:
     runs-on: ubuntu-latest
-    timeout-minutes: 30
+    # The full exact suite has 260+ cases: Criterion's default 3 s warm-up
+    # plus 5 s measurement already needs 35+ minutes, before build/analysis.
+    timeout-minutes: 90
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -109,8 +111,7 @@ jobs:
               repo: context.repo.repo,
               workflow_id: 'benchmarks.yml',
               branch: 'main',
-              status: 'completed',
-              conclusion: 'success',
+              status: 'success',
               per_page: 5,
             });
 
@@ -158,15 +159,16 @@ jobs:
             echo "::notice::Baseline found — comparing against main"
             echo "comparison_available=true" >> "$GITHUB_OUTPUT"
             # --baseline-lenient rather than --baseline: benches added on the
-            # PR branch that don't yet exist in the main baseline get a
-            # "no baseline data" notice instead of aborting the whole run.
+            # PR branch that don't yet exist in the main baseline run without
+            # a comparison instead of aborting the whole run.
+            # Keep normal sampling; plots/HTML are unused by the summary.
             cargo bench --locked --features bench,exact --bench exact \
-              -- --baseline-lenient main 2>&1 | tee bench-output.txt
+              -- --noplot --baseline-lenient main 2>&1 | tee bench-output.txt
           else
             echo "::notice::No baseline found — running without comparison"
             echo "comparison_available=false" >> "$GITHUB_OUTPUT"
             cargo bench --locked --features bench,exact --bench exact \
-              2>&1 | tee bench-output.txt
+              -- --noplot 2>&1 | tee bench-output.txt
           fi
 
           if grep -q "Performance has regressed" bench-output.txt; then
@@ -182,11 +184,11 @@ jobs:
           github.ref == 'refs/heads/main'
         run: >
           cargo bench --locked --features bench,exact --bench exact
-          -- --save-baseline main
+          -- --noplot --save-baseline main
 
       - name: Run benchmarks (manual ref)
         if: github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main'
-        run: cargo bench --locked --features bench,exact --bench exact
+        run: cargo bench --locked --features bench,exact --bench exact -- --noplot
 
       - name: Upload baseline artifact
         if: >
@@ -208,12 +210,24 @@ jobs:
           comparison_available="${BENCH_COMPARISON_AVAILABLE:-}"
           regression="${BENCH_REGRESSION:-}"
 
+          # Lenient comparisons silently skip missing baselines. Require a
+          # change report for every analyzed case before claiming coverage.
+          if [ -f bench-output.txt ]; then
+            analyzed="$(grep -c '^Benchmarking .*: Analyzing$' bench-output.txt || true)"
+            compared="$(grep -c '^[[:space:]]*change:' bench-output.txt || true)"
+            if [ "$analyzed" = "0" ] || [ "$analyzed" != "$compared" ]; then
+              comparison_available=false
+            fi
+          else
+            comparison_available=false
+          fi
+
           if [ "$comparison_available" != "true" ] || [ -z "$regression" ]; then
             {
               echo "### ❓ Benchmark Comparison Unavailable"
               echo ""
               echo "No usable comparison against the main baseline was produced."
-              echo "The benchmark still ran, but no regression claim can be made."
+              echo "Benchmarks may be incomplete or lack a baseline; no regression claim can be made."
             } >> "$GITHUB_STEP_SUMMARY"
             echo "::warning::Benchmark comparison unavailable"
           elif [ "$regression" = "true" ]; then

AGENTS.md

@@ -230,12 +230,32 @@ When user requests commit message generation:
 
 - `src/lib.rs` includes `README.md` with `#![doc = include_str!("../README.md")]`, so README examples are the
   docs.rs landing page examples.
+- Keep the README quickstart and brief capability descriptions discoverable;
+  put fuller worked API examples and caller contracts in the documentation-only
+  `guide` module in `src/lib.rs`. Preserve useful detail in the linked guide when
+  shortening README sections, including numerical limitations and error semantics.
+- Link API references and worked API guides to docs.rs. Keep repository-owned
+  mathematical background, benchmark reports, roadmap, contributing, and release
+  instructions on GitHub, using absolute URLs to the intended repository revision.
+- README links and Contents anchors must work both on GitHub and in generated
+  rustdoc. Repository-relative file links can resolve incorrectly from rustdoc;
+  verify destinations in both contexts and use intra-doc links within Rust docs
+  where the referenced item is available under the selected features.
+- Choose docs.rs `latest` links for intentionally current guidance and explicit
+  versions for release-specific contracts. docs.rs builds published crates, so
+  merging changes does not publish new guide pages. Local rendering checks do
+  not establish availability on the published site.
 - When changing Rust examples in `README.md`, mirror executable versions in the private `readme_doctests` module in
   `src/lib.rs`. Keep mirrors hidden/private so they do not duplicate the docs.rs landing page, but make them runnable
   by `cargo test --doc`.
 - README examples that require optional features may remain `rust,ignore` in README for default-feature doctest
   compatibility, but must have a `#[cfg(feature = "...")]` hidden doctest mirror in `src/lib.rs` and be verified with
   the matching feature set (for example, `cargo test --features exact --doc`).
+- Guide examples run directly as doctests; gate feature-dependent guides with
+  the matching feature and remove obsolete private mirrors when moving examples
+  out of README. Run `just doc-check` for changed guide docs and inspect generated
+  pages and anchors for explicit links, which rustdoc does not validate. Validate
+  changed executable examples with the default and matching feature doctest recipes.
 - When intentionally updating package versions or dependency snippets, keep README `la-stack` dependency examples in
   sync with the package `version` in `Cargo.toml`. Do not perform version bumps unless explicitly requested by the
   maintainer; see **Public-API stability** above.