@anik-2/autosar 0.0.0-stage → 0.1.1

package/python/ecuc_engine/defs.py

@@ -0,0 +1,330 @@
+"""ECUC parameter-definition model (StMD and vendor VSMD alike).
+
+Schema-free: every def kind is recognised by its tag suffix, so the loader works across AUTOSAR
+releases (R4.0 ... R25-11) without an XSD. A def is addressed by its AUTOSAR path, the chain of
+SHORT-NAMEs from the root package, which is exactly what a value's DEFINITION-REF holds.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+import pickle
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from typing import Optional
+
+from . import ENGINE_VERSION
+
+MODULE_TAG = "ECUC-MODULE-DEF"
+CONTAINER_TAGS = {"ECUC-PARAM-CONF-CONTAINER-DEF", "ECUC-CHOICE-CONTAINER-DEF"}
+CHOICE_TAG = "ECUC-CHOICE-CONTAINER-DEF"
+COLLECTIONS_CONTAINER = {"CONTAINERS", "SUB-CONTAINERS", "CHOICES"}
+
+NUMERICAL_KINDS = {"INTEGER", "FLOAT", "BOOLEAN"}
+TEXTUAL_KINDS = {"ENUMERATION", "STRING", "FUNCTION-NAME", "LINKER-SYMBOL", "MULTILINE-STRING"}
+ECUC_REF_KINDS = {"REFERENCE", "CHOICE-REFERENCE", "SYMBOLIC-NAME-REFERENCE"}
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def param_kind(tag: str) -> Optional[str]:
+    """ECUC-INTEGER-PARAM-DEF -> INTEGER; ECUC-FUNCTION-NAME-DEF -> FUNCTION-NAME; refs -> e.g. FOREIGN-REFERENCE."""
+    if not tag.startswith("ECUC-") or not tag.endswith("-DEF"):
+        return None
+    core = tag[5:-4]
+    if core.endswith("-PARAM"):
+        return core[:-6]
+    if core in ("FUNCTION-NAME", "LINKER-SYMBOL"):
+        return core
+    if core.endswith("-REFERENCE") or core == "REFERENCE":
+        return core
+    return None
+
+
+def is_ref_kind(kind: str) -> bool:
+    return kind.endswith("REFERENCE")
+
+
+@dataclass
+class DefNode:
+    path: str
+    tag: str
+    name: str
+    file: str
+    lower: int = 1
+    upper: Optional[int] = 1  # None = infinite
+    kind: Optional[str] = None  # params/refs only
+    min: Optional[str] = None
+    max: Optional[str] = None
+    min_open: bool = False
+    max_open: bool = False
+    literals: list = field(default_factory=list)
+    default: Optional[str] = None
+    regex: Optional[str] = None
+    min_len: Optional[int] = None
+    max_len: Optional[int] = None
+    dest_refs: list = field(default_factory=list)
+    dest_type: Optional[str] = None
+    with_auto: bool = False
+    symbolic_name: bool = False
+    obsolete: bool = False
+    trace: Optional[str] = None
+    containers: list = field(default_factory=list)  # child container def paths (incl. choices)
+    params: list = field(default_factory=list)  # child param def paths
+    refs: list = field(default_factory=list)  # child ref def paths
+    parent: Optional[str] = None
+    module: Optional[str] = None  # module def path
+
+    @property
+    def is_container(self) -> bool:
+        return self.tag in CONTAINER_TAGS or self.tag == MODULE_TAG
+
+    @property
+    def mult(self) -> str:
+        return f"{self.lower}..{'*' if self.upper is None else self.upper}"
+
+
+def _int(s: Optional[str], default):
+    try:
+        return int(s.strip()) if s is not None else default
+    except ValueError:
+        return default
+
+
+class DefIndex:
+    def __init__(self):
+        self.by_path: dict[str, DefNode] = {}
+        self.modules: dict[str, DefNode] = {}  # module def path -> node
+        self.files: list[str] = []
+
+    def __bool__(self):
+        return bool(self.modules)
+
+    def get(self, path: Optional[str]) -> Optional[DefNode]:
+        return self.by_path.get(path) if path else None
+
+    def module_of(self, def_path: str) -> Optional[DefNode]:
+        best = None
+        for mp, m in self.modules.items():
+            if (def_path == mp or def_path.startswith(mp + "/")) and (best is None or len(mp) > len(best.path)):
+                best = m
+        return best
+
+    def rel(self, def_path: str) -> str:
+        """Release/vendor-neutral form: '<ModuleName>/<rest>' (so /MICROSAR/Com/X == /AUTOSAR/EcucDefs/Com/X)."""
+        m = self.module_of(def_path)
+        if m is not None:
+            return m.name + def_path[len(m.path):]
+        parts = def_path.strip("/").split("/")
+        # Unknown module: fall back to dropping the conventional package prefix.
+        return "/".join(parts[2:]) if len(parts) > 2 else def_path
+
+    def merge(self, other: "DefIndex"):
+        self.by_path.update(other.by_path)
+        self.modules.update(other.modules)
+        self.files.extend(other.files)
+
+
+def _cache_path(path: str) -> str:
+    st = os.stat(path)
+    key = f"{ENGINE_VERSION}|{os.path.abspath(path)}|{st.st_size}|{st.st_mtime_ns}"
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+    return os.path.join(base, "hydron-autosar", "defs-" + hashlib.sha256(key.encode()).hexdigest()[:24] + ".pkl")
+
+
+def load_def_file(path: str, use_cache: bool = True) -> DefIndex:
+    cp = None
+    if use_cache:
+        try:
+            cp = _cache_path(path)
+            with open(cp, "rb") as f:
+                return pickle.load(f)
+        except Exception:
+            pass
+    idx = _parse_def_file(path)
+    if cp:
+        try:
+            os.makedirs(os.path.dirname(cp), exist_ok=True)
+            tmp = cp + f".{os.getpid()}.tmp"
+            with open(tmp, "wb") as f:
+                pickle.dump(idx, f, protocol=pickle.HIGHEST_PROTOCOL)
+            os.replace(tmp, cp)
+        except Exception:
+            pass
+    return idx
+
+
+def _parse_def_file(path: str) -> DefIndex:
+    idx = DefIndex()
+    idx.files.append(path)
+    root = ET.parse(path).getroot()
+
+    def short(el) -> Optional[str]:
+        for c in el:
+            if _local(c.tag) == "SHORT-NAME":
+                return (c.text or "").strip()
+        return None
+
+    skip = {"DESC", "INTRODUCTION", "ADMIN-DATA", "ANNOTATIONS", "LONG-NAME", "VALUE-CONFIG-CLASSES",
+            "MULTIPLICITY-CONFIG-CLASSES"}
+
+    def walk(el, prefix: str, module: Optional[DefNode], parent: Optional[DefNode]):
+        tag = _local(el.tag)
+        sn = short(el)
+        path = prefix
+        if sn is not None:
+            path = f"{prefix}/{sn}"
+            is_def = tag == MODULE_TAG or tag in CONTAINER_TAGS or (param_kind(tag) is not None and parent is not None)
+            if not is_def:
+                parent = None  # some other identifiable (package, collection, value element)
+            else:
+                node = _make_def(el, tag, sn, path, path_file=path_file)
+                node.parent = parent.path if parent else None
+                if tag == MODULE_TAG:
+                    module = node
+                    idx.modules[path] = node
+                node.module = module.path if module else None
+                idx.by_path[path] = node
+                if parent is not None:
+                    if node.is_container:
+                        parent.containers.append(path)
+                    elif is_ref_kind(node.kind or ""):
+                        parent.refs.append(path)
+                    else:
+                        parent.params.append(path)
+                if node.kind:  # params/refs hold no nested defs
+                    return
+                parent = node
+        for c in el:
+            if _local(c.tag) not in skip:
+                walk(c, path, module, parent)
+
+    path_file = path
+    walk(root, "", None, None)
+    return idx
+
+
+def _make_def(el, tag: str, sn: str, path: str, path_file: str) -> DefNode:
+    d = DefNode(path=path, tag=tag, name=sn, file=path_file)
+    d.kind = param_kind(tag) if tag not in CONTAINER_TAGS and tag != MODULE_TAG else None
+    direct = {}
+    for c in el:
+        direct.setdefault(_local(c.tag), c)
+    d.lower = _int(direct["LOWER-MULTIPLICITY"].text if "LOWER-MULTIPLICITY" in direct else None, 1)
+    inf = direct.get("UPPER-MULTIPLICITY-INFINITE")
+    if inf is not None and (inf.text or "").strip().lower() == "true":
+        d.upper = None
+    else:
+        d.upper = _int(direct["UPPER-MULTIPLICITY"].text if "UPPER-MULTIPLICITY" in direct else None, 1)
+    tr = direct.get("RELATED-TRACE-ITEM-REF")
+    if tr is not None:
+        d.trace = (tr.text or "").strip()
+    for c in el.iter():
+        t = _local(c.tag)
+        if t == "LIFE-CYCLE-INFO" or t == "LIFE-CYCLE-STATE-REF":
+            if "obsolete" in (c.text or "").lower():
+                d.obsolete = True
+    if d.kind is None:
+        return d
+    # Params/refs carry no nested identifiables except enum literals: a descendant scan is safe.
+    for c in el.iter():
+        t = _local(c.tag)
+        txt = (c.text or "").strip()
+        if t == "MIN" and d.min is None:
+            d.min, d.min_open = txt, (c.get("INTERVAL-TYPE") or "").upper() == "OPEN"
+        elif t == "MAX" and d.max is None:
+            d.max, d.max_open = txt, (c.get("INTERVAL-TYPE") or "").upper() == "OPEN"
+        elif t == "DEFAULT-VALUE" and d.default is None:
+            d.default = txt
+        elif t == "ECUC-ENUMERATION-LITERAL-DEF":
+            for s in c:
+                if _local(s.tag) == "SHORT-NAME":
+                    d.literals.append((s.text or "").strip())
+        elif t == "REGULAR-EXPRESSION" and d.regex is None:
+            d.regex = txt
+        elif t == "MIN-LENGTH":
+            d.min_len = _int(txt, None)
+        elif t == "MAX-LENGTH":
+            d.max_len = _int(txt, None)
+        elif t in ("DESTINATION-REF",):
+            d.dest_refs.append(txt)
+        elif t == "DESTINATION-TYPE":
+            d.dest_type = txt
+        elif t == "WITH-AUTO":
+            d.with_auto = txt.lower() == "true"
+        elif t == "SYMBOLIC-NAME-VALUE":
+            d.symbolic_name = txt.lower() == "true"
+    return d
+
+
+def load_defs(paths: list[str], use_cache: bool = True) -> DefIndex:
+    idx = DefIndex()
+    for p in paths:
+        idx.merge(load_def_file(p, use_cache=use_cache))
+    return idx
+
+
+def describe(d: DefNode, defs: "DefIndex") -> dict:
+    """Compact schema view of a def, for the agent (what may be set/added under it)."""
+    out: dict = {"@def": d.path, "@tag": d.tag, "@mult": d.mult}
+    if d.trace:
+        out["@trace"] = d.trace
+    if d.tag == CHOICE_TAG:
+        out["@choice"] = "exactly one of the sub-containers"
+    if d.kind:
+        out.update(_param_summary(d))
+        return out
+    params = {}
+    for p in d.params + d.refs:
+        pd = defs.by_path[p]
+        params[pd.name] = _param_line(pd)
+    if params:
+        out["params"] = params
+    subs = {}
+    for cpath in d.containers:
+        cd = defs.by_path[cpath]
+        subs[cd.name] = f"[{cd.mult}]" + (" choice" if cd.tag == CHOICE_TAG else "")
+    if subs:
+        out["containers"] = subs
+    return out
+
+
+def _param_summary(d: DefNode) -> dict:
+    s: dict = {"type": d.kind, "mult": d.mult}
+    if d.min is not None or d.max is not None:
+        s["range"] = f"{'(' if d.min_open else '['}{d.min},{d.max}{')' if d.max_open else ']'}"
+    if d.literals:
+        s["literals"] = d.literals
+    if d.default is not None:
+        s["default"] = d.default
+    if d.regex:
+        s["regex"] = d.regex
+    if d.dest_refs:
+        s["dest"] = d.dest_refs
+    if d.dest_type:
+        s["destType"] = d.dest_type
+    if d.symbolic_name:
+        s["symbolicName"] = True
+    if d.obsolete:
+        s["obsolete"] = True
+    return s
+
+
+def _param_line(d: DefNode) -> str:
+    bits = [d.kind or "?", f"[{d.mult}]"]
+    if d.min is not None or d.max is not None:
+        bits.append(f"{'(' if d.min_open else '['}{d.min}..{d.max}{')' if d.max_open else ']'}")
+    if d.literals:
+        lits = d.literals if len(d.literals) <= 12 else d.literals[:12] + [f"+{len(d.literals) - 12}"]
+        bits.append("{" + "|".join(lits) + "}")
+    if d.default is not None:
+        bits.append(f"default={d.default}")
+    if d.dest_refs:
+        bits.append("-> " + ",".join(r.rsplit("/", 1)[-1] for r in d.dest_refs))
+    if d.dest_type:
+        bits.append("-> " + d.dest_type)
+    if d.obsolete:
+        bits.append("OBSOLETE")
+    return " ".join(bits)

package/python/ecuc_engine/diff.py

@@ -0,0 +1,111 @@
+"""Semantic ARXML diff by AUTOSAR path.
+
+Ignores UUIDs, whitespace, comments, element order and split-file layout. ECUC elements are compared
+parameter by parameter (by def name); other identifiables by a canonical form of their own content
+(nested identifiables are compared separately under their own paths).
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .model import MODULE_VALUES, CONTAINER_VALUE, _walk_arxml, build_file_model
+from .values import parse_int, parse_float
+from .xmltree import Node
+
+IGNORED_ATTRS = {"UUID", "T", "S"}
+
+
+def _norm(raw: Optional[str], numerical: bool):
+    if raw is None:
+        return None
+    t = raw.strip()
+    if numerical:
+        lo = t.lower()
+        if lo in ("true", "false"):
+            return lo
+        i = parse_int(t)
+        if i is not None:
+            return str(i)
+        f = parse_float(t)
+        if f is not None:
+            return repr(f)
+    return t
+
+
+def _canon(node: Node, top: bool = True) -> str:
+    if not top and node.short_name is not None:
+        return ""  # nested identifiable: diffed under its own path
+    attrs = ",".join(f"{k}={v}" for k, v in sorted(node.attrs.items()) if k not in IGNORED_ATTRS and not k.startswith("xmlns"))
+    kids = sorted(c for c in (_canon(ch, False) for ch in node.children) if c)
+    txt = " ".join(node.text.split()) if not node.children else ""
+    return f"<{node.tag}[{attrs}]{txt}{''.join(kids)}>"
+
+
+def _side(target: str) -> dict:
+    files = [target] if os.path.isfile(target) else sorted(_walk_arxml(target))
+    out: dict = {}
+    for f in files:
+        with open(f, "rb") as fh:
+            fm = build_file_model(f, fh.read())
+
+        def visit(node: Node, prefix: str):
+            sn = node.short_name
+            p = prefix
+            if sn is not None:
+                p = f"{prefix}/{sn}"
+                if node.tag in (MODULE_VALUES, CONTAINER_VALUE):
+                    ent = out.setdefault(p, {"tag": node.tag, "file": f, "line": node.line, "ecuc": True,
+                                             "def": node.child_text("DEFINITION-REF"), "values": {}})
+                    for coll in node.children:
+                        if coll.tag in ("PARAMETER-VALUES", "REFERENCE-VALUES"):
+                            for pv in coll.children:
+                                name = (pv.child_text("DEFINITION-REF") or "?").rsplit("/", 1)[-1]
+                                vn = pv.child("VALUE") or pv.child("VALUE-REF")
+                                v = _norm(vn.text if vn is not None else None, pv.tag == "ECUC-NUMERICAL-PARAM-VALUE")
+                                if vn is None and pv.child("VALUE-IREF") is not None:
+                                    v = _canon(pv.child("VALUE-IREF"))
+                                ent["values"].setdefault(name, []).append(v)
+                    for coll in node.children:
+                        if coll.tag in ("CONTAINERS", "SUB-CONTAINERS"):
+                            for c in coll.children:
+                                visit(c, p)
+                    return
+                out.setdefault(p, {"tag": node.tag, "file": f, "line": node.line, "ecuc": False, "canon": _canon(node)})
+            for c in node.children:
+                visit(c, p)
+
+        visit(fm.root, "")
+    for ent in out.values():
+        if ent.get("ecuc"):
+            ent["values"] = {k: sorted(v, key=lambda x: (x is None, str(x))) for k, v in ent["values"].items()}
+    return out
+
+
+def diff(a: str, b: str, rel=lambda f: f) -> dict:
+    A, B = _side(a), _side(b)
+    added = [{"path": p, "tag": B[p]["tag"], "at": f"{rel(B[p]['file'])}:{B[p]['line']}"} for p in sorted(set(B) - set(A))]
+    removed = [{"path": p, "tag": A[p]["tag"], "at": f"{rel(A[p]['file'])}:{A[p]['line']}"} for p in sorted(set(A) - set(B))]
+    changed = []
+    for p in sorted(set(A) & set(B)):
+        x, y = A[p], B[p]
+        ch: dict = {}
+        if x["tag"] != y["tag"]:
+            ch["tag"] = [x["tag"], y["tag"]]
+        if x.get("ecuc") and y.get("ecuc"):
+            if x["def"] != y["def"]:
+                ch["definitionRef"] = [x["def"], y["def"]]
+            vals = {}
+            for k in sorted(set(x["values"]) | set(y["values"])):
+                va, vb = x["values"].get(k), y["values"].get(k)
+                if va != vb:
+                    un = lambda v: v[0] if v and len(v) == 1 else v  # noqa: E731
+                    vals[k] = [un(va), un(vb)]
+            if vals:
+                ch["values"] = vals
+        elif x.get("canon") != y.get("canon"):
+            ch["content"] = "changed"
+        if ch:
+            changed.append({"path": p, "at": f"{rel(y['file'])}:{y['line']}", **ch})
+    return {"added": added, "removed": removed, "changed": changed,
+            "summary": {"added": len(added), "removed": len(removed), "changed": len(changed)}}

