@h2loop/autosar 1.1.0 → 1.2.1

package/python/ecuc_engine/specids.py

@@ -0,0 +1,163 @@
+"""Requirement-ID check (autosar_spec_id_check) against the user's own AUTOSAR spec texts.
+
+No requirement IDs or spec text are bundled with the pack: AUTOSAR documents are licensed to the user, so the
+index is built at run time from text exports the project points at (`.hydron/autosar.json` "specDocs" globs, or
+$AUTOSAR_SPEC_DOCS, an os.pathsep-separated list of files/dirs/globs; .txt and .md files). The index is cached
+per file set (size + mtime) under $XDG_CACHE_HOME/h2loop-autosar.
+
+An ID is "defined" where a line starts with "[ID]" alone (optionally after a label such as "Signature:", as the
+RTE spec writes API requirements), followed within a few lines by the requirement
+bracket "⌈" or "Upstream requirements" (how SWS/TPS/SRS/ECUC requirements are introduced), and "mentioned" when
+it only occurs in running text or trace tables.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from typing import Optional
+
+from . import paths
+
+ID = re.compile(r"\b([A-Z][A-Za-z]{1,7}_[A-Za-z0-9]+_\d{3,6})\b")
+# "SWS_NvM_00898/00899" -> both IDs
+SHORTHAND = re.compile(r"\b([A-Z][A-Za-z]{1,7}_[A-Za-z0-9]+_)(\d{3,6})((?:/\d{3,6})+)")
+DEF_LINE = re.compile(r"^\s*(?:[A-Z][A-Za-z ]{0,30}:\s*)?\[([A-Z][A-Za-z]{1,7}_[A-Za-z0-9]+_\d{3,6})\]")
+INDEX_VERSION = 3
+
+
+def expand_ids(text: str) -> list:
+    """Every requirement ID written in text, with "X_Mod_00001/00002" shorthand expanded, in order, unique."""
+    out: list = []
+    for m in SHORTHAND.finditer(text):
+        out.append(m.group(1) + m.group(2))
+        out.extend(m.group(1) + n for n in m.group(3).strip("/").split("/"))
+    out.extend(m.group(1) for m in ID.finditer(text))
+    seen: set = set()
+    return [x for x in out if not (x in seen or seen.add(x))]
+
+
+def _is_doc(f: str) -> bool:
+    return f.lower().endswith((".txt", ".md"))
+
+
+def doc_files(root: str, docs: Optional[list] = None) -> tuple:
+    """(files, origin) of the spec text docs to index."""
+    pats, origin = list(docs or []), "argument"
+    if not pats:
+        cfg = os.path.join(root, ".hydron", "autosar.json")
+        try:
+            with open(cfg) as fh:
+                spec = json.load(fh).get("specDocs")
+            if spec:
+                pats, origin = ([spec] if isinstance(spec, str) else list(spec)), ".hydron/autosar.json specDocs"
+        except (OSError, ValueError, AttributeError):
+            pass
+    if not pats and os.environ.get("AUTOSAR_SPEC_DOCS"):
+        pats, origin = os.environ["AUTOSAR_SPEC_DOCS"].split(os.pathsep), "AUTOSAR_SPEC_DOCS"
+    files: list = []
+    for p in paths.patterns(root, [x for x in pats if x]):
+        files.extend(f for f in p.expand(_is_doc) if _is_doc(f) and os.path.isfile(f))
+    return sorted({os.path.abspath(f) for f in files}), origin if pats else None
+
+
+def _cache_path(files: list) -> str:
+    h = hashlib.sha1(str(INDEX_VERSION).encode())
+    for f in files:
+        st = os.stat(f)
+        h.update(f"{f}\0{st.st_size}\0{int(st.st_mtime)}\n".encode())
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache")
+    return os.path.join(base, "h2loop-autosar", f"specids-{h.hexdigest()[:16]}.json")
+
+
+def build_index(files: list) -> dict:
+    """ID -> [file index, line, defined] (the defining line when there is one, else the first mention)."""
+    idx: dict = {}
+    for fi, f in enumerate(files):
+        with open(f, encoding="utf-8", errors="replace") as fh:
+            lines = fh.readlines()
+        for i, line in enumerate(lines):
+            d = DEF_LINE.match(line)
+            if d and len(ID.findall(line)) == 1 and any(
+                    "⌈" in x or "Upstream requirements" in x for x in lines[i: i + 5]):
+                cur = idx.get(d.group(1))
+                if cur is None or not cur[2]:
+                    idx[d.group(1)] = [fi, i + 1, True]
+            for m in ID.finditer(line):
+                idx.setdefault(m.group(1), [fi, i + 1, False])
+    return idx
+
+
+def load_index(files: list) -> dict:
+    cache = _cache_path(files)
+    try:
+        with open(cache) as fh:
+            data = json.load(fh)
+        if data.get("files") == files:
+            return data["ids"]
+    except (OSError, ValueError):
+        pass
+    ids = build_index(files)
+    try:
+        os.makedirs(os.path.dirname(cache), exist_ok=True)
+        tmp = cache + ".tmp"
+        with open(tmp, "w") as fh:
+            json.dump({"files": files, "ids": ids}, fh)
+        os.replace(tmp, cache)
+    except OSError:
+        pass
+    return ids
+
+
+def _snippet(f: str, line: int, max_lines: int = 14, max_chars: int = 700) -> str:
+    out: list = []
+    with open(f, encoding="utf-8", errors="replace") as fh:
+        for ln, text in enumerate(fh, 1):
+            if ln < line:
+                continue
+            out.append(text.strip())
+            if "⌋" in text or len(out) >= max_lines:
+                break
+    s = re.sub(r"\s+", " ", " ".join(out)).strip()
+    return s if len(s) <= max_chars else s[: max_chars - 1] + "…"
+
+
+def check_ids(root: str, ids: list, docs: Optional[list] = None) -> dict:
+    files, origin = doc_files(root, docs)
+    wanted: list = []
+    for raw in ids:
+        got = expand_ids(str(raw))
+        wanted.extend(got or [str(raw).strip().strip("[]")])
+    if not files:
+        return {"error": "no AUTOSAR spec text docs configured, so no requirement ID can be confirmed. Set "
+                         "`specDocs` (globs of .txt/.md spec exports) in .hydron/autosar.json or $AUTOSAR_SPEC_DOCS. "
+                         "Until then cite only IDs that appear verbatim in a tool result or a spec text you read; "
+                         "otherwise describe the rule without an ID.",
+                "ids": wanted}
+    idx = load_index(files)
+    lower: dict = {}
+    for k in idx:
+        lower.setdefault(k.lower(), k)
+    results = []
+    for i in wanted:
+        hit = idx.get(i)
+        if hit is None:
+            alt = lower.get(i.lower())
+            r = {"id": i, "status": "NOT-FOUND"}
+            if not ID.fullmatch(i):
+                r["status"] = "MALFORMED"
+            if alt:
+                r["didYouMean"] = alt
+            results.append(r)
+            continue
+        f = files[hit[0]]
+        r = {"id": i, "status": "DEFINED" if hit[2] else "MENTIONED-ONLY",
+             "doc": os.path.basename(f), "line": hit[1]}
+        if hit[2]:
+            r["text"] = _snippet(f, hit[1])
+        results.append(r)
+    counts: dict = {}
+    for r in results:
+        counts[r["status"]] = counts.get(r["status"], 0) + 1
+    return {"docs": len(files), "docsOrigin": origin, "indexedIds": len(idx), "counts": counts, "results": results}

package/python/ecuc_engine/values.py

@@ -144,3 +144,29 @@ def from_json(d: Optional[DefNode], v) -> str:
     if d is not None and d.kind == "BOOLEAN" and s.lower() in ("true", "false"):
         s = s.lower()
     return s
+
+
+def hex_str(v: int) -> str:
+    return f"-0x{-v:X}" if v < 0 else f"0x{v:X}"
+
+
+DEST_KIND = {"ECUC-INTEGER-PARAM-DEF": "INTEGER", "ECUC-FLOAT-PARAM-DEF": "FLOAT", "ECUC-BOOLEAN-PARAM-DEF": "BOOLEAN"}
+
+
+def int_forms(d: Optional[DefNode], raw: Optional[str], is_ref: bool, numerical: bool,
+              dest: Optional[str] = None) -> Optional[dict]:
+    """{"dec": int, "hex": "0x..."} for an integer-typed value (def kind INTEGER; without loaded defs the
+    DEFINITION-REF DEST, else a numerical value whose text is an integer), else None. Computed here so answers
+    never convert bases by hand."""
+    if raw is None or is_ref:
+        return None
+    k = d.kind if d is not None else DEST_KIND.get(dest or "") or ("NUMBER" if numerical else None)
+    if k not in ("INTEGER", "NUMBER"):
+        return None
+    t = raw.strip()
+    if t.lower() in ("true", "false"):
+        return None
+    v = parse_int(t)
+    if v is None:
+        return None
+    return {"dec": v, "hex": hex_str(v)}

package/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ecuc-engine"
-version = "1.2.0-pre"
+version = "1.4.0-pre"
 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.

package/skills/autosar/SKILL.md

@@ -23,12 +23,35 @@ in `Output/` is derived from it; in-house code in `Source/` calls the generated
    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.
+3. **Cite** the AUTOSAR path, the DEFINITION-REF and file:line for every element you discuss or change —
+   copied from tool output (see *Citations and numbers*), never estimated.
 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.
+   not settle a question (cross-module consistency, handle IDs, timing), say so plainly. Quote the SWS
+   requirement only if you have its text from a tool result this session; otherwise describe the rule
+   without an ID — never fill the gap from memory.
+
+## Citations and numbers (always)
+- **Requirement IDs** (SWS_/SRS_/TPS_/ECUC_/RS_…): cite one only when it appears verbatim in a tool result
+  (e.g. the `spec:` line of `autosar_audit`, an H2L rule message, `autosar_spec_id_check`) or in spec text you
+  actually read this session. Before citing any other ID, run `autosar_spec_id_check ids=[…]`; cite it only if it
+  is DEFINED, and describe it with the returned text. If the check is unavailable or says NOT-FOUND /
+  MENTIONED-ONLY, describe the rule without an ID. An invented or misremembered ID is worse than none.
+- **No requirement IDs for plain value questions** ("what is X", "which file sets Y", "trace Z"): answer with the
+  value, its AUTOSAR path and file:line. Add an ID only when the user asks why/what the standard requires.
+- **file:line** must come from a tool result or a file you read: for a value use `"@at:<Param>"` (the VALUE
+  element) from `ecuc_read`/`ecuc_find`, or the `@ file:line` of a `VALUES` line from `autosar_trace` /
+  `autosar_config_lookup`; `@at` / `at` is the container. A graph `file:line` of an element not in the local
+  checkout is where the element starts: read the file to find the value line. Never estimate or offset a line.
+- **Numbers and units**: never convert bases or units in your head. Copy `"@hex:<Param>"` / `"@dec:<Param>"`
+  (and the `dec …, hex …` of VALUES lines, CAN IDs, audit `…Hex` evidence). For any other conversion or
+  arithmetic (bytes ↔ bits, ms ↔ s, address + offset), compute it with a tool or say it is not computed.
+- **Parameter semantics**: explain what a parameter means only from its param def (`ecuc_read schema=true`,
+  the def `DESC`) or spec text you read; if neither covers it, say the meaning is not in the loaded defs/specs
+  rather than inventing one.
+- **Simple look-ups get short, exact answers**: the value (with hex if integer), the AUTOSAR path, the
+  DEFINITION-REF and file:line — no spec background, no padding.
 
 ## Tool map
 | Need | Tool |
@@ -51,6 +74,7 @@ in `Output/` is derived from it; in-house code in `Source/` calls the generated
 | Generate BSW config code ourselves (NvM/Fee/MemIf/Dem/PduR/CanIf/Port/Dio) | `autosar_codegen`, then `autosar_codegen_diff reference_dir=Output` (see `references/codegen.md`) |
 | Regenerate code with the vendor tool | `autosar_generate` (configured command, asks permission) |
 | Compile/link | `autosar_build` |
+| Is this requirement ID real, and what does it say? | `autosar_spec_id_check ids=[…]` (needs `specDocs` / `$AUTOSAR_SPEC_DOCS`) |
 | Spec questions (SWS/TPS requirement text) | the project's ingested docs search tools |
 
 ## Workflow (validation and fix tasks)
@@ -86,9 +110,11 @@ Details and failure handling: `references/workflow.md`.
    `autosar_trace <symbol>` for the owning I-PDU, generated symbol and other callers.
 3. Review what the audit lists as *unchecked* by hand (pointer arguments, expressions as handles), and
    look for logic issues it cannot see (wrong signal chosen although types match, missing error handling).
-4. Report: file:line, the call, the configured facts (AUTOSAR paths + values), the spec ID, the fix.
+4. Report: file:line, the call, the configured facts (AUTOSAR paths + values with their `…At` lines), the spec
+   ID exactly as the audit's `spec:` line gives it (never add others), the fix.
 
-Facts that decide common review calls:
+Facts that decide common review calls (the IDs below are checked against R25-11; still cite one only when a
+tool result this session shows it, per *Citations and numbers*):
 - A Com signal's layout must match the System extract it came from (ISignalToIPduMapping startPosition /
   packingByteOrder, ISignal length) and an EcuC Pdu's PduLength the system I-PDU length (H2L-SYS-001/002).
 - A PduR routing path forwards one I-PDU: source and destination must stand for the same system I-PDU (or the same

package/skills/autosar/references/codegen.md

@@ -12,11 +12,39 @@ Generated C is never written by hand or by the model: run `autosar_codegen`, rev
 | `SchM_<Mip>.h` | exclusive areas the static code uses (`SchM_Enter_<Mip>_<EA>` found in non-generated C) + main functions |
 | `<Mip>_MemMap.h` | SWS_MemMap_00032 keyword file; pragmas from `codegen.memmap.pragmas` |
 
+Release macros: `<MIP>_CFG_AR_RELEASE_*` come from the static code's published information (`<MIP>_AR_RELEASE_*` in
+`<Mip>.h`, SWS_BSW_00059), so the generated release check matches the SIP; the ECUC schema release is the fallback.
+
 Handle IDs: missing symbolic values are assigned (lowest free >= def MIN, existing values kept, duplicates
 are errors) and written back into the ARXML in place (TPS_ECUC_02107); `write_back=false` keeps them in memory.
 
+A binding may declare `handleLayout` (e.g. Com: Tx signals/I-PDUs before Rx, because the static code indexes its
+tables by handle). Values that break it are renumbered and written back, only for withAuto params (ComHandleId,
+ComIPduHandleId); otherwise it is an error. Configuration the static code cannot represent (binding `require` /
+`unsupported`, e.g. BIG_ENDIAN signals or signal groups for the stand-in Com) fails generation; nothing is written.
+Notes list C code that uses a `<Mip>Conf_*` symbol the configuration no longer has (the build would fail on it).
+
 Output goes to `.hydron/codegen/out` unless `out_dir` is given (`project` = `codegen.outDir`, default `Output`).
 
+## Com
+`Com_Cfg.h`: ComGeneral switches, `COM_DEV_ERROR_DETECT` (ECUC_Com_00141), `ComConf_ComSignal_*`, `ComConf_ComIPdu_*`,
+`ComConf_ComIPduGroup_*` (and signal-group / group-signal) symbols. `Com_PBcfg.c` (binding): I-PDU buffers sized from the
+EcuC Pdu, signal tables (bit position, size, type, init value, transfer property, notification), Tx I-PDU table (PduR
+source handle via the shared EcuC Pdu, Tx mode, cycle = ComTxModeTimePeriod / ComMainTxTimeBase), Rx I-PDU table (deadline
+= smallest non-zero ComFirstTimeout/ComTimeout of its signals without update bit, SWS_Com_00291).
+Notification callouts: R25-11 Com users (ComUserModule -> ComUserModuleCnf, ComUserSignal with the same system signal,
+ComUserCallback of type COM_RX_ACK / COM_TX_ACK; `call:comUserCallback`), or, for a static Com with `void(void)`
+callbacks, the RTE's `Rte_COMCbk_<sn>()` / `Rte_COMCbkTAck_<sn>()` when the RTE's Rte_Cbk.h declares it
+(`call:rteSignalCallback`). Nothing is bound from guesses: no declaration, no callback.
+
+## Known differences from the sample/large fixture oracle (all explained)
+| Item | Oracle | Ours | Why |
+|---|---|---|---|
+| `NvM_BlockDescriptorTable[*].RamBlockDataAddress` | `X` | `&X` (as configured) | ECUC_NvM_00482 value is the address expression; kept verbatim, same address for arrays |
+| Rx I-PDU `TimeoutTicks` with mixed signal timeouts | largest ComTimeout | smallest non-zero | SWS_Com_00291 |
+| `<MIP>_CFG_*` version macros, generic ComGeneral/NvMCommon/... switches, Dem/Fee tables | absent | extra | def-driven output the oracle does not emit |
+| SchM main function names | `Com_MainFunctionTx` | same | SWS_Com says `Com_MainFunctionTx_<shortName>`; the instance named like its def keeps the SIP's legacy name |
+
 ## Reading a diff
 - *missing*: in the reference only (e.g. a symbol whose ECUC container was deleted: stale Output, not a generator bug).
 - *extra*: generated only (generic def-driven macros/tables the reference generator does not emit).

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

@@ -15,7 +15,10 @@ its def through `DEFINITION-REF` (an AUTOSAR path); the `DEST` attribute names t
 
 **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.
+params as arrays, refs as `"->/path"`, `@path`/`@def`/`@at` metadata (`@at` = the container's file:line).
+Each value is followed by `"@at:<Param>"` (file:line of its `VALUE`/`VALUE-REF` element — cite this one for a
+value) and integers by `"@hex:<Param>"` (plus `"@dec:<Param>"` when the ARXML text is hex). Keys starting with
+`@` are metadata; `ecuc_edit` ignores them.
 
 **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`)

package/skills/autosar/references/project-layout.md

@@ -25,7 +25,8 @@ Optional; pins what the tools load and how to generate/build:
   "generate":  {"command": "<vendor-cli> -p Config/Ecu.dpa --generate {module}", "cwd": ".", "timeoutSec": 3600},
   "build":     {"command": "make -C Build -j8 all", "timeoutSec": 3600},
   "probe":     {"cc": "tricore-elf-gcc", "flags": ["-I", "SIP/include", "-DCPU=TC4D"]},
-  "checkGenerated": false
+  "checkGenerated": false,
+  "specDocs":  ["~/autosar/R25-11/txt/*.txt"]
 }
 ```
 Without it: param defs = every `.arxml` holding `ECUC-MODULE-DEF` (else `$AUTOSAR_PARAMDEFS`, a
@@ -36,3 +37,5 @@ BSWMD defs take precedence for vendor-specific parameters.
 `probe` sets the compiler/flags for the compile-only sizeof probe (H2L-NVM-001; default: the Makefile's CC/CFLAGS,
 else host `cc` with the discovered header dirs). `checkGenerated` turns the stale-Output check (H2L-GEN-001, run in a
 scratch copy) on/off; by default it is on when a `generate` command exists and the configuration is under 5 MB.
+`specDocs` (else `$AUTOSAR_SPEC_DOCS`, a path list) points `autosar_spec_id_check` at your own text exports
+(.txt/.md) of the AUTOSAR specifications; the pack bundles no spec text and no requirement-ID index.