maishac 0.3.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- maishac-0.3.1/LICENSE +28 -0
- maishac-0.3.1/PKG-INFO +410 -0
- maishac-0.3.1/README.md +383 -0
- maishac-0.3.1/maishac/__init__.py +16 -0
- maishac-0.3.1/maishac/analyzers/__init__.py +60 -0
- maishac-0.3.1/maishac/analyzers/base.py +66 -0
- maishac-0.3.1/maishac/analyzers/clang_tidy.py +90 -0
- maishac-0.3.1/maishac/analyzers/cppcheck.py +136 -0
- maishac-0.3.1/maishac/analyzers/native.py +269 -0
- maishac-0.3.1/maishac/cli.py +317 -0
- maishac-0.3.1/maishac/engine/__init__.py +414 -0
- maishac-0.3.1/maishac/mcp_server.py +428 -0
- maishac-0.3.1/maishac/memory/__init__.py +466 -0
- maishac-0.3.1/maishac/model.py +157 -0
- maishac-0.3.1/maishac/patterns.py +481 -0
- maishac-0.3.1/maishac/report.py +660 -0
- maishac-0.3.1/maishac/rules/__init__.py +113 -0
- maishac-0.3.1/maishac/rules/barr_c_2018.json +26 -0
- maishac-0.3.1/maishac/rules/cert_c.json +36 -0
- maishac-0.3.1/maishac/rules/misra_c_2012.json +37 -0
- maishac-0.3.1/maishac.egg-info/PKG-INFO +410 -0
- maishac-0.3.1/maishac.egg-info/SOURCES.txt +35 -0
- maishac-0.3.1/maishac.egg-info/dependency_links.txt +1 -0
- maishac-0.3.1/maishac.egg-info/entry_points.txt +2 -0
- maishac-0.3.1/maishac.egg-info/requires.txt +4 -0
- maishac-0.3.1/maishac.egg-info/top_level.txt +1 -0
- maishac-0.3.1/pyproject.toml +44 -0
- maishac-0.3.1/setup.cfg +4 -0
- maishac-0.3.1/tests/test_benchmark_fixes.py +305 -0
- maishac-0.3.1/tests/test_check_snippet.py +38 -0
- maishac-0.3.1/tests/test_gep_grp.py +83 -0
- maishac-0.3.1/tests/test_misra_compliance.py +64 -0
- maishac-0.3.1/tests/test_patterns.py +55 -0
- maishac-0.3.1/tests/test_sarif_dialects.py +105 -0
- maishac-0.3.1/tests/test_sarif_import.py +167 -0
- maishac-0.3.1/tests/test_smoke.py +142 -0
- maishac-0.3.1/tests/test_verification_gate.py +133 -0
maishac-0.3.1/LICENSE
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kiran Sekar and Maisha contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
This license covers the Maisha software only. MISRA®, BARR-C and SEI CERT C
|
|
26
|
+
are the property of their respective owners; the bundled rule knowledge bases
|
|
27
|
+
contain original paraphrased summaries, not reproduced standard text. Maisha
|
|
28
|
+
output does not constitute a formal compliance certification.
|
maishac-0.3.1/PKG-INFO
ADDED
|
@@ -0,0 +1,410 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: maishac
|
|
3
|
+
Version: 0.3.1
|
|
4
|
+
Summary: Agent harness for MISRA C, BARR-C and CERT C compliance: persistent memory, engineered fix loops, and an MCP server usable from any agentic IDE.
|
|
5
|
+
Author: Maisha contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Kiransekar/maisha
|
|
8
|
+
Project-URL: Repository, https://github.com/Kiransekar/maisha
|
|
9
|
+
Project-URL: Issues, https://github.com/Kiransekar/maisha/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/Kiransekar/maisha/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: misra,cert-c,barr-c,static-analysis,mcp,agent,embedded
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: C
|
|
17
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
18
|
+
Classifier: Topic :: Software Development :: Embedded Systems
|
|
19
|
+
Classifier: Environment :: Console
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: mcp>=1.2.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
26
|
+
Dynamic: license-file
|
|
27
|
+
|
|
28
|
+
<p align="center"><img src="assets/banner.svg" alt="Maisha — MISRA, BARR-C and CERT C compliance harness" width="100%"></p>
|
|
29
|
+
|
|
30
|
+
# Maisha
|
|
31
|
+
|
|
32
|
+
[](https://github.com/Kiransekar/maisha/actions/workflows/ci.yml)
|
|
33
|
+
[](https://github.com/Kiransekar/maisha/releases/tag/v0.3.1)
|
|
34
|
+

|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
> ### Searching for an open-source alternative to Polyspace, Helix QAC or Coverity for MISRA C? **This is it.** Free, vendor-neutral, and driven from your IDE. → [`pipx install maishac`](#install)
|
|
38
|
+
|
|
39
|
+
**The open-source compliance-workflow layer for MISRA C:2012, BARR-C:2018 and CERT C — usable from any agentic IDE.**
|
|
40
|
+
|
|
41
|
+
Maisha is the free, vendor-neutral alternative to the paid compliance *workflow*
|
|
42
|
+
that tools like Polyspace, Helix QAC, Coverity and Parasoft now sell as agentic
|
|
43
|
+
toolkits: the fix loop, verification gate, deviation & audit-evidence workflow,
|
|
44
|
+
and author-time guidance — running on free engines (cppcheck + clang-tidy) **or**
|
|
45
|
+
layered on top of a qualified engine you already own (via SARIF). It is *not* a
|
|
46
|
+
qualified detection engine and does not pretend to be. → See
|
|
47
|
+
[**How Maisha compares**](COMPARISON.md).
|
|
48
|
+
|
|
49
|
+
> *Maisha* is Swahili for **"life."** Compliance standards like MISRA and CERT C
|
|
50
|
+
> exist because this is the software that flies planes, drives cars and runs
|
|
51
|
+
> medical devices — code where a defect costs lives, not uptime. The name is the
|
|
52
|
+
> goal the tool works toward. The CLI and package are `maishac` (*Maisha-for-C*).
|
|
53
|
+
|
|
54
|
+
> ⚠️ **Maisha is a workflow orchestrator and audit-trail layer, not a qualified/certified static-analysis tool.** Its findings do **not** by themselves satisfy tool-qualification requirements for DO-178C, ISO 26262 or IEC 62304, and running it is not a formal compliance certification. It is best used *upstream* of a qualified engine (see [Scope & Limitations](#scope--limitations)).
|
|
55
|
+
|
|
56
|
+
Maisha is not another linter. It is the *deterministic half* of an autonomous
|
|
57
|
+
compliance workflow. Your IDE's LLM (Claude Code, Cursor, Windsurf, Zed, anything
|
|
58
|
+
that speaks [MCP](https://modelcontextprotocol.io)) does the code edits; Maisha
|
|
59
|
+
does everything that must never hallucinate:
|
|
60
|
+
|
|
61
|
+
- **Scanning & evidence merging** — a zero-dependency native analyzer plus adapters
|
|
62
|
+
for `cppcheck` (with its MISRA addon) and `clang-tidy` (`cert-*` checks). Findings
|
|
63
|
+
from multiple analyzers that hit the same defect are fingerprint-merged into a
|
|
64
|
+
single finding with reinforcing evidence (`analyzer: native+cppcheck`).
|
|
65
|
+
- **Proactive authoring (write it compliant the first time)** — two author-time
|
|
66
|
+
surfaces, so an agent writes compliant code on the first pass instead of fixing
|
|
67
|
+
it on a later scan:
|
|
68
|
+
- `compliance_guidance` (CLI: `maishac guide "<topic>"`) — a compliant-pattern
|
|
69
|
+
library: *before* writing code for a concern (dynamic memory, string copy,
|
|
70
|
+
switch, recursion, integer overflow, …) it returns the idiom to **prefer**,
|
|
71
|
+
the anti-pattern to **avoid**, **why**, and the MISRA/CERT/BARR-C rules it
|
|
72
|
+
satisfies.
|
|
73
|
+
- `compliance_check_snippet` (CLI: `maishac check`) — lints a draft *in memory,
|
|
74
|
+
before it is written to a file*, returning violations, fix hints, and the
|
|
75
|
+
compliant idiom to swap in. (Native lexical checks only — the syntactic
|
|
76
|
+
subset, not whole-program rules; a clean snippet is not a compliance
|
|
77
|
+
guarantee.)
|
|
78
|
+
|
|
79
|
+
See [`AUTHORING_PLAYBOOK.md`](AUTHORING_PLAYBOOK.md) for the guidance → draft →
|
|
80
|
+
check → rewrite protocol to hand your IDE agent.
|
|
81
|
+
- **Stable fingerprints** — findings are identified by
|
|
82
|
+
`sha1(rule + file + normalized line content + enclosing function)`, *not* line
|
|
83
|
+
numbers, so they survive edits, insertions and refactors across sessions.
|
|
84
|
+
- **Persistent memory** — a SQLite store per project (`.maishac/memory.db`)
|
|
85
|
+
tracking finding lifecycle (open → resolved → regressed), every fix attempt and
|
|
86
|
+
its outcome, false-positive suppressions, MISRA-style deviation records with
|
|
87
|
+
justification/approver/expiry, and free-form project convention notes.
|
|
88
|
+
- **An engineered fix loop** — sessions with severity-ranked, file-grouped batches;
|
|
89
|
+
regressions always jump the queue; each finding is briefed with the rule summary,
|
|
90
|
+
a fix hint, strategies that *already failed* on it, relevant memory notes and
|
|
91
|
+
cross-standard equivalents. Guard rails: iteration budgets, stall detection, and
|
|
92
|
+
oscillation freezing (a finding that regresses twice is frozen as `needs_human`).
|
|
93
|
+
- **A verification gate** — a fix is not `resolved` just because the analyzer
|
|
94
|
+
stopped flagging it. It enters `pending_verification` until a passing test run
|
|
95
|
+
or an explicit human approval confirms it; semantic-risk and high-severity
|
|
96
|
+
findings always require human sign-off. See [below](#the-verification-gate).
|
|
97
|
+
- **Reporting** — per-standard compliance matrices, a markdown report with a
|
|
98
|
+
deviation register, SARIF 2.1.0 export with `partialFingerprints` for CI, and
|
|
99
|
+
the **MISRA Compliance:2020 evidence set** — the three documents a
|
|
100
|
+
functional-safety assessor asks for: the **Guideline Compliance Summary**
|
|
101
|
+
(every guideline Compliant / Deviations / Violations / Disapplied, tied to
|
|
102
|
+
deviation permits), the **Guideline Enforcement Plan** (how each guideline is
|
|
103
|
+
checked + a tool inventory with versions/options), and the **Guideline
|
|
104
|
+
Re-categorization Plan** (with the legality rules enforced — a Mandatory
|
|
105
|
+
guideline may not be re-categorized, a Required one may not drop to
|
|
106
|
+
Advisory/Disapplied), plus honest disclosure of which guidelines are *not
|
|
107
|
+
checked*.
|
|
108
|
+
|
|
109
|
+
The three rule knowledge bases (**81 rules** — 31 MISRA C:2012, 20 BARR-C:2018,
|
|
110
|
+
30 CERT C) contain **original paraphrased
|
|
111
|
+
summaries** written for this project — no standard text is reproduced. For
|
|
112
|
+
authoritative wording you still need the official MISRA / BARR / SEI CERT documents.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Scope & Limitations
|
|
117
|
+
|
|
118
|
+
**What Maisha *is*:**
|
|
119
|
+
|
|
120
|
+
- A **workflow orchestrator** for agent-driven compliance triage and fix loops.
|
|
121
|
+
- A **persistent audit-trail layer**: finding lifecycle, fix attempts, deviation
|
|
122
|
+
records, suppressions, and a verification gate that records *how* every fix was
|
|
123
|
+
confirmed (test run vs. human sign-off, and by whom).
|
|
124
|
+
- A **pre-certification cleanup** tool that catches and helps fix the obvious
|
|
125
|
+
violations early — in the IDE loop, before code reaches a qualified engine.
|
|
126
|
+
|
|
127
|
+
**What Maisha is *not*:**
|
|
128
|
+
|
|
129
|
+
- **Not a qualified or certified analysis tool.** Its engines are the
|
|
130
|
+
open-source cppcheck + clang-tidy + a native analyzer — none carry a tool
|
|
131
|
+
qualification kit. DO-178C / ISO 26262 / IEC 62304 generally require the
|
|
132
|
+
analysis tool *itself* to be qualified or proven-in-use; Maisha does not
|
|
133
|
+
meet that bar and does not claim to.
|
|
134
|
+
- **Not complete rule coverage.** 81 curated rules across three standards is a
|
|
135
|
+
fraction of MISRA C:2012 (180+ rules/directives with amendments) or CERT C.
|
|
136
|
+
Detection is bounded by the underlying engines, not the curated set. Every
|
|
137
|
+
covered rule and which analyzer backs it is listed in
|
|
138
|
+
[COVERAGE.md](COVERAGE.md) (generated from the code, so gaps are explicit).
|
|
139
|
+
A real-world run against the FreeRTOS kernel — with a measured false-positive
|
|
140
|
+
rate and the tool bugs it surfaced — is in [BENCHMARKS.md](BENCHMARKS.md).
|
|
141
|
+
Headline lesson: **pass your include paths to cppcheck/clang-tidy** with
|
|
142
|
+
`--include`/`-I` (repeatable), or most of the substantive findings are
|
|
143
|
+
configuration false positives. A from-scratch accuracy/reliability suite —
|
|
144
|
+
ground-truthed fixtures, a full fix-loop simulation, SARIF import, CLI
|
|
145
|
+
end-to-end and edge-case tests — is in
|
|
146
|
+
[BENCHMARK-SUITE-REPORT.md](BENCHMARK-SUITE-REPORT.md).
|
|
147
|
+
- **Not a substitute for human review.** By default a fix is never marked
|
|
148
|
+
`resolved` on a clean rescan alone — a passing test run or an explicit human
|
|
149
|
+
approval is required, and semantic-risk / high-severity findings *always*
|
|
150
|
+
require human sign-off (see [The verification gate](#the-verification-gate)).
|
|
151
|
+
|
|
152
|
+
**Recommended use for certification pipelines:** run Maisha's loop for early,
|
|
153
|
+
agent-driven cleanup, then hand off to a qualified engine (Astrée, Polyspace,
|
|
154
|
+
Helix QAC, Parasoft C/C++test, IAR C-STAT) for the evidence an auditor accepts.
|
|
155
|
+
Those engines emit SARIF, and `maishac import findings.sarif` layers Maisha's
|
|
156
|
+
loop, memory, verification gate and deviation register on top of their findings —
|
|
157
|
+
recognized MISRA/CERT ruleIds map onto the knowledge base, and imported findings
|
|
158
|
+
are never cleared by a native rescan.
|
|
159
|
+
|
|
160
|
+
**Robust across real engine dialects.** Qualified engines rarely put the
|
|
161
|
+
MISRA/CERT number in `ruleId` — Helix QAC / Coverity emit a checker-specific id
|
|
162
|
+
(e.g. `ABV.GENERAL`), reference the rule by `ruleIndex`, and attach the guideline
|
|
163
|
+
through `relationships` into a `taxonomies` component. Maisha's importer resolves
|
|
164
|
+
the rule via `result.rule` / `ruleIndex` / `ruleId`, follows relationships and
|
|
165
|
+
taxonomies (and result-level `taxa`) to recover the real guideline, honors
|
|
166
|
+
`defaultConfiguration` levels, skips non-defect results (`kind: pass`,
|
|
167
|
+
`notApplicable`) and baseline-`absent` findings, tolerates missing regions and
|
|
168
|
+
multi-location results, and normalizes scheme-prefixed URIs.
|
|
169
|
+
|
|
170
|
+
**Rich SARIF mapping.** Import isn't lossy: a qualified engine's `codeFlows`
|
|
171
|
+
(the data-flow path *to* the defect) are parsed and surfaced in the agent
|
|
172
|
+
briefing, so a fixer sees how a defect flows, not just where it lands; and
|
|
173
|
+
`result.suppressions` are honored so a team's existing triage/baseline carries
|
|
174
|
+
over instead of resurfacing as fresh violations. Export emits cross-standard
|
|
175
|
+
equivalences as SARIF `reportingDescriptor.relationships` (e.g. a MISRA rule
|
|
176
|
+
linked to its CERT equivalent), with every relationship target present as a
|
|
177
|
+
descriptor. Maisha's own identity travels in `partialFingerprints`
|
|
178
|
+
(`maishac/v1`), and `startColumn` + code flows survive an import → export
|
|
179
|
+
round-trip, so re-exporting a qualified engine's findings loses nothing.
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Install
|
|
184
|
+
|
|
185
|
+
Requires Python 3.10+.
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
pipx install maishac # isolated CLI install (recommended)
|
|
189
|
+
# or
|
|
190
|
+
pip install maishac
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
This installs the `maishac` CLI and the `maishac` Python package. Verify with
|
|
194
|
+
`maishac --help`. To hack on Maisha itself:
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
git clone https://github.com/Kiransekar/maisha.git
|
|
198
|
+
cd maisha
|
|
199
|
+
pip install -e ".[dev]" # editable install with pytest
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Optional but strongly recommended external analyzers — native works with
|
|
203
|
+
zero dependencies, but cppcheck (MISRA addon) and clang-tidy (`cert-*`
|
|
204
|
+
checks) meaningfully increase coverage:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
# Debian/Ubuntu
|
|
208
|
+
apt install cppcheck clang-tidy
|
|
209
|
+
|
|
210
|
+
# or, without root, anywhere pip works (prebuilt wheels, incl. Windows/macOS)
|
|
211
|
+
pip install cppcheck clang-tidy
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Maisha degrades gracefully: any analyzer not on `PATH` is skipped and the
|
|
215
|
+
native analyzer always works. Run `maishac scan` once and check
|
|
216
|
+
`analyzers_used` in the output to confirm what's actually active.
|
|
217
|
+
|
|
218
|
+
## Quickstart (CLI)
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
cd your-firmware-project
|
|
222
|
+
|
|
223
|
+
maishac scan src/ # one-shot scan, syncs memory
|
|
224
|
+
# headers outside src/ (e.g. a vendor SDK or FreeRTOSConfig.h)? forward them:
|
|
225
|
+
maishac scan src/ --include include/ --include vendor/sdk/inc
|
|
226
|
+
|
|
227
|
+
maishac findings --limit 20 # ranked open findings
|
|
228
|
+
maishac rule "MISRA 21.3" # explain a rule + cross-standard refs
|
|
229
|
+
|
|
230
|
+
# The engineered loop (what an agent drives via MCP):
|
|
231
|
+
maishac session begin src/ --verification-policy human_gated
|
|
232
|
+
# -> {"session_id": "abc123...", ...} — use that id below
|
|
233
|
+
maishac session batch abc123 # next prioritized batch with briefings
|
|
234
|
+
# ...edit code (you or your agent)...
|
|
235
|
+
maishac session verify abc123 # rescan, diff, grade attempts, run the test gate
|
|
236
|
+
maishac approve <fingerprint> --by lead@example.com # human sign-off on a verified fix
|
|
237
|
+
maishac session status abc123
|
|
238
|
+
|
|
239
|
+
maishac deviate "MISRA 19.2" --scope "drivers/**" \
|
|
240
|
+
--justification "Union required for hardware register overlay mapping" \
|
|
241
|
+
--approver lead@example.com --expires 2027-01-01
|
|
242
|
+
maishac suppress <fingerprint> --reason "false positive: macro expansion"
|
|
243
|
+
maishac note "This codebase uses FreeRTOS; heap_4 allocator is approved" --tags misra-21.3
|
|
244
|
+
maishac recategorize "MISRA 15.1" --to disapplied \
|
|
245
|
+
--rationale "No goto in this codebase; disapplied by acquirer/supplier agreement" \
|
|
246
|
+
--approver lead@example.com
|
|
247
|
+
maishac report --format sarif > compliance.sarif
|
|
248
|
+
maishac report --format misra-compliance > gcs.md # Guideline Compliance Summary
|
|
249
|
+
maishac report --format gep > gep.md # Guideline Enforcement Plan
|
|
250
|
+
maishac report --format grp > grp.md # Guideline Re-categorization Plan
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
## Quickstart (any agentic IDE, via MCP)
|
|
254
|
+
|
|
255
|
+
Add the server to your IDE's MCP configuration (ready-made snippets in
|
|
256
|
+
[`integrations/`](integrations/)):
|
|
257
|
+
|
|
258
|
+
```json
|
|
259
|
+
{
|
|
260
|
+
"mcpServers": {
|
|
261
|
+
"maisha": {
|
|
262
|
+
"command": "maishac",
|
|
263
|
+
"args": ["serve"],
|
|
264
|
+
"env": { "MAISHAC_PROJECT": "/path/to/your/project" }
|
|
265
|
+
}
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Then tell your agent something like:
|
|
271
|
+
|
|
272
|
+
> Begin a Maisha compliance session on `src/`, work through batches until
|
|
273
|
+
> converged, record every attempt, and add deviations only where a fix is
|
|
274
|
+
> genuinely impossible.
|
|
275
|
+
|
|
276
|
+
The recommended agent protocol is documented in
|
|
277
|
+
[`AGENT_PLAYBOOK.md`](AGENT_PLAYBOOK.md).
|
|
278
|
+
|
|
279
|
+
## MCP tools
|
|
280
|
+
|
|
281
|
+
| Tool | Purpose |
|
|
282
|
+
|---|---|
|
|
283
|
+
| `compliance_scan` | Scan paths, merge analyzers, sync memory, return diff (new/persisting/resolved/regressed) |
|
|
284
|
+
| `compliance_list_findings` | Ranked open findings above a severity floor |
|
|
285
|
+
| `compliance_get_finding` | Full briefing for one fingerprint (history, failed strategies, notes) |
|
|
286
|
+
| `compliance_explain_rule` | Rule summary, severity, fix hint, cross-standard equivalents |
|
|
287
|
+
| `compliance_search_rules` | Keyword search across all three standards |
|
|
288
|
+
| `compliance_guidance` | **Before** writing code on a concern, get the compliant idiom to reach for (avoid/prefer/why + the rules it satisfies) — the author-time pattern library |
|
|
289
|
+
| `compliance_check_snippet` | Lint a draft snippet **in memory, before writing it** — proactive authoring aid; returns violations, fix hints, and the compliant idiom to swap in; stores nothing |
|
|
290
|
+
| `compliance_begin_session` | Baseline scan + session with budgets (`max_iterations`, `batch_size`) |
|
|
291
|
+
| `compliance_next_batch` | Next prioritized batch, regressions first, with per-finding briefings |
|
|
292
|
+
| `compliance_record_attempt` | Log the strategy used on a finding (auto-graded on verify) |
|
|
293
|
+
| `compliance_verify` | Rescan, diff, grade attempts, run the test gate, advance state machine |
|
|
294
|
+
| `compliance_approve_finding` | Human sign-off moving a `pending_verification` finding to `resolved` (required for semantic-risk / high-severity fixes) |
|
|
295
|
+
| `compliance_session_status` | Progress, iteration budget, state (`active`/`awaiting_verification`/`converged`/`stalled`/`budget_exhausted`) |
|
|
296
|
+
| `compliance_add_deviation` | MISRA-style deviation record (justification ≥ 15 chars enforced) |
|
|
297
|
+
| `compliance_recategorize` | MISRA GRP re-categorization (legality enforced: no Mandatory re-cat; Required→Advisory/Disapplied forbidden) |
|
|
298
|
+
| `compliance_suppress_finding` | Mark a fingerprint as false positive (reason required) |
|
|
299
|
+
| `memory_note` / `memory_search` / `memory_stats` | Project convention memory |
|
|
300
|
+
| `compliance_import_sarif` | Ingest an external engine's SARIF (qualified engine or cppcheck `--output-format=sarif`) into the same loop/memory/gate; **honors `result.suppressions`** so a team's existing triage/baseline carries over instead of resurfacing as fresh violations |
|
|
301
|
+
| `compliance_report` | Markdown, JSON, SARIF 2.1.0, or the MISRA Compliance:2020 evidence set: `misra-compliance` (GCS), `gep` (enforcement plan), `grp` (re-categorization plan) |
|
|
302
|
+
|
|
303
|
+
## Architecture
|
|
304
|
+
|
|
305
|
+
```
|
|
306
|
+
┌──────────────────────────── your agentic IDE ───────────────────────────┐
|
|
307
|
+
│ LLM agent: reads briefings, edits code, records attempts │
|
|
308
|
+
└──────────────▲──────────────────────────────────────────────────────────┘
|
|
309
|
+
│ MCP (stdio)
|
|
310
|
+
┌──────────────┴────────────── maisha ──────────────────────────────┐
|
|
311
|
+
│ engine/ LoopEngine: sessions, batching, budgets, stall/oscillation │
|
|
312
|
+
│ memory/ SQLite: findings, fix_attempts, deviations, suppressions, │
|
|
313
|
+
│ notes, sessions (.maishac/memory.db) │
|
|
314
|
+
│ analyzers/ native (0-dep) + cppcheck(+MISRA addon) + clang-tidy(cert-*) │
|
|
315
|
+
│ → fingerprint-deduped, severity-sorted evidence │
|
|
316
|
+
│ rules/ MISRA C:2012 + BARR-C:2018 + CERT C KBs, fuzzy resolver, │
|
|
317
|
+
│ cross-standard references │
|
|
318
|
+
│ report.py compliance matrix, markdown, SARIF 2.1.0 │
|
|
319
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
Design principles:
|
|
323
|
+
|
|
324
|
+
1. **Determinism where it matters.** Prioritization, verification, memory and
|
|
325
|
+
budgets are code, not prompts. The LLM only does what LLMs are good at.
|
|
326
|
+
2. **Findings are identities, not line numbers.** Fingerprints keep history
|
|
327
|
+
attached to the defect through refactors.
|
|
328
|
+
3. **The loop must terminate.** Iteration budgets, stall limits and oscillation
|
|
329
|
+
freezing guarantee a session always ends in a well-defined state.
|
|
330
|
+
4. **Compliance is a process, not a scan.** Deviations and suppressions are
|
|
331
|
+
first-class, auditable records — exactly as MISRA compliance expects.
|
|
332
|
+
|
|
333
|
+
## The verification gate
|
|
334
|
+
|
|
335
|
+
The trap Maisha guards against: the only judge of a fix is the same analyzer
|
|
336
|
+
whose blind spot may have created the finding. "The warning stopped firing"
|
|
337
|
+
rewards the syntactically minimal edit — often the one most likely to change
|
|
338
|
+
behavior at a boundary. Casting a signed sentinel (`-1` = "no limit") to
|
|
339
|
+
`uint32_t` to silence a signed/unsigned comparison warning turns "no limit" into
|
|
340
|
+
"an enormous limit" — the rescan passes, no static check ever catches it.
|
|
341
|
+
|
|
342
|
+
So a fix does **not** go straight to `resolved`. It enters
|
|
343
|
+
`pending_verification` and leaves only under the session's **`verification_policy`**:
|
|
344
|
+
|
|
345
|
+
| Policy | A pending fix becomes `resolved` when… |
|
|
346
|
+
|---|---|
|
|
347
|
+
| `analyzer_only` | the analyzer stops flagging it (⚠️ not recommended for compliance work) |
|
|
348
|
+
| `test_gated` | a configured `test_command` exits 0 |
|
|
349
|
+
| `human_gated` | a human calls `approve_finding` |
|
|
350
|
+
|
|
351
|
+
Default: `test_gated` if a `test_command` is configured, else `human_gated`.
|
|
352
|
+
Regardless of policy, **semantic-risk findings** (casts, comparisons, sign
|
|
353
|
+
conversions, control-flow changes) and **high-severity findings** always require
|
|
354
|
+
human approval — a green test suite that never exercises the sentinel case cannot
|
|
355
|
+
resolve them. Every resolution records how it was confirmed (`analyzer`/`test`/
|
|
356
|
+
`human`) and, for human sign-off, `approved_by`.
|
|
357
|
+
|
|
358
|
+
> **Set expectations accordingly:** the semantic-risk rule-category list is
|
|
359
|
+
> broad (it covers most of MISRA's essential-type, control-flow and
|
|
360
|
+
> switch-statement rules, plus CERT's `INT`/`FLP` families) — in practice,
|
|
361
|
+
> `test_gated` sessions on typical MISRA findings end up requiring human
|
|
362
|
+
> sign-off almost as often as `human_gated` does. A full end-to-end
|
|
363
|
+
> simulation confirmed a passing test suite auto-resolved **zero** of eight
|
|
364
|
+
> pending findings in one representative session — see
|
|
365
|
+
> [BENCHMARK-SUITE-REPORT.md §3.2](BENCHMARK-SUITE-REPORT.md#32-the-gate-is-more-conservative-than-it-looks).
|
|
366
|
+
> Budget human review time accordingly; don't expect `test_gated` to remove
|
|
367
|
+
> most of the review load.
|
|
368
|
+
|
|
369
|
+
```bash
|
|
370
|
+
maishac session begin src/ --verification-policy test_gated --test-command "make test"
|
|
371
|
+
# ...agent fixes, then:
|
|
372
|
+
maishac session verify <id> # -> awaiting_verification if fixes need sign-off
|
|
373
|
+
maishac approve <fingerprint> --by lead@example.com
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
## Teams & concurrency
|
|
377
|
+
|
|
378
|
+
Project memory lives in a per-project SQLite file, `.maishac/memory.db`.
|
|
379
|
+
|
|
380
|
+
- **Gitignore it.** It is local, machine-specific state, not source — add
|
|
381
|
+
`.maishac/` to `.gitignore` (this repo already does). To share state
|
|
382
|
+
deliberately, export a `compliance_report` (SARIF/JSON), don't commit the DB.
|
|
383
|
+
- **Concurrent access.** The DB runs in WAL mode with a busy-timeout, so a CI
|
|
384
|
+
scan and a local session can read/write without hard-blocking. `session begin`
|
|
385
|
+
refuses to start a second session while one is already active on the same
|
|
386
|
+
project (pass `--force` to override) so two runs don't race on finding state.
|
|
387
|
+
|
|
388
|
+
## Development
|
|
389
|
+
|
|
390
|
+
```bash
|
|
391
|
+
pip install -e . && python -m pytest tests/ -q
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
`examples/bad.c` is a deliberately non-compliant fixture exercising ~18 rules —
|
|
395
|
+
useful as a demo target.
|
|
396
|
+
|
|
397
|
+
## Contributing
|
|
398
|
+
|
|
399
|
+
Contributions are very welcome — especially to the community-extensible parts:
|
|
400
|
+
adding a coding-standard **rule**, an authoring **pattern** (compliant idiom), or
|
|
401
|
+
an **analyzer adapter** / SARIF-dialect mapping. None of these touch the engine.
|
|
402
|
+
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the how-to and the design invariants
|
|
403
|
+
to preserve, and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Good first issues are
|
|
404
|
+
labeled on the tracker.
|
|
405
|
+
|
|
406
|
+
## License / disclaimer
|
|
407
|
+
|
|
408
|
+
Rule summaries are original paraphrases; MISRA®, BARR-C and SEI CERT C are the
|
|
409
|
+
property of their respective owners. Maisha output does not constitute a
|
|
410
|
+
formal compliance certification.
|