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/crablang/crab 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

• 25+ active contributors
• Distributed ownership (top contributor 25% 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 crablang/crab repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/crablang/crab.

What it runs against: a local clone of crablang/crab — 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 crablang/crab | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 656 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "crablang/crab(\\.git)?\\b" \\
  && ok "origin remote is crablang/crab" \\
  || miss "origin remote is not crablang/crab (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"

# 4. Critical files exist
test -f "compiler/rustc/src/main.rs" \\
  && ok "compiler/rustc/src/main.rs" \\
  || miss "missing critical file: compiler/rustc/src/main.rs"
test -f "compiler/rustc_ast/src/lib.rs" \\
  && ok "compiler/rustc_ast/src/lib.rs" \\
  || miss "missing critical file: compiler/rustc_ast/src/lib.rs"
test -f "compiler/rustc_ast_lowering/src/lib.rs" \\
  && ok "compiler/rustc_ast_lowering/src/lib.rs" \\
  || miss "missing critical file: compiler/rustc_ast_lowering/src/lib.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

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

CrabLang is a community fork of the Rust programming language that maintains 100% memory-safety guarantees while reducing governance overhead. It compiles to LLVM IR and produces native binaries identical to upstream Rust, but operates as an independent project with faster decision-making. The master branch runs an experimental 'playground' fork, while the stable branch mirrors upstream Rust directly. Monorepo with compiler toolchain at compiler/rustc, standard library at library/std and library/sysroot, and 25+ build tools under src/tools (clippy, rustfmt, miri, rustdoc, etc.). Python x.py orchestrates the bootstrapping pipeline; see .github/workflows/ci.yml for CI stages. Language-agnostic: 98K Rust, but also HTML docs, C interop, shell scripts, TypeScript for web tooling.

Systems programmers, language enthusiasts, and contributors who want Rust's memory safety but prefer community governance over the Rust Foundation's RFC process. Also appeals to developers exploring language implementation via a well-documented compiler codebase with 98K+ lines of Rust already present.

Actively developed with sophisticated CI/CD (see .github/workflows/ci.yml, dependencies.yml) and comprehensive testing infrastructure (compiletest, miri, clippy). The codebase is mature—it's a fork of a production-ready compiler—but CrabLang itself is relatively young as an independent fork. Master branch explicitly warns it's 'not guaranteed to be up to date with upstream'; stable branch is recommended for actual toolchain use.

Significant risk: master branch explicitly disclaims parity with upstream ('not guaranteed to be up to date'). Upstream Rust changes would need manual porting. The monorepo's 25+ workspace members create complex dependency graphs (see Cargo.toml). Single-maintainer or small-team risk is likely given the community fork model. LLVM bootstrap and compiler-builtins (profile.release.package) add hard-to-debug build constraints.

No specific commits visible, but the repo maintains active CI (ci.yml runs on pushes/PRs), dependency scanning (dependencies.yml), and manages LLVM/stage0 bootstrap complexity. The master→stable branch split suggests ongoing maintenance of upstream synchronization on stable while experimental features bake on master.

git clone https://github.com/crablang/crab.git
cd crab
# Install Python 3, git, C compiler, curl, pkg-config (Linux)
./x.py build  # Bootstraps compiler using x.py Python orchestrator
./x.py test   # Runs compiletest suite

See ./x.py --help for subcommands; also try ./x (shell wrapper) if Python3 unavailable.

Daily commands:

./x.py build --stage 2              # Full compiler + stdlib (slow, ~1hr+)
./x.py build --stage 1 --keep-stage 0  # Faster incremental
./x.py test compiler/rustc_ast    # Test specific crate
./x.py doc                         # Generate docs

Bootstrapping is required; you cannot cargo build directly in compiler/rustc.

• compiler/rustc/src/main.rs — Entry point for the Crab compiler; every contributor must understand how compilation begins and how arguments are processed.
• compiler/rustc_ast/src/lib.rs — Core AST definitions that define the syntax tree structure used throughout the entire compiler pipeline.
• compiler/rustc_ast_lowering/src/lib.rs — Transforms high-level AST into HIR (High-level IR); critical abstraction layer between parsing and type checking.
• Cargo.toml — Workspace configuration defining all compiler and library crates; essential for understanding the build structure.
• CONTRIBUTING.md — Outlines contribution guidelines, coding conventions, and development workflow specific to this fork.
• compiler/rustc_ast/src/ast.rs — Detailed AST node definitions; foundational reference for understanding syntax representation.
• README.md — Project overview and quick-start guide; clarifies this is a community fork with a playground branch focus.

• rustc_ast (AST definitions) (Rust enums, structs, derive macros) — Defines all syntax nodes, tokens, and attributes. Source of truth for language grammar.

Add a new AST node type

1. Define the new node struct in the appropriate enum section (compiler/rustc_ast/src/ast.rs)
2. Add token/keyword definition if needed (compiler/rustc_ast/src/token.rs)
3. Implement lowering logic to HIR equivalent (compiler/rustc_ast_lowering/src/lib.rs)
4. Add validation rules in AST passes (compiler/rustc_ast_passes/src/ast_validation.rs)
5. Implement pretty-printing for diagnostics (compiler/rustc_ast_pretty/src/pprust/mod.rs)

Add a new compiler pass or validation

1. Create new visitor/pass module in rustc_ast_passes (compiler/rustc_ast_passes/src/lib.rs)
2. Implement validation logic using AST visitor pattern (compiler/rustc_ast_passes/src/ast_validation.rs)
3. Add error definitions if needed (compiler/rustc_ast_passes/src/errors.rs)
4. Register pass in orchestration code (compiler/rustc_ast_passes/src/lib.rs)

Add a new lowering rule for complex expressions

1. Add pattern matching case for the AST variant (compiler/rustc_ast_lowering/src/expr.rs)
2. Generate appropriate HIR nodes using builder methods (compiler/rustc_ast_lowering/src/lib.rs)
3. Handle lifetime collection if applicable (compiler/rustc_ast_lowering/src/lifetime_collector.rs)
4. Add error handling for invalid constructs (compiler/rustc_ast_lowering/src/errors.rs)

• Rust (self-hosted compiler) — The Crab fork is based on the original language compiler; using the language itself demonstrates its capabilities and enables tight integration.
• Multi-crate workspace (Cargo) — Modular separation of concerns (parsing, lowering, validation, pretty-printing) allows independent testing and reuse of compiler phases.
• Arena allocation (rustc_arena) — Improves performance and memory locality for compiler data structures during phase execution.
• Visitor pattern for AST traversal — Standard idiom for tree processing; enables clean separation of logic across different compilation phases.

• Multi-phase lowering (AST → HIR → further passes)

  • Why: Allows incremental validation and clearer separation of concerns; easier to debug and extend each phase independently.
  • Consequence: Multiple tree transformations increase memory usage and compile time; requires careful bookkeeping of spans and IDs.

• Feature gating as a dedicated AST pass

  • Why: Centralizes stability policy enforcement and allows feature toggles without pervasive conditional logic.
  • Consequence: Requires all features to go through explicit gate checks; less convenient for rapid prototyping but maintains strict stability boundaries.

• Fork maintained as community project with master = playground, stable = upstream mirror

  • Why: Allows experimentation on master without breaking upstream synchronization; users can choose stability or cutting-edge.
  • Consequence: Master branch is unstable; users following quick-start will get experimental features; requires clear communication.

• Not a production-grade language fork—the master branch is a playground for community experimentation.
• Does not aim to diverge permanently from upstream; the stable branch mirrors the original project.
• Not currently cross-platform; installation script explicitly states 'currently Unix only'.
• Does not include complete runtime or standard library; focuses on compiler and core language semantics.
• No real-time compilation or incremental builds at the compiler level (uses Cargo for incremental dependencies).
• Does not handle authentication, distribution, or package management—relies on Cargo ecosystem.

1. x.py must be run from repo root; paths are hardcoded relative to it. 2) Bootstrap requires a working 'stage 0' compiler (downloaded automatically, see build.rs in compiler/rustc); network access during first build. 3) LLVM may compile from source if pre-built unavailable; adds 30min–2hr. 4) Cargo.lock is committed; diverging versions break CI reproducibility. 5) .git-blame-ignore-revs exists; some commits are mechanically large (reformats); git blame may skip them. 6) master vs. stable branch split: master is experimental, stable mirrors upstream—pull requests should clarify target. 7) compiler/rustc_codegen_cranelift and rustc_codegen_gcc are excluded from workspace but may still be referenced in docs.

