@anik-2/autosar 0.0.0-stage → 0.1.1

package/python/ecuc_engine/validate.py

@@ -0,0 +1,227 @@
+"""Mechanical ECUC checks, derived from the param defs only (no hand-written module rules).
+
+Diagnostics are LSP-like: {file, line, path, rule, severity, message, defRef}.
+Rules:
+  ECUC-NO-DEF            module's definition is not among the loaded param defs (module skipped)
+  ECUC-UNKNOWN-DEF       container / parameter / reference whose DEFINITION-REF is not in the module def
+  ECUC-WRONG-PARENT      container's def is not a child of its parent's def
+  ECUC-DEST-MISMATCH     DEFINITION-REF DEST attribute differs from the def element type
+  ECUC-VALUE-TYPE        NUMERICAL vs TEXTUAL value element does not match the def kind
+  ECUC-MULT-CONTAINER    sub-container count outside the def multiplicity (incl. missing mandatory)
+  ECUC-CHOICE            choice container does not hold exactly one choice
+  ECUC-MULT-PARAM        parameter / reference count outside the def multiplicity
+  ECUC-MISSING-PARAM     mandatory parameter / reference absent
+  ECUC-TYPE / ECUC-RANGE / ECUC-ENUM / ECUC-STRING / ECUC-EMPTY-VALUE   value checks
+  ECUC-REF-DANGLING      reference target does not exist
+  ECUC-REF-DEST          reference target is of the wrong definition / metaclass
+  ECUC-REF-UNRESOLVED    foreign reference target not in any loaded file (warning)
+  ECUC-DUP-NAME          two containers with the same AUTOSAR path
+  ECUC-OBSOLETE          value for an obsolete def (warning)
+Hand-written semantic rules (ecuc_engine/rules, ids H2L-*) run afterwards, with or without defs.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from . import defs as D
+from .model import Project
+from .values import check_value, expected_value_tag
+
+GENERIC_CONTAINER_DESTS = {"ECUC-CONTAINER-DEF"}
+SEV_ORDER = {"error": 0, "warning": 1, "info": 2, "hint": 3}
+
+
+class Diags:
+    def __init__(self, project: Project):
+        self.p = project
+        self.items: list = []
+
+    def add(self, file, line, path, rule, severity, message, def_ref=None):
+        self.items.append({"file": self.p.rel(file), "line": line, "path": path, "rule": rule,
+                           "severity": severity, "message": message, "defRef": def_ref})
+
+
+def _same_def(defs: D.DefIndex, a: Optional[str], b: Optional[str]) -> bool:
+    if not a or not b:
+        return False
+    return a == b or defs.rel(a) == defs.rel(b)
+
+
+def _resolve_def(defs: D.DefIndex, ref: Optional[str]) -> Optional[D.DefNode]:
+    if not ref:
+        return None
+    d = defs.get(ref)
+    if d is not None:
+        return d
+    # vendor-relocated path (/Vendor/Com/... vs /AUTOSAR/EcucDefs/Com/...): match by module-relative path
+    rel = defs.rel(ref)
+    for m in defs.modules.values():
+        if rel.split("/", 1)[0] == m.name:
+            return defs.get(m.path + rel[len(m.name):])
+    return None
+
+
+def validate(project: Project, files: Optional[list] = None, module: Optional[str] = None) -> dict:
+    defs = project.defs
+    dg = Diags(project)
+    warned_modules = set()
+    visited = set()
+
+    def fmult(lo, up):
+        return f"{lo}..{'*' if up is None else up}"
+
+    def check_elem_group(path: str):
+        if path in visited:
+            return
+        visited.add(path)
+        group = project.find(path)
+        e0 = group[0]
+        if e0.kind == "container" and len(group) > 1:
+            for e in group[1:]:
+                dg.add(e.file, e.line, path, "ECUC-DUP-NAME", "error",
+                       f"duplicate container path {path} (also at {project.rel(e0.file)}:{e0.line})", e.def_ref)
+        d = _resolve_def(defs, e0.def_ref)
+        if d is None:
+            if e0.kind == "module":
+                key = e0.def_ref or path
+                if key not in warned_modules:
+                    warned_modules.add(key)
+                    dg.add(e0.file, e0.line, path, "ECUC-NO-DEF", "warning",
+                           f"no param def loaded for {e0.def_ref}; module not validated", e0.def_ref)
+            else:
+                dg.add(e0.file, e0.line, path, "ECUC-UNKNOWN-DEF", "error",
+                       f"container definition {e0.def_ref} does not exist in the loaded param defs", e0.def_ref)
+            return
+        if e0.def_dest and e0.def_dest != d.tag and not (e0.def_dest in GENERIC_CONTAINER_DESTS and d.is_container):
+            dg.add(e0.file, e0.line, path, "ECUC-DEST-MISMATCH", "warning",
+                   f"DEFINITION-REF DEST={e0.def_dest} but the def is {d.tag}", d.path)
+        if e0.kind == "container" and e0.parent is not None:
+            pd = _resolve_def(defs, e0.parent.def_ref)
+            if pd is not None and d.parent != pd.path:
+                dg.add(e0.file, e0.line, path, "ECUC-WRONG-PARENT", "error",
+                       f"{d.name} is not a sub-container of {pd.name} (allowed: "
+                       f"{', '.join(defs.by_path[c].name for c in pd.containers) or 'none'})", d.path)
+        if d.obsolete:
+            dg.add(e0.file, e0.line, path, "ECUC-OBSOLETE", "warning", f"{d.name} is obsolete", d.path)
+
+        # children (merged across split fragments)
+        children = [c for e in group for c in e.children]
+        params = [(e, pv) for e in group for pv in e.params]
+        counts: dict = {}
+        seen_child_paths = set()
+        for c in children:
+            if c.path in seen_child_paths:
+                continue
+            seen_child_paths.add(c.path)
+            cd = _resolve_def(defs, c.def_ref)
+            if cd is not None:
+                counts[cd.path] = counts.get(cd.path, 0) + 1
+        if d.tag == D.CHOICE_TAG:
+            n = sum(counts.get(c, 0) for c in d.containers)
+            if n != 1:
+                dg.add(e0.file, e0.line, path, "ECUC-CHOICE", "error",
+                       f"choice container {d.name} holds {n} choices, needs exactly 1 of "
+                       f"{', '.join(defs.by_path[c].name for c in d.containers)}", d.path)
+        else:
+            for cpath in d.containers:
+                cd = defs.by_path[cpath]
+                n = counts.get(cpath, 0)
+                if n < cd.lower or (cd.upper is not None and n > cd.upper):
+                    dg.add(e0.file, e0.line, path, "ECUC-MULT-CONTAINER", "error",
+                           f"{d.name} '{e0.name}': {cd.name} has {n} instance(s), def requires {fmult(cd.lower, cd.upper)}",
+                           cd.path)
+        pcounts: dict = {}
+        for e, pv in params:
+            pd = _resolve_def(defs, pv.def_ref)
+            line = pv.node.line
+            if pd is None or pd.parent != d.path:
+                dg.add(e.file, line, path, "ECUC-UNKNOWN-DEF", "error",
+                       f"parameter/reference {pv.def_ref} is not defined for {d.name}", pv.def_ref)
+                continue
+            pcounts[pd.path] = pcounts.get(pd.path, 0) + 1
+            if pd.obsolete:
+                dg.add(e.file, line, path, "ECUC-OBSOLETE", "warning", f"{pd.name} is obsolete", pd.path)
+            if pv.def_dest and pv.def_dest != pd.tag:
+                dg.add(e.file, line, path, "ECUC-DEST-MISMATCH", "warning",
+                       f"{pd.name}: DEFINITION-REF DEST={pv.def_dest} but the def is {pd.tag}", pd.path)
+            exp = expected_value_tag(pd)
+            if exp and pv.tag != exp:
+                dg.add(e.file, line, path, "ECUC-VALUE-TYPE", "warning",
+                       f"{pd.name} is a {pd.kind} def; value element should be {exp}, found {pv.tag}", pd.path)
+            if D.is_ref_kind(pd.kind or ""):
+                check_ref(e, pv, pd, path, line)
+            elif pd.kind != "ADD-INFO" and not pv.is_auto:
+                for rule, msg in check_value(pd, pv.value):
+                    sev = "warning" if rule == "ECUC-EMPTY-VALUE" else "error"
+                    dg.add(e.file, (pv.value_node or pv.node).line, path, rule, sev, f"{d.name} '{e0.name}': {msg}", pd.path)
+        for ppath in d.params + d.refs:
+            pd = defs.by_path[ppath]
+            n = pcounts.get(ppath, 0)
+            if n == 0 and pd.lower > 0:
+                dg.add(e0.file, e0.line, path, "ECUC-MISSING-PARAM", "error",
+                       f"{d.name} '{e0.name}': mandatory {pd.name} ({pd.kind}, {pd.mult}) is missing", pd.path)
+            elif n < pd.lower or (pd.upper is not None and n > pd.upper):
+                dg.add(e0.file, e0.line, path, "ECUC-MULT-PARAM", "error",
+                       f"{d.name} '{e0.name}': {pd.name} has {n} value(s), def requires {pd.mult}", pd.path)
+        for c in children:
+            check_elem_group(c.path)
+
+    def check_ref(e, pv, pd, path, line):
+        tgt = (pv.value or "").strip()
+        if pd.kind in ("INSTANCE-REFERENCE", "URI-REFERENCE"):
+            return
+        if not tgt:
+            dg.add(e.file, line, path, "ECUC-EMPTY-VALUE", "error", f"{pd.name}: empty reference", pd.path)
+            return
+        if pd.kind == "FOREIGN-REFERENCE":
+            hit = project.identifiables.get(tgt)
+            if hit is None:
+                if project.input_loaded:
+                    dg.add(e.file, line, path, "ECUC-REF-DANGLING", "error",
+                           f"{pd.name} -> {tgt}: target not found in any loaded ARXML", pd.path)
+                else:
+                    dg.add(e.file, line, path, "ECUC-REF-UNRESOLVED", "warning",
+                           f"{pd.name} -> {tgt}: target not in loaded files (add the System/SWC ARXML to "
+                           f"'input' in .hydron/autosar.json)", pd.path)
+                return
+            # DESTINATION-TYPE is often an abstract metaclass (RTE-EVENT for TIMING-EVENT), which needs the
+            # metamodel to check; the VALUE-REF DEST attribute must name the target's concrete type exactly.
+            if pv.dest and pv.dest != hit[0]:
+                dg.add(e.file, line, path, "ECUC-REF-DEST", "error",
+                       f"{pd.name} -> {tgt}: VALUE-REF DEST={pv.dest} but the target is a {hit[0]}", pd.path)
+            return
+        targets = project.find(tgt)
+        if not targets:
+            dg.add(e.file, line, path, "ECUC-REF-DANGLING", "error",
+                   f"{pd.name} -> {tgt}: no ECUC container with that path", pd.path)
+            return
+        t = targets[0]
+        if pd.dest_refs and not any(_same_def(defs, t.def_ref, dr) for dr in pd.dest_refs):
+            dg.add(e.file, line, path, "ECUC-REF-DEST", "error",
+                   f"{pd.name} -> {tgt} is a {t.def_ref.rsplit('/', 1)[-1] if t.def_ref else '?'}, def requires "
+                   f"{' or '.join(r.rsplit('/', 1)[-1] for r in pd.dest_refs)}", pd.path)
+
+    for m in project.modules:
+        if module and m.name != module and (m.def_ref or "").rsplit("/", 1)[-1] != module:
+            continue
+        check_elem_group(m.path)
+
+    from .rules import run_rules
+    dg.items.extend(run_rules(project))
+
+    items = dg.items
+    if files:
+        want = {project.rel(f) for f in files} | set(files)
+        items = [i for i in items if i["file"] in want]
+    items.sort(key=lambda i: (i["file"], i["line"], SEV_ORDER.get(i["severity"], 9), i["rule"]))
+    summary: dict = {}
+    for i in items:
+        summary[i["severity"]] = summary.get(i["severity"], 0) + 1
+    return {
+        "validated": bool(defs),
+        "rules": "semantic rule packs ran (H2L-*)",
+        "defsLoaded": len(defs.modules),
+        "modules": sorted({m.name for m in project.modules}),
+        "summary": summary,
+        "diagnostics": items,
+    }

package/python/ecuc_engine/values.py

@@ -0,0 +1,146 @@
+"""Typed value checks and ECUC-JSON value rendering, driven by the param def."""
+from __future__ import annotations
+
+import math
+import re
+from typing import Optional
+
+from .defs import DefNode
+
+C_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+BOOL_TRUE = {"true", "1"}
+BOOL_FALSE = {"false", "0"}
+JS_SAFE = 2 ** 53 - 1
+
+
+def parse_int(s: str) -> Optional[int]:
+    s = s.strip()
+    try:
+        return int(s, 0)
+    except ValueError:
+        try:
+            return int(s)  # leading zeros, e.g. "007"
+        except ValueError:
+            return None
+
+
+def parse_float(s: str) -> Optional[float]:
+    t = s.strip()
+    if t.upper() in ("INF", "+INF"):
+        return math.inf
+    if t.upper() == "-INF":
+        return -math.inf
+    try:
+        return float(t)
+    except ValueError:
+        iv = parse_int(t)
+        return float(iv) if iv is not None else None
+
+
+def _bound(s: Optional[str], f):
+    if s is None or s == "":
+        return None
+    return f(s)
+
+
+def check_value(d: DefNode, raw: Optional[str]) -> list:
+    """Return [(rule, message)] problems with ``raw`` against ``d``. Empty list = OK."""
+    if raw is None or raw == "":
+        return [("ECUC-EMPTY-VALUE", f"{d.name}: empty value")]
+    k = d.kind
+    out = []
+    if k == "INTEGER":
+        v = parse_int(raw)
+        if v is None:
+            return [("ECUC-TYPE", f"{d.name}: '{raw}' is not an integer")]
+        lo, hi = _bound(d.min, parse_int), _bound(d.max, parse_int)
+        if (lo is not None and v < lo) or (hi is not None and v > hi):
+            out.append(("ECUC-RANGE", f"{d.name}={raw} outside [{d.min}..{d.max}]"))
+    elif k == "FLOAT":
+        v = parse_float(raw)
+        if v is None or math.isnan(v):
+            return [("ECUC-TYPE", f"{d.name}: '{raw}' is not a float")]
+        lo, hi = _bound(d.min, parse_float), _bound(d.max, parse_float)
+        bad = (lo is not None and (v < lo or (d.min_open and v == lo))) or \
+              (hi is not None and (v > hi or (d.max_open and v == hi)))
+        if bad:
+            out.append(("ECUC-RANGE", f"{d.name}={raw} outside {'(' if d.min_open else '['}{d.min}..{d.max}{')' if d.max_open else ']'}"))
+    elif k == "BOOLEAN":
+        if raw.strip().lower() not in BOOL_TRUE | BOOL_FALSE:
+            out.append(("ECUC-TYPE", f"{d.name}: '{raw}' is not a boolean (true/false/1/0)"))
+    elif k == "ENUMERATION":
+        if d.literals and raw.strip() not in d.literals:
+            lits = ", ".join(d.literals[:20]) + (" …" if len(d.literals) > 20 else "")
+            out.append(("ECUC-ENUM", f"{d.name}: '{raw}' is not a literal of the def ({lits})"))
+    elif k in ("STRING", "FUNCTION-NAME", "LINKER-SYMBOL", "MULTILINE-STRING"):
+        if d.min_len is not None and len(raw) < d.min_len:
+            out.append(("ECUC-STRING", f"{d.name}: length {len(raw)} < min {d.min_len}"))
+        if d.max_len is not None and len(raw) > d.max_len:
+            out.append(("ECUC-STRING", f"{d.name}: length {len(raw)} > max {d.max_len}"))
+        if k in ("FUNCTION-NAME", "LINKER-SYMBOL") and not C_IDENT.match(raw.strip()):
+            out.append(("ECUC-STRING", f"{d.name}: '{raw}' is not a valid C identifier"))
+        if d.regex:
+            try:
+                if not re.fullmatch(d.regex, raw):
+                    out.append(("ECUC-STRING", f"{d.name}: '{raw}' does not match /{d.regex}/"))
+            except re.error:
+                pass
+    return out
+
+
+def expected_value_tag(d: DefNode) -> Optional[str]:
+    k = d.kind or ""
+    if k in ("INTEGER", "FLOAT", "BOOLEAN"):
+        return "ECUC-NUMERICAL-PARAM-VALUE"
+    if k in ("ENUMERATION", "STRING", "FUNCTION-NAME", "LINKER-SYMBOL", "MULTILINE-STRING"):
+        return "ECUC-TEXTUAL-PARAM-VALUE"
+    if k == "ADD-INFO":
+        return "ECUC-ADD-INFO-PARAM-VALUE"
+    if k == "INSTANCE-REFERENCE":
+        return "ECUC-INSTANCE-REFERENCE-VALUE"
+    if k.endswith("REFERENCE"):
+        return "ECUC-REFERENCE-VALUE"
+    return None
+
+
+def to_json(d: Optional[DefNode], raw: Optional[str], is_ref: bool, numerical: bool):
+    """Raw ARXML text -> compact JSON value (int/float/bool/str, refs as '->/path')."""
+    if raw is None:
+        return None
+    if is_ref:
+        return "->" + raw if raw.startswith("/") else raw
+    k = d.kind if d is not None else ("NUMBER" if numerical else None)
+    t = raw.strip()
+    if k == "BOOLEAN" or (k == "NUMBER" and t.lower() in ("true", "false")):
+        lo = t.lower()
+        return True if lo in BOOL_TRUE else False if lo in BOOL_FALSE else raw
+    if k in ("INTEGER", "NUMBER"):
+        v = parse_int(t)
+        if v is not None:
+            return v if abs(v) <= JS_SAFE and t == str(v) else t  # keep hex / huge as text
+        if k == "INTEGER":
+            return raw
+    if k in ("FLOAT", "NUMBER"):
+        v = parse_float(t)
+        if v is not None and math.isfinite(v):
+            return v
+        return raw
+    return raw
+
+
+def from_json(d: Optional[DefNode], v) -> str:
+    """JSON value from an edit op -> ARXML text."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        if isinstance(v, float) and v.is_integer() and d is not None and d.kind == "FLOAT":
+            return repr(v)
+        return str(v)
+    if v is None:
+        raise ValueError("null is not a value; use op 'remove' to delete a parameter")
+    s = str(v)
+    if s.startswith("->"):
+        s = s[2:]
+    if d is not None and d.kind == "BOOLEAN" and s.lower() in ("true", "false"):
+        s = s.lower()
+    return s

