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/TeXitoi/structopt 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.

WAIT — Stale — last commit 2y ago

• 26+ active contributors
• Distributed ownership (top contributor 48% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Non-standard license (Other) — review terms

_{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 TeXitoi/structopt repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TeXitoi/structopt.

What it runs against: a local clone of TeXitoi/structopt — 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 TeXitoi/structopt | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 881 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TeXitoi/structopt. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TeXitoi/structopt.git
#   cd structopt
#
# 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 TeXitoi/structopt and re-run."
  exit 2
fi

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

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

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

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 881 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~851d)"
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/TeXitoi/structopt"
  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).

structopt is a Rust procedural macro library that auto-generates command-line argument parsing from struct definitions using the clap parser. Instead of writing boilerplate clap builder code, you annotate a struct with #[derive(StructOpt)] and doc comments become help text, field names become CLI flags, and the macro generates a fully-featured parser. It combines clap v2.33 with custom derive to eliminate repetition. Monorepo with two coupled crates: structopt/ (src/lib.rs, main interface) depends on structopt-derive/ (the procedural macro implementation under structopt-derive/src/lib.rs). Derive logic is split into attrs.rs (attribute parsing), parse.rs (token stream parsing), ty.rs (type analysis), and doc_comments.rs (help text generation). Examples in examples/ are runnable demos; tests/ are integration tests covering naming, flags, subcommands, and edge cases.

Rust developers building CLI applications who want to define command-line interfaces as strongly-typed structs with minimal boilerplate. Especially useful for those migrating from docopt or hand-written argument parsing, and those who prefer declarative over procedural CLI definitions.

Production-ready but in maintenance mode. The project is well-established (v0.3.26), has comprehensive test coverage (tests/ directory with 13+ test files), TravisCI integration, and clear documentation on docs.rs. However, it explicitly states 'no new features will be added' as clap v3+ integrated these features natively—bugs and docs are still accepted, but this is essentially a stable legacy library.

Low-to-moderate risk for new code. The codebase depends on clap v2.33 (not v3+), creating a technical debt if clap v2 loses support. Single maintainer (TeXitoi) is a concern for critical issues. The README explicitly recommends migration to clap v3 for new projects. However, the maintenance-mode status means stability is prioritized over breaking changes, making it safe for existing users.

In maintenance mode—no active feature development. Focus is on fixing reported bugs, improving documentation, and reviewing PRs. The maintenance status in the README indicates the project is stable but not evolving. Users are encouraged to migrate to clap v3's built-in derive features for new projects.

Clone: git clone https://github.com/TeXitoi/structopt.git && cd structopt. Build: cargo build. Run examples: cargo run --example basic -- --help. Run tests: cargo test. The project uses standard Rust tooling with Cargo; no special setup required beyond a standard Rust installation.

Daily commands: No dev server. Build with cargo build. Run examples: cargo run --example basic -- --help. Run all tests: cargo test. Run a specific example: cargo run --example git -- --help. For the derive proc-macro tests: cargo test -p structopt-derive.

• structopt-derive/src/lib.rs: Core procedural macro implementation; this is where struct-to-clap-builder transformation happens via the derive function
• structopt-derive/src/attrs.rs: Parses #[structopt(...)] and #[doc] attributes on structs/fields; defines the semantic rules for all CLI options
• src/lib.rs: Public API surface; re-exports StructOpt trait and clap types; documents the main usage patterns
• structopt-derive/src/doc_comments.rs: Converts Rust doc comments into clap help text; critical for the declarative documentation feature
• examples/basic.rs: Canonical example showing the full feature set (flags, options, positional args, defaults); reference implementation
• tests/arguments.rs: Integration test suite covering argument parsing behavior; validates correctness of attribute-driven parsing
• CHANGELOG.md: Documents all breaking changes and features; essential for understanding compatibility since maintenance mode

