If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/xd009642/tarpaulin shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 12 active contributors
• Distributed ownership (top contributor 44% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live xd009642/tarpaulin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xd009642/tarpaulin.

What it runs against: a local clone of xd009642/tarpaulin — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in xd009642/tarpaulin | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xd009642/tarpaulin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xd009642/tarpaulin.git
#   cd tarpaulin
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of xd009642/tarpaulin and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "xd009642/tarpaulin(\\.git)?\\b" \\
  && ok "origin remote is xd009642/tarpaulin" \\
  || miss "origin remote is not xd009642/tarpaulin (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/process_handling/mod.rs" \\
  && ok "src/process_handling/mod.rs" \\
  || miss "missing critical file: src/process_handling/mod.rs"
test -f "src/source_analysis/mod.rs" \\
  && ok "src/source_analysis/mod.rs" \\
  || miss "missing critical file: src/source_analysis/mod.rs"
test -f "src/statemachine/mod.rs" \\
  && ok "src/statemachine/mod.rs" \\
  || miss "missing critical file: src/statemachine/mod.rs"
test -f "src/report/mod.rs" \\
  && ok "src/report/mod.rs" \\
  || miss "missing critical file: src/report/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/xd009642/tarpaulin"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Tarpaulin is a code coverage reporting tool for Rust projects that uses ptrace (Linux/x86_64) or LLVM instrumentation to trace test execution and measure line coverage. It integrates directly with Cargo, reports coverage in multiple formats (Cobertura, Coveralls, LCOV, HTML, JSON, Markdown), and runs as a cargo subcommand (cargo tarpaulin), solving the problem of code coverage measurement in the Rust ecosystem where native compiler instrumentation was historically limited. Single-binary architecture: src/main.rs is the CLI entry point, src/lib.rs exports the core API, src/cargo/ handles Cargo.toml parsing and test discovery, src/process_handling/ptrace_control.rs + linux.rs implement the ptrace-based tracer, and src/report/ contains multiple output format generators (cobertura.rs, coveralls.rs, html.rs, lcov.rs, etc.). Configuration flows through src/config/parse.rs → src/config/types.rs, and event logging is centralized in src/event_log.rs.

Rust developers and CI/CD pipeline maintainers who need to measure test coverage across their projects, validate coverage thresholds in continuous integration, and generate coverage reports for stakeholders—particularly those using Linux with x86_64 processors or containerized CI environments.

Tarpaulin is production-ready with 525KB of Rust code, active maintenance (releases through crates.io at v0.35.4), comprehensive CI via GitHub Actions (coverage.yml, docker.yml, release.yml, rust.yml), and Docker distribution. However, the README acknowledges known accuracy limitations in edge cases and the codebase is single-maintainer (xd009642), creating sustainability risk.

The project carries moderate risk: it's heavily platform-dependent (ptrace only works on Linux x86_64), has 25+ external dependencies including gimli for DWARF parsing and nix for ptrace syscalls, and relies on undocumented compiler behavior. The single-maintainer model and specialized Linux kernel interaction (ptrace_control.rs) mean bugs could have high impact. Last visible activity appears recent (based on version 0.35.4 and active GitHub workflows), but the TROUBLESHOOTING.md document length suggests accumulated compatibility issues.

The project actively maintains Dockerfiles (including nightly variants), uses GitHub Actions for CI/release automation, and publishes to crates.io regularly. The codebase shows active debugging support (--dump-traces, --debug flags in src/args.rs) and multiple reporting backend implementations suggest ongoing expansion of output formats.

Clone and install via Cargo: git clone https://github.com/xd009642/tarpaulin.git && cd tarpaulin && cargo install --path . (builds the cargo-tarpaulin binary). Then run against any Rust project: cd /path/to/rust/project && cargo tarpaulin --out Html --output-dir coverage/.

Daily commands: For development: cargo build produces a debug binary. To test coverage on tarpaulin itself: cargo tarpaulin --out Html. To run the integration test suite: cargo test --test integration. Docker users: docker run --rm -v $(pwd):/src xd009642/tarpaulin.

• src/main.rs — Entry point for the cargo-tarpaulin binary; handles CLI parsing and orchestrates the coverage analysis workflow.
• src/process_handling/mod.rs — Core process instrumentation module that manages ptrace-based code execution tracking and breakpoint handling on Linux.
• src/source_analysis/mod.rs — AST analysis engine that identifies coverable code statements, expressions, and control flow to instrument coverage targets.
• src/statemachine/mod.rs — State machine driving the instrumentation pipeline; coordinates compilation, breakpoint injection, and trace collection.
• src/report/mod.rs — Report generation abstraction; dispatches coverage data to multiple output formats (Cobertura, LCOV, JSON, HTML, Coveralls).
• src/cargo/mod.rs — Cargo integration layer; invokes cargo build with instrumentation flags and manages workspace/package discovery.
• src/traces.rs — Trace collection and aggregation; converts raw ptrace events into line-level and region-level coverage records.

Add Support for a New Report Format

1. Create a new module under src/report/ (e.g., src/report/newformat.rs) implementing the Reportable trait or format-specific logic (src/report/newformat.rs)
2. Add module declaration and import in src/report/mod.rs (src/report/mod.rs)
3. Extend the format enum/match statement in src/report/mod.rs to handle the new format variant and invoke your serializer (src/report/mod.rs)
4. Add CLI argument option in src/args.rs to allow users to select the new format (src/args.rs)
5. Add integration test under tests/ to validate the new format output against sample coverage data (tests/mod.rs)

Add a New Source Code Analysis Rule

1. Identify the appropriate submodule in src/source_analysis/ (e.g., statements.rs for statement coverage, expressions.rs for branch coverage) (src/source_analysis/mod.rs)
2. Add a new visitor function or extend an existing one to detect and annotate the new coverable construct (e.g., match arms, loop conditions) (src/source_analysis/statements.rs)
3. Update the coverage tracking data structures in src/source_analysis/mod.rs to account for the new rule (src/source_analysis/mod.rs)
4. Register your new rule in the source analysis visitor pipeline so it fires during AST traversal (src/source_analysis/mod.rs)
5. Add test cases in tests/data/ with Rust code that exercises the new rule and verify coverage is correctly recorded (tests/data/)

Add Support for a New Instrumentation Strategy

1. Create or extend src/statemachine/instrumented.rs with a new instrumentation method (e.g., for binary rewriting, LLVM pass, or compiler plugin) (src/statemachine/instrumented.rs)
2. Implement the instrumentation logic that inserts coverage probes into compiled binaries or intermediate representations (src/statemachine/instrumented.rs)
3. Extend src/statemachine/mod.rs to incorporate the new instrumentation strategy into the state machine workflow (src/statemachine/mod.rs)
4. Update src/process_handling/mod.rs if the new strategy requires different event capture or trace collection mechanisms (src/process_handling/mod.rs)
5. Add configuration option in src/config/types.rs and CLI flag in src/args.rs to allow users to select the instrumentation strategy (src/config/types.rs)

Extend Platform Support (Add Non-Linux Coverage)

1. Create a new module in src/process_handling/ (e.g., src/process_handling/macos.rs or src/process_handling/windows.rs) for platform-specific ptrace/debugger APIs (src/process_handling/macos.rs)
2. Implement platform-specific process control, signal handling, and register access matching the interface in src/process_handling/linux.rs (src/process_handling/macos.rs)
3. Update src/process_handling/mod.rs with cfg-gated module declarations and conditionally export the platform module (src/process_handling/mod.rs)
4. Extend src/statemachine/mod.rs (or create src/statemachine/macos.rs) with platform-specific state transitions and process spawning logic (src/statemachine/mod.rs)
5. Update build.rs to handle platform-specific dependencies and validation (build.rs)

• ptrace (Linux syscall) — Enables low-level process instrumentation and breakpoint-driven execution tracing without requiring source code recompilation or compiler modifications; allows non-invasive coverage measurement.
• Syn + Quote (AST parsing) — Provides Rust-native, stable, and widely-used AST traversal and code generation; essential for accurate identification of coverable code constructs and annotation injection.
• Cargo metadata crate — Standardized interface to

Ptrace limitations on Linux: tool only works on x86_64/x86 Linux by default (checked in Cargo.toml conditional dependencies), requires ptrace capability (may fail in strict seccomp containers or with certain Docker configs). DWARF/symbol parsing fragility: coverage accuracy depends on compiler-generated debug symbols (gimli crate reads DWARF); optimized builds or stripped binaries will fail. Cargo workspace complexity: src/cargo/config_file.rs parses Cargo.lock and workspace structure; monorepo projects with path dependencies may have edge cases. Breakpoint stability: src/process_handling/breakpoint.rs injects int3 instructions; incompatible with code that uses SIGTRAP or inline assembly. Environment setup: requires Rust toolchain in PATH and libc on Linux (libc 0.2.184 dependency); CI containers must have build-essential or equivalents.

• ptrace (process trace) — The Linux syscall mechanism Tarpaulin relies on to intercept and observe test process execution; understanding ptrace is critical for debugging Linux-specific coverage failures
• DWARF debugging format — Tarpaulin parses DWARF symbol tables (via gimli crate) to map machine code back to source lines; broken or missing DWARF breaks coverage accuracy
• Breakpoint injection / int3 instruction — Tarpaulin injects x86 int3 (0xCC) breakpoint instructions to halt at specific lines; understanding breakpoint semantics is necessary for modifying coverage collection logic
• LLVM coverage instrumentation — Tarpaulin supports LLVM's native coverage mode as an alternative to ptrace; understanding instrumentation-based coverage helps explain the --engine llvm flag and non-Linux platform support
• Cobertura coverage report format — Industry-standard XML format for coverage reports that Tarpaulin generates; understanding the schema is necessary to extend report generation or integrate with third-party tools
• Signal handling in forked processes — Tarpaulin forks test binaries and uses signals (SIGTRAP, SIGTERM) to control them; misunderstanding signal semantics across fork boundaries causes test execution bugs
• Cargo metadata discovery — Tarpaulin uses cargo_metadata crate to parse Cargo.toml and discover test targets; workspace-aware coverage requires correct metadata parsing

• mozilla/grcov — Alternative Rust code coverage tool using LLVM coverage instrumentation; shares similar goal but different underlying engine
• taiki-e/cargo-hack — Sibling Cargo plugin ecosystem; helpful for understanding integration patterns with Cargo subcommands
• rust-lang/rustfmt — Similar Rust development tool that ships as a cargo subcommand; architectural reference for CLI tooling patterns
• codecov/codecov-rs — Codecov service integration layer for CI; common downstream consumer of tarpaulin coverage reports
• coveralls-io/coveralls-api — Coveralls service API client; tarpaulin uses the Rust wrapper (coveralls-api crate) to ship coverage upstream

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/source_analysis/ modules

The source_analysis directory contains 6 modules (attributes.rs, expressions.rs, items.rs, macros.rs, statements.rs, tests.rs) that parse and analyze Rust source code for coverage instrumentation. These are critical path components but the tests/ directory only contains integration tests. Adding targeted unit tests for edge cases in AST parsing, macro handling, and statement detection would improve reliability and make future refactoring safer.

• [ ] Create tests/source_analysis_unit_tests.rs with unit test modules
• [ ] Add tests for macro expansion edge cases in src/source_analysis/macros.rs
• [ ] Add tests for expression classification in src/source_analysis/expressions.rs
• [ ] Add tests for attribute filtering logic in src/source_analysis/attributes.rs
• [ ] Document test coverage for each module in CONTRIBUTING.md

Add GitHub Actions workflow for cross-platform binary testing (Windows/macOS)

The .github/workflows/ directory shows coverage.yml, rust.yml, and release.yml, but all are Linux-focused. Tarpaulin is a Cargo tool that users run on multiple OSes, yet only Linux is tested in CI. The conditional dependency on nix/libc for Linux suggests platform-specific code paths. Adding workflows for Windows and macOS (even if only smoke tests) would catch platform-specific regressions and improve release confidence.

• [ ] Create .github/workflows/macos.yml with Rust build and basic cargo-tarpaulin test runs
• [ ] Create .github/workflows/windows.yml with similar structure
• [ ] Update .github/workflows/rust.yml to document why Linux-only
• [ ] Test at least one integration test from tests/data on each platform
• [ ] Update CONTRIBUTING.md with platform-specific testing guidance

Add integration tests for src/report/ format outputs (cobertura, lcov, json, markdown, coveralls)

The src/report/ directory implements 5+ output formats (cobertura.rs, lcov.rs, json.rs, markdown.rs, coveralls.rs) but tests/data appears minimal. There's no evidence of round-trip tests or format validation. Adding integration tests that verify output against known-good coverage reports and validate against format specifications (e.g., Cobertura schema) would catch format regressions and make the tool more reliable for CI/CD pipelines.

• [ ] Create tests/report_formats.rs with fixtures for each format
• [ ] Add test for Cobertura XML output structure validation against schema
• [ ] Add test for LCOV output parsing and line coverage accuracy
• [ ] Add test for JSON output serialization and required fields
• [ ] Add test for Coveralls API format compliance in src/report/coveralls.rs
• [ ] Document format examples in TROUBLESHOOTING.md or new docs/FORMATS.md

• Add test coverage for src/config/parse.rs TOML parsing edge cases (workspace root detection, profile overrides)—currently missing unit tests for malformed tarpaulin.toml files
• Implement a plain-text or Markdown table output format in src/report/markdown.rs to match the existing HTML/JSON/Cobertura formatters, enabling easier CI log parsing
• Add --fail-under <percent> flag enforcement in src/args.rs and src/main.rs to fail the build if coverage drops below a threshold, solving a common CI gate pattern

• High · Outdated libc Dependency — Cargo.toml, libc = "0.2.184" (Linux x86_64/x86 only). The libc dependency version 0.2.184 is specified in Cargo.toml. While this is a relatively recent version, libc is a critical low-level dependency. Any vulnerability in libc could compromise the entire application. Regular security audits and updates are essential. Fix: Regularly run 'cargo audit' to check for known vulnerabilities in libc and all dependencies. Keep libc updated to the latest stable version and monitor security advisories from the Rust Security Advisory Database.
• High · ptrace Usage Without Additional Security Context — Cargo.toml, nix dependency with ptrace feature; src/process_handling/ptrace_control.rs. The project uses the 'nix' crate with 'ptrace' feature enabled for process introspection. ptrace is a powerful system call that requires careful handling. Running tarpaulin with elevated privileges could pose security risks if not properly isolated or validated. Fix: Implement strict privilege checking and validation. Document ptrace security requirements clearly. Consider running tarpaulin in isolated containers or sandboxes. Validate all input to process handling code paths.
• High · Incomplete Dependency Version in Cargo.toml — Cargo.toml, procfs dependency definition. The procfs dependency version appears to be incomplete/truncated in the provided Cargo.toml content (procfs = "0."). This incomplete specification could lead to unexpected version resolution and potential security issues. Fix: Ensure the procfs dependency has a complete and pinned version specification. Run 'cargo check' and 'cargo audit' to verify dependency resolution. Provide complete version constraints in Cargo.toml.
• Medium · Docker Multi-Stage Build Without Non-Root User — Dockerfile, Dockerfile-slim, Dockerfile-nightly, Dockerfile-nightly-slim. The Dockerfile builds the application in a container but the final stage runs as root (default user in the rust base image). This could allow container escape or privilege escalation attacks if the tarpaulin binary has vulnerabilities. Fix: Create a non-root user in the final stage and use it to run the application. Example: 'RUN useradd -m -u 1000 tarpaulin && USER tarpaulin'. This limits the impact of potential vulnerabilities.
• Medium · Dependency on Unsafe Code in nix Crate — Cargo.toml, nix = "0.31.2" with multiple unsafe-code requiring features. The nix crate provides bindings to libc and contains unsafe code. The ptrace, sched, signal, and personality features all involve unsafe system calls. Any vulnerability in nix's unsafe code could compromise the application. Fix: Review the nix crate's changelog and security advisories regularly. Consider using 'cargo-deny' to audit unsafe code usage. Test ptrace functionality thoroughly in isolated environments before deployment.
• Medium · No Security Policy or Vulnerability Disclosure Process Evident — Repository root (missing SECURITY.md). Based on the repository structure, there is no visible SECURITY.md or security policy file that documents how security vulnerabilities should be reported. This makes it difficult for security researchers to responsibly disclose issues. Fix: Create a SECURITY.md file in the repository root documenting: (1) How to report security vulnerabilities privately, (2) Expected response times, (3) Preferred communication channels, (4) Whether rewards/credits are offered.
• Medium · Cargo Vendor in Docker Without Verification — Dockerfile lines with 'RUN cargo vendor > .cargo/config'. The Dockerfile uses 'cargo vendor' to download dependencies offline, but there is no checksum verification or signature validation of the vendored packages before use. A MITM attack could inject malicious dependencies. Fix: Add checksum verification after vendoring. Use '--locked' flag with Cargo.lock to ensure reproducible builds. Consider using 'cargo-deny' for additional dependency security checks. Verify Cargo.lock checksums are present.
• Low · Hardcoded Cargo Profile in Docker — undefined. The Docker build uses default cargo profiles which may include debug symbols and unoptimized code in the final binary. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.