crucihil analyze

Synopsis

crucihil analyze --source <path> --component <name> --rig <toml> [options]

Requirements

crucihil analyze requires the analyze optional extra:

pip install 'crucihil[analyze]'

This installs tree-sitter, tree-sitter-c, and tree-sitter-cpp.

What it does

Real firmware components never reference DBC signal names directly. Instead, they go through shim layers:

AUTOSAR RTE:  Rte_Read_BC_BrakeDemandVal(...)
COM module:   Com_ReceiveSignal(COM_SIG_ENGINE_RPM, &val)
Custom HAL:   hal_can_read_engine_speed()

crucihil analyze bridges this gap using a three-step pipeline:

Parse — tree-sitter walks every .c, .cpp, .h, .hpp file in the source directory and collects all identifiers (functions, variables, macros, type names).
Corpus — DBC files from [rig.definitions] in the rig TOML (or from --dbc) are parsed with cantools. Every MessageName.SignalName pair becomes a corpus entry, tagged with its interface type (CAN, ETH, etc.).
Match — An AI (Claude, GPT-4o, or Gemini) receives the filtered identifier list and the full signal corpus. It returns JSON: which identifiers map to which signals, whether each is an input or output, and a confidence score.

The result is the signal interface contract of the component — which signals it reads (inputs) and writes (outputs) — without needing to manually trace every RTE wrapper.

Options

path

required

Path to the SWC source directory or a single .c/.cpp/.h file. All .c, .cpp, .cc, .cxx, .h, .hpp files under this path are included. Short form: -s.

string

required

Label for this component in the output (e.g. BrakeController, EngineManagement). Short form: -c.

path

Path to a rig TOML config. CruciHiL reads [rig.definitions] and auto-discovers DBC files. Interface type is inferred from the key name: can_dbc → CAN, eth_dbc → ETH. Can be combined with --dbc.

path

Path to a DBC file. Repeatable — pass multiple DBC files for multi-bus components. Interface type defaults to unknown unless inferred from key name in TOML. Example: --dbc defs/powertrain.dbc --dbc defs/chassis.dbc.

path

Path to a shim header directory or another SWC path to parse alongside the primary source. Repeatable. Use this to include RTE headers, COM module headers, or any other files where signal-related identifiers are defined. See Dependency resolution below.

string

AI provider override. One of anthropic, openai, gemini. If omitted, auto-detected from environment variables in this order: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY. Short form: -p.

string

default:"pretty"

Output format. pretty prints a human-readable summary. json prints the raw result as JSON.

API key setup

Set one of these environment variables before running:

export ANTHROPIC_API_KEY=sk-ant-...   # uses Claude
export OPENAI_API_KEY=sk-...          # uses GPT-4o
export GOOGLE_API_KEY=...             # uses Gemini

The provider is auto-detected from whichever key is present. If multiple keys are set, Anthropic takes priority, then OpenAI, then Google.

Example

crucihil analyze \
  --source swc/brake_controller \
  --component BrakeController \
  --rig rigs/bench.toml \
  --dep rte/ \
  --dep com/ \
  --output pretty

Example output

AI provider : Anthropic (claude-sonnet-4-6)
Key status  : found (ANTHROPIC_API_KEY)

  Component : BrakeController
  Files     : 7
  Corpus    : 26 signals
  Extracted : 87 identifiers

── Inputs (signals consumed by this SWC) ───────────────────
  BrakeDemand.Value      [ETH]  conf=0.95  via Rte_Read_BC_BrakeDemandVal
  EngineData.RPM         [CAN]  conf=0.90  via COM_SIG_ENGINE_RPM
  VehicleSpeed.Speed     [CAN]  conf=0.87  via Rte_Read_VS_SpeedVal

── Outputs (signals produced by this SWC) ──────────────────
  BrakeStatus.Active     [CAN]  conf=0.95  via Rte_Write_BC_BrakeActive
  BrakeStatus.Pressure   [CAN]  conf=0.95  via Rte_Write_BC_BrakePressure

  5 signal(s) matched  ·  5 high confidence · 0 medium · 0 low

JSON output

crucihil analyze \
  --source swc/brake_controller \
  --component BrakeController \
  --rig rigs/bench.toml \
  --output json

