misch 0.1.0__tar.gz

misch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff check
+      # Catch packaging breaks (bad metadata, missing files) before a release.
+      - run: uv build
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      # cppcheck (with its bundled misra.py addon) powers the end-to-end tests;
+      # without it they skip, so it must be present for real coverage here.
+      - name: Install cppcheck
+        run: sudo apt-get update && sudo apt-get install -y cppcheck
+      - name: Check cppcheck + misra addon are available
+        run: |
+          cppcheck --version
+          # Addon install paths vary by distro (Debian/Ubuntu use
+          # /usr/lib/<arch>/cppcheck/addons), so probe functionally: the
+          # addon must produce a misra finding on a known violation.
+          printf 'int f(int x){if(x>0){return 1;}return 0;}\n' > /tmp/misra_probe.c
+          cppcheck --enable=style --addon=misra /tmp/misra_probe.c 2>&1 \
+            | grep -q "misra-c2012"
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked
+      # Coverage is reported for visibility, not (yet) gated on a threshold.
+      - run: uv run pytest -q --cov=misch --cov-report=term

misch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+# Publishes to PyPI via trusted publishing (no API token: configure the
+# "pending publisher" for this repo/workflow on pypi.org first).
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Check tag matches project version
+        run: |
+          version=$(uv version --short)
+          test "v$version" = "${GITHUB_REF_NAME}" || {
+            echo "tag ${GITHUB_REF_NAME} != pyproject version $version"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

misch-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+
+# uv
+.uv/
+
+# Tooling caches
+.ruff_cache/
+.pytest_cache/
+
+# Harness artefacts (findings, generated compile DBs)
+build_analysis/
+*.misra.json
+
+# Bring-your-own rule texts must never be committed
+misra_c_2023_headlines_for_cppcheck.txt
+
+# Local work tracking, not part of the public tree
+TODO.md
+.coverage

misch-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-07
+
+First public release.
+
+### Added
+
+- `misch run`: analyse a C project via cppcheck + the `misra.py` addon, driven off a normalised `compile_commands.json`. Categorised rich-terminal report (rule table + summary by default; `-v`/`--verbose` adds the per-location listing) and deterministic JSON output; non-zero exit on findings. Interpolated paths and messages are escaped and emoji substitution is disabled, so a `:100:` line number is never rendered as an emoji.
+- Compile-DB sources: `existing`, `meson`, and `cmake` (paths normalised to absolute up front). Plain-Make projects can generate a DB with an interceptor (e.g. `bear -- make`) and use `existing`.
+- Scope control: `scope` / `exclude` globs with a hard failure on any unattributed file, so nothing is ever silently ignored.
+- Bring-your-own MISRA rule texts (`$MISRA_RULE_TEXTS` > `[rules].texts`); headlines and Mandatory/Required/Advisory categories parsed from them. No copyrighted material is bundled.
+- `misch init`: generate a commented `misra.toml`, with flags to pre-fill every section.
+- `misch baseline` and `misch run --baseline`: count-based ratchet keyed on a line-independent fingerprint; report all findings but fail only on new ones.
+- `misch deviations`: grammar-aware harvest of every `cppcheck-suppress*` form, justification enforcement, rule-id validation against the headlines, project suppressions-file parsing, and a terminal + Markdown deviation record. `--check-stale` cross-references an unsuppressed run to flag suppressions that hide nothing.
+- SARIF 2.1.0 output (`--format sarif`) for GitHub code scanning and IDE annotations, with MISRA category mapped to error/warning levels.
+- Coloured `--help` output via `rich-argparse` (auto-disables when stdout is not a TTY or `NO_COLOR` is set).
+- `misch --version`.
+- Release pipeline: `uv build` in CI, and a tag-triggered GitHub Actions workflow publishing to PyPI via trusted publishing.
+
+### Fixed
+
+- Findings at in-tree locations matching neither `scope` nor `exclude` are now a hard error (exit 2, offending files listed) instead of being silently dropped. The compile DB only lists translation units, so the scope-coverage gate never sees headers; previously a public-header directory left out of `scope` simply vanished from the audit. Findings at explicitly excluded paths and in system headers outside the tree are still dropped silently by design.
+- Error messages no longer lose TOML section names to rich markup: `[project].scope`, `[project].exclude`, and `[rules].texts` were being parsed as style tags and dropped from the scope-error and missing-rule-texts notices.
+- `misch run` now applies the project suppressions file (`[deviations].suppressions`) to the analysis via cppcheck `--suppressions-list`, so a project-level deviation actually silences the findings it names. Previously the file was only harvested into the deviation record by `misch deviations`; findings it covered still surfaced and failed the run. The suppressions file is dropped on the `--check-stale` pass (alongside inline `cppcheck-suppress` comments) so staleness detection still sees what each entry hides.

misch-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to misch
+
+`misch` is a small, focused tool: a config-driven MISRA C:2023 harness around cppcheck. Contributions are held to that bar: dependency-light, tested, and honest about what the analysis can and cannot prove.
+
+## Dev setup
+
+```sh
+uv sync                     # install the project + dev deps into .venv
+uv run misch --help
+uv run pytest -q            # unit tests (no cppcheck needed)
+uv run ruff check .         # lint
+```
+
+`cppcheck` (with its bundled `misra.py` addon) must be on `PATH` for the `run`/`baseline` commands and any end-to-end test.
+
+## Architecture in one paragraph
+
+`compile_commands.json` is the universal seam; a single internal `Finding` model backs every output. The pipeline is `resolve config → obtain + normalise compile DB → scope-check → cppcheck (XML) → Finding model → classify → render`. See [`docs/DESIGN.md`](docs/DESIGN.md) for the full picture. Keep renderers pure (model in, bytes out) so the terminal, JSON, baseline, and deviation views can never disagree.
+
+## Where things live
+
+- `src/misch/cli.py`: argument parsing and command handlers.
+- `config.py`: `misra.toml` loading and path/rule-texts resolution.
+- `db/`: compile-DB resolution, normalisation, and scope classification.
+- `engine/cppcheck.py`: the only place that shells out to cppcheck; parses XML into Findings.
+- `report/`: the `Finding` model, headlines parser, baseline, deviation harvester, and renderers.
+- `scaffold.py`: the `init` config template.
+
+## Adding an engine or a DB normaliser
+
+- **A new engine** implements the same contract as `engine/cppcheck.run`: take the config + compile DB, return `list[Finding]`. Nothing downstream should know which engine produced a finding.
+- **A DB normaliser** (e.g. a cross-toolchain flag translator) transforms the compile DB before analysis. Keep it optional and selected by config, so the common native case needs none.
+
+## Rules of the house
+
+- **No bundled MISRA material.** The rule-texts file is bring-your-own and gitignored; never commit it or paraphrase copyrighted rule text into the tree.
+- **Python ≥ 3.11**, standard library first. New runtime dependencies need a good reason.
+- **Determinism.** Sort output by `(rule, file, line)`; keep JSON key order stable. No non-deterministic tests.
+- **Be honest about coverage.** cppcheck checks a subset of MISRA C:2023; if a feature is best-effort (e.g. staleness), say so in the docstring and the docs rather than overclaim.
+- Run `ruff check .` and `pytest` before opening a PR. Add a test for every bug fix and every feature.
+
+## Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `doc:`, `test:`, `chore:`, `refactor:`). Explain _why_ in the body, not _what_ the diff already shows.

misch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron James Long
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

misch-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: misch
+Version: 0.1.0
+Summary: Config-driven MISRA C:2023 static-analysis harness for arbitrary C projects (cppcheck-backed, bring-your-own rule texts).
+Project-URL: Repository, https://github.com/aajll/misch
+Project-URL: Changelog, https://github.com/aajll/misch/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/aajll/misch/issues
+Author: Aaron James Long
+License-Expression: MIT
+License-File: LICENSE
+Keywords: c,cppcheck,embedded,misra,safety,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: rich-argparse>=1.5
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# misch
+
+[![CI](https://github.com/aajll/misch/actions/workflows/ci.yml/badge.svg)](https://github.com/aajll/misch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/misch)](https://pypi.org/project/misch/)
+[![Python](https://img.shields.io/pypi/pyversions/misch)](https://pypi.org/project/misch/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Point it at any C project and ratchet it toward MISRA C:2023.** `misch` (MISra-CHeck) is a config-driven static-analysis harness: it wraps [cppcheck](https://cppcheck.sourceforge.io/) and its `misra.py` addon, drives them off a real `compile_commands.json`, and turns per-project difference into a small `misra.toml` instead of a forked shell script.
+
+- **Bring-your-own rule texts:** ships no copyrighted MISRA material (see [`docs/rule-texts.md`](docs/rule-texts.md)).
+- **Baseline / ratchet:** adopt MISRA on an existing codebase without a day-one wall of findings; fail CI only on _new_ ones.
+- **Deviation records:** harvests every `cppcheck-suppress`, enforces a justification, and emits an audit-ready record.
+- **No silent scope creep:** every file is consciously analysed or excluded, or the run fails.
+
+> `misch` is a **guidance + ratchet** tool, not a compliance-certification tool: cppcheck's addon covers a subset of MISRA C:2023. The engine sits behind an interface so a certified analyser can slot in later. See [`docs/DESIGN.md`](docs/DESIGN.md).
+
+## Install
+
+Requires Python ≥ 3.11 and `cppcheck` (with its bundled `misra.py` addon) on `PATH`. Tested with cppcheck 2.21; any recent release with the `misra.py` addon should work.
+
+```sh
+uv tool install misch        # or: pipx install misch / pip install misch
+```
+
+From a checkout: `uv tool install .` (or `uv sync && uv run misch ...`).
+
+## Quick start
+
+```sh
+cd /path/to/your/c-project
+misch init                 # write a commented misra.toml (flags pre-fill it)
+misch run                  # analyse; categorised report; non-zero exit on findings
+misch baseline             # accept current findings as the baseline
+misch run --baseline       # from now on, fail only on NEW findings
+misch deviations           # audit every suppression + its justification
+```
+
+Bring your own rule texts (optional, for headlines + Mandatory/Required/Advisory):
+
+```sh
+export MISRA_RULE_TEXTS=/path/to/misra_c_2023_headlines_for_cppcheck.txt
+```
+
+A run against a project with findings looks like this (headline text comes from your own rule-texts file):
+
+```text
+──────────────────────────────── MISRA analysis ────────────────────────────────
+scope: 1 analysed  0 excluded  files with findings: 1
+
+Findings by rule
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Rule             ┃ Category ┃ Count ┃ Headline                               ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ misra-c2012-8.4  │ required │     2 │ Headline from your licensed MISRA copy │
+│ misra-c2012-17.7 │ required │     1 │ Headline from your licensed MISRA copy │
+│ misra-c2012-21.6 │ required │     1 │ Headline from your licensed MISRA copy │
+│ misra-c2012-15.5 │ advisory │     1 │ Headline from your licensed MISRA copy │
+│ misra-c2012-8.7  │ advisory │     1 │ Headline from your licensed MISRA copy │
+└──────────────────┴──────────┴───────┴────────────────────────────────────────┘
+
+Run with -v/--verbose for the per-location listing.
+
+6 MISRA finding(s): 4 required  2 advisory
+```
+
+## Commands
+
+| Command            | Purpose                                                                                                                                                         |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `misch init`       | Generate a commented `misra.toml`; flags (`--db`, `--scope`, `--exclude`, `--platform`, `--rule-texts`, …) pre-fill each section.                               |
+| `misch run`        | Analyse. Rule table + summary (add `-v` for per-location detail, or `--format json`/`--format sarif`). Exit 1 on findings; `--baseline` fails only on new ones. |
+| `misch baseline`   | Snapshot the current findings as the accepted baseline.                                                                                                         |
+| `misch deviations` | Harvest `cppcheck-suppress*`, enforce justifications, validate rule ids, emit a Markdown deviation record (`--format md`).                                      |
+
+Exit codes are CI-friendly and format-independent: `0` clean (or no new findings under `--baseline`), `1` findings (or unjustified/unknown deviations), `2` config, compile-DB, scope, or engine error.
+
+## Configuration
+
+`misch init` writes a documented `misra.toml`; the essentials:
+
+```toml
+[project]
+scope   = ["src/", "include/"]                 # analysed
+exclude = ["tests/", "subprojects/"]           # explicitly out of scope
+
+[db]
+source = "meson"                               # meson | cmake | existing
+# Plain-Make projects: generate a DB (e.g. `bear -- make`) and use "existing".
+
+[platform]
+preset = "unix64"                              # cppcheck built-in, or [platform].xml
+
+[rules]
+texts = "${MISRA_RULE_TEXTS}"                  # bring-your-own; optional
+```
+
+## How it works
+
+`compile_commands.json` is the universal seam: every build-system and toolchain concern collapses into "produce a normalised compile DB". A single internal Finding model backs every output (terminal, JSON, baseline diff, deviation record), so they can never disagree. Full architecture and rationale in [`docs/DESIGN.md`](docs/DESIGN.md).
+
+## Documentation
+
+- [`docs/DESIGN.md`](docs/DESIGN.md): architecture, the scope and deviation strategy.
+- [`docs/rule-texts.md`](docs/rule-texts.md): bringing your own MISRA headlines.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md): dev setup, tests, adding engines/normalisers.
+- [`CHANGELOG.md`](CHANGELOG.md): release notes.
+
+## License
+
+MIT (see [`LICENSE`](LICENSE)). `misch` contains and ships no MISRA material; rule texts are bring-your-own from your licensed copy.

misch-0.1.0/README.md

@@ -0,0 +1,110 @@
+# misch
+
+[![CI](https://github.com/aajll/misch/actions/workflows/ci.yml/badge.svg)](https://github.com/aajll/misch/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/misch)](https://pypi.org/project/misch/)
+[![Python](https://img.shields.io/pypi/pyversions/misch)](https://pypi.org/project/misch/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Point it at any C project and ratchet it toward MISRA C:2023.** `misch` (MISra-CHeck) is a config-driven static-analysis harness: it wraps [cppcheck](https://cppcheck.sourceforge.io/) and its `misra.py` addon, drives them off a real `compile_commands.json`, and turns per-project difference into a small `misra.toml` instead of a forked shell script.
+
+- **Bring-your-own rule texts:** ships no copyrighted MISRA material (see [`docs/rule-texts.md`](docs/rule-texts.md)).
+- **Baseline / ratchet:** adopt MISRA on an existing codebase without a day-one wall of findings; fail CI only on _new_ ones.
+- **Deviation records:** harvests every `cppcheck-suppress`, enforces a justification, and emits an audit-ready record.
+- **No silent scope creep:** every file is consciously analysed or excluded, or the run fails.
+
+> `misch` is a **guidance + ratchet** tool, not a compliance-certification tool: cppcheck's addon covers a subset of MISRA C:2023. The engine sits behind an interface so a certified analyser can slot in later. See [`docs/DESIGN.md`](docs/DESIGN.md).
+
+## Install
+
+Requires Python ≥ 3.11 and `cppcheck` (with its bundled `misra.py` addon) on `PATH`. Tested with cppcheck 2.21; any recent release with the `misra.py` addon should work.
+
+```sh
+uv tool install misch        # or: pipx install misch / pip install misch
+```
+
+From a checkout: `uv tool install .` (or `uv sync && uv run misch ...`).
+
+## Quick start
+
+```sh
+cd /path/to/your/c-project
+misch init                 # write a commented misra.toml (flags pre-fill it)
+misch run                  # analyse; categorised report; non-zero exit on findings
+misch baseline             # accept current findings as the baseline
+misch run --baseline       # from now on, fail only on NEW findings
+misch deviations           # audit every suppression + its justification
+```
+
+Bring your own rule texts (optional, for headlines + Mandatory/Required/Advisory):
+
+```sh
+export MISRA_RULE_TEXTS=/path/to/misra_c_2023_headlines_for_cppcheck.txt
+```
+
+A run against a project with findings looks like this (headline text comes from your own rule-texts file):
+
+```text
+──────────────────────────────── MISRA analysis ────────────────────────────────
+scope: 1 analysed  0 excluded  files with findings: 1
+
+Findings by rule
+┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Rule             ┃ Category ┃ Count ┃ Headline                               ┃
+┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ misra-c2012-8.4  │ required │     2 │ Headline from your licensed MISRA copy │
+│ misra-c2012-17.7 │ required │     1 │ Headline from your licensed MISRA copy │
+│ misra-c2012-21.6 │ required │     1 │ Headline from your licensed MISRA copy │
+│ misra-c2012-15.5 │ advisory │     1 │ Headline from your licensed MISRA copy │
+│ misra-c2012-8.7  │ advisory │     1 │ Headline from your licensed MISRA copy │
+└──────────────────┴──────────┴───────┴────────────────────────────────────────┘
+
+Run with -v/--verbose for the per-location listing.
+
+6 MISRA finding(s): 4 required  2 advisory
+```
+
+## Commands
+
+| Command            | Purpose                                                                                                                                                         |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `misch init`       | Generate a commented `misra.toml`; flags (`--db`, `--scope`, `--exclude`, `--platform`, `--rule-texts`, …) pre-fill each section.                               |
+| `misch run`        | Analyse. Rule table + summary (add `-v` for per-location detail, or `--format json`/`--format sarif`). Exit 1 on findings; `--baseline` fails only on new ones. |
+| `misch baseline`   | Snapshot the current findings as the accepted baseline.                                                                                                         |
+| `misch deviations` | Harvest `cppcheck-suppress*`, enforce justifications, validate rule ids, emit a Markdown deviation record (`--format md`).                                      |
+
+Exit codes are CI-friendly and format-independent: `0` clean (or no new findings under `--baseline`), `1` findings (or unjustified/unknown deviations), `2` config, compile-DB, scope, or engine error.
+
+## Configuration
+
+`misch init` writes a documented `misra.toml`; the essentials:
+
+```toml
+[project]
+scope   = ["src/", "include/"]                 # analysed
+exclude = ["tests/", "subprojects/"]           # explicitly out of scope
+
+[db]
+source = "meson"                               # meson | cmake | existing
+# Plain-Make projects: generate a DB (e.g. `bear -- make`) and use "existing".
+
+[platform]
+preset = "unix64"                              # cppcheck built-in, or [platform].xml
+
+[rules]
+texts = "${MISRA_RULE_TEXTS}"                  # bring-your-own; optional
+```
+
+## How it works
+
+`compile_commands.json` is the universal seam: every build-system and toolchain concern collapses into "produce a normalised compile DB". A single internal Finding model backs every output (terminal, JSON, baseline diff, deviation record), so they can never disagree. Full architecture and rationale in [`docs/DESIGN.md`](docs/DESIGN.md).
+
+## Documentation
+
+- [`docs/DESIGN.md`](docs/DESIGN.md): architecture, the scope and deviation strategy.
+- [`docs/rule-texts.md`](docs/rule-texts.md): bringing your own MISRA headlines.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md): dev setup, tests, adding engines/normalisers.
+- [`CHANGELOG.md`](CHANGELOG.md): release notes.
+
+## License
+
+MIT (see [`LICENSE`](LICENSE)). `misch` contains and ships no MISRA material; rule texts are bring-your-own from your licensed copy.

misch-0.1.0/docs/DESIGN.md

@@ -0,0 +1,115 @@
+# misch design
+
+A standalone, config-driven harness that runs MISRA C:2023 static analysis on **arbitrary C projects** and guides them toward the standard. It wraps [cppcheck](https://cppcheck.sourceforge.io/) and its `misra.py` addon, driven off a real `compile_commands.json` so the checker sees exactly the include paths and defines the compiler sees.
+
+It ships **no copyrighted MISRA material**. The rule-texts (headlines) file is bring-your-own; the harness supplies only the machinery.
+
+## Why this exists
+
+Firmware/controller projects each grew their own `misra_static_analysis.sh` (cppcheck + addon + platform + suppressions), and those scripts copy-pasted and diverged. Public primitive libraries can't bundle any MISRA rule material at all. This harness factors the shared machinery out once, keeps every copyrighted artifact out of the tree, and turns per-project difference into a small `misra.toml` instead of a forked script.
+
+## Core architecture
+
+Two ideas drive everything:
+
+1. **`compile_commands.json` is the universal seam.** All project-specific concerns (build system, cross toolchain, flag dialects) collapse into "produce a normalised compile DB." The harness core consumes a compile DB and nothing else, so "point it at any C project" is real.
+2. **One internal Finding model; outputs are pure renderers.** cppcheck is always run in XML mode and normalised into a single `Finding` model. The terminal view, JSON, the baseline diff, the scope-coverage report and the deviation record are all projections of that one model, so they can never disagree.
+
+### Pipeline
+
+```
+resolve config
+  → obtain compile DB (source: existing | meson | cmake)
+  → normalise (base; ti-c2000 plugin later)
+  → run cppcheck (platform + misra addon + suppressions), XML out
+  → parse → Finding model
+  → classify (category from BYO headlines)
+  → scope-coverage check (fail on unattributed files)
+  → baseline diff (optional)
+  → render (terminal default; json/md/sarif on request)
+  → exit code (findings → non-zero, or new-only under --baseline)
+```
+
+## Rule-texts (headlines): bring-your-own
+
+The cppcheck misra addon runs its checks regardless; the headlines file only makes output human-readable and carries each rule's category (Mandatory / Required / Advisory). We do **not** bundle it. Resolution precedence:
+
+```
+$MISRA_RULE_TEXTS  >  misra.toml [rules].texts
+```
+
+With neither set, analysis still runs but findings are tagged `category: unknown` and a one-line notice points at `docs/rule-texts.md`. Rule **classification** is parsed from this file too, so we never ship a second copyrighted table.
+
+## Configuration (`misra.toml`)
+
+Everything that differs between projects is data, not shell:
+
+```toml
+[project]
+scope   = ["components/", "src/"]                    # analysed
+exclude = ["vendor/", "subprojects/", "src/generated/", "tests/"]
+
+[db]
+source = "meson"        # meson | cmake | existing
+# Plain-Make projects: generate a DB (e.g. `bear -- make`) and use "existing".
+# path = "build/compile_commands.json"               # for source = "existing"
+
+[platform]
+preset = "unix64"       # cppcheck built-in, or a custom XML path
+# xml = "analysis/c2000_platform.xml"
+
+[toolchain]
+defines = []            # e.g. TI keyword neutralisation on cross targets
+
+[rules]
+texts = "${MISRA_RULE_TEXTS}"                         # BYO; env expands
+
+[report]
+outputs = ["terminal"]  # + {format="json", path="build_analysis/misra.json"}
+```
+
+## Scope: protecting non-audited content
+
+The failure mode is silent scope creep, so **exclusion is explicit and enumerated, never implicit**:
+
+- Central `scope`/`exclude` globs in `misra.toml`: one reviewable boundary, not scattered markers.
+- Each exclude glob applies at **both** levels from one key: skip the TU (`-i`) *and* drop findings whose location falls in the excluded path (findings can leak from an excluded header included by an in-scope source).
+- A **scope-coverage report** buckets every file in the compile DB into `{analysed, excluded-by-rule, unattributed}` and makes `unattributed` a **hard error**. A newly added `tests/` (or anything) must match an exclude rule or fail CI; nothing is implicitly ignored.
+- The compile DB only lists translation units, so the coverage check cannot see **headers**: they enter the analysis via inclusion and findings land at their locations. A finding at an in-tree location matching neither `scope` nor `exclude` is therefore also a **hard error** -- a public-header directory left out of `scope` must not silently vanish from the audit. Findings at explicitly excluded paths, and in system/toolchain headers outside the tree, are dropped silently by design. This gate fires only when something is actually found at the unclassified location; a clean forgotten header produces nothing to drop, so full header coverage would need include-graph extraction (possible future work).
+
+## Deviations: harvesting `cppcheck-suppress*`
+
+Every inline suppression is a MISRA deviation and must land in the deviation record with a rationale.
+
+- **Grammar-aware harvest** of in-scope sources: `cppcheck-suppress <id>`, bracketed `cppcheck-suppress[id1,id2]`, and `-suppress-begin/-end/-file/-macro`. Project standardises on the bracketed form.
+- **Justification required** via a structured tag; the run **fails** if any inline suppression lacks one:
+  ```c
+  /* cppcheck-suppress misra-c2012-11.4 ; @deviation MSGRAM base is a device-fixed literal */
+  ```
+- **Validate ids** against the real rule set (from the headlines file) to catch typos that silently suppress nothing.
+- **Staleness**: `--check-stale` runs the engine with inline suppression disabled, then flags any harvested `cppcheck-suppress` whose rule has no finding at its site. A dead deviation is an audit smell. (This cross-reference sidesteps cppcheck's `unmatchedSuppression`, which it does not reliably emit under `--project`.)
+- **Merge** inline + project-level `suppressions.txt` into one categorised, justified record (scope / advisory-deviation / false-positive / inline-pointer) → the deviation report.
+
+## Outputs
+
+- **Default: rich terminal** (rule table grouped by category, plus summary counts; `-v` adds the per-location listing). Interpolated data is escaped and emoji substitution is off so line numbers cannot be misread as emoji. No file unless asked.
+- **Opt-in file formats** via `--format`/`--output` or `[report].outputs`:
+  - `json`: canonical, stable key order; substrate for baseline + deviation record; `jq`/`grep`-friendly.
+  - `md`: PR summary and the audit/deviation doc.
+  - `sarif`: SARIF 2.1.0 for GitHub code scanning / IDE annotations.
+  - `junit`: optional CI panels (planned).
+- Deterministic sort `(rule, file, line)`; artifacts under the build dir, gitignored. Exit code is format-independent.
+
+## Honest scope
+
+cppcheck's addon covers a subset of MISRA C:2023 (many rules are undecidable without a certified analyser). This is a **guidance + ratchet** tool, not a compliance-certification tool, which matches the goal. The engine sits behind an interface so a commercial tool (Axivion / Parasoft / PC-lint) can slot in later behind the same config and report format.
+
+## Status
+
+The analysis pipeline, config scaffolding (`init`), baseline/ratchet, and the deviation harvester/record are all implemented and dogfooded on the `ucrc` primitive. Planned work (cross-target platform presets, toolchain normaliser plugins, JUnit output) is tracked in the issue tracker.
+
+## Non-goals
+
+- Not a certified compliance tool.
+- Does not bundle, reproduce, or derive MISRA rule text.
+- Does not require a specific build system (compile DB is the seam).

misch-0.1.0/docs/rule-texts.md

@@ -0,0 +1,48 @@
+# Bring-your-own MISRA rule texts (headlines)
+
+`misch` ships **no MISRA material**. The MISRA C:2023 guideline text is copyrighted by The MISRA Consortium and must not be redistributed, so the harness never bundles, reproduces, or derives it.
+
+## What the file is for
+
+cppcheck's `misra.py` addon runs its **checks** without any rule-texts file; it just reports rule numbers (`misra-c2012-11.4`). The rule-texts file adds two things the harness uses for display and classification only:
+
+- a short **headline** per rule, and
+- the guideline **category** (Mandatory / Required / Advisory).
+
+Without it, analysis still runs; findings are simply tagged `category: unknown`.
+
+## How to provide it
+
+Create the file from your own licensed copy of the MISRA C:2023 document, in the [cppcheck rule-texts format](https://cppcheck.sourceforge.io/misra.php), then point the harness at it by either exporting an environment variable:
+
+```sh
+export MISRA_RULE_TEXTS=/path/to/misra_c_2023_headlines_for_cppcheck.txt
+```
+
+or naming it in `misra.toml`:
+
+```toml
+[rules]
+texts = "${MISRA_RULE_TEXTS}"          # env-expanded
+# texts = "analysis/headlines.txt"     # or a path relative to the config
+```
+
+Resolution precedence is `$MISRA_RULE_TEXTS` → `[rules].texts`.
+
+## In CI
+
+Inject the file as a secret (or fetch it from a private, licensed location) and export `MISRA_RULE_TEXTS` before `misch run`. It must never be committed to a public repository; `.gitignore` already excludes the conventional filename.
+
+## Format the parser expects
+
+Tolerant and best-effort. Each rule block begins with a line like:
+
+```
+Appendix A Summary of guidelines
+Rule 11.4 Advisory
+A conversion should not be performed between a pointer to object and an integer type
+```
+
+or `Dir 4.9 Advisory` for directives. The category token (`Mandatory` / `Required` / `Advisory`) may sit on the head line or the following line. Anything the parser cannot read stays `category: unknown`, and never fails the run.
+
+The `Appendix A Summary of guidelines` first line matters: `misch` passes the same file to cppcheck's `misra.py` addon, whose own parser skips everything **until** a line containing `Appendix A` and `Summary of guidelines`. Without that heading the addon loads zero rules and tags every finding with a misleading `(rule-texts-file not found: ...)` note, even though `misch`'s table still shows headlines and categories (its parser is more tolerant). Files exported for cppcheck usually carry the heading already.