@h2loop/autosar 0.0.0-stage → 1.0.1

package/python/ecuc_engine/audit.py

@@ -0,0 +1,475 @@
+"""Deterministic audit of BSW API calls in integration C code against the ECUC configuration.
+
+Finds calls that take a configuration handle (Com signals/groups, NvM blocks, Dem events, PduR
+source PDUs; Rte_Write_/Rte_Read_ macros resolved through the generated RTE headers), resolves the
+handle to its ECUC container via the symbolic-name rule (<Mod>Conf_<ContainerDef>_<ShortName>,
+TPS_ECUC_02108) or a raw number via the module's handle-ID parameter, and checks:
+
+  H2L-API-001  raw numeric handle (use the symbolic name)
+  H2L-API-002  unknown handle (symbol or number matches no configured container)
+  H2L-API-003  direction mismatch (send on a RECEIVE I-PDU signal, receive on a SEND one)
+  H2L-API-004  C object width differs from the signal's ComSignalType / ComBitSize
+  H2L-API-005  NvM NULL_PTR without a permanent RAM block or explicit synchronization
+
+Width is checked only when the C type is known (compound literal, or a declaration in the same
+translation unit); anything else is listed under "unchecked", never guessed.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .model import Elem, Project
+from .values import parse_int
+
+from . import paths
+
+GENERATED_MARK = re.compile(r"generated by|automatically generated|auto-generated|this file (?:is|was) generated|do not edit",
+                            re.IGNORECASE)
+
+
+def is_generated(path: str) -> bool:
+    """Generator output, recognised by the file itself (name pattern or header banner), not its folder."""
+    name = os.path.basename(path)
+    if re.search(r"(?:_(?:Cfg|PBcfg|Lcfg)\.[ch]|^Rte\w*\.c)$", name, re.IGNORECASE):
+        return True
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(2048).decode("utf-8", "replace")
+    except OSError:
+        return False
+    return bool(GENERATED_MARK.search(head))
+
+
+@dataclass
+class Api:
+    module: str
+    defs: tuple  # container def names the handle may refer to
+    handle_param: str
+    kind: str  # send | receive | nvm | dem | pdur
+    data: Optional[int]  # index of the data pointer argument
+    cite: str
+
+
+APIS = {
+    "Com_SendSignal": Api("Com", ("ComSignal", "ComGroupSignal"), "ComHandleId", "send", 1, "SWS_Com_00197"),
+    "Com_ReceiveSignal": Api("Com", ("ComSignal", "ComGroupSignal"), "ComHandleId", "receive", 1, "SWS_Com_00198"),
+    "Com_SendSignalGroup": Api("Com", ("ComSignalGroup",), "ComHandleId", "send", None, "SWS_Com_00200"),
+    "Com_ReceiveSignalGroup": Api("Com", ("ComSignalGroup",), "ComHandleId", "receive", None, "SWS_Com_00201"),
+    "NvM_ReadBlock": Api("NvM", ("NvMBlockDescriptor",), "NvMNvramBlockIdentifier", "nvm", 1, "SWS_NvM_00454"),
+    "NvM_WriteBlock": Api("NvM", ("NvMBlockDescriptor",), "NvMNvramBlockIdentifier", "nvm", 1, "SWS_NvM_00455"),
+    "NvM_RestoreBlockDefaults": Api("NvM", ("NvMBlockDescriptor",), "NvMNvramBlockIdentifier", "nvm", 1, "SWS_NvM_00456"),
+    "Dem_SetEventStatus": Api("Dem", ("DemEventParameter",), "DemEventId", "dem", None, "SWS_Dem_00183"),
+    "Dem_ReportErrorStatus": Api("Dem", ("DemEventParameter",), "DemEventId", "dem", None, "SWS_Dem (Dem_ReportErrorStatus, pre-R4.2 releases)"),
+}
+PDUR = Api("PduR", ("PduRSrcPdu",), "PduRSourcePduHandleId", "pdur", None, "SWS_PduR_00406")
+CALL = re.compile(r"\b(Com_(?:Send|Receive)Signal(?:Group)?|NvM_(?:ReadBlock|WriteBlock|RestoreBlockDefaults)|"
+                  r"Dem_(?:SetEventStatus|ReportErrorStatus)|PduR_\w*Transmit|Rte_(?:Write|Read)_\w+)\s*\(")
+NUM = re.compile(r"^\(?\s*(?:\(\s*\w+\s*\)\s*)?(0[xX][0-9a-fA-F]+|\d+)[uUlL]*\s*\)?$")
+SYM = re.compile(r"^(\w+?)Conf_(\w+?)_(\w+)$")
+NULLS = {"NULL_PTR", "NULL", "0", "((void*)0)", "(void*)0"}
+TYPE_BITS = {"boolean": 8, "uint8": 8, "sint8": 8, "uint16": 16, "sint16": 16, "uint32": 32, "sint32": 32,
+             "uint64": 64, "sint64": 64, "float32": 32, "float64": 64, "char": 8, "int8_t": 8, "uint8_t": 8,
+             "int16_t": 16, "uint16_t": 16, "int32_t": 32, "uint32_t": 32, "int64_t": 64, "uint64_t": 64,
+             "float": 32, "double": 64, "bool": 8}
+SIG_BITS = {"BOOLEAN": 8, "UINT8": 8, "SINT8": 8, "UINT16": 16, "SINT16": 16, "UINT32": 32, "SINT32": 32,
+            "UINT64": 64, "SINT64": 64, "FLOAT32": 32, "FLOAT64": 64}
+
+
+def strip_comments(src: str) -> str:
+    """Blank out comments and string literals, keeping offsets and newlines."""
+    out = list(src)
+    i, n = 0, len(src)
+    while i < n:
+        c = src[i]
+        if src.startswith("/*", i):
+            j = src.find("*/", i + 2)
+            j = n if j < 0 else j + 2
+            for k in range(i, j):
+                if out[k] != "\n":
+                    out[k] = " "
+            i = j
+        elif src.startswith("//", i):
+            j = src.find("\n", i)
+            j = n if j < 0 else j
+            for k in range(i, j):
+                out[k] = " "
+            i = j
+        elif c in "\"'":
+            j = i + 1
+            while j < n and src[j] != c:
+                j += 2 if src[j] == "\\" else 1
+            for k in range(i + 1, min(j, n)):
+                if out[k] != "\n":
+                    out[k] = " "
+            i = j + 1
+        else:
+            i += 1
+    return "".join(out)
+
+
+def split_args(src: str, open_idx: int):
+    """Args of the call whose '(' is at open_idx -> (list of arg strings, index after ')')."""
+    depth, args, cur, i = 0, [], [], open_idx
+    while i < len(src):
+        c = src[i]
+        if c in "([{":
+            depth += 1
+            if depth > 1:
+                cur.append(c)
+        elif c in ")]}":
+            depth -= 1
+            if depth == 0:
+                args.append("".join(cur).strip())
+                return [a for a in args if a != "" or len(args) > 1], i + 1
+            cur.append(c)
+        elif c == "," and depth == 1:
+            args.append("".join(cur).strip())
+            cur = []
+        else:
+            cur.append(c)
+        i += 1
+    return None, i
+
+
+def parse_defines(files: list) -> dict:
+    """NAME -> (params|None, body, file, line) for every #define in the given headers."""
+    out: dict = {}
+    rx = re.compile(r"^[ \t]*#[ \t]*define[ \t]+(\w+)(\([^)]*\))?[ \t]*(.*)$")
+    for f in files:
+        try:
+            text = strip_comments(open(f, encoding="utf-8", errors="replace").read())
+        except OSError:
+            continue
+        lines = text.split("\n")
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+            start = i
+            while line.endswith("\\") and i + 1 < len(lines):
+                i += 1
+                line = line[:-1] + " " + lines[i]
+            m = rx.match(line)
+            if m:
+                params = [p.strip() for p in m.group(2)[1:-1].split(",")] if m.group(2) else None
+                out.setdefault(m.group(1), (params, m.group(3).strip(), f, start + 1))
+            i += 1
+    return out
+
+
+class Auditor:
+    def __init__(self, project: Project, defines: dict):
+        self.p = project
+        self.defines = defines
+        self.findings: list = []
+        self.unchecked: list = []
+        self.calls = 0
+        self._handles: dict = {}
+
+    # ---------- ECUC lookups ----------
+    def module(self, name: str) -> list:
+        return [m for m in self.p.modules if (m.def_ref or "").rsplit("/", 1)[-1] == name or m.name == name]
+
+    def containers(self, module: str, defnames: tuple) -> list:
+        out = []
+        for m in self.module(module):
+            stack = list(m.children)
+            while stack:
+                e = stack.pop()
+                stack.extend(e.children)
+                if (e.def_ref or "").rsplit("/", 1)[-1] in defnames:
+                    out.append(e)
+        return out
+
+    def val(self, e: Elem, name: str) -> Optional[str]:
+        for g in self.p.find(e.path):
+            for pv in g.params:
+                if pv.name == name:
+                    return pv.value
+        return None
+
+    def by_handle(self, api: Api, num: int) -> list:
+        key = (api.module, api.defs)
+        if key not in self._handles:
+            idx: dict = {}
+            for e in self.containers(api.module, api.defs):
+                v = parse_int(self.val(e, api.handle_param) or "")
+                if v is not None:
+                    idx.setdefault(v, []).append(e)
+            self._handles[key] = idx
+        return self._handles[key].get(num, [])
+
+    def by_symbol(self, api: Api, sym: str) -> Optional[Elem]:
+        m = SYM.match(sym)
+        if not m:
+            return None
+        mod, dname, short = m.groups()
+        if mod != api.module:
+            return None
+        for e in self.containers(api.module, (dname,)):
+            if e.name == short:
+                return e
+        return None
+
+    def symbol_of(self, e: Elem, api: Api) -> str:
+        return f"{api.module}Conf_{(e.def_ref or '').rsplit('/', 1)[-1]}_{e.name}"
+
+    def ipdus_of(self, sig: Elem) -> list:
+        """I-PDUs that reference this signal (or, for a group signal, its signal group)."""
+        targets = {sig.path}
+        if (sig.def_ref or "").endswith("/ComGroupSignal") and sig.parent is not None:
+            targets = {sig.parent.path}
+        out = []
+        for ip in self.containers("Com", ("ComIPdu",)):
+            for g in self.p.find(ip.path):
+                if any(pv.is_ref and pv.name in ("ComIPduSignalRef", "ComIPduSignalGroupRef") and (pv.value or "").strip() in targets
+                       for pv in g.params):
+                    out.append(ip)
+                    break
+        return out
+
+    # ---------- findings ----------
+    def add(self, rule, sev, f, line, call, msg, cite, evidence, fix=None):
+        d = {"rule": rule, "severity": sev, "file": self.p.rel(f), "line": line, "call": call,
+             "message": msg, "cite": cite, "evidence": evidence}
+        if fix:
+            d["fix"] = fix
+        self.findings.append(d)
+
+    # ---------- per call ----------
+    def handle_value(self, expr: str):
+        """-> ("num", int) | ("sym", name, resolved_int|None) | ("expr", text)."""
+        e = expr.strip()
+        m = NUM.match(e)
+        if m:
+            return ("num", int(m.group(1), 0))
+        while e.startswith("(") and e.endswith(")") and split_args("x" + e, 1)[1] == len(e) + 1:
+            e = e[1:-1].strip()
+        if re.fullmatch(r"\w+", e):
+            d = self.defines.get(e)
+            num = None
+            if d and d[0] is None:
+                mm = NUM.match(d[1])
+                num = int(mm.group(1), 0) if mm else None
+            return ("sym", e, num)
+        return ("expr", e)
+
+    def audit_call(self, f: str, line: int, name: str, args: list, unit: str, via: Optional[str] = None):
+        if name.startswith("Rte_"):
+            self.audit_rte(f, line, name, args, unit)
+            return
+        api = APIS.get(name) or (PDUR if name.startswith("PduR_") else None)
+        if api is None or not args:
+            return
+        self.calls += 1
+        call = f"{name}({', '.join(args)})" + (f" via {via}" if via else "")
+        h = self.handle_value(args[0])
+        target: Optional[Elem] = None
+        cite_sym = "TPS_ECUC_02108 symbolic name values"
+        if h[0] == "num":
+            hits = self.by_handle(api, h[1])
+            if not hits:
+                self.add("H2L-API-002", "error", f, line, call,
+                         f"handle {args[0]} matches no {'/'.join(api.defs)} with {api.handle_param}={h[1]}",
+                         f"{api.cite}; {cite_sym}", {"handleParam": api.handle_param, "value": h[1]})
+                return
+            target = hits[0]
+            sym = self.symbol_of(target, api)
+            self.add("H2L-API-001", "warning", f, line, call,
+                     f"raw numeric handle {args[0]} = {target.path} ({api.handle_param}={h[1]}); use {sym} so the call "
+                     "survives handle re-assignment", f"{cite_sym}; TPS_ECUConfiguration 3.4.1.1",
+                     {"path": target.path, api.handle_param: h[1]}, fix=f"replace {args[0]} with {sym}")
+        elif h[0] == "sym":
+            target = self.by_symbol(api, h[1])
+            if target is None and h[2] is not None:
+                hits = self.by_handle(api, h[2])
+                target = hits[0] if hits else None
+            if target is None:
+                if SYM.match(h[1]) or h[2] is not None:
+                    self.add("H2L-API-002", "error", f, line, call,
+                             f"handle {h[1]} resolves to no configured {'/'.join(api.defs)} in {api.module}",
+                             f"{api.cite}; {cite_sym}", {"symbol": h[1], "define": h[2]})
+                else:
+                    self.unchecked.append({"file": self.p.rel(f), "line": line, "call": call,
+                                           "reason": f"handle {h[1]} is not a configured symbol or constant"})
+                return
+        else:
+            self.unchecked.append({"file": self.p.rel(f), "line": line, "call": call, "reason": "handle is an expression"})
+            return
+        if api.kind in ("send", "receive"):
+            self.check_direction(f, line, call, api, target)
+            if api.data is not None and len(args) > api.data:
+                self.check_width(f, line, call, target, args[api.data], unit)
+        if api.kind == "nvm" and api.data is not None and len(args) > api.data:
+            self.check_nvm_null(f, line, call, name, target, args[api.data])
+
+    def audit_rte(self, f, line, name, args, unit):
+        d = self.defines.get(name)
+        if d is None or d[0] is None:
+            self.unchecked.append({"file": self.p.rel(f), "line": line, "call": f"{name}(...)",
+                                   "reason": "RTE API not a macro in the generated headers (function-mapped)"})
+            return
+        params, body = d[0], d[1]
+        subst = body
+        for prm, arg in zip(params, args):
+            subst = re.sub(rf"\b{re.escape(prm)}\b", lambda _m, a=arg: f"({a})", subst)
+        clean = strip_comments(subst)
+        for m in CALL.finditer(clean):
+            inner, _ = split_args(clean, m.end() - 1)
+            if inner is not None and not m.group(1).startswith("Rte_"):
+                self.audit_call(f, line, m.group(1), inner, unit, via=f"{name} ({self.p.rel(d[2])}:{d[3]})")
+
+    def check_direction(self, f, line, call, api, sig):
+        ipdus = self.ipdus_of(sig)
+        dirs = [(ip, (self.val(ip, "ComIPduDirection") or "").strip()) for ip in ipdus]
+        want = "SEND" if api.kind == "send" else "RECEIVE"
+        bad = [(ip, d) for ip, d in dirs if d and d != want]
+        if bad and not any(d == want for _, d in dirs):
+            ip, d = bad[0]
+            self.add("H2L-API-003", "error", f, line, call,
+                     f"{sig.name} belongs to I-PDU {ip.name} with ComIPduDirection={d}; {call.split('(')[0]} needs a "
+                     f"{want} signal (Com returns COM_SERVICE_NOT_AVAILABLE / E_NOT_OK)",
+                     f"ECUC_Com_00493 ComIPduDirection; {api.cite}",
+                     {"signal": sig.path, "ipdu": ip.path, "ComIPduDirection": d})
+
+    def c_type(self, expr: str, unit: str):
+        """Type of the object a data-pointer argument points to -> (type, array_len|None), or None if unknown."""
+        e = expr.strip()
+        while e.startswith("(") and e.endswith(")") and split_args("x" + e, 1)[1] == len(e) + 1:
+            e = e[1:-1].strip()
+        lit = re.fullmatch(r"&\s*\(\s*(\w+)\s*\)\s*\{.*\}", e, re.S)  # &(uint8){ x }
+        if lit:
+            return lit.group(1), None
+        ref = re.fullmatch(r"&\s*(\w+)", e)  # &var
+        elem = re.fullmatch(r"&\s*(\w+)\s*\[[^\]]*\]", e)  # &buf[i]
+        bare = re.fullmatch(r"(\w+)", e)  # buf (array decays) or a pointer variable
+        var = (ref or elem or bare).group(1) if (ref or elem or bare) else None
+        if var is None:
+            return None
+        decl = re.search(rf"\b(?:(?:static|volatile|const|extern)\s+)*(\w+)\s+(?:const\s+)?{re.escape(var)}"
+                         rf"\s*(\[\s*(\w*)\s*\])?\s*[;=,)]", unit)
+        if not decl or decl.group(1) in ("return", "else", "case", "goto", "sizeof", "struct", "union", "enum"):
+            return None
+        is_array = bool(decl.group(2))
+        if ref:
+            return decl.group(1), (decl.group(3) if is_array else None)
+        if elem or (bare and is_array):
+            return decl.group(1), None
+        return None  # bare non-array variable: a pointer whose pointee is not visible here
+
+    def check_width(self, f, line, call, sig, arg, unit):
+        typ = (self.val(sig, "ComSignalType") or "").strip()
+        if typ in ("UINT8_N", "UINT8_DYN"):
+            self.unchecked.append({"file": self.p.rel(f), "line": line, "call": call, "reason": f"array signal type {typ}"})
+            return
+        expect = SIG_BITS.get(typ)
+        ct = self.c_type(arg, unit)
+        if expect is None or ct is None or ct[0] not in TYPE_BITS:
+            self.unchecked.append({"file": self.p.rel(f), "line": line, "call": call,
+                                   "reason": f"width unknown (C type {ct[0] if ct else '?'}, ComSignalType {typ or '?'})"})
+            return
+        cbits = TYPE_BITS[ct[0]]
+        if ct[1]:
+            n = parse_int(ct[1])
+            cbits = cbits * n if n is not None else cbits
+        if cbits != expect:
+            bs = self.val(sig, "ComBitSize")
+            self.add("H2L-API-004", "error", f, line, call,
+                     f"{arg} is a {ct[0]}{'[' + ct[1] + ']' if ct[1] else ''} ({cbits} bits) but {sig.name} is "
+                     f"ComSignalType={typ} ({expect // 8}-byte object, ComBitSize={bs}); Com accesses {expect // 8} "
+                     f"byte(s) at that address — wrong signal or wrong variable",
+                     "SWS_Com_00197/00198 SignalDataPtr points to an object of the ComSignalType; ECUC_Com_00127 ComSignalType",
+                     {"signal": sig.path, "ComSignalType": typ, "ComBitSize": bs, "cType": ct[0]})
+
+    def check_nvm_null(self, f, line, call, name, blk, arg):
+        if arg.replace(" ", "") not in NULLS:
+            return
+        ram = (self.val(blk, "NvMRamBlockDataAddress") or "").strip()
+        sync = (self.val(blk, "NvMBlockUseSyncMechanism") or "").strip().lower() in ("true", "1")
+        if ram or sync:
+            return  # valid: SWS_NvM_00898/00900 (permanent RAM) or 00899/00901 (explicit sync)
+        self.add("H2L-API-005", "error", f, line, call,
+                 f"{name} with NULL_PTR on {blk.name}, which has no permanent RAM block (NvMRamBlockDataAddress unset) and "
+                 "no explicit synchronization; NvM rejects the request (DET parameter error)",
+                 "SWS_NvM_00898/00899 (ReadBlock), SWS_NvM_00900/00901 (WriteBlock), SWS_NvM_00278/00280",
+                 {"block": blk.path, "NvMRamBlockDataAddress": None, "NvMBlockUseSyncMechanism": sync})
+
+
+def audit(project: Project, paths_arg: Optional[list] = None, headers_arg: Optional[list] = None) -> dict:
+    root = project.root
+    cfg = {}
+    try:
+        import json
+        with open(os.path.join(root, ".hydron", "autosar.json")) as fh:
+            raw = json.load(fh).get("audit")
+            cfg = raw if isinstance(raw, dict) else ({"paths": raw} if isinstance(raw, list) else {})
+    except (OSError, ValueError):
+        pass
+    explicit = paths_arg or cfg.get("paths")
+    notes: list = []
+    tree = paths.walk(root, paths.is_c)
+    notes.extend(tree.notes(root))
+    if explicit:
+        scan = paths.expand(root, explicit, paths.is_c)
+        for p in paths.patterns(root, explicit):
+            if not p.expand(paths.is_c):
+                notes.append(f"audit path {p.raw!r} matched no C file under {root}")
+        sources = [f for f in scan if f.lower().endswith(".c")]
+        generated = []
+    else:  # whole tree, minus generator output (recognised by the file, not the folder)
+        cfiles = [f for f in tree.files if f.lower().endswith(".c")]
+        generated = [f for f in cfiles if is_generated(f)]
+        gen = set(generated)
+        sources = [f for f in cfiles if f not in gen]
+    extra = paths.expand(root, headers_arg or cfg.get("headers") or [], paths.is_c)
+    hdrs = sorted({f for f in tree.files + extra if f.lower().endswith(".h")})
+    a = Auditor(project, parse_defines(hdrs))
+    for f in sources:
+        try:
+            unit = strip_comments(open(f, encoding="utf-8", errors="replace").read())
+        except OSError:
+            continue
+        for m in CALL.finditer(unit):
+            ls = unit.rfind("\n", 0, m.start()) + 1
+            if unit[ls:m.start()].lstrip().startswith("#"):
+                continue  # macro definition, not a call
+            before = unit[ls:m.start()].rstrip()
+            prev = re.search(r"(\w+)\s*$", before)
+            if prev and prev.group(1) not in ("return", "void") and not before.endswith(")"):
+                continue  # a declaration/prototype ("Std_ReturnType Com_SendSignal(")
+            args, _ = split_args(unit, m.end() - 1)
+            if args is None:
+                continue
+            a.audit_call(f, unit.count("\n", 0, m.start()) + 1, m.group(1), args, unit)
+    a.findings.sort(key=lambda d: (d["file"], d["line"], d["rule"]))
+    summary: dict = {}
+    for d in a.findings:
+        summary[d["severity"]] = summary.get(d["severity"], 0) + 1
+    res = {"scanned": {"sources": [project.rel(f) for f in sources], "headers": len(hdrs), "calls": a.calls,
+                       "generatedSkipped": len(generated)},
+           "summary": summary, "findings": a.findings, "unchecked": a.unchecked}
+    if notes:
+        res["notes"] = notes
+    if explicit and not sources:
+        res["error"] = (f"audit paths {list(explicit)} matched no .c file under {root}; nothing was audited. "
+                        "Pass files, directories or globs relative to the project root, or omit paths.")
+    return res
+
+
+def signal_owners(project: Project, paths: list) -> dict:
+    """AUTOSAR path of a ComSignal / ComGroupSignal -> [{ipdu, direction, pdu}] from the local ECUC."""
+    a = Auditor(project, {})
+    out: dict = {}
+    for p in paths:
+        g = project.find(p)
+        if not g:
+            out[p] = None  # not in the local checkout
+            continue
+        sig = g[0]
+        if not (sig.def_ref or "").endswith(("/ComSignal", "/ComGroupSignal", "/ComSignalGroup")):
+            continue
+        out[p] = [{"ipdu": ip.path, "direction": (a.val(ip, "ComIPduDirection") or "").strip() or None,
+                   "pdu": (a.val(ip, "ComPduIdRef") or "").strip() or None} for ip in a.ipdus_of(sig)]
+    return out