• LLVM IR (Intermediate Representation) — CrabLang compiles Rust→LLVM IR→native code; understanding IR is essential for optimizations, debugging codegen bugs, and understanding why two semantically equivalent programs compile to different machine code
• Borrow Checker & Lifetime Elision — Core to Rust's memory safety; CrabLang enforces this at compile time via borrowck phase (usually in compiler/rustc_borrowck), critical for understanding why code compiles or fails
• Two-Stage Bootstrap — x.py uses stage 0 (downloaded compiler) to build stage 1 (fresh compiler), then stage 1 to build stage 2 (final stdlib). Understanding this avoids false 'LLVM version mismatch' errors and explains CI complexity
• AST (Abstract Syntax Tree) & Lowering to HIR — compiler/rustc_ast defines the grammar post-parsing; HIR is a desugared form used for type-checking. Changes to syntax (keywords, operators) require updates in both; critical for language extensions
• Monomorphization — Generic code (T: AsRef<str>) is compiled separately for each concrete type; CrabLang's codegen does this at rustc_monomorphize stage. Understanding this explains why generic-heavy code bloats binary size
• Proc Macros & Derive — Compiler plugins (used in src/tools/clippy and stdlib macros); they execute compile-time code to transform AST. Risk: macros can obscure errors and cause circular dependencies in workspace
• UI Testing (Compiletest) — CrabLang's test harness (src/tools/compiletest) captures exact compiler error messages and compares diffs; crucial for ensuring error messages don't regress. .stderr/.stdout files are the ground truth

