ARForge v1.4.0 — Git-integrated model diffing for AUTOSAR Classic projects

#autosar #embedded #opensource #automotive

What is ARForge

ARForge is an open-source CLI tool for AUTOSAR Classic SWC design. Instead of a GUI tool with a license server, you describe your software components, interfaces, data types, and system composition in plain YAML. ARForge validates the model against 191 semantic rules and generates standards-compliant ARXML, PlantUML architecture diagrams, and C code skeletons — all from the command line, on any machine, with no vendor dependency.

The core idea is simple: your AUTOSAR model should live in version control like any other source artifact, with readable diffs, CI integration, and no license gating.

v1.4.0 ships the feature that completes that picture.

Model diff command

ARXML diffs have always been the same story: a wall of XML noise that tells you something changed but not what it means architecturally. Whether a port direction flipped, an interface was renamed, or an entire SWC was restructured — the raw XML diff is practically unreadable for review purposes.

ARForge now solves this with a dedicated diff command.

# Compare two project files directly
arforge diff old_project.yaml new_project.yaml --out diff.md

# Compare working tree against a Git reference
arforge diff project.yaml --base-git-ref origin/main --out diff.md

The output is a structured Markdown report summarizing every structural change across:

SWCs: added, removed, modified
Interfaces: Sender-Receiver, Client-Server, Mode-Switch changes
Ports: provides and requires port changes per SWC
Component prototypes: added or removed instances
Connectors: new or removed connections
Compositions and sub-compositions: structural changes A sample diff output section looks like this:

## SWC Changes

### Added
- `TemperatureSensor` (application)

### Modified
- `PlatformSWC`
  - Port added: `Pp_DiagnosticStatus` (provides, SR)
  - Runnable added: `Runnable_ReportDiagnostics` (TimingEvent 100ms)

## Interface Changes

### Added
- `If_DiagnosticStatus` (Sender-Receiver)

The Git integration is direct. Point the command at any branch, tag, or commit and ARForge extracts the baseline model from Git history automatically. No manual file extraction, no stashing, no scripting around it.

This output is designed to be attached to pull requests as a CI artifact, used in architecture review meetings, and committed alongside the model changes as a change log.

Validation profile examples and documentation

v1.3.0 introduced the validation extension system. v1.4.0 makes it practical to use by shipping:

Ready-to-use sample profiles covering common cases:

Naming convention enforcement (SWC prefix rules, port naming patterns)
Stricter project hygiene rules Custom rule documentation explaining how to write a rule from scratch: how to access model context, how to emit findings with correct severity, how to integrate with the existing registry.

The documentation reduces the need to read core implementation code to understand how to extend the tool. Writing a custom rule is now a documented, supported workflow.

Schema and consistency improvements

The JSON schema coverage for supported YAML constructs has been expanded and tightened. Constraints that previously allowed invalid structures to pass schema validation now catch them earlier, before the validation and export stages see them.

The consistency improvements ensure that anything the schema accepts, the parser handles, the validator checks, and the exporter generates correctly. Gaps between pipeline stages that could produce confusing errors are closed.

Developer experience improvements

Restructured examples directory

The examples/ directory is now organized into three clear sections:

examples/
├── minimal/     ← beginner-friendly starter project
├── features/    ← focused demonstrations of individual features
└── invalid/     ← validation test corpus showing what errors look like

If you're new to ARForge, start in minimal/. If you want to understand a specific feature, go to features/. If you're writing tests or exploring error cases, invalid/ is the reference.

Improved arforge init scaffold

The starter project generated by arforge init now reflects current recommended modeling patterns. First-time users get a starting point that actually represents how ARForge is meant to be used, not a legacy structure from an earlier design.

Test suite reorganization

Tests are now organized by domain: CLI, schema, validation, export, report, diff. The previous structure with large catch-all test files is replaced with focused domain-specific test modules. This makes it significantly easier to understand what is tested and where to add new tests.

The full pipeline

YAML model
    │
    ▼
arforge validate      ← 191 core rules + optional project profiles
    │
    ├──▶ arforge diff       ← structured Markdown architecture diff
    │                          direct Git integration
    │
    ├──▶ arforge report     ← Markdown architecture summary
    │                          for reviews, PRs, CI/CD artifacts
    │
    ├──▶ arforge export     ← schema-valid, checker-passing ARXML
    │                          monolithic or split
    │
    ├──▶ arforge diagram    ← PlantUML topology + per-SWC diagrams
    │                          renders in VS Code and GitHub markdown
    │
    └──▶ arforge generate   ← .c and .h skeletons per SWC
                               correct Rte_ signatures from model

One YAML source of truth. Everything downstream is generated, regeneratable, and version-controlled.

Getting started

git clone https://github.com/bzivkovic1986/arforge
cd arforge
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Initialize a new project
python -m arforge.cli init my-project

# Validate
python -m arforge.cli validate my-project/autosar.project.yaml

# Diff against main branch
python -m arforge.cli diff my-project/autosar.project.yaml --base-git-ref origin/main --out build/diff.md

# Generate architecture report
python -m arforge.cli report my-project/autosar.project.yaml --out build/report.md

# Export ARXML
python -m arforge.cli export my-project/autosar.project.yaml --out build/out

# Generate diagrams
python -m arforge.cli diagram my-project/autosar.project.yaml --out build/diagrams

# Generate C skeletons
python -m arforge.cli generate code my-project/autosar.project.yaml --lang c --out build/code