package/python/ecuc_engine/xmltree.py

@@ -0,0 +1,141 @@
+"""Byte-offset-preserving XML tree for ARXML.
+
+The engine never re-serialises a whole file. It parses with expat, records the byte span of every
+element (start tag, content, end tag) and the line it starts on, and later patches only the spans
+an edit touches. Comments, whitespace, attribute order, UUIDs and everything else outside the
+patched spans stay byte-identical.
+
+Namespace-agnostic: a prefixed tag (``ar:ECUC-CONTAINER-VALUE``) is stored without its prefix, so
+any AUTOSAR schema namespace (r4.0 or a later one) parses the same way.
+"""
+from __future__ import annotations
+
+import xml.parsers.expat as expat
+from typing import Iterator, Optional
+
+
+class Node:
+    __slots__ = ("tag", "attrs", "start", "stag_end", "end", "cstart", "cend", "line", "children", "parent", "_text")
+
+    def __init__(self, tag: str, attrs: dict, start: int, stag_end: int, line: int, parent: "Optional[Node]"):
+        self.tag = tag
+        self.attrs = attrs
+        self.start = start  # byte offset of '<'
+        self.stag_end = stag_end  # byte offset just after the start tag's '>'
+        self.end = stag_end  # byte offset just after the element (set on close)
+        self.cstart: Optional[int] = None  # content span (None for <X/>)
+        self.cend: Optional[int] = None
+        self.line = line
+        self.children: list[Node] = []
+        self.parent = parent
+        self._text: list[str] = []
+
+    @property
+    def text(self) -> str:
+        return "".join(self._text)
+
+    def child(self, tag: str) -> "Optional[Node]":
+        for c in self.children:
+            if c.tag == tag:
+                return c
+        return None
+
+    def child_text(self, tag: str) -> Optional[str]:
+        c = self.child(tag)
+        return c.text.strip() if c is not None else None
+
+    def iter(self) -> Iterator["Node"]:
+        stack = [self]
+        while stack:
+            n = stack.pop()
+            yield n
+            stack.extend(reversed(n.children))
+
+    @property
+    def short_name(self) -> Optional[str]:
+        return self.child_text("SHORT-NAME")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<Node {self.tag} {self.short_name or ''} @{self.line}>"
+
+
+def _local(name: str) -> str:
+    return name.rsplit(":", 1)[-1]
+
+
+def _stag_end(data: bytes, start: int) -> int:
+    """Index just past the '>' closing the start tag at ``start`` (quote-aware)."""
+    i = start + 1
+    n = len(data)
+    quote = 0
+    while i < n:
+        b = data[i]
+        if quote:
+            if b == quote:
+                quote = 0
+        elif b in (0x22, 0x27):  # " '
+            quote = b
+        elif b == 0x3E:  # >
+            return i + 1
+        i += 1
+    raise ValueError(f"unterminated start tag at byte {start}")
+
+
+def parse(data: bytes) -> Node:
+    """Parse ``data`` and return the document element with byte spans filled in."""
+    p = expat.ParserCreate()
+    p.buffer_text = True
+    stack: list[Node] = []
+    root: list[Node] = []
+
+    def start(name, attrs):
+        s = p.CurrentByteIndex
+        se = _stag_end(data, s)
+        node = Node(_local(name), {_local(k): v for k, v in attrs.items()}, s, se, p.CurrentLineNumber,
+                    stack[-1] if stack else None)
+        if stack:
+            stack[-1].children.append(node)
+        else:
+            root.append(node)
+        stack.append(node)
+
+    def end(name):
+        node = stack.pop()
+        if data[node.stag_end - 2] == 0x2F:  # '/' of '/>'
+            node.end = node.stag_end
+        else:
+            idx = p.CurrentByteIndex
+            node.cstart = node.stag_end
+            node.cend = idx
+            node.end = data.index(b">", idx) + 1
+
+    def chars(t):
+        if stack:
+            stack[-1]._text.append(t)
+
+    p.StartElementHandler = start
+    p.EndElementHandler = end
+    p.CharacterDataHandler = chars
+    p.Parse(data, True)
+    if not root:
+        raise ValueError("no root element")
+    return root[0]
+
+
+def escape(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def escape_attr(s: str) -> str:
+    return escape(s).replace('"', "&quot;")
+
+
+def line_indent(data: bytes, pos: int) -> Optional[bytes]:
+    """Whitespace between the previous newline and ``pos`` if it is all whitespace, else None."""
+    nl = data.rfind(b"\n", 0, pos)
+    seg = data[nl + 1:pos]
+    return seg if seg.strip() == b"" else None
+
+
+def line_of(data: bytes, pos: int) -> int:
+    return data.count(b"\n", 0, pos) + 1

package/python/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "ecuc-engine"
+version = "0.1.1"
+description = "Load, read, edit in place, validate and diff AUTOSAR ECUC ARXML (Hydron AUTOSAR pack)"
+requires-python = ">=3.10"
+# The core is stdlib-only; autosar-data adds a strict schema check of every edited file.
+dependencies = ["autosar-data==0.17.0"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/skills/autosar/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: autosar
+description: >-
+  AUTOSAR Classic integration expertise — ECUC configuration (ARXML), param defs, BSW module
+  config, code generation and build, and config-to-code tracing. Load it at the START of any task
+  that touches .arxml files, ECUC values/param defs, DEFINITION-REFs, a BSW module's configuration
+  (Com, PduR, CanIf, EcuC, Os, Rte, NvM, Dem, Dcm, …), generated Output/ code, or the vendor
+  configurator / SIP. It carries the tool map (ecuc_read/ecuc_edit/ecuc_validate/arxml_diff,
+  autosar_trace/autosar_config_lookup, autosar_generate/autosar_build), the edit → validate →
+  generate → build → trace loop, and the ECUC model rules needed to edit correctly.
+---
+# AUTOSAR skill — Classic Platform integration layer
+
+You are working on an AUTOSAR Classic ECU project. The configuration is ECUC ARXML; generated C
+in `Output/` is derived from it; in-house code in `Source/` calls the generated symbols.
+
+## Hard rules
+0. **Configured values are answered with `ecuc_read`** (it accepts a SHORT-NAME or partial path) or
+   `autosar_config_lookup` — not grep/read on ARXML. A value's AUTOSAR path is its `@path`; `@def` is its
+   DEFINITION-REF. Never give one when the other is asked.
+1. **Never hand-write or hand-edit ARXML** (no `write`/`edit`/`sed` on `.arxml`; the pack blocks them). Every change goes
+   through `ecuc_edit`, which picks the value element, DEFINITION-REF/DEST and VALUE-REF DEST from
+   the param defs and patches only the changed bytes. Reading raw ARXML for context is fine; prefer `ecuc_read`.
+2. **Validate after every edit**: `ecuc_validate` (scoped with `files`/`module` if large). Fix
+   every error you introduced before moving on; report pre-existing ones separately.
+3. **Cite** the AUTOSAR path, the DEFINITION-REF and file:line for every element you discuss or change.
+4. **Generated code is an output.** Never edit `Output/` (or other generated files) to fix a
+   problem — change the configuration and regenerate.
+5. Values come from the param defs (ranges, literals, multiplicity) and the SWS; when the defs do
+   not settle a question (cross-module consistency, handle IDs, timing), say so and cite the SWS
+   requirement rather than guessing.
+
+## Tool map
+| Need | Tool |
+|---|---|
+| What modules/files/defs exist | `ecuc_read` (no path) |
+| Values of a module/container | `ecuc_read path=… depth=…` |
+| What may be set/added here (types, ranges, literals, multiplicity) | `ecuc_read path=… schema=true`, or a def path `/AUTOSAR/EcucDefs/<Mod>/…` |
+| Change config | `ecuc_edit ops=[…]` (`dry_run` first for large edits) |
+| Check config | `ecuc_validate` |
+| Review a change / PR / two versions | `arxml_diff a b` |
+| Which C symbols does this config produce, who calls them / where does this symbol come from | `autosar_trace query=…` |
+| Refs in/out, children of an element in the ingested repo | `autosar_config_lookup path=…` |
+| Regenerate code | `autosar_generate` (configured command, asks permission) |
+| Compile/link | `autosar_build` |
+| Spec questions (SWS/TPS requirement text) | the project's ingested docs search tools |
+
+## The loop
+`ecuc_read (schema) → ecuc_edit → ecuc_validate → autosar_generate → arxml_diff / inspect Output → autosar_build → autosar_trace (impact on Source/)`.
+Details and failure handling: `references/workflow.md`.
+
+## References (load when relevant)
+- `references/ecuc-model.md` — module/container/param/ref values vs defs, DEFINITION-REF, ECUC JSON, multiplicity, choice containers, refs vs foreign refs.
+- `references/symbolic-names.md` — the symbolic-name rule (TPS_ECUC_02108) that links config to generated `#define`s, handle IDs.
+- `references/config-classes.md` — pre-compile / link-time / post-build config classes, variants, post-build loadable/selectable.
+- `references/project-layout.md` — Config / Input / Output / Source / Build / SIP and `.hydron/autosar.json`.
+- `references/workflow.md` — the edit → validate → generate → build → trace loop, diagnostics rules, and what to do when a step fails.
+
+## Reading diagnostics
+`file:line SEVERITY RULE path — message [def DEFINITION-REF]`. Rules: ECUC-MISSING-PARAM,
+ECUC-MULT-CONTAINER/-PARAM, ECUC-CHOICE, ECUC-RANGE, ECUC-ENUM, ECUC-TYPE, ECUC-STRING,
+ECUC-REF-DANGLING, ECUC-REF-DEST, ECUC-REF-UNRESOLVED (foreign target not loaded: add System/SWC
+ARXML to `input`), ECUC-UNKNOWN-DEF (often a release mismatch between config and param defs),
+ECUC-DUP-NAME, ECUC-NO-DEF (module defs not loaded → module not validated), ECUC-VALUE-TYPE,
+ECUC-DEST-MISMATCH, ECUC-OBSOLETE. These are mechanical checks from the defs.
+Semantic rule packs (run even without defs; each message carries its spec citation):
+H2L-COM-001 signal/update bit outside its I-PDU (ComBitPosition/ComBitSize vs EcuC PduLength*8),
+H2L-COM-002 overlapping signals in one I-PDU (Motorola numbering for BIG_ENDIAN; ComBitPosition = LSB),
+H2L-HID-001 duplicate handle IDs per module. Other SWS cross-module rules are not checked yet — reason
+about them explicitly.

package/skills/autosar/references/config-classes.md

@@ -0,0 +1,23 @@
+# Configuration classes and post-build
+
+Every param/ref def lists, per implementation variant, when its value is fixed
+(`VALUE-CONFIG-CLASSES` in recent releases):
+
+| Class | Fixed at | Generated as | Changing it needs |
+|---|---|---|---|
+| PRE-COMPILE | compile time | `#define`s in `<Mod>_Cfg.h` | regenerate + full rebuild |
+| LINK | link time | `const` data in `<Mod>_Lcfg.c` | regenerate + relink of that object |
+| POST-BUILD | after build (flash/load) | `const` tables in `<Mod>_PBcfg.c`, passed to `<Mod>_Init(ConfigPtr)` | regenerate post-build data only (if the project uses post-build loadable) |
+
+The module's `IMPLEMENTATION-CONFIG-VARIANT` (VARIANT-PRE-COMPILE / VARIANT-LINK-TIME /
+VARIANT-POST-BUILD) selects which class applies; it must be one of the module def's
+`SUPPORTED-CONFIG-VARIANTS`.
+
+**Post-build selectable** (several configuration sets in one image, chosen at init via
+`EcuM`/`<Mod>_Init` config pointer) and **post-build loadable** (configuration flashed separately)
+only allow changing values whose class is POST-BUILD for the selected variant, and multiplicity
+only where `MULTIPLICITY-CONFIG-CLASSES` allows it. `POST-BUILD-VARIANT-VALUE=true` means the value
+may differ between post-build variants (predefined variants / variation points).
+
+When proposing a change, state its class: a pre-compile change forces a full rebuild and a new
+software version; a post-build change may ship as a data update.

package/skills/autosar/references/ecuc-model.md

@@ -0,0 +1,42 @@
+# ECUC model basics
+
+**Definitions vs values.** Param defs (`ECUC-MODULE-DEF` trees: the AUTOSAR StMD
+`/AUTOSAR/EcucDefs/<Mod>` and vendor VSMD/BSWMD refinements) describe what may be configured.
+Values (`ECUC-MODULE-CONFIGURATION-VALUES`) are the configuration. Every value element points to
+its def through `DEFINITION-REF` (an AUTOSAR path); the `DEST` attribute names the def's metaclass.
+
+**Hierarchy.**
+- Module configuration → `CONTAINERS` → `ECUC-CONTAINER-VALUE` → `SUB-CONTAINERS` …
+- A container holds `PARAMETER-VALUES` (`ECUC-NUMERICAL-PARAM-VALUE` for integer/float/boolean,
+  `ECUC-TEXTUAL-PARAM-VALUE` for enum/string/function-name/linker-symbol) and `REFERENCE-VALUES`
+  (`ECUC-REFERENCE-VALUE` with `VALUE-REF DEST=…`, `ECUC-INSTANCE-REFERENCE-VALUE`).
+- A value's AUTOSAR path is the chain of SHORT-NAMEs: `/<Pkg>/<Module>/<Container>/…`. The def
+  path follows the *def* names: `/AUTOSAR/EcucDefs/Com/ComConfig/ComSignal`.
+
+**ECUC JSON** (what `ecuc_read` returns and `ecuc_edit add` accepts): containers keyed
+`"<DefName>:<ShortName>"` (just `"<Name>"` when equal), params by def short-name, multi-valued
+params as arrays, refs as `"->/path"`, `@path`/`@def`/`@at` metadata.
+
+**Multiplicity.** `LOWER/UPPER-MULTIPLICITY` (or `UPPER-MULTIPLICITY-INFINITE`) on every container,
+param and ref def. Lower ≥ 1 = mandatory. A **choice container** (`ECUC-CHOICE-CONTAINER-DEF`)
+must hold exactly one of its `CHOICES`.
+
+**Parameter kinds.** INTEGER (uint64-safe, MIN/MAX), FLOAT (MIN/MAX with OPEN/CLOSED interval,
+INF), BOOLEAN (`true`/`false`/`1`/`0`), ENUMERATION (literals), STRING / FUNCTION-NAME /
+LINKER-SYMBOL (length, regex, C identifiers), ADD-INFO, MULTILINE-STRING.
+
+**References.**
+- ECUC reference (`ECUC-REFERENCE-DEF`, choice/symbolic-name refs): target is another container
+  value whose DEFINITION-REF matches a `DESTINATION-REF` (e.g. `ComPduIdRef → EcuC/…/Pdu`).
+- Foreign reference (`ECUC-FOREIGN-REFERENCE-DEF`): target is a System/SWC element of the metaclass
+  in `DESTINATION-TYPE` (e.g. `I-SIGNAL-TO-I-PDU-MAPPING`); `VALUE-REF DEST` names the target's
+  concrete metaclass. Resolving it needs the System extract in `input`.
+- Instance references point into a component instance context; the engine reads but does not edit them.
+
+**Split files.** One module's configuration may be split across several files with the same
+module path; tools merge them for reading and edit each element in the file it lives in.
+
+**Releases.** The def metamodel drifts across releases (e.g. `VALUE-CONFIG-CLASSES` vs older
+`ECUC-IMPLEMENTATION-CONFIGURATION-CLASS`; params added/removed). Always validate against the
+param defs of the release the project's SIP targets; an ECUC-UNKNOWN-DEF burst usually means
+mismatched defs, not broken config.