• rust-lang/rust — Upstream project; CrabLang stable branch auto-mirrors it, master branch diverges with experimental features
• rust-lang/rfcs — Upstream RFC process; CrabLang's governance difference is a key selling point vs. this bureaucratic alternative
• LLVM/llvm-project — Compiler backend; CrabLang's codegen targets LLVM IR; mismatches in LLVM version can cause silent bugs
• rust-lang/clippy — Linting plugin ecosystem; CrabLang bundles clippy (src/tools/clippy) as part of the toolchain

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 CI workflow for rustdoc-gui-test tool

The repo has a rustdoc-gui-test tool in src/tools/rustdoc-gui-test (listed in Cargo.toml workspace members) but no dedicated GitHub Actions workflow validates it. Given the .github/workflows structure already has ci.yml and dependencies.yml, a new workflow should test GUI rendering changes across the documentation toolchain to prevent regressions in rustdoc output.

• [ ] Create .github/workflows/rustdoc-gui-test.yml workflow file
• [ ] Add steps to build and run src/tools/rustdoc-gui-test against compiler/rustc changes
• [ ] Include matrix testing for different rustdoc theme variants (reference LICENSES/OFL-1.1.txt for theme assets)
• [ ] Integrate results into existing ci.yml status checks

Complete missing ISSUE_TEMPLATE diagnostics configuration

