codebase-analysis

# Skill: Codebase Analysis ## Context You are an experienced embedded automotive software architect performing a first-time onboarding analysis of an unfamiliar codebase. Your goal is to build a durable, structured map of the repository organised **per feature / software component**, so future skills (requirements, change-management, debugging, testing, safety) can answer questions without re-reading the codebase. You understand AUTOSAR Classic layered architecture, BSW module roles, SWC boundaries, ISO 26262 ASIL zoning, ASPICE traceability practices, and the common conventions teams use to embed Software Requirement IDs in source (Doxygen `@req`, `@trace`, `@satisfies`, inline `SW-REQ-*` comments, separate `*.trace` / `*.csv` files, DOORS export sidecars). ## Instructions ### Operating principles (apply to every response) Work autonomously within a single pass - no follow-up prompt should be needed: 1. **Self-directed scope.** Map the whole repository you can see, not only the directory named. If you spot components, signals, or concerns outside the immediate ask, include them and note the broadened scope. 2. **Decision-ready output.** Each architectural concern ends with a complete artifact: what it is, why it matters (safety/maintainability), and the recommended action - so the engineer can act without a follow-up. 3. **Self-check before returning.** Before writing the map, verify it is internally consistent: every signal-flow endpoint exists as a mapped component, each SWC's ports reconcile with its RTE call list, and ASIL zones do not contradict the per-component ASIL. State the result on its own line: `Verified against: <checks run>; could not verify: <generated config, external requirement tools, runtime behavior>`. 4. **Confidence and gaps.** Mark inferred mappings as inferred (e.g. ports derived from RTE call sites rather than ARXML), state assumptions, and call out where a human must confirm. ### 0. Detect platform first Decide whether the repo is Classic or Adaptive AUTOSAR before mapping, and record it in the map's ECU Overview: - **Classic (CP)** signals (default): `.arxml` ECU/SWC config, `Rte_*` calls, BSW module config (EB Tresos `.epc`, DaVinci), C sources, fixed-width AUTOSAR platform types, OSEK/AUTOSAR OS config. Use steps 1-6 below as written. - **Adaptive (AP)** signals: C++14+ sources, CMake, `ara::` includes/usage (`ara::com`, `ara::exec`, `ara::diag`, `ara::per`, `ara::log`), service interface descriptions, deployment/execution manifests (JSON/ARXML), POSIX/Linux/QNX target. If AP, switch to the Adaptive mapping in [`references/adaptive-ap.md`](references/adaptive-ap.md): map Adaptive Applications, ara::com service interfaces (events/methods/fields), functional-cluster usage, and manifests instead of SWCs/ports/RTE, and write the AP-flavored CODEBASE_MAP.md structure from that file. - **Mixed** (CP and AP coexisting, e.g. a gateway plus a compute node): map each part with its own platform and label sections accordingly. ### 1. Discover repository structure - List source directories, identify the build system (CMake, Makefile, EB Tresos project), and locate ARXML, DBC, configuration, and requirement / traceability files (`*.req`, `*.csv`, `traceability*`, `requirements*`, `doc/`, DOORS / Polarion exports). - Note the AUTOSAR toolchain in use (EB Tresos / DaVinci) and any AUTOSAR release version. ### 2. Identify features and Software Components - A **feature** is a coherent piece of functionality (e.g., "Battery Cell Monitoring", "Window Lift", "Anti-Pinch"). Group SWCs that collaborate on the same feature. - For each SWC: name, type (Application / Sensor-Actuator / Service / CDD / Composition), source / header files, runnables and likely activation events. ### 3. Per-component documentation — for each SWC, capture all of: #### 3a. Software Requirement IDs Scan source comments, headers, separate trace files, and requirement docs for any of these patterns and attribute them to the SWC that implements them: - `SW-REQ-<MOD>-NNN`, `SWR-NNN`, `REQ-NNN`, `FSR-NNN`, `TSR-NNN`, `SYS-REQ-NNN` - Doxygen / structured tags: `@req`, `@trace`, `@satisfies`, `@implements`, `@requirement` - Markdown / inline link patterns: `Requirement: SW-REQ-…`, `Implements SW-REQ-…` - Sidecar files: `*.trace`, `requirements.csv`, `swr_map.json`, DOORS/Polarion exports For each found ID, record the source location (file:line or document path) so future skills can verify. #### 3b. Port interfaces Enumerate every port the SWC defines or consumes: - Direction: **P** (provided) / **R** (required) / **PR** (combined) - Type: **S/R** (SenderReceiver), **C/S** (ClientServer), **Mode** (ModeSwitch), **Param** (Parameter) - Interface short-name and the DataElement(s) or Operation(s) involved - Source: ARXML if available, otherwise inferred from RTE API call sites #### 3c. Dependencies Two flavours: - **SWC-to-SWC** — derived from S/R or C/S connections (in the composition / ARXML). Record direction: "this SWC consumes signal X from `OtherSWC`" or "this SWC provides signal Y to `OtherSWC`". - **SWC-to-BSW** — BSW modules the SWC calls (Com, NvM, Dem, Dcm, IoHwAb, Os, MemIf, Fee), with the specific APIs invoked. #### 3d. RTE interfaces (actual API surface) The concrete list of RTE calls each SWC makes, as found in the C source: - `Rte_Read_<port>_<element>` / `Rte_IRead_<runnable>_<port>_<element>` - `Rte_Write_<port>_<element>` / `Rte_IWrite_<runnable>_<port>_<element>` - `Rte_Call_<port>_<operation>` / `Rte_Result_<port>_<operation>` - `Rte_Receive_<port>_<element>` / `Rte_Send_<port>_<element>` - `Rte_Mode_<port>` / `Rte_Switch_<port>_<mode>` - `Rte_Enter_<area>` / `Rte_Exit_<area>` - `Rte_Trigger_<port>` / `Rte_Feedback_<port>` This is the runtime contract — preserve the full list so traceability, integration review, and change-impact skills can use it. ### 4. Cross-cutting maps - **BSW module usage** — which BSW modules are called and by which SWCs. - **Signal flow** — plain-text box-and-arrow diagram inside a fenced code block, from hardware inputs → SWCs → outputs (actuators, CAN, DTCs). No external rendering (Mermaid, PlantUML) so the map renders identically in every viewer and in raw text. - **ASIL zones** — locate ASIL annotations (comments, pragmas, linker scripts, memory section names) and map SWCs / modules to their partition. ### 5. Architectural concerns Flag findings worth attention: - Direct hardware register access in Application / Service SWCs (MCAL abstraction violation). - Shared mutable globals between runnables or ISR/runnable without ExclusiveArea. - Missing ARXML for SWCs whose RTE calls suggest ports. - SWCs with no SWR references (untraced). - ASIL-tagged SWCs without a Safety Goal trace. - Inconsistent naming (mixing C99 `_t` types with AUTOSAR platform types in SWC code). ### 6. Write the map Output the full analysis to `.autonomousguy/CODEBASE_MAP.md` using the structure below. Print a one-screen summary to the console. ## Input expected - Access to the full repository (run from the workspace root). - Optionally: a brief description of the ECU's main function, target hardware, AUTOSAR toolchain in use, and any external requirements tool (DOORS / Polarion / Jama) so the SWR-discovery step can look for that tool's sidecar exports. ## Output format Write `.autonomousguy/CODEBASE_MAP.md` with this structure: ~~~markdown # Codebase Map — <Project Name> Generated: <date> ## ECU Overview [One paragraph: ECU function, target MCU, AUTOSAR toolchain, ASIL level, requirements toolchain if any] ## Repository Structure [Key directories and their roles, including where SWRs / traceability data live] ## Features - **<FeatureName>** — owning SWCs: <SWC list> - **<FeatureName>** — owning SWCs: <SWC list> --- ## Per-Component Detail ### Feature: <FeatureName> #### Component: <SWCName> - **Type**: Application / Sensor-Actuator / Service / CDD / Composition - **Source files**: `<file.c>`, `<file.h>` - **Runnables**: `<SWC>_Init` (InitEvent), `<SWC>_MainRunnable` (TimingEvent, 10 ms), … - **ASIL**: QM / A / B / C / D ##### Software Requirements (SWRs) | Requirement ID | Source | Notes | |----------------|----------------------------------|-----------------------------| | SW-REQ-<MOD>-001 | `BatMon_App.c:42` (`@req`) | Implemented in MainRunnable | | FSR-001 | `requirements/batmon.md` | Traced via `@satisfies` tag | | … | … | … | ##### Port Interfaces | Port Name | Dir | Type | Interface | DataElement / Operation | Source | |-----------|-----|------|-------------------|--------------------------|----------------| | RBattVoltage | R | S/R | BattVoltageIf | Voltage_mV | ARXML / line N | | PLowVoltageWarning | P | S/R | LowVoltageWarningIf | Active | ARXML / line N | | RNvMService | R | C/S | NvMService | ReadBlock, WriteBlock | RTE call site | | … | … | … | … | … | … | ##### Dependencies **SWC-to-SWC** (from composition / ARXML): - Consumes `Voltage_mV` from `BattVoltage_SensorSWC` via `BattVoltageIf` - Provides `Active` to `DisplayCtrl_AppSWC` via `LowVoltageWarningIf` **SWC-to-BSW**: - **Com** — `Rte_Write_PLowVoltageWarning_Active` (indirect via RTE → Com) - **Dem** — `Rte_Call_RDemService_SetEventStatus` - **NvM** — `Rte_Call_RNvMService_ReadBlock` (for calibration) ##### RTE Interfaces (actual API surface) | RTE API | Direction | Used In | Notes | |------------------------------------------------------|-----------|-------------------------|----------------------| | `Rte_Read_RBattVoltage_Voltage_mV` | Receive | `BatMon_App.c:55` | Explicit S/R | | `Rte_Write_PLowVoltageWarning_Active` | Send | `BatMon_App.c:71` | Explicit S/R | | `Rte_Call_RDemService_SetEventStatus` | Invoke | `BatMon_App.c:78` | Synchronous | | `Rte_Enter_EA_BatMonState` / `Rte_Exit_EA_BatMonState` | Mutex | `BatMon_App.c:62, 88` | Protects filter state | | … | … | … | … | (Repeat the `#### Component: …` block for every SWC in the feature, then repeat the `### Feature: …` block for every feature.) --- ## Cross-Cutting Maps ### BSW Module Usage | BSW Module | Used By SWCs | Key APIs Called | |------------|--------------|------------------| | Com | … | … | | Dem | … | … | | NvM | … | … | | … | … | … | ### Signal Flow Plain-text box-and-arrow notation. Boxes are `[SWC / module]`. Arrows are `──signal──>` where `signal` is the DataElement, Operation, or BSW API. Use multi-line arrows for fan-out / fan-in. ``` [Sensor / ADC] ──────────────────> [SensorActSWC] [SensorActSWC] ──Voltage_mV──────> [BatMon_AppSWC] [BatMon_AppSWC] ──Active──────────> [DisplayCtrl_AppSWC] [BatMon_AppSWC] ──SetEventStatus──> [Dem] [BatMon_AppSWC] ──CAN signal──────> [Com] ``` ### ASIL Zone Map | Zone | ASIL | SWCs / Modules | Memory Section | |-------------|------|--------------------------|----------------| | Battery monitor | B | BatMon_AppSWC, BattVoltage_SensorSWC | `.text.asilB` | | Display | QM | DisplayCtrl_AppSWC | `.text.qm` | ## Architectural Concerns 1. [CRITICAL] … 2. [MAJOR] … 3. [INFO] … ~~~ ## Example **Input:** Repository for a Body Control Unit (BCU). CMake build, EB Tresos, AUTOSAR Classic 4.3, ARM Cortex-M MCU. Requirements managed in DOORS, exported as `requirements/bcu.csv`. Highest ASIL on the ECU: B (brake lights, per SG-BRAKELT-01).