playbooks

home / skills / redisearch / redisearch / analyze-rust-ffi-crate-surface

analyze-rust-ffi-crate-surface skill

/.skills/analyze-rust-ffi-crate-surface

This skill analyzes Rust FFI crate surfaces to map C-visible symbols and their usage in the C codebase.

npx playbooks add skill redisearch/redisearch --skill analyze-rust-ffi-crate-surface

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
name: analyze-rust-ffi-crate-surface
description: Determine which parts of the C codebase use Rust-defined C symbols.
---

# Analyze Rust FFI Crate Surface

Compile a list of all C-visible symbols defined in a given Rust FFI crate or file (e.g. an `extern "C" fn` annotated with `#[unsafe(no_mangle)]` or a type definition).
Then determine which parts of the C codebase use these symbols.

## Arguments
- `<path>`: Path to the Rust crate or file.
- `<path 1> <path 2>`: Multiple Rust crates/files.

If the path doesn't start with `src/`, assume it to be in the `src/redisearch_rs/c_entrypoint` directory. E.g. `numeric_range_tree_ffi` becomes `src/redisearch_rs/numeric_range_tree_ffi`.
If the path points to a directory, review the documentation of all Rust files in that directory.

## Instructions

- Read the relevant Rust source files.
- Compile a list of all the FFI symbols defined they expose (e.g. `extern "C" fn` annotated with `#[unsafe(no_mangle)]` or type definitions).
  You can use the corresponding auto-generated header file in `src/redisearch_rs/headers`, if it helps.
- For each symbol, determine which modules in the C codebase use it:
  - For functions, look for calls to the function in the C codebase.
  - For types, check out if they are used as function arguments, field types, or in type casts.

Emit a report that lists, for each symbol, the following information:
- The symbol name.
- The module(s) in the C codebase that use it.
- The type(s) of the symbol (function, type, etc.).
- If it's only used in C/C++ unit tests (i.e. under `tests/)

## Auto-generated header files

Each `*_ffi` Rust crate has a corresponding auto-generated header file in `src/redisearch_rs/headers`, created by the `build.rs` script via `cbindgen`.
The auto-generated header file includes all the FFI symbols defined by the Rust crate, no matter the sub-module they are defined in.

Overview

This skill inspects a Rust FFI crate or source file and reports every C-visible symbol it defines, then maps those symbols to where they are used in the C codebase. It produces a concise, actionable report listing symbol names, types, consuming C modules, and whether usage appears only in tests. The output helps maintainers understand cross-language dependencies and safely refactor or remove FFI surface area.

How this skill works

The skill scans the specified Rust files or crate directory to collect all extern "C" functions, #[no_mangle] items, and C-ABI-visible type definitions. It cross-references the auto-generated header in src/redisearch_rs/headers when available, then searches the C source tree for calls, type usages, casts, and inclusion sites to identify consuming modules. The result is a per-symbol mapping that notes symbol kind, consumer modules, and if a symbol is only referenced under tests/.

When to use it

  • Before removing or renaming FFI functions or types in Rust to find dependent C code.
  • When auditing cross-language surface area for maintenance, security, or API cleanup.
  • During code review to verify new FFI symbols are actually consumed by C code.
  • To produce a migration plan when rewriting C consumers or Rust providers.
  • When documenting the public C interface of a Rust crate for module maintainers.

Best practices

  • Prefer consulting the auto-generated header in src/redisearch_rs/headers as a canonical symbol list.
  • Run the analysis across the whole C tree, including tests/, to avoid missing conditional or test-only usage.
  • Use exact symbol name matching and inspect includes to handle macros, inline wrappers, or casts.
  • Report consumers at the module level (file or directory) to keep findings actionable for maintainers.
  • Re-run the analysis after any change to build.rs or cbindgen configuration to keep the header and findings in sync.

Example use cases

  • List all C-visible symbols from numeric_range_tree_ffi and identify which C modules call them.
  • Audit an FFI crate before merging a refactor that renames an extern "C" function.
  • Identify Rust types used directly by C code to detect ABI coupling before upgrading the Rust crate.
  • Generate a cleanup plan showing symbols only used by tests so they can be deprioritized for compatibility guarantees.

FAQ

What path formats are supported?

You can pass a full path or a crate/file name. If the path does not start with src/, it is resolved under src/redisearch_rs/c_entrypoint (for example numeric_range_tree_ffi -> src/redisearch_rs/numeric_range_tree_ffi).

Does it rely on the auto-generated header?

It can use the auto-generated header in src/redisearch_rs/headers as a canonical list, but it also parses Rust sources directly so it works even if the header is missing or stale.