The .github/ISSUE_TEMPLATE/ directory has both diagnostics.yaml and diagnostics.md template files, but diagnostics.yaml appears incomplete or not fully integrated. This causes confusion for contributors reporting diagnostic/error message issues. CrabLang inherits complex diagnostic systems from rustc that need proper issue triaging.

• [ ] Review and complete .github/ISSUE_TEMPLATE/diagnostics.yaml with required fields matching config.yml structure
• [ ] Add specific prompts for error code (E####), backtrace, and diagnostic output fields
• [ ] Sync structure with existing ice.yaml and regression.md patterns
• [ ] Test issue creation via GitHub UI to verify template renders correctly

Add integration tests for tools in src/tools/ workspace packages

The Cargo.toml lists 20+ tools (clippy, rustfmt, miri, rustdoc, rls, etc.) but there's no dedicated integration test suite validating that changes to compiler/rustc remain compatible with these tools. Given the large workspace and tool interdependencies, regressions go undetected until end-users report them.

• [ ] Create tests/tools-integration/ directory with test harness
• [ ] Add focused tests validating clippy, rustfmt, and rustdoc against sample Crab code
• [ ] Reference src/tools/compiletest infrastructure for test execution patterns
• [ ] Add new GitHub Actions step in ci.yml to run tools-integration tests on compiler changes

• Add missing doctests to compiler/rustc_abi/src/layout.rs for public ABI layout functions (e.g., size_align_of); many public fns lack usage examples
• Write a simple clippy lint rule (src/tools/clippy/clippy_lints/src) that warns when using unsafe {} without a safety comment, checking against SAFETY: pattern in comments
• Expand compiler/rustc_ast/README.md with examples showing how to add a new token type (e.g., Crab-specific keyword) and wire it through the lexer→parser→AST pipeline

This is a large compiler infrastructure project (CrabLang fork) with a complex multi-crate workspace. The primary security concerns are related to dependency management at scale, supply chain risks from numerous integrated tools, and build configuration complexity. No critical hardcoded secrets, SQL injection risks, or XSS vulnerabilities were identified in the provided file structure. The project appears to follow good practices with proper licensing (Apache 2.0 and MIT), contributor guidelines, and issue templates. Main recommendations focus on dependency auditing, path configuration hardening, and submodule integrity verification.

• Medium · Workspace Dependencies Management Complexity — Cargo.toml (workspace members). The Cargo workspace contains 50+ member crates with interdependencies. This large attack surface requires careful dependency management. The workspace includes several third-party tools (clippy, miri, rustfmt, rls) that may introduce supply chain risks if their dependencies are not regularly audited. Fix: Implement regular dependency audits using 'cargo audit'. Consider using cargo-deny for policy enforcement. Maintain a Software Bill of Materials (SBOM) and review transitive dependencies quarterly.
• Medium · Excluded Build Directories Not Clearly Isolated — Cargo.toml (exclude section). The workspace excludes several directories (build, obj, src/bootstrap) from workspace members. The comment mentions hardcoded CI path '/checkout/obj', suggesting potential issues with path handling across different environments. This could lead to path traversal or build artifact confusion. Fix: Use environment variables for build paths instead of hardcoding. Document the rationale for each exclusion. Ensure build artifacts are always placed in designated directories with proper isolation.
• Low · Git Blame Ignore Configuration Present — .git-blame-ignore-revs. The presence of .git-blame-ignore-revs suggests large refactoring commits. While not a security vulnerability per se, this can obscure attribution of code changes in security reviews. Fix: Ensure all refactoring commits are properly documented. Maintain clear commit history for security-critical code sections. Consider additional code review processes for security-sensitive modules.
• Low · External Submodules Dependency — .gitmodules. The .gitmodules file indicates external git submodules are used (likely for stdarch and other components). Submodules can introduce version management complexity and potential supply chain risks if upstream repositories are compromised. Fix: Regularly audit submodule sources. Consider pinning to specific commits rather than branches. Implement verification of submodule integrity in CI/CD pipeline.

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.