For derive logic changes: Edit structopt-derive/src/lib.rs (macro entry point), structopt-derive/src/attrs.rs (attribute parsing), structopt-derive/src/parse.rs (struct/field analysis). For runtime behavior: Edit src/lib.rs (public traits and re-exports). For tests: Add cases to tests/*.rs for integration tests or structopt-derive/src/lib.rs for macro tests. For examples: Add a new file in examples/ and document it in examples/README.md. For docs: Update README.md or add doc comments to public items in src/lib.rs.

No special env vars required. However, be aware: (1) The macro assumes Rust 2018 edition (see Cargo.toml edition = 2018). (2) clap v2.33 is pinned, so you cannot upgrade to clap v3 without migrating away from structopt—the feature sets diverged. (3) structopt-derive is a separate crate but version-locked (=0.4.18 in main Cargo.toml); version mismatches cause cryptic macro errors. (4) The paw feature requires the optional paw_dep crate; it's disabled by default and rarely used. (5) Attribute parsing is strict—typos in #[structopt(...)] fail at compile time with unhelpful error messages from syn.

• Procedural Macros (Derive Macros) — structopt is entirely built on procedural derive macros; understanding how #[derive(StructOpt)] transforms struct definitions into clap builder code is fundamental to extending or debugging the library
• Attribute Macros & Meta Syntax — The entire feature set is driven by custom attributes like #[structopt(short, long, parse(from_os_str))]; parsing and validating these attributes is the core responsibility of attrs.rs
• Abstract Syntax Tree (AST) Traversal — structopt-derive walks the struct AST (fields, types, attributes) to extract metadata and generate code; syn provides the AST primitives and quote! generates new code
• Builder Pattern — structopt generates clap builder code (App::new().arg(...).arg(...)) at compile time; understanding the clap builder API is necessary to know what the macro produces
• Type-driven Code Generation — The macro infers CLI behavior from Rust types (e.g., Vec<T> implies multiple values, Option<T> implies optional, bool implies flag); ty.rs codifies these type-to-behavior mappings
• Docstring-Driven Documentation — structopt converts Rust doc comments directly into clap help text via doc_comments.rs; this eliminates duplication and keeps CLI help in sync with code
• Compile-Time vs Runtime Errors — structopt pushes many validation errors to compile time (e.g., incompatible attribute combinations, type mismatches); understanding when errors appear helps avoid runtime surprises in CLI apps

• clap-rs/clap — The underlying command-line parser that structopt wraps; clap v3+ integrated structopt's derive feature natively, making it the successor for new projects
• rust-lang/rust — Structopt relies on Rust's procedural macro system (syn/quote); understanding macro expansion is essential for debugging derive behavior
• docopt/docopt.rs — docopt.rs is a predecessor approach to CLI parsing using docstrings; structopt and clap replaced it with more type-safe derive macros
• dtolnay/syn — structopt-derive heavily uses syn for parsing Rust token streams and AST manipulation; understanding syn is critical for modifying the macro
• bheisler/criterion.rs — Not directly related, but structopt's test suite uses similar patterns for comparing generated code and validating help output formatting

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 UI tests for derive macro error messages

The repo has a tests/ui/ directory with trybuild tests, but it's incomplete. There are only 7 UI test files covering edge cases like bool_default_value, enum_flatten, and external_subcommand_wrong_type. Given the complexity of the derive macro in structopt-derive/src/lib.rs and structopt-derive/src/attrs.rs, many error scenarios lack concrete test coverage. This would catch regressions and improve error message quality for users.

• [ ] Review structopt-derive/src/attrs.rs to identify all validation errors that can be triggered
• [ ] Add UI tests in tests/ui/ for uncovered error paths (e.g., conflicting attributes, invalid type combinations)
• [ ] Create corresponding .stderr files documenting expected compiler error output
• [ ] Run cargo test --test macro-errors to verify new tests integrate properly

Add tests for doc_comments feature with edge cases

The repo has tests/doc-comments-help.rs and structopt-derive/src/doc_comments.rs, but the test coverage appears minimal. The doc_comments feature is important for users who want to auto-generate help text from doc comments. Edge cases like multi-line comments, special characters, and interaction with #[doc] attributes across nested structures should be thoroughly tested.

• [ ] Examine structopt-derive/src/doc_comments.rs to understand all parsing logic
• [ ] Expand tests/doc-comments-help.rs with edge cases: nested structs with #[flatten], tuple variants, special markdown characters
• [ ] Add regression tests for common doc comment formatting patterns
• [ ] Verify integration with examples/doc_comments.rs works as expected

Add GitHub Actions CI to replace deprecated Travis CI

The repo uses .travis.yml for CI (noted in badges), but Travis CI is deprecated and the badges point to a legacy system. GitHub Actions is now the standard for Rust projects on GitHub. This will improve reliability, provide faster feedback to contributors, and reduce reliance on external services.

• [ ] Create .github/workflows/ci.yml with steps for: cargo check, cargo test, cargo test --doc, cargo clippy, and cargo fmt --check
• [ ] Add a MSRV (Minimum Supported Rust Version) test job against the edition specified in Cargo.toml (2018)
• [ ] Configure the workflow to run on push to master and all pull requests
• [ ] Remove or update .travis.yml and badges in README.md to point to GitHub Actions
• [ ] Verify all tests pass locally and in the new CI before merging

• Add integration tests for #[structopt(rename_all = ...)] in kebab-case, snake_case, and PascalCase for struct field names. Currently rename_all.rs exists but only covers simple rename; extend to verify flattened subcommands and nested enums preserve case properly.
• Improve compiler error messages when users write invalid #[structopt(...)] attributes (e.g., typos like #[structopt(lone)] instead of #[structopt(long)]). Currently errors are generic syn parse errors; add a validation pass in structopt-derive/src/attrs.rs to suggest corrections.
• Add tests for the interaction between #[structopt(env)] and #[structopt(default_value)] when both are present. The env.rs example exists but no test validates precedence (env should override default). Add cases to tests/default_value.rs or tests/env.rs.

The structopt codebase has moderate security concerns primarily stemming from its maintenance-only status and reliance on outdated clap v2.33. While the code itself appears well-structured with comprehensive tests and no obvious injection risks or hardcoded credentials, the lack of active maintenance combined with an EOL dependency represents a significant long-term security risk. The project's own documentation recommends migrating to clap v3+. Users should prioritize upgrading to actively maintained alternatives. The codebase shows no evidence of hardcoded secrets, infrastructure misconfiguration, or unsafe Rust patterns (badge indicates unsafe code is forbidden).

• High · Outdated clap Dependency — Cargo.toml - clap dependency. The codebase depends on clap version 2.33, which is significantly outdated. clap v2 reached end-of-life and no longer receives security updates. Multiple security vulnerabilities may exist in this version that are patched in clap v3 and v4. Fix: Migrate to clap v3 or v4. The README acknowledges clap v3 is out and recommends migration. Update the dependency: clap = { version = "4.x", default-features = false } and follow the migration guide provided by the clap project.
• Medium · Maintenance Mode Project with Limited Security Support — README.md and overall project status. The project is in maintenance mode per the README: 'no new feature will be added.' This means security improvements and dependency updates may not be prioritized. The project explicitly states users should migrate to clap v3+, indicating the maintainers are not actively developing this crate for long-term use. Fix: Users should migrate to clap's built-in struct derive (clap v3+) which receives active maintenance and security updates. If continuing to use structopt, establish a process to monitor for security advisories.
• Medium · Transitive Dependency Risk - lazy_static — Cargo.toml - lazy_static dependency. The codebase uses lazy_static 1.4.0, which is functional but considered legacy. Modern Rust provides std::sync::OnceLock (stable in 1.70+) as a replacement. While not a vulnerability per se, using outdated lazy initialization patterns may indicate less active maintenance. Fix: For Rust 1.70+, consider migrating to std::sync::OnceLock. Otherwise, keep lazy_static updated and monitor for any security advisories.

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.