@anik-2/autosar 0.1.0 → 0.1.2

package/README.md

@@ -13,6 +13,7 @@ Deterministic tools for AUTOSAR Classic integration work, so the agent never han
 | `arxml_diff` | semantic diff by AUTOSAR path (ignores UUIDs, order, whitespace, file splits) | local |
 | `autosar_trace` | config ↔ generated C symbol ↔ in-house callers, via the H2Loop code graph | H2Loop backend |
 | `autosar_config_lookup` | element + children + refs in/out + links from the code graph | H2Loop backend |
+| `autosar_audit` | integration review of C code: BSW API handles, direction, widths, NvM NULL_PTR vs ECUC | local |
 | `autosar_generate` / `autosar_build` | run the project's configured generator / build command (asks permission) | local |
 
 Plus the `autosar` skill (ECUC model, symbolic-name rule, config classes, project layout, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anik-2/autosar",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AUTOSAR Classic pack for Hydron: ECUC read/edit-in-place/validate/diff on ARXML, config-to-code trace, generator and build runners",
   "type": "module",
   "private": false,
@@ -16,6 +16,7 @@
     "plugins/index.js",
     "python/pyproject.toml",
     "python/ecuc_engine/*.py",
+    "python/ecuc_engine/rules/*.py",
     "README.md"
   ],
   "scripts": {

package/plugins/index.js

@@ -1,21 +1,26 @@
 // @bun
-import{isAbsolute as W,join as T,resolve as G}from"path";import{tool as p}from"@kilocode/plugin";import{homedir as j}from"os";import{join as h}from"path";var I=()=>process.env.HYDRON_TEST_HOME||j(),R=(t,n)=>process.env[t]||h(I(),n),D=()=>h(R("XDG_CONFIG_HOME",".config"),"hydron-cli"),L=()=>h(R("XDG_DATA_HOME",".local/share"),"hydron-cli"),M=()=>h(R("XDG_STATE_HOME",".local/state"),"hydron-cli");async function v(t){let n=Bun.file(t);if(!await n.exists())return;return n.json().catch(()=>{return})}async function N(){let t=process.env.KILO_API_URL?.trim();if(t)return t.replace(/\/+$/,"");let n=await v(h(D(),"server-config.json")),e=typeof n?.apiBaseUrl==="string"?n.apiBaseUrl:void 0;if(!e)throw Error("H2Loop backend URL unknown: set KILO_API_URL or sign in with `hydron auth login`.");return e.replace(/\/+$/,"")}function F(t){let n=t?.split(".")[1];if(!n)return"";try{let e=JSON.parse(Buffer.from(n.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf8"));return typeof e.sub==="string"?e.sub:""}catch{return""}}async function J(t){let n=F(t.access);if(n)return n;if(!t.refresh)return"";return new Bun.CryptoHasher("sha256").update(t.refresh).digest("hex").slice(0,12)}async function E(){let n=(await v(h(L(),"auth.json")))?.hydron;if(!n||n.type!=="oauth"||!n.access)throw Error("Not signed in to H2Loop. Run `hydron auth login` (or sign in from the TUI), then retry.");return n}async function x(){let t=await E();if(typeof t.expires==="number"&&t.expires>0&&Date.now()>=t.expires-30000)throw Error("The H2Loop session token has expired. Send any message in Hydron (the CLI refreshes it) or re-login with `hydron auth login`, then retry.");return t.access}async function A(t){if(t!==void 0&&String(t).trim())return String(t).trim();let n=await v(h(M(),"h2loop-project.json")),e=await E(),o=await J(e),i=n?.project??void 0;if(i?.id!==void 0&&typeof n?.account==="string"&&n.account===o)return String(i.id);throw Error("No H2Loop project selected for this account. Select one in Hydron (project picker) or pass workspace_id explicitly.")}async function $(t,n,e,o){let i=`${await N()}${t}?workspace_id=${encodeURIComponent(n)}`,a=await fetch(i,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${await x()}`},body:JSON.stringify(e),signal:o?AbortSignal.any([o,AbortSignal.timeout(120000)]):AbortSignal.timeout(120000)}),r=await a.text();if(a.status===401)throw Error("H2Loop rejected the session (401). Re-login with `hydron auth login`, then retry.");if(a.status===404&&r.includes("Not Found"))throw Error(`${t} is not available on ${await N()} (backend predates the AUTOSAR endpoints).`);if(!a.ok)throw Error(`H2Loop ${t} failed: HTTP ${a.status} ${r.slice(0,800)}`);try{return JSON.parse(r)}catch(d){throw Error(`H2Loop ${t} returned non-JSON (${String(d)}): ${r.slice(0,300)}`)}}import{existsSync as P}from"fs";import{dirname as q,join as S}from"path";import{fileURLToPath as X}from"url";var H="autosar-data==0.17.0";function B(){let t=q(X(import.meta.url)),n=[S(t,"..","python"),S(t,"..","..","python")].find((e)=>P(S(e,"ecuc_engine","__main__.py")));if(!n)throw Error(`ECUC engine not found next to ${t} (expected ../python/ecuc_engine)`);return n}async function V(t){try{return await Bun.spawn([...t,"-c","import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"],{stdout:"ignore",stderr:"ignore",stdin:"ignore"}).exited===0}catch{return!1}}var _={};async function Y(){if(_.cmd!==void 0)return _.cmd;let t=process.env.AUTOSAR_PYTHON?.trim(),e=t?[[t]]:[["uv","run","--no-project","--quiet","--with",H,"--python",">=3.10","python"],["python3"],["python"],["py","-3"]];for(let o of e)if(await V(o))return _.cmd=o,o;return _.cmd=null,null}async function y(t,n,e){let o=await Y();if(!o)return{ok:!1,error:"no Python >= 3.10 found. Install uv (https://docs.astral.sh/uv/) or Python 3.10+, or set AUTOSAR_PYTHON to an interpreter path."};let i=B(),a=Bun.spawn([...o,"-m","ecuc_engine","--root",t,...n,"--json"],{cwd:t,env:{...process.env,PYTHONPATH:[i,process.env.PYTHONPATH].filter(Boolean).join(process.platform==="win32"?";":":")},stdout:"pipe",stderr:"pipe",stdin:"ignore",signal:e}),[r,d]=await Promise.all([new Response(a.stdout).text(),new Response(a.stderr).text()]);await a.exited;let u=r.trim().split(`
-`).filter(Boolean).at(-1);if(!u)return{ok:!1,error:`engine produced no output (exit ${a.exitCode}): ${d.trim().slice(-2000)}`};try{return JSON.parse(u)}catch(c){return{ok:!1,error:`engine output was not JSON (${String(c)}): ${u.slice(0,500)} ${d.slice(-500)}`}}}var s=p.schema,K=["# AUTOSAR pack active","For AUTOSAR/ECUC/ARXML work load the `autosar` skill. Never hand-write ARXML: use ecuc_read, ecuc_edit,","then ecuc_validate after every edit; arxml_diff to review. autosar_trace links config to C code.","Cite AUTOSAR path + DEFINITION-REF."].join(`
-`),b=" In your answer cite the AUTOSAR path and the DEFINITION-REF (and file:line) of every element you rely on.";function C(t,n=200){let e=t.slice(0,n).map((o)=>`${o.file}:${o.line} ${o.severity.toUpperCase()} ${o.rule} ${o.path} \u2014 ${o.message}${o.defRef?` [def ${o.defRef}]`:""}`);if(t.length>n)e.push(`\u2026 ${t.length-n} more`);return e}function w(t){let n=t.didYouMean?`
-Did you mean: ${t.didYouMean.join(", ")}`:"",e=t.schema?`
-Schema errors: ${JSON.stringify(t.schema)}`:"";return`ERROR: ${t.error}${n}${e}`}function g(t){let n=t.warnings??[];return n.length?n.map((e)=>`WARNING: ${e}`).join(`
+import{isAbsolute as H_,join as w,resolve as J_}from"path";import{tool as P}from"@kilocode/plugin";import{homedir as d}from"os";import{join as N}from"path";var l=()=>process.env.HYDRON_TEST_HOME||d(),C=(q,J)=>process.env[q]||N(l(),J),c=()=>N(C("XDG_CONFIG_HOME",".config"),"hydron-cli"),i=()=>N(C("XDG_DATA_HOME",".local/share"),"hydron-cli"),g=()=>N(C("XDG_STATE_HOME",".local/state"),"hydron-cli");async function L(q){let J=Bun.file(q);if(!await J.exists())return;return J.json().catch(()=>{return})}async function O(){let q=process.env.KILO_API_URL?.trim();if(q)return q.replace(/\/+$/,"");let J=await L(N(c(),"server-config.json")),_=typeof J?.apiBaseUrl==="string"?J.apiBaseUrl:void 0;if(!_)throw Error("H2Loop backend URL unknown: set KILO_API_URL or sign in with `hydron auth login`.");return _.replace(/\/+$/,"")}function n(q){let J=q?.split(".")[1];if(!J)return"";try{let _=JSON.parse(Buffer.from(J.replace(/-/g,"+").replace(/_/g,"/"),"base64").toString("utf8"));return typeof _.sub==="string"?_.sub:""}catch{return""}}async function o(q){let J=n(q.access);if(J)return J;if(!q.refresh)return"";return new Bun.CryptoHasher("sha256").update(q.refresh).digest("hex").slice(0,12)}async function k(){let J=(await L(N(i(),"auth.json")))?.hydron;if(!J||J.type!=="oauth"||!J.access)throw Error("Not signed in to H2Loop. Run `hydron auth login` (or sign in from the TUI), then retry.");return J}async function z(){let q=await k();if(typeof q.expires==="number"&&q.expires>0&&Date.now()>=q.expires-30000)throw Error("The H2Loop session token has expired. Send any message in Hydron (the CLI refreshes it) or re-login with `hydron auth login`, then retry.");return q.access}async function v(q){let J=await fetch(`${await O()}/api/v1/workspaces`,{headers:{Authorization:`Bearer ${await z()}`},signal:q?AbortSignal.any([q,AbortSignal.timeout(30000)]):AbortSignal.timeout(30000)});if(J.status===401)throw Error("H2Loop rejected the session (401). Re-login with `hydron auth login`, then retry.");if(!J.ok)throw Error(`could not list H2Loop projects: HTTP ${J.status}`);let _=await J.json();return Array.isArray(_)?_:_?.items??[]}var f=()=>N(g(),"h2loop-project.json");async function S(q,J){let _=q===void 0||q===null?"":String(q).trim();if(/^\d+$/.test(_))return _;if(_){let V=await v(J),D=V.filter((W)=>W.name===_),B=D.length?D:V.filter((W)=>W.name?.toLowerCase()===_.toLowerCase());if(B.length===1)return String(B[0].id);if(B.length>1)throw Error(`workspace "${_}" is ambiguous: ${B.map((W)=>`${W.name} (id ${W.id})`).join(", ")}; pass the numeric id`);let F=V.filter((W)=>W.name?.toLowerCase().includes(_.toLowerCase())).slice(0,10);throw Error(`no H2Loop project named "${_}"`+(F.length?`; similar: ${F.map((W)=>`${W.name} (id ${W.id})`).join(", ")}`:`; you have ${V.length} project(s)`))}let H=await L(f());if(!H)throw Error("No H2Loop project selected (run `hydron projects select <id>`), or pass workspace_id (id or name).");let Y=await k();if(H.project&&typeof H.project==="object"){let V=H.project;if(typeof H.account==="string"&&H.account!==await o(Y))throw Error("The selected H2Loop project belongs to another account; select one again or pass workspace_id.");if(V.id!==void 0)return String(V.id)}let Q=H;if(Q.id===void 0)throw Error(`${f()} holds no project id; select a project again or pass workspace_id.`);if(!(await v(J)).some((V)=>String(V.id)===String(Q.id)))throw Error(`The selected project ${Q.name??""} (id ${Q.id}) is not accessible to the signed-in account; select another or pass workspace_id.`);return String(Q.id)}async function T(q,J,_,H){let Y=`${await O()}${q}?workspace_id=${encodeURIComponent(J)}`,Q=await fetch(Y,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${await z()}`},body:JSON.stringify(_),signal:H?AbortSignal.any([H,AbortSignal.timeout(120000)]):AbortSignal.timeout(120000)}),Z=await Q.text();if(Q.status===401)throw Error("H2Loop rejected the session (401). Re-login with `hydron auth login`, then retry.");if(Q.status===404&&Z.includes("Not Found"))throw Error(`${q} is not available on ${await O()} (backend predates the AUTOSAR endpoints).`);if(!Q.ok)throw Error(`H2Loop ${q} failed: HTTP ${Q.status} ${Z.slice(0,800)}`);try{return JSON.parse(Z)}catch(V){throw Error(`H2Loop ${q} returned non-JSON (${String(V)}): ${Z.slice(0,300)}`)}}var A=/\.arxml\b/i,b="Blocked: .arxml files must not be edited by hand (it breaks DEFINITION-REF/DEST, UUIDs and the round trip). Use ecuc_edit with ops by AUTOSAR path (read paths and allowed params with ecuc_read schema=true), then ecuc_validate.";function y(q,J){if(process.env.AUTOSAR_ALLOW_ARXML_EDIT==="1"||!J)return;let _=typeof J.filePath==="string"?J.filePath:typeof J.file_path==="string"?J.file_path:"";if(["edit","write","multiedit"].includes(q)){let H=Array.isArray(J.edits)?J.edits.some((Y)=>typeof Y?.filePath==="string"&&A.test(Y.filePath)):!1;if(A.test(_)||H)return`${b} (${q} on ${_||"an .arxml file"})`;return}if(q==="apply_patch"||q==="patch"){let H=String(J.patchText??J.patch??""),Y=H.match(/^\*\*\* (?:Add|Update|Delete) File: (.+\.arxml)\s*$/im)??H.match(/^\+\+\+ (?:b\/)?(.+\.arxml)/im);return Y?`${b} (${q} on ${Y[1].trim()})`:void 0}if(q==="bash"){let H=String(J.command??"");if(!A.test(H))return;let Y=/\b(?:sed|gsed)\b[^|;&]*\s-(?:[a-zA-Z]*i|-in-place)\b/.test(H)||/\bperl\b[^|;&]*\s-[a-zA-Z]*i/.test(H),Q=/(?:^|[^<>&0-9])>>?\s*['"]?[^\s'"|;&]*\.arxml\b/i.test(H)||/\btee\b[^|;&]*\.arxml\b/i.test(H);if(Y||Q)return`${b} (bash: ${H.slice(0,120)})`}return}import{existsSync as a}from"fs";import{dirname as t,join as E}from"path";import{fileURLToPath as s}from"url";var e="autosar-data==0.17.0";function r(){let q=t(s(import.meta.url)),J=[E(q,"..","python"),E(q,"..","..","python")].find((_)=>a(E(_,"ecuc_engine","__main__.py")));if(!J)throw Error(`ECUC engine not found next to ${q} (expected ../python/ecuc_engine)`);return J}async function __(q){try{return await Bun.spawn([...q,"-c","import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"],{stdout:"ignore",stderr:"ignore",stdin:"ignore"}).exited===0}catch{return!1}}var R={};async function q_(){if(R.cmd!==void 0)return R.cmd;let q=process.env.AUTOSAR_PYTHON?.trim(),_=q?[[q]]:[["uv","run","--no-project","--quiet","--with",e,"--python",">=3.10","python"],["python3"],["python"],["py","-3"]];for(let H of _)if(await __(H))return R.cmd=H,H;return R.cmd=null,null}async function G(q,J,_){let H=await q_();if(!H)return{ok:!1,error:"no Python >= 3.10 found. Install uv (https://docs.astral.sh/uv/) or Python 3.10+, or set AUTOSAR_PYTHON to an interpreter path."};let Y=r(),Q=Bun.spawn([...H,"-m","ecuc_engine","--root",q,...J,"--json"],{cwd:q,env:{...process.env,PYTHONPATH:[Y,process.env.PYTHONPATH].filter(Boolean).join(process.platform==="win32"?";":":")},stdout:"pipe",stderr:"pipe",stdin:"ignore",signal:_}),[Z,V]=await Promise.all([new Response(Q.stdout).text(),new Response(Q.stderr).text()]);await Q.exited;let D=Z.trim().split(`
+`).filter(Boolean).at(-1);if(!D)return{ok:!1,error:`engine produced no output (exit ${Q.exitCode}): ${V.trim().slice(-2000)}`};try{return JSON.parse(D)}catch(B){return{ok:!1,error:`engine output was not JSON (${String(B)}): ${D.slice(0,500)} ${V.slice(-500)}`}}}var $=P.schema,Q_=["# AUTOSAR pack active","Load the `autosar` skill for ARXML/ECUC work. Configured values: use ecuc_read (accepts a SHORT-NAME) or","autosar_config_lookup, not grep/read. Change config only with ecuc_edit (hand edits of .arxml are blocked),","then ecuc_validate. Reviewing C code using BSW APIs: run autosar_audit first. Cite @path (AUTOSAR path) and","@def (DEFINITION-REF) separately."].join(`
+`);function x(q){if(typeof q!=="string")return q;let J=q.trim();if(!J.startsWith("[")&&!J.startsWith("{")&&!J.startsWith('"'))return q;try{return x(JSON.parse(J))}catch{return q}}var U=(q)=>$.preprocess(x,q),I=" In answers cite, for every element, its AUTOSAR path (the value's @path, e.g. /Pkg/Com/ComConfig/MySig), its"+" DEFINITION-REF (@def, e.g. /AUTOSAR/EcucDefs/Com/ComConfig/ComSignal) and file:line \u2014 never give the"+" DEFINITION-REF when the path is asked.";function p(q,J=200){let _=q.slice(0,J).map((H)=>`${H.file}:${H.line} ${H.severity.toUpperCase()} ${H.rule} ${H.path} \u2014 ${H.message}${H.defRef?` [def ${H.defRef}]`:""}`);if(q.length>J)_.push(`\u2026 ${q.length-J} more`);return _}function M(q){let J=q.didYouMean?`
+Did you mean: ${q.didYouMean.join(", ")}`:"",_=q.schema?`
+Schema errors: ${JSON.stringify(q.schema)}`:"";return`ERROR: ${q.error}${J}${_}`}function X(q){let J=q.warnings??[];return J.length?J.map((_)=>`WARNING: ${_}`).join(`
 `)+`
-`:""}function l(t,n){if(!n)return t;return W(n)?n:G(t,n)}async function z(t){let n=Bun.file(T(t,".hydron","autosar.json"));if(!await n.exists())return{};return n.json().catch((e)=>{throw Error(`.hydron/autosar.json is not valid JSON: ${String(e)}`)})}async function Q(t,n){let e=(await z(t))[n];if(typeof e==="string")return{command:e};if(e&&typeof e==="object"&&typeof e.command==="string")return e;return}function k(t,n=150){let e=t.split(`
-`);return e.length>n?[`\u2026 (${e.length-n} earlier lines omitted)`,...e.slice(-n)].join(`
-`):t}async function Z(t,n,e,o){let i=process.platform==="win32"?["cmd","/d","/s","/c",t]:["sh","-c",t],a=Date.now(),r=Bun.spawn(i,{cwd:n,stdout:"pipe",stderr:"pipe",stdin:"ignore",signal:AbortSignal.any([o,AbortSignal.timeout(e*1000)])}),[d,u]=await Promise.all([new Response(r.stdout).text(),new Response(r.stderr).text()]);return{code:await r.exited,out:d,err:u,secs:Math.round((Date.now()-a)/1000)}}var U=(t)=>{let n=t.notes??[],e=t.errors??[];return[...n.map((o)=>`NOTE: ${typeof o==="string"?o:JSON.stringify(o)}`),...e.map((o)=>`BACKEND ERROR: ${typeof o==="string"?o:JSON.stringify(o)}`)]},ee=async(t)=>{let n=(e)=>p({description:e==="generate"?"Run the project's AUTOSAR code generator (e.g. the vendor's configurator CLI) as configured in .hydron/autosar.json `generate` ({command, cwd?, timeoutSec?} or a string; `{module}` and `{args}` placeholders are substituted). Run it only after ecuc_validate reports no errors. Asks the user for permission. Returns the exit code and the output tail; follow with arxml_diff/autosar_build.":"Run the project's build command as configured in .hydron/autosar.json `build` ({command, cwd?, timeoutSec?} or a string; `{module}`/`{args}` substituted). Asks the user for permission. Returns the exit code and the output tail (compiler/linker errors). Use after autosar_generate.",args:{module:s.string().optional().describe("module name substituted for {module} in the command, if used"),args:s.string().optional().describe("extra arguments substituted for {args} (or appended if no placeholder)"),project_dir:s.string().optional().describe("project root (default: session directory)")},async execute(o,i){let a=l(i.directory,o.project_dir),r=await Q(a,e);if(!r)return`No \`${e}\` command configured. Add it to ${T(a,".hydron","autosar.json")}, e.g.
-{"${e}": {"command": "${e==="generate"?"<vendor-cli> -p Config/Ecu.dpa -g {module}":"make -C Build all"}", "cwd": ".", "timeoutSec": 1800}}`;let d=o.args??"",u=r.command.replaceAll("{module}",o.module??""),c=u.includes("{args}")?u.replaceAll("{args}",d):`${u}${d?` ${d}`:""}`,m=l(a,r.cwd);await i.ask({permission:`autosar_${e}`,patterns:[c],always:[r.command],metadata:{command:c,cwd:m}}),i.metadata({title:`${e}: ${c}`});let f=await Z(c,m,r.timeoutSec??3600,i.abort),O=f.code===0?"OK":`FAILED (exit ${f.code})`;return{title:`autosar_${e} ${O}`,output:[`$ ${c}   (cwd ${m}, ${f.secs}s) -> ${O}`,f.out.trim()?`--- stdout (tail) ---
-${k(f.out)}`:"",f.err.trim()?`--- stderr (tail) ---
-${k(f.err,80)}`:""].filter(Boolean).join(`
-`),metadata:{exit:f.code}}}});return{"experimental.chat.system.transform":async(e,o)=>{o.system.push(K)},tool:{ecuc_read:p({description:'Read AUTOSAR ECUC configuration as compact ECUC JSON (keyed by def names: "<DefName>:<ShortName>" for containers, params by def short-name, references as "->/path"; every container carries @path). No path: lists modules and the param-def/config files found. A module/container path: its values to '+"`depth` levels (merged across split files). A param path (\u2026/Container/Param) or a def path "+"(/AUTOSAR/EcucDefs/\u2026): the value and/or the definition. schema=true adds the def summary (allowed "+"params with type/range/literals/multiplicity, allowed sub-containers) \u2014 read it before ecuc_edit. "+"Never read or edit ARXML by hand."+b,args:{path:s.string().optional().describe("AUTOSAR path of a module/container/parameter, or a def path"),depth:s.number().int().min(0).max(20).optional().describe("sub-container levels to expand (default 2)"),schema:s.boolean().optional().describe("include the param-def summary for the element"),project_dir:s.string().optional().describe("project root (default: session directory)")},async execute(e,o){let i=["read"];if(e.path)i.push(e.path);if(i.push("--depth",String(e.depth??2)),e.schema)i.push("--schema");let a=await y(l(o.directory,e.project_dir),i,o.abort);if(!a.ok)return g(a)+w(a);let{ok:r,engine:d,ms:u,warnings:c,...m}=a;return g(a)+JSON.stringify(m,null,1)}}),ecuc_edit:p({description:"Edit ECUC ARXML in place \u2014 the ONLY way to change configuration (never write ARXML yourself). Ops by "+"AUTOSAR path: {op:'set', path, param, value} (value scalar, '->/ref/path', or a list for multi-valued "+"params), {op:'add', path:<parent>, container:'DefName:ShortName', values:{\u2026ECUC JSON\u2026}}, {op:'add', "+"path, param, value} (append a value), {op:'remove', path[, param[, value]]}. The engine picks the value element type, DEFINITION-REF/DEST and VALUE-REF DEST from the param defs, rejects out-of-range/non-literal values, patches only the changed bytes in the file each element lives in (UUIDs, order, comments preserved), applies all ops or none, and checks ARXML schema validity. Returns the unified diff and the validation of touched files. ALWAYS run ecuc_validate after editing and fix what it reports."+b,args:{ops:s.array(s.object({op:s.enum(["set","add","remove"]),path:s.string().describe("AUTOSAR path of the target (or parent for add-container)"),param:s.string().optional().describe("parameter/reference def short-name"),value:s.any().optional().describe("value: number | boolean | string | '->/path' | list"),container:s.string().optional().describe("for add: 'DefName:ShortName' (or 'Name' if equal)"),values:s.record(s.string(),s.any()).optional().describe("for add: ECUC JSON of the new container")})).min(1),dry_run:s.boolean().optional().describe("compute and show the diff without writing"),force:s.boolean().optional().describe("write values that fail def checks (avoid; explain why if used)"),project_dir:s.string().optional().describe("project root (default: session directory)")},async execute(e,o){let i=["edit","--ops",JSON.stringify(e.ops)];if(e.dry_run)i.push("--dry-run");if(e.force)i.push("--force");let a=await y(l(o.directory,e.project_dir),i,o.abort);if(!a.ok){let c=a.changes??[];return g(a)+w(a)+(c.length?`
+`:""}function K(q,J){if(!J)return q;return H_(J)?J:J_(q,J)}async function V_(q){let J=Bun.file(w(q,".hydron","autosar.json"));if(!await J.exists())return{};return J.json().catch((_)=>{throw Error(`.hydron/autosar.json is not valid JSON: ${String(_)}`)})}async function Y_(q,J){let _=(await V_(q))[J];if(typeof _==="string")return{command:_};if(_&&typeof _==="object"&&typeof _.command==="string")return _;return}function m(q,J=150){let _=q.split(`
+`);return _.length>J?[`\u2026 (${_.length-J} earlier lines omitted)`,..._.slice(-J)].join(`
+`):q}async function Z_(q,J,_,H){let Y=process.platform==="win32"?["cmd","/d","/s","/c",q]:["sh","-c",q],Q=Date.now(),Z=Bun.spawn(Y,{cwd:J,stdout:"pipe",stderr:"pipe",stdin:"ignore",signal:AbortSignal.any([H,AbortSignal.timeout(_*1000)])}),[V,D]=await Promise.all([new Response(Z.stdout).text(),new Response(Z.stderr).text()]);return{code:await Z.exited,out:V,err:D,secs:Math.round((Date.now()-Q)/1000)}}async function u(q,J,_){let H=J.filter((V)=>V?.path&&/\/Com(Group)?Signal$/.test(String(V.definition_ref??""))&&V.ipdu===void 0&&V.direction===void 0);if(!H.length)return[];let Y=await G(q,["signal-owners",...new Set(H.map((V)=>V.path))],_);if(!Y.ok)return[`NOTE: owning I-PDU not computed locally (${Y.error})`];let Q=Y.owners,Z=[];for(let V of H){let D=Q[V.path];if(D===null||D===void 0){Z.push(`NOTE: ${V.path} is not in the local checkout (${q}); owning I-PDU/direction unknown`);continue}V.ipdu_local=D,Z.push(D.length?`${V.path}: owning I-PDU ${D.map((B)=>`${B.ipdu} (ComIPduDirection=${B.direction??"?"})`).join(", ")} [local ECUC]`:`${V.path}: referenced by no ComIPdu (ComIPduSignalRef) in the local ECUC`)}return Z}var h=(q)=>{let J=q.notes??[],_=q.errors??[];return[...J.map((H)=>`NOTE: ${typeof H==="string"?H:JSON.stringify(H)}`),..._.map((H)=>`BACKEND ERROR: ${typeof H==="string"?H:JSON.stringify(H)}`)]};async function $_(q,J){try{let _=await J(),H=typeof _==="string"?_:_.output;if(H&&H.trim())return _;return`${q}: no output (this is a bug in the AUTOSAR pack; retry or report it)`}catch(_){return`ERROR (${q}): ${_ instanceof Error?_.message:String(_)}`}}function B_(q){for(let[J,_]of Object.entries(q)){let H=_.execute;_.execute=(Y,Q)=>$_(J,()=>H(Y,Q))}return q}var D_=async(q)=>{let J=(_)=>P({description:_==="generate"?"Run the project's AUTOSAR code generator (e.g. the vendor's configurator CLI) as configured in .hydron/autosar.json `generate` ({command, cwd?, timeoutSec?} or a string; `{module}` and `{args}` placeholders are substituted). Run it only after ecuc_validate reports no errors. Asks the user for permission. Returns the exit code and the output tail; follow with arxml_diff/autosar_build.":"Run the project's build command as configured in .hydron/autosar.json `build` ({command, cwd?, timeoutSec?} or a string; `{module}`/`{args}` substituted). Asks the user for permission. Returns the exit code and the output tail (compiler/linker errors). Use after autosar_generate.",args:{module:$.string().optional().describe("module name substituted for {module} in the command, if used"),args:$.string().optional().describe("extra arguments substituted for {args} (or appended if no placeholder)"),project_dir:$.string().optional().describe("project root (default: session directory)")},async execute(H,Y){let Q=K(Y.directory,H.project_dir),Z=await Y_(Q,_);if(!Z)return`No \`${_}\` command configured. Add it to ${w(Q,".hydron","autosar.json")}, e.g.
+{"${_}": {"command": "${_==="generate"?"<vendor-cli> -p Config/Ecu.dpa -g {module}":"make -C Build all"}", "cwd": ".", "timeoutSec": 1800}}`;let V=H.args??"",D=Z.command.replaceAll("{module}",H.module??""),B=D.includes("{args}")?D.replaceAll("{args}",V):`${D}${V?` ${V}`:""}`,F=K(Q,Z.cwd);await Y.ask({permission:`autosar_${_}`,patterns:[B],always:[Z.command],metadata:{command:B,cwd:F}}),Y.metadata({title:`${_}: ${B}`});let W=await Z_(B,F,Z.timeoutSec??3600,Y.abort),j=W.code===0?"OK":`FAILED (exit ${W.code})`;return{title:`autosar_${_} ${j}`,output:[`$ ${B}   (cwd ${F}, ${W.secs}s) -> ${j}`,W.out.trim()?`--- stdout (tail) ---
+${m(W.out)}`:"",W.err.trim()?`--- stderr (tail) ---
+${m(W.err,80)}`:""].filter(Boolean).join(`
+`),metadata:{exit:W.code}}}});return{"tool.execute.before":async(_,H)=>{let Y=y(_.tool,H.args);if(Y)throw Error(Y)},"experimental.chat.system.transform":async(_,H)=>{H.system.push(Q_)},tool:B_({ecuc_read:P({description:`THE way to answer any question about configured ECUC values (use it instead of grep/read on .arxml). Read AUTOSAR ECUC configuration as compact ECUC JSON (keyed by def names: "<DefName>:<ShortName>" for containers, params by def short-name, references as "->/path"; every container carries @path = its AUTOSAR path, and @def = its DEFINITION-REF). No path: lists modules and the param-def/config files found. path may be a full AUTOSAR path, a SHORT-NAME ('DoorLatch') or a partial path ('ComConfig/DoorLatch', 'DoorLatch/ComBitPosition'); ambiguous names return candidate paths. A module/container: its values to `+"`depth` levels (merged across split files). A param path (\u2026/Container/Param) or a def path "+"(/AUTOSAR/EcucDefs/\u2026): the value and/or the definition. schema=true adds the def summary (allowed "+"params with type/range/literals/multiplicity, allowed sub-containers) \u2014 read it before ecuc_edit. "+"Never read or edit ARXML by hand."+I,args:{path:$.string().optional().describe("AUTOSAR path, SHORT-NAME or partial path of a module/container/parameter, or a def path"),depth:$.number().int().min(0).max(20).optional().describe("sub-container levels to expand (default 2)"),schema:$.boolean().optional().describe("include the param-def summary for the element"),project_dir:$.string().optional().describe("project root (default: session directory)")},async execute(_,H){let Y=["read"];if(_.path)Y.push(_.path);if(Y.push("--depth",String(_.depth??2)),_.schema)Y.push("--schema");let Q=await G(K(H.directory,_.project_dir),Y,H.abort);if(!Q.ok)return X(Q)+M(Q);let{ok:Z,engine:V,ms:D,warnings:B,...F}=Q;return X(Q)+JSON.stringify(F,null,1)}}),ecuc_edit:P({description:"Edit ECUC ARXML in place \u2014 the ONLY way to change configuration (edit/write/sed on .arxml are blocked). "+"Get exact paths and allowed params from ecuc_read (schema=true) first. Ops by AUTOSAR path: {op:'set', path, param, value} (value scalar, '->/ref/path', or a list for multi-valued "+"params), {op:'add', path:<parent>, container:'DefName:ShortName', values:{\u2026ECUC JSON\u2026}}, {op:'add', "+"path, param, value} (append a value), {op:'remove', path[, param[, value]]}. The engine picks the value element type, DEFINITION-REF/DEST and VALUE-REF DEST from the param defs, rejects out-of-range/non-literal values, patches only the changed bytes in the file each element lives in (UUIDs, order, comments preserved), applies all ops or none, and checks ARXML schema validity. Returns the unified diff and the validation of touched files. ALWAYS run ecuc_validate after editing and fix what it reports."+I,args:{ops:U($.array(U($.object({op:$.enum(["set","add","remove"]),path:$.string().describe("AUTOSAR path of the target (or parent for add-container)"),param:$.string().optional().describe("parameter/reference def short-name"),value:$.any().optional().describe("value: number | boolean | string | '->/path' | list"),container:$.string().optional().describe("for add: 'DefName:ShortName' (or 'Name' if equal)"),values:U($.record($.string(),$.any()).optional()).describe("for add: ECUC JSON of the new container")}))).min(1)).describe("list of ops (a JSON array; a JSON-encoded string is also accepted)"),dry_run:$.boolean().optional().describe("compute and show the diff without writing"),force:$.boolean().optional().describe("write values that fail def checks (avoid; explain why if used)"),project_dir:$.string().optional().describe("project root (default: session directory)")},async execute(_,H){let Y=["edit","--ops",JSON.stringify(_.ops)];if(_.dry_run)Y.push("--dry-run");if(_.force)Y.push("--force");let Q=await G(K(H.directory,_.project_dir),Y,H.abort);if(!Q.ok){let B=Q.changes??[];return X(Q)+M(Q)+(B.length?`
 Rejected diff:
-${c.map((m)=>m.diff).join(`
-`)}`:"")}let r=a.changes??[],d=a.validation,u=[`${a.written?"Written":"Dry run (nothing written)"}: ${a.applied} op(s), ${r.length} file(s) changed.`,...(a.notes??[]).map((c)=>`NOTE: ${c}`),...r.map((c)=>c.diff)];if(d)u.push(d.validated?`Validation of touched files: ${JSON.stringify(d.summary)}`:"Validation skipped: no param defs loaded.",...C(d.diagnostics,50));return{title:`ecuc_edit ${r.map((c)=>c.file).join(", ")}`,output:g(a)+u.join(`
-`)}}}),ecuc_validate:p({description:"Validate ECUC configuration against the param defs (project .hydron/autosar.json paramDefs, auto-discovered ECUC-MODULE-DEF files, or $AUTOSAR_PARAMDEFS): multiplicity, mandatory params/containers, integer/float ranges, enum literals, booleans, string length/regex, reference targets and destination types, dangling refs, duplicate paths, unknown definitions. Returns LSP-like diagnostics "+"file:line severity rule path \u2014 message [def DEFINITION-REF]. Run after EVERY ecuc_edit and before "+"autosar_generate. Without param defs it only warns."+b,args:{files:s.array(s.string()).optional().describe("only report diagnostics in these files"),module:s.string().optional().describe("only validate this module (e.g. Com)"),max:s.number().int().min(1).optional().describe("cap the diagnostics listed (default 200)"),project_dir:s.string().optional().describe("project root (default: session directory)")},async execute(e,o){let i=l(o.directory,e.project_dir),a=["validate"];for(let c of e.files??[])a.push("--file",l(i,c));if(e.module)a.push("--module",e.module);let r=await y(i,a,o.abort);if(!r.ok)return g(r)+w(r);let d=r.diagnostics,u=r.validated?`Validated ${r.modules.join(", ")||"(no modules)"} against ${r.defsLoaded} module def(s): ${d.length?JSON.stringify(r.summary):"no findings"}`:"NOT validated: no param definitions loaded.";return{title:`ecuc_validate ${JSON.stringify(r.summary)}`,output:g(r)+[u,...C(d,e.max??200)].join(`
-`)}}}),arxml_diff:p({description:"Semantic ARXML diff by AUTOSAR path between two files or directories (e.g. a git checkout of the old Config/ vs the current one, or Output/ before/after generation inputs). Ignores UUIDs, whitespace, comments, element order and file splits; ECUC values are compared per parameter. Returns added/removed/changed elements with the changed parameter values. Use it to review edits and PRs instead of a textual diff.",args:{a:s.string().describe("old file or directory"),b:s.string().describe("new file or directory"),project_dir:s.string().optional().describe("project root (default: session directory)")},async execute(e,o){let i=l(o.directory,e.project_dir),a=await y(i,["diff",l(i,e.a),l(i,e.b)],o.abort);if(!a.ok)return w(a);let{ok:r,engine:d,ms:u,...c}=a;return JSON.stringify(c,null,1)}}),autosar_trace:p({description:"Trace AUTOSAR configuration to code through the H2Loop code graph of the selected project: query with an AUTOSAR path, a SHORT-NAME, or a C symbol (reverse lookup). Returns the ARXML element (path, module, DEFINITION-REF, file:line, values), the C symbols it configures (generated macros/const tables via the symbolic-name rule or token/value matching, with method + score) and their callers in in-house code. Use for impact analysis ('what code changes if I change X?') and 'where does this symbol come from?'. Requires the project's code to be ingested."+b,args:{query:s.string().describe("AUTOSAR path, SHORT-NAME, or C symbol"),data_source_id:s.number().int().optional().describe("restrict to one code data source"),limit:s.number().int().min(1).max(100).optional().describe("max matches (default server-side)"),workspace_id:s.string().optional().describe("H2Loop project id (default: the selected project)")},async execute(e,o){let i=await A(e.workspace_id),a={query:e.query};if(e.data_source_id!==void 0)a.data_source_id=e.data_source_id;if(e.limit!==void 0)a.limit=e.limit;let r=await $("/api/v1/mcp/autosar/trace",i,a,o.abort),d=r.matches??[],u=[`${d.length} match(es) for "${e.query}" in workspace ${i}`+(r.data_sources_queried!==void 0?` (data sources queried: ${JSON.stringify(r.data_sources_queried)})`:""),...U(r),JSON.stringify(d,null,1)];if(!d.length)u.push("No match: try a SHORT-NAME, a full AUTOSAR path from ecuc_read, or the C symbol.");return{title:`autosar_trace ${e.query}`,output:u.join(`
-`)}}}),autosar_config_lookup:p({description:"Look up one ARXML element in the H2Loop code graph by AUTOSAR path: the element (module, DEFINITION-REF, file:line, values), its direct children, references out and in (who points at it), and linked C symbols. Use it to navigate config relations across the ingested repo (including files not in the local checkout); for local edits use ecuc_read/ecuc_edit."+b,args:{path:s.string().describe("AUTOSAR path, e.g. /Pkg/Com/ComConfig/MySignal"),data_source_id:s.number().int().optional().describe("restrict to one code data source"),workspace_id:s.string().optional().describe("H2Loop project id (default: the selected project)")},async execute(e,o){let i=await A(e.workspace_id),a={path:e.path};if(e.data_source_id!==void 0)a.data_source_id=e.data_source_id;let r=await $("/api/v1/mcp/autosar/config-lookup",i,a,o.abort),d=r.matches??[];return{title:`autosar_config_lookup ${e.path}`,output:[`${d.length} match(es) for ${e.path} in workspace ${i}`,...U(r),JSON.stringify(d,null,1)].join(`
-`)}}}),autosar_generate:n("generate"),autosar_build:n("build")}}},te=ee;export{te as Autosar};
+${B.map((F)=>F.diff).join(`
+`)}`:"")}let Z=Q.changes??[],V=Q.validation,D=[`${Q.written?"Written":"Dry run (nothing written)"}: ${Q.applied} op(s), ${Z.length} file(s) changed.`,...(Q.notes??[]).map((B)=>`NOTE: ${B}`),...Z.map((B)=>B.diff)];if(V)D.push(V.validated?`Validation of touched files: ${JSON.stringify(V.summary)}`:"Validation skipped: no param defs loaded.",...p(V.diagnostics,50));return{title:`ecuc_edit ${Z.map((B)=>B.file).join(", ")}`,output:X(Q)+D.join(`
+`)}}}),ecuc_validate:P({description:"Validate ECUC configuration against the param defs (project .hydron/autosar.json paramDefs, auto-discovered ECUC-MODULE-DEF files, or $AUTOSAR_PARAMDEFS): multiplicity, mandatory params/containers, integer/float ranges, enum literals, booleans, string length/regex, reference targets and destination types, dangling refs, duplicate paths, unknown definitions, plus semantic rule packs (H2L-*: Com signals inside their I-PDU and non-overlapping incl. Motorola bit order, unique handle IDs) that run even without defs. Returns LSP-like diagnostics "+"file:line severity rule path \u2014 message [def DEFINITION-REF]. Run after EVERY ecuc_edit and before "+"autosar_generate. Without param defs it only warns."+I,args:{files:U($.array($.string()).optional()).describe("only report diagnostics in these files"),module:$.string().optional().describe("only validate this module (e.g. Com)"),max:$.number().int().min(1).optional().describe("cap the diagnostics listed (default 200)"),project_dir:$.string().optional().describe("project root (default: session directory)")},async execute(_,H){let Y=K(H.directory,_.project_dir),Q=["validate"];for(let B of _.files??[])Q.push("--file",K(Y,B));if(_.module)Q.push("--module",_.module);let Z=await G(Y,Q,H.abort);if(!Z.ok)return X(Z)+M(Z);let V=Z.diagnostics,D=Z.validated?`Validated ${Z.modules.join(", ")||"(no modules)"} against ${Z.defsLoaded} module def(s): ${V.length?JSON.stringify(Z.summary):"no findings"}`:"NOT validated: no param definitions loaded.";return{title:`ecuc_validate ${JSON.stringify(Z.summary)}`,output:X(Z)+[D,...p(V,_.max??200)].join(`
+`)}}}),arxml_diff:P({description:"Semantic ARXML diff by AUTOSAR path between two files or directories (e.g. a git checkout of the old Config/ vs the current one, or Output/ before/after generation inputs). Ignores UUIDs, whitespace, comments, element order and file splits; ECUC values are compared per parameter. Returns added/removed/changed elements with the changed parameter values. Use it to review edits and PRs instead of a textual diff.",args:{a:$.string().describe("old file or directory"),b:$.string().describe("new file or directory"),project_dir:$.string().optional().describe("project root (default: session directory)")},async execute(_,H){let Y=K(H.directory,_.project_dir),Q=await G(Y,["diff",K(Y,_.a),K(Y,_.b)],H.abort);if(!Q.ok)return M(Q);let{ok:Z,engine:V,ms:D,...B}=Q;return JSON.stringify(B,null,1)}}),autosar_trace:P({description:"Trace AUTOSAR configuration to code through the H2Loop code graph of the selected project: query with an AUTOSAR path, a SHORT-NAME, or a C symbol (reverse lookup). Returns the ARXML element (path, module, DEFINITION-REF, file:line, values), the C symbols it configures (generated macros/const tables via the symbolic-name rule or token/value matching, with method + score) and their callers in in-house code. For a ComSignal it also shows the owning I-PDU and its ComIPduDirection (direction lives on the I-PDU). Use for impact analysis ('what code changes if I change X?') and 'where does this symbol come from?'. Requires the project's code to be ingested."+I,args:{query:$.string().describe("AUTOSAR path, SHORT-NAME, or C symbol"),data_source_id:$.number().int().optional().describe("restrict to one code data source"),limit:$.number().int().min(1).max(100).optional().describe("max matches (default server-side)"),workspace_id:$.union([$.string(),$.number()]).optional().describe("H2Loop project id or name (default: the project selected with `hydron projects select`)"),project_dir:$.string().optional().describe("local project root used to add I-PDU/direction for signals (default: session directory)")},async execute(_,H){let Y=await S(_.workspace_id,H.abort),Q={query:_.query};if(_.data_source_id!==void 0)Q.data_source_id=_.data_source_id;if(_.limit!==void 0)Q.limit=_.limit;let Z=await T("/api/v1/mcp/autosar/trace",Y,Q,H.abort),V=Z.matches??[],D=await u(K(H.directory,_.project_dir),V.map((F)=>F.arxml).filter((F)=>!!F),H.abort),B=[`${V.length} match(es) for "${_.query}" in workspace ${Y}`+(Z.data_sources_queried!==void 0?` (data sources queried: ${JSON.stringify(Z.data_sources_queried)})`:""),...h(Z),...D,JSON.stringify(V,null,1)];if(!V.length)B.push("No match: try a SHORT-NAME, a full AUTOSAR path from ecuc_read, or the C symbol.");return{title:`autosar_trace ${_.query}`,output:B.join(`
+`)}}}),autosar_config_lookup:P({description:"Look up one ARXML element in the H2Loop code graph by AUTOSAR path: the element (module, DEFINITION-REF, file:line, values), its direct children, references out and in (who points at it), and linked C symbols. Use it to navigate config relations across the ingested repo (including files not in the local checkout); for local edits use ecuc_read/ecuc_edit."+I,args:{path:$.string().describe("AUTOSAR path, e.g. /Pkg/Com/ComConfig/MySignal"),data_source_id:$.number().int().optional().describe("restrict to one code data source"),workspace_id:$.union([$.string(),$.number()]).optional().describe("H2Loop project id or name (default: the project selected with `hydron projects select`)"),project_dir:$.string().optional().describe("local project root used to add I-PDU/direction for signals (default: session directory)")},async execute(_,H){let Y=await S(_.workspace_id,H.abort),Q={path:_.path};if(_.data_source_id!==void 0)Q.data_source_id=_.data_source_id;let Z=await T("/api/v1/mcp/autosar/config-lookup",Y,Q,H.abort),V=Z.matches??[],D=await u(K(H.directory,_.project_dir),V.map((B)=>B.element).filter((B)=>!!B),H.abort);return{title:`autosar_config_lookup ${_.path}`,output:[`${V.length} match(es) for ${_.path} in workspace ${Y}`,...h(Z),...D,JSON.stringify(V,null,1)].join(`
+`)}}}),autosar_audit:P({description:"Integration review \u2014 run this FIRST when reviewing C code that uses BSW services. Deterministically scans "+"C files (default: .hydron/autosar.json `audit` paths, else Source/) for Com_Send/ReceiveSignal[Group], NvM_Read/WriteBlock/RestoreBlockDefaults, Dem_SetEventStatus/ReportErrorStatus, PduR_*Transmit and Rte_Write_/Rte_Read_ (resolved through the generated Output/ RTE headers), resolves every handle through the ECUC (symbolic name or raw number), and reports: H2L-API-001 raw numeric handle, -002 unknown handle, -003 direction mismatch (send on a RECEIVE I-PDU signal or receive on SEND), -004 C object width vs ComSignalType, -005 NvM NULL_PTR without a permanent RAM block (NULL_PTR WITH one is valid, SWS_NvM_00900). Each finding has file:line, evidence (configured values + AUTOSAR paths) and a spec citation; calls it cannot check are listed as unchecked, never guessed. Confirm findings with ecuc_read / autosar_trace.",args:{paths:U($.array($.string()).optional()).describe("C files/dirs to scan (default: audit paths or Source/)"),project_dir:$.string().optional().describe("project root (default: session directory)")},async execute(_,H){let Y=K(H.directory,_.project_dir),Q=await G(Y,["audit",...(_.paths??[]).map((F)=>K(Y,F))],H.abort);if(!Q.ok)return X(Q)+M(Q);let{findings:Z,unchecked:V,scanned:D}=Q,B=[`Scanned ${D.sources.length} C file(s), ${D.calls} BSW call(s): ${Z.length?JSON.stringify(Q.summary):"no findings"}`,...Z.map((F)=>`${F.file}:${F.line} ${F.severity.toUpperCase()} ${F.rule} ${F.call}
+  ${F.message}
+  evidence: ${JSON.stringify(F.evidence)}
+  spec: ${F.cite}${F.fix?`
+  fix: ${F.fix}`:""}`)];if(V.length)B.push(`Unchecked (${V.length}):`,...V.slice(0,50).map((F)=>`  ${F.file}:${F.line} ${F.call} \u2014 ${F.reason}`));return{title:`autosar_audit ${JSON.stringify(Q.summary)}`,output:X(Q)+B.join(`
+`)}}}),autosar_generate:J("generate"),autosar_build:J("build")})}},F_=D_;export{F_ as Autosar};

package/python/ecuc_engine/__init__.py

@@ -1,2 +1,2 @@
 """ECUC engine: load, read, edit, validate and diff AUTOSAR ECUC ARXML without regenerating files."""
-ENGINE_VERSION = "0.1.0"
+ENGINE_VERSION = "0.1.2"

package/python/ecuc_engine/audit.py

@@ -0,0 +1,452 @@
+"""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
+
+C_EXT = (".c", ".h")
+SKIP_DIRS = {".git", "node_modules", ".hydron", "Output", "build", "Build"}
+
+
+@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
+
+
+def _files(root: str, paths: list, exts=C_EXT, skip=SKIP_DIRS) -> list:
+    res = []
+    for p in paths:
+        full = p if os.path.isabs(p) else os.path.join(root, p)
+        if os.path.isfile(full):
+            res.append(full)
+            continue
+        for dp, dns, fns in os.walk(full):
+            dns[:] = sorted(d for d in dns if d not in skip and not d.startswith("."))
+            res.extend(os.path.join(dp, fn) for fn in sorted(fns) if fn.endswith(exts))
+    return res
+
+
+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: Optional[list] = None, headers: 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
+    paths = paths or cfg.get("paths") or (["Source"] if os.path.isdir(os.path.join(root, "Source")) else ["."])
+    headers = headers or cfg.get("headers") or [d for d in ("Output",) if os.path.isdir(os.path.join(root, d))]
+    sources = [f for f in _files(root, paths) if f.endswith(".c")]
+    hdrs = _files(root, headers, exts=(".h",), skip={".git", "node_modules"}) + [f for f in _files(root, paths) if f.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
+    return {"scanned": {"sources": [project.rel(f) for f in sources], "headers": len(hdrs), "calls": a.calls},
+            "summary": summary, "findings": a.findings, "unchecked": a.unchecked}
+
+
+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

@@ -21,6 +21,11 @@ def _ops(arg: str):
     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]
 
 
@@ -45,10 +50,15 @@ def main(argv=None) -> int:
     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):  # allow --json after the subcommand too
+    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()
@@ -64,6 +74,11 @@ def main(argv=None) -> int:
 
 
 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
         for x in (a.a, a.b):
@@ -74,6 +89,15 @@ def run(a) -> dict:
         return diff(a.a, a.b, rel)
     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=a.paths or None, headers=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],
@@ -85,7 +109,7 @@ def run(a) -> dict:
         return read(project, a.path, depth=a.depth, schema=a.schema)
     if a.cmd == "edit":
         from .edit import edit
-        res = edit(project, _ops(a.ops), dry_run=a.dry_run, force=a.force, run_validate=not a.no_validate)
+        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

package/python/ecuc_engine/ecucjson.py

@@ -78,6 +78,13 @@ def read(project: Project, path: Optional[str], depth: int = 2, schema: bool = F
         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)}
@@ -116,3 +123,32 @@ def _walk(e: Elem):
         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 "")

package/python/ecuc_engine/edit.py

@@ -206,6 +206,7 @@ class Editor:
     # ---------- ops ----------
     def apply(self, ops: list, force: bool = False):
         self.force = force
+        check_ops(ops)
         for i, op in enumerate(ops):
             kind = op.get("op")
             try:
@@ -355,6 +356,35 @@ class Editor:
                 os.replace(tmp, f)
 
 
+OP_KEYS = {"op", "path", "param", "value", "container", "values"}
+
+
+def check_ops(ops) -> None:
+    """Shape-check ops before touching anything: clear errors instead of tracebacks."""
+    if not isinstance(ops, list) or not ops:
+        raise EditError(f"ops must be a non-empty list of op objects, got {type(ops).__name__}")
+    for i, op in enumerate(ops):
+        if not isinstance(op, dict):
+            raise EditError(f"op {i} must be an object like {{\"op\": \"set\", \"path\": ..., \"param\": ..., \"value\": ...}}, "
+                            f"got {type(op).__name__}: {str(op)[:120]}")
+        unknown = set(op) - OP_KEYS
+        if unknown:
+            raise EditError(f"op {i}: unknown key(s) {sorted(unknown)}; allowed: {sorted(OP_KEYS)}")
+        if op.get("op") not in ("set", "add", "remove"):
+            raise EditError(f"op {i}: 'op' must be set, add or remove (got {op.get('op')!r})")
+        if not isinstance(op.get("path"), str) or not op["path"].startswith("/"):
+            raise EditError(f"op {i}: 'path' must be an absolute AUTOSAR path string ('/Pkg/Module/...'), got {op.get('path')!r}")
+        for k in ("param", "container"):
+            if k in op and op[k] is not None and not isinstance(op[k], str):
+                raise EditError(f"op {i}: '{k}' must be a string, got {type(op[k]).__name__}")
+        if "values" in op and op["values"] is not None and not isinstance(op["values"], dict):
+            raise EditError(f"op {i}: 'values' must be an object of ECUC JSON, got {type(op['values']).__name__}")
+        if op["op"] == "set" and "value" not in op:
+            raise EditError(f"op {i}: set needs 'value'")
+        if op["op"] == "add" and not op.get("container") and not op.get("param"):
+            raise EditError(f"op {i}: add needs 'container' (\"DefName:ShortName\") or 'param' + 'value'")
+
+
 def schema_check(path: str, data: bytes) -> Optional[str]:
     """Strict schema load with autosar-data when available. Returns an error string or None."""
     try:

package/python/ecuc_engine/rules/__init__.py

@@ -0,0 +1,82 @@
+"""Hand-written semantic rule packs (the "H" checks the param defs cannot express).
+
+A rule is a function registered with @rule(...). It receives a RuleContext and yields
+(elem, line, message, def_ref) tuples; the registry adds the rule id, severity and spec citation.
+Rules are keyed by module-relative DEFINITION-REFs ("Com/ComConfig/ComSignal/ComBitPosition"), so
+they work for /AUTOSAR/EcucDefs/... and vendor-relocated defs alike, and run with or without the
+param defs loaded. To add a pack: create a module here with @rule functions and import it below.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Optional
+
+from ..model import Elem, ParamVal, Project
+
+
+@dataclass
+class Rule:
+    id: str
+    severity: str
+    cite: str
+    title: str
+    fn: Callable
+
+
+RULES: list = []
+
+
+def rule(id: str, severity: str, cite: str, title: str):
+    def deco(fn):
+        RULES.append(Rule(id, severity, cite, title, fn))
+        return fn
+    return deco
+
+
+class RuleContext:
+    def __init__(self, project: Project):
+        self.p = project
+        self.defs = project.defs
+        self._by_rel: Optional[dict] = None
+
+    def rel(self, def_ref: Optional[str]) -> str:
+        return self.defs.rel(def_ref) if def_ref else ""
+
+    def containers(self, rel_def: str) -> list:
+        """All container values (first fragment per path) whose def is ``rel_def`` (module-relative)."""
+        if self._by_rel is None:
+            self._by_rel = {}
+            for path, group in self.p.by_path.items():
+                self._by_rel.setdefault(self.rel(group[0].def_ref), []).append(group[0])
+        return self._by_rel.get(rel_def, [])
+
+    def values(self, e: Elem, name: str) -> list:
+        return [pv for g in self.p.find(e.path) for pv in g.params if pv.name == name]
+
+    def value(self, e: Elem, name: str) -> Optional[ParamVal]:
+        v = self.values(e, name)
+        return v[0] if v else None
+
+    def text(self, e: Elem, name: str) -> Optional[str]:
+        v = self.value(e, name)
+        return v.value if v is not None else None
+
+    def target(self, pv: Optional[ParamVal]) -> Optional[Elem]:
+        if pv is None or not pv.value:
+            return None
+        hit = self.p.find(pv.value.strip())
+        return hit[0] if hit else None
+
+    def module_of(self, e: Elem) -> Elem:
+        while e.parent is not None:
+            e = e.parent
+        return e
+
+
+def run_rules(project: Project) -> Iterable[dict]:
+    from . import com, handles  # noqa: F401  (registers the packs)
+    ctx = RuleContext(project)
+    for r in RULES:
+        for e, line, msg, def_ref in r.fn(ctx):
+            yield {"file": project.rel(e.file), "line": line, "path": e.path, "rule": r.id,
+                   "severity": r.severity, "message": f"{msg} [{r.cite}]", "defRef": def_ref}

package/python/ecuc_engine/rules/com.py

@@ -0,0 +1,107 @@
+"""COM I-PDU packing rules: signals inside the I-PDU, no overlapping signals."""
+from __future__ import annotations
+
+from typing import Optional
+
+from . import rule
+from ..values import parse_int
+
+TYPE_BITS = {"BOOLEAN": 1, "UINT8": 8, "SINT8": 8, "UINT16": 16, "SINT16": 16, "UINT32": 32, "SINT32": 32,
+             "UINT64": 64, "SINT64": 64, "FLOAT32": 32, "FLOAT64": 64}
+CITE_BOUNDS = "ECUC_Com_00259 ComBitPosition (position within the I-PDU), ECUC_Com_00158 ComBitSize, ECUC_EcuC_00003 PduLength"
+CITE_OVERLAP = "SWS_Com_CONSTR_00102 Signals Separated in I-PDU"
+
+
+def _size(ctx, s) -> Optional[int]:
+    bs = parse_int(ctx.text(s, "ComBitSize") or "")
+    if bs is not None:
+        return bs
+    typ = (ctx.text(s, "ComSignalType") or "").strip()
+    if typ in ("UINT8_N", "UINT8_DYN"):
+        n = parse_int(ctx.text(s, "ComSignalLength") or "")
+        return n * 8 if n is not None else None
+    return TYPE_BITS.get(typ)
+
+
+def bits(pos: int, size: int, endian: str) -> list:
+    """Occupied bit indices (byte*8 + bit). ComBitPosition is the LSB. BIG_ENDIAN (Motorola) walks
+    toward the MSB by going up within a byte, then to bit 0 of the previous byte."""
+    if endian == "BIG_ENDIAN":
+        out, b = [], pos
+        for _ in range(size):
+            out.append(b)
+            b = b + 1 if b % 8 != 7 else b - 15
+        return out
+    return list(range(pos, pos + size))  # LITTLE_ENDIAN and OPAQUE (bit0 of first byte, little-endian order)
+
+
+def _ipdus(ctx):
+    """(ipdu, length_bytes|None, [(member, kind)]) for every ComIPdu."""
+    for ipdu in ctx.containers("Com/ComConfig/ComIPdu"):
+        pdu = ctx.target(ctx.value(ipdu, "ComPduIdRef"))
+        length = parse_int(ctx.text(pdu, "PduLength") or "") if pdu is not None else None
+        members = []
+        for ref in ctx.values(ipdu, "ComIPduSignalRef"):
+            s = ctx.target(ref)
+            if s is not None:
+                members.append(s)
+        for ref in ctx.values(ipdu, "ComIPduSignalGroupRef"):
+            grp = ctx.target(ref)
+            if grp is None:
+                continue
+            members.extend(c for g in ctx.p.find(grp.path) for c in g.children
+                           if ctx.rel(c.def_ref).endswith("/ComGroupSignal"))
+            members.append(grp)  # contributes only its update bit
+        yield ipdu, length, pdu, members
+
+
+def _layout(ctx, s):
+    """[(label, bitset, line)] a signal/group occupies: its value bits and its update bit."""
+    out = []
+    pos = parse_int(ctx.text(s, "ComBitPosition") or "")
+    size = _size(ctx, s)
+    if pos is not None and size:
+        endian = (ctx.text(s, "ComSignalEndianness") or "LITTLE_ENDIAN").strip()
+        out.append((s.name, bits(pos, size, endian), ctx.value(s, "ComBitPosition").node.line, pos, size, endian))
+    ub = parse_int(ctx.text(s, "ComUpdateBitPosition") or "")
+    if ub is not None:
+        out.append((f"{s.name}.updateBit", [ub], ctx.value(s, "ComUpdateBitPosition").node.line, ub, 1, "LITTLE_ENDIAN"))
+    return out
+
+
+@rule("H2L-COM-001", "error", CITE_BOUNDS, "signal bits lie inside its I-PDU (PduLength * 8)")
+def signal_in_pdu(ctx):
+    for ipdu, length, pdu, members in _ipdus(ctx):
+        if length is None:
+            continue
+        limit = length * 8
+        for s in members:
+            for label, bs, line, pos, size, endian in _layout(ctx, s):
+                lo, hi = min(bs), max(bs)
+                if lo < 0 or hi >= limit:
+                    yield s, line, (f"{label}: ComBitPosition={pos} ComBitSize={size} ({endian}) occupies bits {lo}..{hi}, "
+                                    f"outside I-PDU {ipdu.name} ({pdu.path} PduLength={length} bytes = bits 0..{limit - 1})"), \
+                        (ctx.value(s, "ComBitPosition") or ctx.value(s, "ComUpdateBitPosition")).def_ref
+
+
+@rule("H2L-COM-002", "error", CITE_OVERLAP, "signals of one I-PDU do not overlap")
+def no_overlap(ctx):
+    for ipdu, length, pdu, members in _ipdus(ctx):
+        owner: dict = {}
+        reported = set()
+        for s in members:
+            for label, bs, line, pos, size, endian in _layout(ctx, s):
+                for b in bs:
+                    prev = owner.get(b)
+                    if prev is None:
+                        owner[b] = (label, s)
+                        continue
+                    if prev[0] == label:
+                        continue
+                    key = tuple(sorted((prev[0], label)))
+                    if key in reported:
+                        continue
+                    reported.add(key)
+                    yield s, line, (f"{label} overlaps {prev[0]} at bit {b} in I-PDU {ipdu.name} "
+                                    f"({label}: pos {pos} size {size} {endian})"), \
+                        (ctx.value(s, "ComBitPosition") or ctx.value(s, "ComUpdateBitPosition")).def_ref

package/python/ecuc_engine/rules/handles.py

@@ -0,0 +1,42 @@
+"""Handle-ID uniqueness (TPS_ECUConfiguration 3.4.1.1 "Handle ID concept")."""
+from __future__ import annotations
+
+import re
+
+from . import rule
+from ..values import parse_int
+
+# Handle-ID params by name when no defs say so; with defs, any SYMBOLIC-NAME-VALUE integer counts.
+NAME = re.compile(r"(HandleId|^CanIfTxPduId|^CanIfRxPduId)$")
+
+
+@rule("H2L-HID-001", "error",
+      "TPS_ECUConfiguration 3.4.1.1 Handle ID concept; ECUC_Com_00165/00175, ECUC_PduR_00322, ECUC_CanIf_00591/00597",
+      "handle IDs are unique per module and handle-ID parameter")
+def unique_handle_ids(ctx):
+    seen: dict = {}  # (module path, rel def) -> {value: [(elem, pv)]}
+    for path, group in ctx.p.by_path.items():
+        e = group[0]
+        if e.kind != "container":
+            continue
+        mod = ctx.module_of(e)
+        for g in group:
+            for pv in g.params:
+                if pv.is_ref or pv.value is None:
+                    continue
+                d = ctx.defs.get(pv.def_ref)
+                is_handle = (d.kind == "INTEGER" and d.symbolic_name) if d is not None else False
+                if not is_handle and not NAME.search(pv.name):
+                    continue
+                v = parse_int(pv.value)
+                if v is None:
+                    continue
+                key = (mod.path, ctx.rel(pv.def_ref))
+                seen.setdefault(key, {}).setdefault(v, []).append((g, pv))
+    for (mod, rel), by_val in seen.items():
+        for v, hits in by_val.items():
+            if len(hits) < 2:
+                continue
+            names = ", ".join(sorted({h[0].name for h in hits}))
+            for g, pv in hits:
+                yield g, pv.node.line, f"{pv.name}={v} is used by {len(hits)} containers in {mod} ({names}); handle IDs must be unique", pv.def_ref

package/python/ecuc_engine/validate.py

@@ -17,6 +17,7 @@ Rules:
   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
 
@@ -205,6 +206,9 @@ def validate(project: Project, files: Optional[list] = None, module: Optional[st
             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)
@@ -215,6 +219,7 @@ def validate(project: Project, files: Optional[list] = None, module: Optional[st
         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,

package/python/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ecuc-engine"
-version = "0.1.0"
+version = "0.1.2"
 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

@@ -15,7 +15,10 @@ You are working on an AUTOSAR Classic ECU project. The configuration is ECUC ARX
 in `Output/` is derived from it; in-house code in `Source/` calls the generated symbols.
 
 ## Hard rules
-1. **Never hand-write or hand-edit ARXML** (no `write`/`edit`/`sed` on `.arxml`). Every change goes
+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
@@ -38,6 +41,7 @@ in `Output/` is derived from it; in-house code in `Source/` calls the generated
 | 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=…` |
+| Review C code that calls Com/NvM/Dem/PduR/RTE APIs | `autosar_audit` (first), then confirm with `autosar_trace` / `ecuc_read` |
 | 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 |
@@ -46,6 +50,28 @@ in `Output/` is derived from it; in-house code in `Source/` calls the generated
 `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`.
 
+## Integration review recipe (C code against the configuration)
+1. `autosar_audit` (scope with `paths` if asked about specific files). It resolves every BSW call's handle
+   through the ECUC and reports raw numeric handles, unknown handles, direction mismatches, C-width vs
+   ComSignalType mismatches and invalid NvM NULL_PTR use, each with evidence and a spec citation.
+2. Confirm each finding before reporting it: `ecuc_read <signal/block>` for the configured values and
+   `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.
+
+Facts that decide common review calls:
+- **Direction lives on the I-PDU**, not the signal: a ComSignal is TX or RX through the `ComIPduDirection`
+  of the ComIPdu that references it (`ComIPduSignalRef`). Sending an RX signal (or receiving a TX one)
+  fails at runtime (ECUC_Com_00493, SWS_Com_00197/00198).
+- **NvM `NULL_PTR` is valid** for `NvM_ReadBlock`/`NvM_WriteBlock` when the block has a permanent RAM block
+  (`NvMRamBlockDataAddress` set) or explicit synchronization: NvM then uses that RAM block
+  (SWS_NvM_00898/00899, SWS_NvM_00900/00901). It is an error only for a block with neither.
+- The data pointer of `Com_SendSignal`/`Com_ReceiveSignal` must point to an object of the signal's
+  `ComSignalType` size; a smaller variable is overread/overwritten.
+- Raw numeric handles break silently when the generator re-assigns IDs: use the symbolic name
+  `<Mod>Conf_<ContainerDef>_<ShortName>` (TPS_ECUC_02108).
+
 ## 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.
@@ -59,5 +85,9 @@ ECUC-MULT-CONTAINER/-PARAM, ECUC-CHOICE, ECUC-RANGE, ECUC-ENUM, ECUC-TYPE, ECUC-
 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; they do not cover
-SWS cross-module rules — reason about those explicitly.
+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.