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.
Files changed (37) hide show
  1. maishac-0.3.1/LICENSE +28 -0
  2. maishac-0.3.1/PKG-INFO +410 -0
  3. maishac-0.3.1/README.md +383 -0
  4. maishac-0.3.1/maishac/__init__.py +16 -0
  5. maishac-0.3.1/maishac/analyzers/__init__.py +60 -0
  6. maishac-0.3.1/maishac/analyzers/base.py +66 -0
  7. maishac-0.3.1/maishac/analyzers/clang_tidy.py +90 -0
  8. maishac-0.3.1/maishac/analyzers/cppcheck.py +136 -0
  9. maishac-0.3.1/maishac/analyzers/native.py +269 -0
  10. maishac-0.3.1/maishac/cli.py +317 -0
  11. maishac-0.3.1/maishac/engine/__init__.py +414 -0
  12. maishac-0.3.1/maishac/mcp_server.py +428 -0
  13. maishac-0.3.1/maishac/memory/__init__.py +466 -0
  14. maishac-0.3.1/maishac/model.py +157 -0
  15. maishac-0.3.1/maishac/patterns.py +481 -0
  16. maishac-0.3.1/maishac/report.py +660 -0
  17. maishac-0.3.1/maishac/rules/__init__.py +113 -0
  18. maishac-0.3.1/maishac/rules/barr_c_2018.json +26 -0
  19. maishac-0.3.1/maishac/rules/cert_c.json +36 -0
  20. maishac-0.3.1/maishac/rules/misra_c_2012.json +37 -0
  21. maishac-0.3.1/maishac.egg-info/PKG-INFO +410 -0
  22. maishac-0.3.1/maishac.egg-info/SOURCES.txt +35 -0
  23. maishac-0.3.1/maishac.egg-info/dependency_links.txt +1 -0
  24. maishac-0.3.1/maishac.egg-info/entry_points.txt +2 -0
  25. maishac-0.3.1/maishac.egg-info/requires.txt +4 -0
  26. maishac-0.3.1/maishac.egg-info/top_level.txt +1 -0
  27. maishac-0.3.1/pyproject.toml +44 -0
  28. maishac-0.3.1/setup.cfg +4 -0
  29. maishac-0.3.1/tests/test_benchmark_fixes.py +305 -0
  30. maishac-0.3.1/tests/test_check_snippet.py +38 -0
  31. maishac-0.3.1/tests/test_gep_grp.py +83 -0
  32. maishac-0.3.1/tests/test_misra_compliance.py +64 -0
  33. maishac-0.3.1/tests/test_patterns.py +55 -0
  34. maishac-0.3.1/tests/test_sarif_dialects.py +105 -0
  35. maishac-0.3.1/tests/test_sarif_import.py +167 -0
  36. maishac-0.3.1/tests/test_smoke.py +142 -0
  37. 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
+ [![CI](https://github.com/Kiransekar/maisha/actions/workflows/ci.yml/badge.svg)](https://github.com/Kiransekar/maisha/actions/workflows/ci.yml)
33
+ &nbsp;[![Release](https://img.shields.io/badge/release-v0.3.1-blue)](https://github.com/Kiransekar/maisha/releases/tag/v0.3.1)
34
+ &nbsp;![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
35
+ &nbsp;![License: MIT](https://img.shields.io/badge/license-MIT-green)
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.