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/microsoft/windows-rs 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 all four use cases

• Last commit today
• 4 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

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

What it runs against: a local clone of microsoft/windows-rs — 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 microsoft/windows-rs | 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 master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/windows-rs(\\.git)?\\b" \\
  && ok "origin remote is microsoft/windows-rs" \\
  || miss "origin remote is not microsoft/windows-rs (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "crates/libs/bindgen/src/lib.rs" \\
  && ok "crates/libs/bindgen/src/lib.rs" \\
  || miss "missing critical file: crates/libs/bindgen/src/lib.rs"
test -f "crates/libs/bindgen/src/winmd/reader.rs" \\
  && ok "crates/libs/bindgen/src/winmd/reader.rs" \\
  || miss "missing critical file: crates/libs/bindgen/src/winmd/reader.rs"
test -f "crates/libs/bindgen/src/types/mod.rs" \\
  && ok "crates/libs/bindgen/src/types/mod.rs" \\
  || miss "missing critical file: crates/libs/bindgen/src/types/mod.rs"
test -f "crates/libs/bindgen/src/tokens/to_tokens.rs" \\
  && ok "crates/libs/bindgen/src/tokens/to_tokens.rs" \\
  || miss "missing critical file: crates/libs/bindgen/src/tokens/to_tokens.rs"
test -f "crates/libs/bindgen/src/config/mod.rs" \\
  && ok "crates/libs/bindgen/src/config/mod.rs" \\
  || miss "missing critical file: crates/libs/bindgen/src/config/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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/microsoft/windows-rs"
  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).

windows-rs is a code generator and runtime library that lets Rust developers call any Windows API (past, present, and future) by automatically generating bindings from Windows metadata files (.winmd). It provides two crates: windows-sys for raw C-style FFI bindings and windows for safer, idiomatic Rust wrappers around COM, WinRT, and C-style APIs—eliminating the need for manual bindings or unsafe ceremony. Monorepo using Cargo workspace with three tiers: (1) crates/libs/bindgen generates Rust code from .winmd metadata files via syn/quote code generation; (2) crates/libs/core, windows-implement, windows-interface provide runtime support for COM, WinRT, and safe wrappers; (3) crates/libs/windows and windows-sys are the published end-user crates. Supporting crates handle strings, numerics, registry, threading, linking, and error handling. Workflows in .github/workflows drive code generation and validation.

Rust developers building Windows desktop applications, system utilities, or libraries who need to interop with Windows APIs (Win32, WinRT, COM) without writing unsafe code or maintaining hand-written FFI bindings. Also for Windows platform maintainers and Rust ecosystem contributors extending language projection support.

Highly mature and production-ready. The workspace contains 13+ published crates with stable 0.62+ versions, comprehensive CI workflows (clippy, fmt, miri, cross-platform testing), and active development visible in workflow configuration. The monorepo structure with multiple release tracks (windows, windows-sys, windows-bindgen) suggests long-term maintenance and wide ecosystem adoption.

Low technical risk but moderate maintenance risk. The codebase depends heavily on Microsoft's Windows metadata files (crates/libs/bindgen/default/*.winmd) which are external dependencies; breaking metadata changes could require rapid updates. Single-maintainer concern is mitigated by Microsoft sponsorship, but the code-generation-heavy design means subtle bugs in the bindgen layer (crates/libs/bindgen/src/) could affect all downstream users globally.

Continuous bindings generation and version management: the gen.yml workflow regenerates bindings from Windows metadata, with active maintenance of MSRV (minimum supported Rust version) compatibility (.github/workflows/msrv.yml, msrv-windows.yml). The workspace uses dependabot for dependency updates. Recent focus appears to be cross-platform testing (cross.yml) and no_std support validation (no_std.yml).

git clone https://github.com/microsoft/windows-rs.git
cd windows-rs
cargo build --release
cargo test

Daily commands: Primary artifact is code generation (not a runtime service): cargo build compiles the bindgen crate; cargo test runs the full test suite. For actual Windows API usage: add windows = { version = "0.62", features = ["Win32_Foundation"] } to Cargo.toml and call generated bindings. The .github/workflows/test.yml shows the canonical test command.

