misch 0.1.0__py3-none-any.whl

misch/__init__.py

@@ -0,0 +1,3 @@
+"""misch: config-driven MISRA C:2023 analysis for arbitrary C projects."""
+
+__version__ = "0.1.0"

misch/cli.py

@@ -0,0 +1,352 @@
+"""`misch` command-line entry point: run, init, baseline, deviations."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import Counter
+from functools import partial
+from pathlib import Path
+
+from rich.console import Console
+from rich_argparse import RichHelpFormatter
+
+from . import __version__
+from . import db as dbmod
+from .config import ConfigError, load
+from .engine import cppcheck
+from .engine.cppcheck import EngineError
+from .report.baseline import diff as bl_diff
+from .report.baseline import load_baseline, write_baseline
+from .report.dev_render import render_markdown as render_dev_markdown
+from .report.dev_render import render_terminal as render_dev_terminal
+from .report.deviations import (
+    DeviationRecord,
+    discover_sources,
+    find_stale,
+    harvest_inline,
+    parse_suppressions_file,
+)
+from .report.headlines import load_headlines
+from .report.model import Report
+from .report.renderers import (
+    render_baseline_summary,
+    render_json,
+    render_sarif,
+    render_terminal,
+)
+from .scaffold import ScaffoldParams, build_config
+
+_err = Console(stderr=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="misch",
+        description="Config-driven MISRA C:2023 analysis for arbitrary C projects.",
+        formatter_class=RichHelpFormatter,
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    add_parser = partial(sub.add_parser, formatter_class=RichHelpFormatter)
+
+    p_run = add_parser("run", help="analyse a project")
+    p_run.add_argument("-c", "--config", default="misra.toml", type=Path)
+    p_run.add_argument(
+        "--format",
+        action="append",
+        default=[],
+        help="override outputs, e.g. --format json (repeatable)",
+    )
+    p_run.add_argument("--output", type=Path, help="path for a file format")
+    p_run.add_argument(
+        "--baseline",
+        action="store_true",
+        help="ratchet mode: report all, but fail only on findings not in the baseline",
+    )
+    p_run.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="also print the per-location listing (default: table + summary)",
+    )
+    p_run.set_defaults(func=_cmd_run)
+
+    _add_init_parser(add_parser)
+
+    p_bl = add_parser("baseline", help="snapshot current findings as the baseline")
+    p_bl.add_argument("-c", "--config", default="misra.toml", type=Path)
+    p_bl.add_argument("--baseline-file", type=Path, help="override the baseline path")
+    p_bl.set_defaults(func=_cmd_baseline)
+
+    p_dev = add_parser(
+        "deviations", help="harvest + validate MISRA deviations (suppressions)"
+    )
+    p_dev.add_argument("-c", "--config", default="misra.toml", type=Path)
+    p_dev.add_argument(
+        "--check-stale",
+        action="store_true",
+        help="run the engine to flag suppressions that match no finding",
+    )
+    p_dev.add_argument(
+        "--format", action="append", default=[], help="e.g. --format md (repeatable)"
+    )
+    p_dev.add_argument("--output", type=Path, help="path for the Markdown record")
+    p_dev.set_defaults(func=_cmd_deviations)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+def _add_init_parser(add_parser) -> None:
+    p = add_parser("init", help="generate a misra.toml template")
+    p.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=Path("misra.toml"),
+        help="where to write (default: ./misra.toml)",
+    )
+    p.add_argument("--force", action="store_true", help="overwrite an existing file")
+    p.add_argument(
+        "--db",
+        choices=["meson", "cmake", "existing"],
+        default="meson",
+        help="compile-DB source (default: meson)",
+    )
+    p.add_argument("--db-path", help="compile_commands.json path (for --db existing)")
+    p.add_argument(
+        "--scope",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="analysed source root (repeatable; default: src/)",
+    )
+    p.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="excluded path (repeatable; default: tests/, subprojects/)",
+    )
+    p.add_argument("--platform", default="unix64", help="cppcheck platform preset")
+    p.add_argument(
+        "--platform-xml", help="custom cppcheck platform XML (overrides --platform)"
+    )
+    p.add_argument("--rule-texts", default="${MISRA_RULE_TEXTS}", help="headlines path")
+    p.add_argument(
+        "--define",
+        action="append",
+        default=[],
+        metavar="D",
+        help="extra -D define for cppcheck (repeatable)",
+    )
+    p.set_defaults(func=_cmd_init)
+
+
+class _AnalysisError(Exception):
+    """Carries the exit code for a failed analysis pipeline."""
+
+    def __init__(self, code: int):
+        self.code = code
+
+
+def _analyse(cfg, *, inline_suppr: bool = True) -> tuple[Report, dbmod.ScopeCoverage]:
+    """Shared pipeline: db -> scope-check -> engine -> in-scope Report.
+
+    Raises _AnalysisError(code) on any gate so callers just propagate the code.
+    With inline_suppr=False, cppcheck-suppress comments are ignored (used by the
+    deviation staleness check).
+    """
+    if cfg.rule_texts is None:
+        _err.print(
+            "[yellow]note:[/] no MISRA rule-texts found (set $MISRA_RULE_TEXTS "
+            "or \\[rules].texts). Findings will be tagged category: unknown. "
+            "See docs/rule-texts.md."
+        )
+    rules = load_headlines(cfg.rule_texts) if cfg.rule_texts else {}
+
+    try:
+        db_path = dbmod.resolve_compile_db(cfg)
+    except dbmod.DbError as exc:
+        _err.print(f"[red]compile-db error:[/] {exc}")
+        raise _AnalysisError(2) from None
+
+    coverage = dbmod.classify_files(cfg, db_path)
+    if not coverage.ok():
+        _err.print(
+            f"[red]scope error:[/] {len(coverage.unattributed)} file(s) match "
+            "neither \\[project].scope nor \\[project].exclude. Classify them "
+            "explicitly (audit boundary must be enumerated):"
+        )
+        for f in coverage.unattributed:
+            _err.print(f"  [red]?[/] {f}")
+        raise _AnalysisError(2)
+
+    try:
+        findings = cppcheck.run(cfg, db_path, rules, inline_suppr=inline_suppr)
+    except EngineError as exc:
+        _err.print(f"[red]engine error:[/] {exc}")
+        raise _AnalysisError(2) from None
+
+    # Post-filter is authoritative: only report in-scope, non-excluded
+    # locations. Findings at in-tree locations that match neither scope nor
+    # exclude (headers never appear in the compile DB, so classify_files
+    # cannot gate them) are a hard error, not a silent drop.
+    findings, unattributed = dbmod.partition_findings(cfg, findings)
+    if unattributed:
+        by_file = Counter(f.file for f in unattributed)
+        _err.print(
+            f"[red]scope error:[/] {len(unattributed)} finding(s) at "
+            "location(s) matching neither \\[project].scope nor "
+            "\\[project].exclude. Classify them explicitly "
+            "(audit boundary must be enumerated):"
+        )
+        for file, n in sorted(by_file.items()):
+            _err.print(f"  [red]?[/] {file} ({n})")
+        raise _AnalysisError(2)
+    report = Report(
+        findings=findings,
+        analysed_files=coverage.analysed,
+        excluded_files=coverage.excluded,
+    )
+    return report, coverage
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    try:
+        cfg = load(args.config)
+    except ConfigError as exc:
+        _err.print(f"[red]config error:[/] {exc}")
+        return 2
+
+    try:
+        report, coverage = _analyse(cfg)
+    except _AnalysisError as exc:
+        return exc.code
+
+    _emit(cfg, report, coverage, args)
+
+    if not args.baseline:
+        return 1 if report.misra() else 0
+
+    # Ratchet mode: report everything but fail only on findings not in baseline.
+    baseline = load_baseline(cfg.baseline_path)
+    if not baseline:
+        _err.print(
+            f"[yellow]note:[/] --baseline set but {cfg.baseline_path.name} is "
+            "empty/absent. Run [bold]misch baseline[/] to create it."
+        )
+    d = bl_diff(report.misra(), baseline)
+    render_baseline_summary(d, cfg.baseline_path)
+    return 1 if d.new else 0
+
+
+def _cmd_baseline(args: argparse.Namespace) -> int:
+    try:
+        cfg = load(args.config)
+    except ConfigError as exc:
+        _err.print(f"[red]config error:[/] {exc}")
+        return 2
+    try:
+        report, _ = _analyse(cfg)
+    except _AnalysisError as exc:
+        return exc.code
+
+    path = args.baseline_file or cfg.baseline_path
+    n = write_baseline(path, report.misra())
+    _err.print(
+        f"[green]wrote baseline[/] {path}: {n} finding(s) accepted. "
+        "Future [bold]misch run --baseline[/] fails only on new ones."
+    )
+    return 0
+
+
+def _cmd_deviations(args: argparse.Namespace) -> int:
+    try:
+        cfg = load(args.config)
+    except ConfigError as exc:
+        _err.print(f"[red]config error:[/] {exc}")
+        return 2
+
+    known = set(load_headlines(cfg.rule_texts)) if cfg.rule_texts else set()
+
+    record = DeviationRecord()
+    record.deviations.extend(
+        harvest_inline(discover_sources(cfg), cfg.project_root, known)
+    )
+    if cfg.suppressions_path and cfg.suppressions_path.is_file():
+        record.deviations.extend(
+            parse_suppressions_file(cfg.suppressions_path, cfg.project_root, known)
+        )
+
+    if args.check_stale:
+        try:
+            # An unsuppressed run reveals what each suppression actually hides.
+            report, _ = _analyse(cfg, inline_suppr=False)
+            record.stale = find_stale(record.deviations, report.findings)
+        except _AnalysisError:
+            _err.print("[yellow]note:[/] staleness check skipped (analysis failed).")
+
+    render_dev_terminal(record)
+    for out in [{"format": f} for f in args.format]:
+        if out["format"] == "md":
+            path = args.output or (cfg.build_dir / "deviations.md")
+            render_dev_markdown(record, path)
+            _err.print(f"[dim]wrote deviation record to {path}[/]")
+        else:
+            fmt = out["format"]
+            _err.print(f"[yellow]note:[/] deviations format {fmt!r} unsupported")
+
+    return 0 if record.ok() else 1
+
+
+def _emit(cfg, report: Report, coverage, args: argparse.Namespace) -> None:
+    outputs = [{"format": f} for f in args.format] if args.format else list(cfg.outputs)
+    for out in outputs:
+        fmt = out["format"]
+        if fmt == "terminal":
+            render_terminal(report, coverage, verbose=getattr(args, "verbose", False))
+        elif fmt == "json":
+            path = args.output or Path(out.get("path", cfg.build_dir / "misra.json"))
+            render_json(report, coverage, path)
+            _err.print(f"[dim]wrote JSON findings to {path}[/]")
+        elif fmt == "sarif":
+            path = args.output or Path(out.get("path", cfg.build_dir / "misra.sarif"))
+            render_sarif(report, path)
+            _err.print(f"[dim]wrote SARIF to {path}[/]")
+        else:
+            _err.print(
+                f"[yellow]note:[/] output format {fmt!r} unsupported "
+                "(terminal/json/sarif)"
+            )
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    out: Path = args.output
+    if out.exists() and not args.force:
+        _err.print(f"[red]refusing to overwrite {out}[/] (pass --force)")
+        return 2
+
+    params = ScaffoldParams(
+        scope=args.scope or ["src/"],
+        exclude=args.exclude or ["tests/", "subprojects/"],
+        db_source=args.db,
+        db_path=args.db_path,
+        platform_preset=args.platform,
+        platform_xml=args.platform_xml,
+        rule_texts=args.rule_texts,
+        defines=args.define,
+    )
+    out.write_text(build_config(params))
+    _err.print(
+        f"[green]wrote {out}[/]. Review the scope/exclude and db source, "
+        "then run [bold]misch run[/]."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

misch/config.py

@@ -0,0 +1,127 @@
+"""Load and validate `misra.toml`.
+
+Everything that differs between projects is data here, not shell. See
+docs/DESIGN.md for the full schema.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass(slots=True)
+class Config:
+    project_root: Path
+    scope: list[str]
+    exclude: list[str]
+    db_source: str  # meson | cmake | existing
+    db_path: str | None
+    platform: str  # cppcheck preset name or path to a platform XML
+    defines: list[str]
+    rule_texts: str | None  # resolved absolute path, or None (BYO absent)
+    outputs: list[dict]  # [{"format": "terminal"}, {"format": "json", "path": ...}]
+    baseline_path: Path
+    suppressions_path: Path | None  # cppcheck project suppressions file, if any
+
+    build_dir: Path = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.build_dir = self.project_root / "build_analysis"
+
+
+# For build systems without native compile-DB export (plain Make), generate
+# one with an interceptor such as `bear -- make` and use source = "existing".
+_VALID_DB_SOURCES = {"meson", "cmake", "existing"}
+
+
+def load(config_path: Path) -> Config:
+    config_path = config_path.resolve()
+    if not config_path.is_file():
+        raise ConfigError(f"config not found: {config_path}")
+    root = config_path.parent
+
+    with open(config_path, "rb") as fh:
+        data = tomllib.load(fh)
+
+    project = data.get("project", {})
+    db = data.get("db", {})
+    platform = data.get("platform", {})
+    toolchain = data.get("toolchain", {})
+    rules = data.get("rules", {})
+    report = data.get("report", {})
+    baseline = data.get("baseline", {})
+    deviations = data.get("deviations", {})
+
+    db_source = db.get("source", "existing")
+    if db_source not in _VALID_DB_SOURCES:
+        raise ConfigError(
+            f"db.source must be one of {sorted(_VALID_DB_SOURCES)}, got {db_source!r}"
+        )
+
+    plat = platform.get("xml") or platform.get("preset") or "unix64"
+
+    outputs = report.get("outputs") or [{"format": "terminal"}]
+    outputs = [_norm_output(o) for o in outputs]
+
+    return Config(
+        project_root=root,
+        scope=list(project.get("scope", [])),
+        exclude=list(project.get("exclude", [])),
+        db_source=db_source,
+        db_path=db.get("path"),
+        platform=plat,
+        defines=list(toolchain.get("defines", [])),
+        rule_texts=_resolve_rule_texts(rules.get("texts"), root),
+        outputs=outputs,
+        baseline_path=_resolve_path(baseline.get("path"), root, "misra-baseline.json"),
+        suppressions_path=_optional_path(deviations.get("suppressions"), root),
+    )
+
+
+def _optional_path(configured: str | None, root: Path) -> Path | None:
+    if not configured:
+        return None
+    p = Path(configured)
+    return p if p.is_absolute() else (root / p)
+
+
+def _resolve_path(configured: str | None, root: Path, default: str) -> Path:
+    p = Path(configured) if configured else Path(default)
+    return p if p.is_absolute() else (root / p)
+
+
+def _norm_output(o: object) -> dict:
+    if isinstance(o, str):
+        return {"format": o}
+    if isinstance(o, dict) and "format" in o:
+        return dict(o)
+    raise ConfigError(f"invalid report output entry: {o!r}")
+
+
+def _resolve_rule_texts(configured: str | None, root: Path) -> str | None:
+    """Precedence: $MISRA_RULE_TEXTS  >  misra.toml [rules].texts.
+
+    Returns an absolute path if a readable file is found, else None (the run
+    still works; findings are tagged category: unknown).
+    """
+    env = os.environ.get("MISRA_RULE_TEXTS")
+    candidates = [env] if env else []
+    if configured:
+        candidates.append(os.path.expandvars(configured))
+
+    for cand in candidates:
+        if not cand:
+            continue
+        p = Path(cand)
+        if not p.is_absolute():
+            p = root / p
+        if p.is_file():
+            return str(p.resolve())
+    return None