package/python/ecuc_engine/ecucjson.py

@@ -0,0 +1,154 @@
+"""ECUC JSON: the compact view the agent reads.
+
+Keyed by def names, not XML structure:
+  {"Com": {"@path": "/Pkg/Com", "@def": "/AUTOSAR/EcucDefs/Com", "@at": "Config/Com.arxml:12",
+           "ComConfig": {"@path": ...,
+              "ComIPdu:DoorStatus_Tx": {"@path": ..., "ComIPduDirection": "SEND",
+                                        "ComPduIdRef": "->/EcuC/EcucPduCollection/DoorStatus_Tx",
+                                        "ComSignal:DoorLatch": {...}}}}}
+A container key is "<DefName>:<ShortName>", shortened to "<ShortName>" when the two are equal.
+Multi-valued parameters are arrays. References are "->/AUTOSAR/path".
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from . import defs as D
+from .model import Elem, Project
+from .validate import _resolve_def
+from .values import to_json
+
+
+def key_of(e: Elem) -> str:
+    dn = (e.def_ref or "?").rsplit("/", 1)[-1]
+    return e.name if dn == e.name else f"{dn}:{e.name}"
+
+
+def render(project: Project, group: list, depth: int, top: bool = True) -> dict:
+    defs = project.defs
+    e0 = group[0]
+    out: dict = {"@path": e0.path}
+    if top:
+        out["@def"] = e0.def_ref
+        out["@at"] = ", ".join(f"{project.rel(e.file)}:{e.line}" for e in group)
+    vals: dict = {}
+    for e in group:
+        for pv in e.params:
+            pd = _resolve_def(defs, pv.def_ref)
+            v = to_json(pd, pv.value, pv.is_ref, pv.tag == "ECUC-NUMERICAL-PARAM-VALUE")
+            name = pv.name
+            multi = pd is not None and (pd.upper is None or pd.upper > 1)
+            if name in vals:
+                if not isinstance(vals[name], list) or not multi:
+                    vals[name] = vals[name] if isinstance(vals[name], list) else [vals[name]]
+                vals[name].append(v)
+            else:
+                vals[name] = [v] if multi else v
+    out.update(vals)
+    seen = set()
+    for e in group:
+        for c in e.children:
+            if c.path in seen:
+                continue
+            seen.add(c.path)
+            cg = project.find(c.path)
+            if depth <= 0:
+                n_p = sum(len(x.params) for x in cg)
+                n_c = sum(len(x.children) for x in cg)
+                out[key_of(c)] = f"… {n_p} values, {n_c} sub-containers (read {c.path})"
+            else:
+                out[key_of(c)] = render(project, cg, depth - 1, top=False)
+    return out
+
+
+def read(project: Project, path: Optional[str], depth: int = 2, schema: bool = False) -> dict:
+    res: dict = {"defsLoaded": len(project.defs.modules)}
+    if project.warnings:
+        res["warnings"] = project.warnings
+    if not path:
+        mods: dict = {}
+        for m in project.modules:
+            g = project.find(m.path)
+            ent = mods.setdefault(m.path, {"module": m.name, "path": m.path, "def": m.def_ref, "files": [],
+                                           "containers": 0, "values": 0})
+            ent["files"].append(f"{project.rel(m.file)}:{m.line}")
+            ent["containers"] += sum(1 for _ in _walk(m)) - 1
+            ent["values"] += sum(len(x.params) for x in _walk(m))
+        res["modules"] = list(mods.values())
+        res["hint"] = "read a module or container by its AUTOSAR path, e.g. path=" + (
+            res["modules"][0]["path"] if res["modules"] else "/Pkg/Module")
+        return res
+    resolved = resolve(project, path)
+    if isinstance(resolved, dict):
+        res.update(resolved)
+        return res
+    if resolved != path:
+        res["resolved"] = f"{path} -> {resolved}"
+        path = resolved
+    group = project.find(path)
+    if group:
+        res["ecuc"] = {key_of(group[0]): render(project, group, depth)}
+        if schema:
+            d = _resolve_def(project.defs, group[0].def_ref)
+            res["schema"] = D.describe(d, project.defs) if d else None
+        return res
+    # a def path? describe the definition
+    d = project.defs.get(path)
+    if d is not None:
+        res["schema"] = D.describe(d, project.defs)
+        return res
+    # parent/param form: /.../Container/ParamName
+    parent, _, last = path.rstrip("/").rpartition("/")
+    pg = project.find(parent)
+    if pg:
+        hits = [pv for e in pg for pv in e.params if pv.name == last]
+        if hits:
+            pd = _resolve_def(project.defs, hits[0].def_ref)
+            res["param"] = {"@path": path, "@def": hits[0].def_ref,
+                            "@at": [f"{project.rel(hits[0].node and pg[0].file)}:{h.node.line}" for h in hits],
+                            "value": [to_json(pd, h.value, h.is_ref, h.tag == "ECUC-NUMERICAL-PARAM-VALUE") for h in hits]}
+            if pd is not None:
+                res["schema"] = D.describe(pd, project.defs)
+            return res
+    res["error"] = f"no ECUC element or definition at {path}"
+    near = [p for p in project.by_path if p.rsplit("/", 1)[-1] == last][:10]
+    if near:
+        res["didYouMean"] = near
+    return res
+
+
+def _walk(e: Elem):
+    stack = [e]
+    while stack:
+        x = stack.pop()
+        yield x
+        stack.extend(x.children)
+
+
+def resolve(project: Project, q: str):
+    """Exact path, def path, or param path pass through. Otherwise resolve a SHORT-NAME or partial
+    path ("ComConfig/DoorLatch", "DoorLatch", "DoorLatch/ComBitPosition") against value paths.
+    Returns the path, or {"error", "candidates"} when ambiguous / not found."""
+    q = q.strip()
+    if project.find(q) or project.defs.get(q):
+        return q
+    parent, _, last = q.rstrip("/").rpartition("/")
+    if parent.startswith("/") and project.find(parent):
+        return q
+    tail = q.strip("/")
+    paths = list(project.by_path)
+    hits = [p for p in paths if p == "/" + tail or p.endswith("/" + tail)]
+    param = None
+    if not hits and "/" in tail:  # last segment may be a parameter
+        head, _, param = tail.rpartition("/")
+        hits = [p for p in paths if p.endswith("/" + head)]
+        hits = [p for p in hits if any(pv.name == param for e in project.find(p) for pv in e.params)]
+    if not hits:
+        low = tail.lower().rsplit("/", 1)[-1]
+        sugg = sorted(p for p in paths if low in p.rsplit("/", 1)[-1].lower())[:15]
+        return {"error": f"no ECUC element matches '{q}'", "didYouMean": sugg} if sugg else \
+            {"error": f"no ECUC element or definition at {q}; call ecuc_read with no path to list modules"}
+    if len(hits) > 1:
+        return {"error": f"'{q}' is ambiguous ({len(hits)} matches); pass one of these full paths",
+                "didYouMean": sorted(hits)[:25]}
+    return hits[0] + (f"/{param}" if param else "")