package/python/ecuc_engine/cli.py

@@ -0,0 +1,125 @@
+"""CLI: python -m ecuc_engine [--root DIR] <info|read|edit|validate|diff> ... --json
+
+Always prints one JSON object on stdout. {"ok": false, "error": ...} on failure (exit code 0 for
+handled errors, so callers parse stdout rather than the status).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+from . import ENGINE_VERSION
+
+
+def _ops(arg: str):
+    if arg.startswith("@"):
+        with open(arg[1:]) as f:
+            arg = f.read()
+    if arg == "-":
+        arg = sys.stdin.read()
+    ops = json.loads(arg)
+    for _ in range(3):  # tolerate JSON that was encoded more than once ("[{...}]" as a string)
+        if isinstance(ops, str):
+            ops = json.loads(ops)
+    if isinstance(ops, dict) and isinstance(ops.get("ops"), (list, str)):
+        return _ops(json.dumps(ops["ops"]))
+    return ops if isinstance(ops, list) else [ops]
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="ecuc_engine")
+    ap.add_argument("--root", default=os.getcwd(), help="project root (default: cwd)")
+    ap.add_argument("--defs", action="append", help="param-def file/dir/glob (overrides discovery)")
+    ap.add_argument("--config", action="append", help="ECUC value file/dir/glob (overrides discovery)")
+    ap.add_argument("--json", action="store_true", help="JSON output (always on; accepted for clarity)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("info")
+    r = sub.add_parser("read")
+    r.add_argument("path", nargs="?")
+    r.add_argument("--depth", type=int, default=2)
+    r.add_argument("--schema", action="store_true")
+    e = sub.add_parser("edit")
+    e.add_argument("--ops", required=True, help="JSON op or list, @file, or - for stdin")
+    e.add_argument("--dry-run", action="store_true")
+    e.add_argument("--force", action="store_true")
+    e.add_argument("--no-validate", action="store_true")
+    v = sub.add_parser("validate")
+    v.add_argument("--file", action="append")
+    v.add_argument("--module")
+    v.add_argument("--max", type=int, default=0, help="cap the number of diagnostics returned (0 = all)")
+    au = sub.add_parser("audit")
+    au.add_argument("paths", nargs="*", help="C files/dirs to scan (default: audit.paths in .hydron/autosar.json, else Source/)")
+    au.add_argument("--headers", action="append", help="generated header dirs for symbols and RTE macros (default Output/)")
+    so = sub.add_parser("signal-owners")
+    so.add_argument("paths", nargs="+")
+    d = sub.add_parser("diff")
+    d.add_argument("a")
+    d.add_argument("b")
+    for p in (r, e, v, d, au, so):  # allow --json after the subcommand too
+        p.add_argument("--json", action="store_true", help=argparse.SUPPRESS)
+    a = ap.parse_args(argv)
+    t0 = time.time()
+    try:
+        res = run(a)
+    except Exception as ex:  # noqa: BLE001
+        res = {"ok": False, "error": f"{type(ex).__name__}: {ex}"}
+    res.setdefault("ok", "error" not in res)
+    res["engine"] = ENGINE_VERSION
+    res["ms"] = int((time.time() - t0) * 1000)
+    sys.stdout.write(json.dumps(res, ensure_ascii=False, indent=None if a.json else 1, default=str) + "\n")
+    return 0
+
+
+def run(a) -> dict:
+    if a.cmd == "edit":
+        try:
+            a.ops = _ops(a.ops)
+        except (ValueError, OSError) as ex:
+            return {"error": f"ops is not valid JSON: {ex}"}
+    if a.cmd == "diff":
+        from .diff import diff
+        root = os.path.abspath(a.root)
+        rel = lambda f: os.path.relpath(f, root) if not os.path.relpath(f, root).startswith("..") else f  # noqa: E731
+        try:
+            return diff(a.a, a.b, rel, root)
+        except FileNotFoundError as ex:
+            return {"error": str(ex)}
+    from .model import Project
+    project = Project(a.root, config_files=a.config, def_files=a.defs, load_input=a.cmd in ("validate", "edit"))
+    if a.cmd == "signal-owners":
+        from .audit import signal_owners
+        return {"owners": signal_owners(project, a.paths)}
+    if a.cmd == "audit":
+        from .audit import audit
+        res = audit(project, paths_arg=a.paths or None, headers_arg=a.headers)
+        if project.warnings:
+            res["warnings"] = project.warnings
+        return res
+    if a.cmd == "info":
+        s = project.sources
+        return {"root": s.root, "origin": s.origin, "config": [project.rel(f) for f in s.config],
+                "paramDefs": [project.rel(f) for f in s.defs], "input": [project.rel(f) for f in s.input][:200],
+                "defModules": len(project.defs.modules), "modules": sorted({m.name for m in project.modules}),
+                "warnings": project.warnings}
+    if a.cmd == "read":
+        from .ecucjson import read
+        return read(project, a.path, depth=a.depth, schema=a.schema)
+    if a.cmd == "edit":
+        from .edit import edit
+        res = edit(project, a.ops, dry_run=a.dry_run, force=a.force, run_validate=not a.no_validate)
+        if project.warnings:
+            res["warnings"] = project.warnings
+        return res
+    if a.cmd == "validate":
+        from .validate import validate
+        res = validate(project, files=a.file, module=a.module)
+        if a.max and len(res["diagnostics"]) > a.max:
+            res["truncated"] = len(res["diagnostics"]) - a.max
+            res["diagnostics"] = res["diagnostics"][: a.max]
+        if project.warnings:
+            res["warnings"] = project.warnings
+        return res
+    return {"error": f"unknown command {a.cmd}"}