• crates/libs/bindgen/src/lib.rs — Entry point for the code generator that transforms Windows metadata into Rust bindings—all contributors must understand the generation pipeline.
• crates/libs/bindgen/src/winmd/reader.rs — Parses .winmd metadata files describing Windows APIs; core to understanding how API definitions flow into code generation.
• crates/libs/bindgen/src/types/mod.rs — Defines all type representations (structs, interfaces, enums, delegates) that model Windows API constructs before code emission.
• crates/libs/bindgen/src/tokens/to_tokens.rs — Converts internal type models into Rust token streams for code generation; bridges semantic representation and output syntax.
• crates/libs/bindgen/src/config/mod.rs — Handles user-facing configuration (feature selection, filtering, naming conventions); critical for customizing the generation process.
• crates/libs/collections/src/lib.rs — High-level Rust-idiomatic wrapper around Windows Collections runtime; demonstrates the projection pattern applied to a concrete example.
• Cargo.toml — Workspace root defining all member crates, dependencies, and lints; governs build configuration across the entire project.

Add a new Windows API binding (e.g., Win32 function)

1. Add the API name to your manifest or feature selection in the bindgen configuration (typically via Cargo.toml feature flags or a TOML config file). (crates/libs/bindgen/src/config/mod.rs)
2. The metadata reader automatically loads the .winmd file containing the API definition. (crates/libs/bindgen/src/winmd/reader.rs)
3. Type modeling and filtering parse the metadata and build internal type representations. (crates/libs/bindgen/src/types/mod.rs)
4. The code generator converts the type model to Rust tokens, emitting pub extern 'system' fn declarations. (crates/libs/bindgen/src/tokens/to_tokens.rs)
5. Run cargo build (or the bindgen tool directly) to regenerate bindings; the new API appears in the generated module. (Cargo.toml)

Customize naming conventions or filtering for a specific API namespace

1. Edit the configuration rules (namespaces, regex patterns) to target the API family. (crates/libs/bindgen/src/config/mod.rs)
2. Apply naming transformations (case conversion, prefix/suffix rules) via the names submodule. (crates/libs/bindgen/src/config/names.rs)
3. Use the filter module to exclude or include specific types and methods. (crates/libs/bindgen/src/filter.rs)
4. Rebuild the bindings; type modeling respects the new rules. (crates/libs/bindgen/src/type_map.rs)

Create a high-level idiomatic wrapper (like Collections)

1. Create a new crate under crates/libs/ (e.g., crates/libs/my_projection). (Cargo.toml)
2. Import the raw Windows bindings (windows or windows-sys crate). (crates/libs/collections/Cargo.toml)
3. Implement trait adapters (Iterator, FromIterator, etc.) to map Windows COM interfaces to Rust idioms. (crates/libs/collections/src/iterable.rs)
4. Create safe wrapper types (e.g., struct Map<K, V>) that encapsulate raw pointers and COM calls. (crates/libs/collections/src/map.rs)

Add a new metadata source or extend type system (e.g., support a new .winmd file)

1. Place the new .winmd file in crates/libs/bindgen/default/ directory. (crates/libs/bindgen/default/Windows.Win32.winmd)
2. Update the metadata reader to load and parse the new file. (crates/libs/bindgen/src/winmd/mod.rs)
3. Extend the type system in types/mod.rs if new type variants (e.g., new interface patterns) are required. (crates/libs/bindgen/src/types/mod.rs)
4. Update the code generator to emit bindings for the new types. (crates/libs/bindgen/src/tokens/to_tokens.rs)