misch/db/__init__.py

@@ -0,0 +1,178 @@
+"""Compile-database resolution and scope classification.
+
+`compile_commands.json` is the universal seam: every project-specific build
+concern collapses into "produce a normalised compile DB". This module obtains
+that DB (from an existing file, or by configuring Meson/CMake) and classifies
+every file it references as analysed / excluded / unattributed.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..config import Config
+
+
+class DbError(Exception):
+    pass
+
+
+def resolve_compile_db(cfg: Config) -> Path:
+    """Return a *normalised* compile_commands.json for the configured source.
+
+    Normalisation rewrites every entry's `file` to an absolute path (resolved
+    against its `directory`), so downstream scope classification and the engine
+    see uniform paths regardless of whether the build system emitted relative or
+    absolute ones.
+    """
+    if cfg.db_source == "existing":
+        rel = cfg.db_path or "build/compile_commands.json"
+        raw = (cfg.project_root / rel).resolve()
+        if not raw.is_file():
+            raise DbError(f"db.source=existing but {raw} does not exist")
+    elif cfg.db_source == "meson":
+        raw = _meson_db(cfg)
+    elif cfg.db_source == "cmake":
+        raw = _cmake_db(cfg)
+    else:
+        raise DbError(f"unsupported db.source: {cfg.db_source!r}")
+
+    return _normalise_db(raw, cfg.build_dir)
+
+
+def _normalise_db(raw: Path, out_dir: Path) -> Path:
+    entries = json.loads(raw.read_text())
+    for e in entries:
+        f = Path(e["file"])
+        if not f.is_absolute():
+            f = Path(e.get("directory", ".")) / f
+        e["file"] = str(f.resolve())
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out = out_dir / "compile_commands.normalised.json"
+    out.write_text(json.dumps(entries))
+    return out
+
+
+def _meson_db(cfg: Config) -> Path:
+    db = cfg.build_dir / "compile_commands.json"
+    if not db.is_file():
+        _require("meson")
+        subprocess.run(
+            ["meson", "setup", str(cfg.build_dir), str(cfg.project_root)],
+            check=True,
+        )
+    if not db.is_file():
+        raise DbError(f"meson did not produce {db}")
+    return db
+
+
+def _cmake_db(cfg: Config) -> Path:
+    db = cfg.build_dir / "compile_commands.json"
+    if not db.is_file():
+        _require("cmake")
+        subprocess.run(
+            [
+                "cmake",
+                "-S",
+                str(cfg.project_root),
+                "-B",
+                str(cfg.build_dir),
+                "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
+            ],
+            check=True,
+        )
+    if not db.is_file():
+        raise DbError(f"cmake did not produce {db}")
+    return db
+
+
+def _require(tool: str) -> None:
+    if shutil.which(tool) is None:
+        raise DbError(f"{tool} not found on PATH (needed for db.source)")
+
+
+@dataclass(slots=True)
+class ScopeCoverage:
+    analysed: list[str]
+    excluded: list[str]
+    unattributed: list[str]
+
+    def ok(self) -> bool:
+        return not self.unattributed
+
+
+def classify_files(cfg: Config, db_path: Path) -> ScopeCoverage:
+    """Bucket every DB file into analysed / excluded / unattributed.
+
+    Enforces the "exclusion is explicit and enumerated" rule: a file that
+    matches neither `scope` nor `exclude` is unattributed, which is a hard
+    error so nothing is ever silently ignored.
+    """
+    entries = json.loads(db_path.read_text())
+    files = sorted({_rel(cfg.project_root, e["file"]) for e in entries})
+
+    analysed, excluded, unattributed = [], [], []
+    for f in files:
+        if _matches_any(f, cfg.exclude):
+            excluded.append(f)
+        elif not cfg.scope or _matches_any(f, cfg.scope):
+            analysed.append(f)
+        else:
+            unattributed.append(f)
+    return ScopeCoverage(analysed, excluded, unattributed)
+
+
+def _rel(root: Path, file: str) -> str:
+    p = Path(file)
+    try:
+        return p.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return p.as_posix()  # outside the tree (system/toolchain header)
+
+
+def _matches_any(path: str, globs: list[str]) -> bool:
+    for g in globs:
+        g = g.strip()
+        if not g:
+            continue
+        base = g.rstrip("/")
+        # Directory-style pattern: match anything beneath it.
+        if path == base or path.startswith(base + "/"):
+            return True
+        if fnmatch.fnmatch(path, g):
+            return True
+    return False
+
+
+def in_scope(cfg: Config, path: str) -> bool:
+    """True if a finding at `path` should be reported (in scope, not excluded)."""
+    if _matches_any(path, cfg.exclude):
+        return False
+    return not cfg.scope or _matches_any(path, cfg.scope)
+
+
+def partition_findings(cfg: Config, findings: list) -> tuple[list, list]:
+    """Split findings into (kept, unattributed-location).
+
+    The compile DB only lists translation units, so `classify_files` cannot see
+    headers: they enter the analysis via inclusion, and cppcheck reports
+    findings at their locations. A finding inside the project tree whose path
+    matches neither `scope` nor `exclude` is therefore unclassified audit
+    territory and must be surfaced, not silently dropped. Findings at
+    explicitly excluded paths and outside the tree (system/toolchain headers;
+    `_rel` leaves those absolute) are dropped silently by design.
+    """
+    kept, unattributed = [], []
+    for f in findings:
+        if not f.file:
+            continue
+        if in_scope(cfg, f.file):
+            kept.append(f)
+        elif not Path(f.file).is_absolute() and not _matches_any(f.file, cfg.exclude):
+            unattributed.append(f)
+    return kept, unattributed

misch/engine/__init__.py

@@ -0,0 +1,3 @@
+"""Static-analysis engines. cppcheck is the default; the interface is kept
+narrow so a commercial tool can slot in behind the same Finding model later.
+"""