{
  "component": "BrakeController",
  "files_analyzed": 7,
  "identifiers_extracted": 87,
  "signal_corpus_size": 26,
  "inputs": [
    {
      "signal": "BrakeDemand.Value",
      "dbc": "/rigs/../defs/chassis.dbc",
      "interface": "ETH",
      "matched_identifier": "Rte_Read_BC_BrakeDemandVal",
      "confidence": 0.95,
      "review_required": false
    }
  ],
  "outputs": [
    {
      "signal": "BrakeStatus.Active",
      "dbc": "/rigs/../defs/powertrain.dbc",
      "interface": "CAN",
      "matched_identifier": "Rte_Write_BC_BrakeActive",
      "confidence": 0.95,
      "review_required": false
    }
  ],
  "unmatched_identifiers": ["BrakeControllerInit", "BrakePID_calc"],
  "confidence_summary": { "high": 5, "medium": 0, "low": 0 },
  "review_required_count": 0
}

Confidence scores

Every signal match comes with a confidence score:

Range	Label	Meaning	`review_required`
0.85 – 1.00	High	Clear match — use in tests	`false`
0.60 – 0.84	Medium	Plausible match — verify before using	`true`
Below 0.60	Omitted	Not included in output

Focus review on matches where review_required: true. These are signals where the AI found a plausible but not obvious connection between the shim identifier and the DBC signal name.

Dependency resolution

The --dep option is the most powerful knob for improving result quality. In many AUTOSAR projects, the SWC source file contains calls like Rte_Read_BC_BrakeDemandVal(...) but the actual identifier definition lives in rte/Rte_BrakeController.h. Without that header, the AI sees the call but not the type information that makes the semantic match clearer. Pass only the shim headers for the SWC you are analyzing:

# Good — only the shim headers for BrakeController
crucihil analyze \
  --source swc/brake_controller \
  --component BrakeController \
  --rig rigs/bench.toml \
  --dep rte/Rte_BrakeController.h \
  --dep com/Com_Signals_BrakeController.h

# Avoid — passing the entire RTE directory adds noise from other SWCs
crucihil analyze \
  --source swc/brake_controller \
  --component BrakeController \
  --rig rigs/bench.toml \
  --dep rte/                        # too broad

Passing the entire RTE directory as --dep includes identifiers from every SWC. This increases identifier count and can confuse the AI into making cross-component matches. Pass only headers that belong to the component you are analyzing.

Without an AI key

If no API key is found, crucihil analyze returns the extracted identifiers and corpus size for manual inspection:

No AI key found — set ANTHROPIC_API_KEY, OPENAI_API_KEY, or GOOGLE_API_KEY.

  Component : BrakeController
  Files     : 7
  Corpus    : 26 signals
  Extracted : 87 identifiers (signal matching skipped)

The JSON output includes identifiers_extracted (list) and signal_corpus_size so you can perform the matching manually or with a separate tool.

Tips for best results

Use the rig TOML instead of bare --dbc flags. The rig TOML’s [rig.definitions] section specifies interface type per key (can_dbc → CAN, eth_dbc → ETH). This gives the AI better context about which bus each signal lives on.

Analyze one SWC at a time. The tool is calibrated for a single component’s identifier space. Passing multiple SWCs in one --source call degrades precision because the AI context window fills with unrelated identifiers.

Use --output json for CI integration. The JSON output is stable and machine-readable. Pipe it to jq to extract only high-confidence matches: jq '.inputs[] | select(.review_required == false)'.

Review medium-confidence matches against the actual header. A medium confidence (0.60–0.84) match is the AI saying “these names are semantically related but I’m not certain.” Ten minutes with the relevant .h file usually confirms or refutes each one.

How to use the output

The JSON output from crucihil analyze can be fed directly into generate_test_suite as context_items:

# Using the MCP tool from Claude/Copilot
analyze_component(
    source_path="swc/brake_controller",
    component_name="BrakeController",
    rig_toml_path="rigs/bench.toml",
    dependencies=["rte/"],
)
# Then pass the resulting inputs/outputs to generate_test_suite
generate_test_suite(
    suite_name="brake_validation",
    description="Validate BrakeController signal interface",
    rig_toml_path="rigs/bench.toml",
    context_items=["BrakeDemand.Value", "BrakeStatus.Pressure", ...],
)

CLI Reference

Synopsis

Requirements

What it does

Options

API key setup

Example

Example output

JSON output

Confidence scores

Dependency resolution

Without an AI key

Tips for best results

How to use the output

See also

​Synopsis

​Requirements

​What it does

​Options

​API key setup

​Example

​Example output

​JSON output

​Confidence scores

​Dependency resolution

​Without an AI key

​Tips for best results

​How to use the output

​See also

Synopsis

Requirements

What it does

Options

API key setup

Example

Example output

JSON output

Confidence scores

Dependency resolution

Without an AI key

Tips for best results

How to use the output

See also