• proc-macro2 & quote crates — Provides safe, ergonomic token stream construction without string concatenation; ensures generated Rust code is syntactically valid.
• Binary .winmd metadata format (ECMA-335) — Windows uses this standard format to describe all public APIs; reading it directly allows single-source-of-truth generation without manual API definitions.
• Declarative feature selection (Cargo features) — Allows per-project customization of which APIs to include, reducing binary size and compile time by excluding unused APIs.
• COM (Component Object Model) patterns — Windows APIs heavily use COM interfaces (IUnknown,

The .winmd files in crates/libs/bindgen/default/ are not auto-updated—they require manual refresh from Microsoft sources, and breaking metadata changes will require code generator updates before bindings can be regenerated. The code generator uses syn 2.0 with default-features = false, so missing features may silently fail to parse some edge-case Rust syntax. Windows-raw-dylib and windows_slim_errors are non-standard cfg flags (defined in Cargo.toml) that may not propagate correctly to dependent crates; always check the workspace.lints config. MSRV is enforced (check msrv.yml for current version); the bindgen crate may use newer Rust features than windows/windows-sys, causing surprising breakage when upgrading.

• ECMA-335 Metadata Format — windows-rs parses .winmd (Windows metadata) files which are ECMA-335 compliant assemblies; understanding the format is essential for debugging index.rs type resolution and metadata queries
• COM (Component Object Model) Vtable Binding — The implements.rs module generates COM interface vtables and method thunks; knowing how COM dispatch works is critical for understanding how windows-rs wraps Win32 COM APIs safely
• WinRT (Windows Runtime) Projection — windows-rs auto-projects WinRT metadata to Rust; WinRT uses a different calling convention and reference-counting model than Win32, requiring specialized handling in the code generator and core library
• Proc-Macro Code Generation — The bindgen crate uses syn/quote to programmatically emit Rust code at compile time; this is the foundation of how windows-rs generates millions of lines of bindings without manual maintenance
• FFI (Foreign Function Interface) and windows_raw_dylib — windows-rs generates raw FFI declarations and uses the non-standard windows_raw_dylib cfg flag to inline DLL imports, reducing binary size and improving link-time behavior on Windows
• Metadata-Driven Code Generation — Unlike hand-written bindings, windows-rs regenerates all 10,000+ Windows APIs from a single source of truth (.winmd files); this approach eliminates binding drift but introduces metadata update as a critical dependency
• Safe Rust Wrappers Over Unsafe FFI — The windows crate provides zero-cost abstractions over windows-sys raw bindings using ownership rules, lifetimes, and RAII; understanding unsafe blocks in core library is essential for extending safe APIs

• microsoft/cppwinrt — Predecessor language projection for C++; windows-rs explicitly follows its design patterns and philosophy for safe API binding generation
• retep998/winapi-rs — Historical Rust Windows FFI crate that windows-sys/windows replaces; understanding its limitations motivated this project
• microsoft/win32metadata — Upstream source of truth for Windows API metadata; the .winmd files in this repo are derived from there
• microsoft/windows-samples-rs — Official samples and examples demonstrating real-world usage patterns for windows and windows-sys crates
• rust-lang/rust — Core language; windows-rs is deeply invested in MSRV compatibility and tracking Rust edition changes

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 tests for windows-bindgen metadata parsing

The bindgen crate (crates/libs/bindgen/src) contains complex metadata parsing logic across multiple table modules (type_def.rs, method_def.rs, type_ref.rs, etc.) but there are no visible unit tests in the file structure. Adding tests would catch regressions in Windows metadata parsing and improve code coverage for the core code generation pipeline.

• [ ] Create crates/libs/bindgen/tests/ directory for integration tests
• [ ] Add unit tests in crates/libs/bindgen/src/tables/mod.rs for table parsing logic
• [ ] Add integration tests for end-to-end metadata parsing using the default Windows.winmd files in crates/libs/bindgen/default/
• [ ] Test edge cases like nested types, generic parameters, and interface implementations
• [ ] Add tests to crates/libs/bindgen/src/filter.rs and crates/libs/bindgen/src/signature.rs for filtering and signature generation

Add CI workflow for testing cross-platform doc generation

There is a doc.yml workflow, but it likely only tests documentation on Linux. Given that windows-rs is specifically for Windows APIs, there should be a dedicated workflow ensuring docs build correctly with Windows-specific features enabled, and that cross-compilation scenarios work (.github/workflows/cross.yml exists but may need doc-specific coverage).

• [ ] Create .github/workflows/doc-windows.yml to build docs on Windows runners
• [ ] Test doc generation with cfg(windows) features enabled
• [ ] Verify that platform-specific examples in crates/samples/ are documented correctly
• [ ] Add checks for broken intra-doc links specific to Windows APIs
• [ ] Ensure README links to the feature search and documentation are not broken

Add unit tests for config module in windows-bindgen

The crates/libs/bindgen/src/config/ directory contains critical configuration parsing modules (cfg.rs, names.rs, value.rs, format.rs) that control code generation behavior, but there are no visible test files. These modules directly impact output quality and need comprehensive test coverage for different configuration scenarios.

• [ ] Create crates/libs/bindgen/src/config/tests.rs or split into separate test modules
• [ ] Add tests for crates/libs/bindgen/src/config/cfg.rs covering various cfg() attribute combinations
• [ ] Add tests for crates/libs/bindgen/src/config/names.rs testing name resolution and collisions
• [ ] Add tests for crates/libs/bindgen/src/config/value.rs for value type handling
• [ ] Add integration tests combining multiple config options to ensure they compose correctly

• Add unit tests for crates/libs/bindgen/src/config/value.rs—currently appears untested despite handling feature value parsing and validation critical for user-provided configurations
• Document the .winmd metadata file format and update workflow in crates/libs/bindgen/default/readme.md with step-by-step instructions for refreshing Windows metadata from official Microsoft sources
• Create a crate-level integration test in crates/tests/ that exercises the full code generation pipeline (parse .winmd → generate Rust → compile → basic API call) to catch regressions in the bindgen→core→windows chain

The microsoft/windows-rs codebase demonstrates good security practices overall. No critical vulnerabilities were identified. The project uses a monorepo structure with workspace dependencies, explicit feature control, and comprehensive CI/CD workflows. Minor improvements include: (1) documenting the rationale for custom cfg attributes, (2) considering stricter development-time optimizations, (3) explicitly defining MSRV in Cargo.toml, and (4) adding explicit cargo-audit integration. The absence of hardcoded secrets, injection vectors, or misconfigured infrastructure settings is noteworthy. Recommended actions are primarily defensive in nature to catch edge cases and improve maintainability rather than addressing active security gaps.

• Low · Overly Permissive Workspace Linting Configuration — Cargo.toml - workspace.lints.rust. The workspace lints configuration allows unexpected_cfgs with custom check-cfg values. While not a direct vulnerability, this could mask configuration mistakes if typos occur in cfg attributes throughout the codebase. Fix: Review cfg usage across the codebase and consider more restrictive linting rules. Document the rationale for custom cfg values like 'windows_raw_dylib' and 'windows_slim_errors'.
• Low · Development Profile Optimization — Cargo.toml - profile.dev.package. The workspace enables opt-level = 2 for all dev dependencies, which could mask certain runtime issues during development that would appear in release builds. Fix: Consider using opt-level = 1 or 0 for dev dependencies to catch runtime issues earlier. Reserve optimization for release builds.
• Low · No Explicit MSRV (Minimum Supported Rust Version) Documentation — Cargo.toml - missing rust-version field. While MSRV workflows exist (.github/workflows/msrv.yml, msrv-windows.yml), there is no explicit MSRV defined in the root Cargo.toml. This could lead to unexpected breakage for users on older Rust versions. Fix: Add a rust-version field to the root Cargo.toml specifying the minimum supported Rust version. Ensure all workspace members respect this version.
• Low · Default Features Disabled Across Dependencies — Cargo.toml - workspace.dependencies section. All workspace dependencies have default-features = false. While this provides flexibility, it increases the risk of accidentally omitting required features, particularly in transitive dependencies. Fix: Document which features are required for each dependency and ensure they are explicitly enabled where needed. Consider audit tooling to verify feature coverage.
• Low · No Dependency Audit Configuration — .github/dependabot.yml and lack of audit configuration. While dependabot.yml exists, there is no audit.toml or explicit cargo-audit configuration visible. This is a best practice for Rust projects to catch known vulnerabilities in dependencies. Fix: Add cargo-audit to the CI pipeline. Create a cargo-audit.toml configuration file and ensure it runs on all PRs and commits.

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.