feat: Stringy v1.0 -- pipeline architecture, CLI hardening, and comprehensive testing (#141)

## Summary

This PR delivers the complete v1.0 implementation of Stringy,
transforming it from a prototype into a production-ready binary string
extraction tool. The work spans 56 commits across 132 files (+7,963 /
-6,477 lines), organized into five major workstreams.

**610 tests pass** (23 platform-skipped), **zero clippy warnings**, all
pre-commit hooks green.

## What Changed

### 1. Pipeline Architecture (New)

Introduced a modular pipeline orchestrator that replaces ad-hoc
extraction logic:

- `Pipeline::new(config).run(&path)` -- single entry point for all
analysis
- `PipelineConfig` with builder pattern for extraction, filtering,
output, and debug options
- `FilterEngine` for tag inclusion/exclusion, encoding, min-length, and
top-N filtering
- Score normalizer with 0-100 display scores and section weight /
semantic boost / noise penalty breakdown
- `mmap-guard` integration for safe memory-mapped file I/O (replaces raw
`memmap2`)
- Graceful fallback for unknown formats (raw byte scanning with Info
diagnostic)
- Processing warnings via env-var injection for testable error paths

**Key files:** `src/pipeline/mod.rs`, `src/pipeline/config.rs`,
`src/pipeline/filter.rs`, `src/pipeline/normalizer.rs`

### 2. CLI Hardening

Complete rewrite of the CLI layer with production-quality UX:

- **Typed exit codes**: 0=success, 2=config/validation, 3=not-found,
4=permission-denied, 1=other
- **Short flags**: `-j` (json), `-m` (min-len), `-t` (top), `-e` (enc)
- **Actionable error messages** with fix suggestions
- **NO_COLOR** env var support (no-color.org spec)
- **Graceful spinner** fallback (no `.expect()`, hidden when non-TTY or
NO_COLOR)
- **stdin support** via `patharg::InputArg` with progress feedback
- `--notags` renamed to `--no-tags` (kebab-case consistency)
- `--summary`, `--debug`, `--raw` modes with proper conflict
declarations
- Help text with EXAMPLES section and all 21 tag names listed

**Key files:** `src/main.rs`, `src/types/error.rs`

### 3. Core Data Model Improvements

- `FoundString::new()` + builder methods replace struct literals
(forward-compatible)
- `StringContext` constructors for cleaner extraction code
- `SectionInfo` made `#[non_exhaustive]` with `with_*` builders
- `OutputMetadata` with analysis duration, top tag distribution, builder
pattern
- `FilterContext` with builder methods for test ergonomics
- `ExtractionConfig::with_min_length()` builder
- Container parsers split into module directories (elf/, pe/, macho/)
with separate test files

**Key files:** `src/types/constructors.rs`, `src/types/found_string.rs`,
`src/types/mod.rs`

### 4. Output Enhancements

- **Plain text**: Full C0 control character sanitization (not just
newlines)
- **TTY table**: Analysis duration with minute-level formatting, summary
banner
- **JSON**: Debug-only fields (`section_weight`, `semantic_boost`,
`noise_penalty`) via `skip_serializing_if`
- **YARA**: Long string skip behavior with deterministic comments
- `display_score` always present in non-raw mode; forced to 0 in raw
mode

**Key files:** `src/output/table/plain.rs`, `src/output/table/tty.rs`,
`src/output/json.rs`

### 5. Build & Infrastructure

- **Zig cross-compilation** replaces Docker for test fixtures (ELF, PE,
Mach-O)
- **Release profile** optimization: `strip = true`, `codegen-units = 1`,
`lto = "thin"` (release) / `"fat"` (dist)
- **mmap-guard** dependency for safe memory-mapped I/O
- **cargo-dist** version bump to 0.31.0
- **GOTCHAS.md** added as living documentation for edge cases
- CI workflow updates (action versions, scorecard)

## Test Plan

- [x] 610 tests pass across 25 test files (597 previously + 13 new
short-flag tests)
- [x] `cargo clippy --all-targets -- -D warnings` clean
- [x] `cargo fmt --check` clean
- [x] All pre-commit hooks pass (fmt, clippy, cargo-check, mdformat,
cargo-audit)
- [x] Integration test coverage for all CLI flags, exit codes, and
conflict combinations
- [x] Score determinism verified across consecutive runs
- [x] Warning emission tested via debug-build env var injection
- [x] Unknown/empty binary fallback paths tested
- [x] Short flag equivalence verified (-j = --json, -m = --min-len,
etc.)
- [x] NO_COLOR env var tested
- [x] stdin pipe tested with ELF binary and empty input
- [x] Permission denied exit code 4 tested (Unix)

### New Test Files in This PR

| File | Tests | Coverage Area |
|------|-------|--------------|
| `integration_flows_1_5.rs` | 16 | Quick analysis, filtering, top-N,
JSON, YARA |
| `integration_flows_6_7.rs` | 11 | Plain text output, summary mode |
| `integration_flow8_errors.rs` | 11 | Argument conflicts, validation
failures |
| `integration_flow8_diagnostics.rs` | 13 | Warnings, fallback, score
determinism, debug |
| `integration_cli_errors.rs` | 10 | Exit codes, error messages |
| `integration_cli_coverage.rs` | 18 | Encoding, stdin, combined
filters, permissions |
| `integration_cli_short_flags.rs` | 13 | Short flags, NO_COLOR, OR
logic, edge cases |
| `integration_flow1_minlen.rs` | 2 | Min-length default and explicit
filter |
| `integration_flows_5_yara.rs` | 1 | YARA long string deterministic
skip |

## Breaking Changes

- `--notags` renamed to `--no-tags` (CLI flag)
- `FoundString` struct fields are no longer public for direct
construction (use `FoundString::new()` + builders)
- `SectionInfo` is `#[non_exhaustive]` (external crate consumers must
use constructors)
- Exit codes changed: file-not-found is now 3 (was 1), permission-denied
is now 4 (was 1)

## Risk Assessment

**Risk Level: Medium**

| Factor | Assessment |
|--------|-----------|
| Size | Large (132 files), but most changes are additive |
| Breaking changes | CLI flag rename + exit code changes -- documented
above |
| Test coverage | Strong -- 610 tests covering all new paths |
| Dependencies | +mmap-guard (thin wrapper), +patharg (stdin handling) |
| Security | `#![forbid(unsafe_code)]` maintained, no new unsafe |

## Reviewer Notes

- The pipeline module (`src/pipeline/`) is entirely new -- start review
there
- Container parser splits (elf.rs -> elf/mod.rs + elf/tests.rs) are
mechanical moves with no logic changes
- Documentation changes are extensive but mostly rewrites for accuracy
- GOTCHAS.md is a new file worth reading for context on edge cases

---

Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: UncleSp1d3r <unclesp1d3r@evilbitlabs.io>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: unclesp1d3r

.gitattributes

@@ -78,4 +78,8 @@ LICENSE text
 *.so binary
 *.dylib binary
 
+# Test fixture binaries
+tests/fixtures/test_empty.bin binary
+tests/fixtures/test_unknown.bin binary
+
 .env text=utf-8 eol=lf

.github/copilot-instructions.md

@@ -67,8 +67,11 @@ Container parsers assign weights (1.0-10.0) to sections based on string likeliho
 Strings are grouped by `(text, encoding)` tuple in a `HashMap<(String, Encoding), Vec<StringOccurrence>>`:
 
 - **Preserve all occurrences**: Each occurrence captures offset, RVA, section, source, tags, score, confidence
+
 - **Tag merging**: Union all tags via `HashSet`, then sort
+
 - **Combined scoring formula**:
+
   ```text
   base_score = max(occurrence.original_score)
   occurrence_bonus = 5 * (count - 1)

.github/workflows/audit.yml

@@ -22,6 +22,6 @@ jobs:
       contents: read
       issues: write
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions-rust-lang/audit@v1
+      - uses: actions/checkout@v6.0.2
+      - uses: actions-rust-lang/audit@v1.2.7
         name: Audit Rust Dependencies

.github/workflows/ci.yml

@@ -24,17 +24,23 @@ jobs:
   quality:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.2
       - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9
         with:
           components: rustfmt, clippy
           toolchain: 1.93.0
-      - uses: jdx/mise-action@v3
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Ensure rustfmt and clippy are installed
+        run: rustup component add rustfmt clippy
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2.8.2
+
       - name: Rustfmt Check
         run: cargo fmt --all -- --check
 
@@ -52,28 +58,31 @@ jobs:
           - toolchain: stable minus 3 releases
           - toolchain: stable minus 4 releases
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.2
       - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9
         with:
           components: rustfmt, clippy
           toolchain: ${{ matrix.toolchain }}
 
       - name: Cache Rust dependencies
-        uses: Swatinem/rust-cache@v2
+        uses: Swatinem/rust-cache@v2.8.2
 
       - name: Check MSRV compliance
         run: cargo check --all-features
 
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: jdx/mise-action@v3
+      - uses: actions/checkout@v6.0.2
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Generate test fixtures
+        run: just gen-fixtures
+
       - name: Run tests (all features)
         run: just test-ci
 
@@ -93,13 +102,16 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v6
-      - uses: jdx/mise-action@v3
+      - uses: actions/checkout@v6.0.2
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Generate test fixtures
+        run: just gen-fixtures
+
       - name: Run tests (all features)
         run: just test-ci
       - name: Build release
@@ -109,18 +121,21 @@ jobs:
     runs-on: ubuntu-latest
     needs: [test, test-cross-platform]
     steps:
-      - uses: actions/checkout@v6
-      - uses: jdx/mise-action@v3
+      - uses: actions/checkout@v6.0.2
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true
           github_token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Generate test fixtures
+        run: just gen-fixtures
+
       - name: Generate coverage
         run: just coverage
 
       - name: Upload to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v5.5.2
         with:
           files: lcov.info
           fail_ci_if_error: false

.github/workflows/codeql.yml

@@ -19,9 +19,9 @@ jobs:
     name: CodeQL Analyze
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.2
 
-      - uses: jdx/mise-action@v3
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true

.github/workflows/copilot-setup-steps.yml

@@ -22,9 +22,9 @@ jobs:
       contents: read
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.2
 
-      - uses: jdx/mise-action@v3
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true

.github/workflows/docs.yml

@@ -25,9 +25,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
 
-      - uses: jdx/mise-action@v3
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true
@@ -59,4 +59,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4.0.5

.github/workflows/release.yml

@@ -64,9 +64,9 @@ jobs:
         # we specify bash to get pipefail; it guards against the `curl` command
         # failing. otherwise `sh` won't catch that `curl` returned non-0
         shell: bash
-        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.30.3/cargo-dist-installer.sh | sh"
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.31.0/cargo-dist-installer.sh | sh"
       - name: Cache dist
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/dist
@@ -82,7 +82,7 @@ jobs:
           cat plan-dist-manifest.json
           echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT"
       - name: "Upload dist-manifest.json"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: artifacts-plan-dist-manifest
           path: plan-dist-manifest.json
@@ -135,7 +135,7 @@ jobs:
         run: ${{ matrix.install_dist.run }}
       # Get the dist-manifest
       - name: Fetch local artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -151,7 +151,7 @@ jobs:
           dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json
           echo "dist ran successfully"
       - name: Attest
-        uses: actions/attest-build-provenance@v3
+        uses: actions/attest-build-provenance@v4
         with:
           subject-path: "target/distrib/*${{ join(matrix.targets, ', ') }}*"
       - id: cargo-dist
@@ -168,7 +168,7 @@ jobs:
 
           cp dist-manifest.json "$BUILD_MANIFEST_NAME"
       - name: "Upload artifacts"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: artifacts-build-local-${{ join(matrix.targets, '_') }}
           path: |
@@ -190,7 +190,7 @@ jobs:
           persist-credentials: false
           submodules: recursive
       - name: Install cached dist
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/
@@ -202,7 +202,7 @@ jobs:
         shell: bash
       # Get all the local artifacts for the global tasks to use (for e.g. checksums)
       - name: Fetch local artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -233,7 +233,7 @@ jobs:
             find . -name '*.cdx.xml' | tee -a "$GITHUB_OUTPUT"
             echo "EOF" >> "$GITHUB_OUTPUT"
       - name: "Upload artifacts"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: artifacts-build-global
           path: |
@@ -259,14 +259,14 @@ jobs:
           persist-credentials: false
           submodules: recursive
       - name: Install cached dist
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           name: cargo-dist-cache
           path: ~/.cargo/bin/
       - run: chmod +x ~/.cargo/bin/dist
       # Fetch artifacts from scratch-storage
       - name: Fetch artifacts
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: target/distrib/
@@ -279,14 +279,14 @@ jobs:
           cat dist-manifest.json
           echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT"
       - name: "Upload dist-manifest.json"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           # Overwrite the previous copy
           name: artifacts-dist-manifest
           path: dist-manifest.json
       # Create a GitHub Release while uploading all files to it
       - name: "Download GitHub Artifacts"
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: artifacts
@@ -326,7 +326,7 @@ jobs:
           token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
       # So we have access to the formula
       - name: Fetch homebrew formulae
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@v8
         with:
           pattern: artifacts-*
           path: Formula/

.github/workflows/scorecard.yml

@@ -26,7 +26,7 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v6.0.2
         with:
           persist-credentials: false
 
@@ -38,7 +38,7 @@ jobs:
           publish_results: true
 
       - name: "Upload artifact"
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: SARIF file
           path: results.sarif

.github/workflows/security.yml

@@ -24,9 +24,9 @@ jobs:
   audit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.2
 
-      - uses: jdx/mise-action@v3
+      - uses: jdx/mise-action@v3.6.3
         with:
           install: true
           cache: true