Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat: update explain pipeline, render, and facts with package-lock changes
Tanner Kocher6befba7d10df
diff --git a/core-ingestion/package-lock.json b/core-ingestion/package-lock.jsonindex fe5c490e..33917a71 100644--- a/core-ingestion/package-lock.json+++ b/core-ingestion/package-lock.json@@ -418,7 +418,6 @@"integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==","dev": true,"license": "MIT",- "peer": true,"dependencies": {"undici-types": "~6.21.0"}@@ -997,7 +996,6 @@"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==","dev": true,"license": "MIT",- "peer": true,"engines": {"node": ">=12"},@@ -1166,7 +1164,6 @@"integrity": "sha512-7dxoA6kYvtgWw80265MyqJlkRl4yawIjO7S5MigytjELkX43fV2WsAXzsNfO7sBpPPCF5Gp0+XzHk0DwLCq3xQ==","hasInstallScript": true,"license": "MIT",- "peer": true,"dependencies": {"node-addon-api": "^8.0.0","node-gyp-build": "^4.8.0"@@ -1447,7 +1444,6 @@"integrity": "sha512-fPGaRNj9Zytaf8LEiBhY7Z6ijnFKdzU/+mL8EFBaKr7Vw1/FWcTBAMW0wLPJAGMPX38ZPVCVgLceWiEqeoqL2Q==","dev": true,"license": "MIT",- "peer": true,"dependencies": {"@oxc-project/runtime": "0.115.0","lightningcss": "^1.32.0",diff --git a/ix-cli/package-lock.json b/ix-cli/package-lock.jsonindex baefd683..42b46657 100644--- a/ix-cli/package-lock.json+++ b/ix-cli/package-lock.json@@ -1,12 +1,12 @@{"name": "@ix/cli",- "version": "0.1.0",+ "version": "0.2.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@ix/cli",- "version": "0.1.0",+ "version": "0.2.0","dependencies": {"chalk": "^5.3.0","commander": "^12.0.0",@@ -23,9 +23,9 @@}},"node_modules/@esbuild/aix-ppc64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.3.tgz",- "integrity": "sha512-9fJMTNFTWZMh5qwrBItuziu834eOCUcEqymSH7pY+zoMVEZg3gcPuBNxH1EvfVYe9h0x/Ptw8KBzv7qxb7l8dg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.4.tgz",+ "integrity": "sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==","cpu": ["ppc64"],@@ -40,9 +40,9 @@}},"node_modules/@esbuild/android-arm": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.3.tgz",- "integrity": "sha512-i5D1hPY7GIQmXlXhs2w8AWHhenb00+GxjxRncS2ZM7YNVGNfaMxgzSGuO8o8SJzRc/oZwU2bcScvVERk03QhzA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.4.tgz",+ "integrity": "sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==","cpu": ["arm"],@@ -57,9 +57,9 @@}},"node_modules/@esbuild/android-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.3.tgz",- "integrity": "sha512-YdghPYUmj/FX2SYKJ0OZxf+iaKgMsKHVPF1MAq/P8WirnSpCStzKJFjOjzsW0QQ7oIAiccHdcqjbHmJxRb/dmg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.4.tgz",+ "integrity": "sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==","cpu": ["arm64"],@@ -74,9 +74,9 @@}},"node_modules/@esbuild/android-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.3.tgz",- "integrity": "sha512-IN/0BNTkHtk8lkOM8JWAYFg4ORxBkZQf9zXiEOfERX/CzxW3Vg1ewAhU7QSWQpVIzTW+b8Xy+lGzdYXV6UZObQ==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.4.tgz",+ "integrity": "sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==","cpu": ["x64"],@@ -91,9 +91,9 @@}},"node_modules/@esbuild/darwin-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.3.tgz",- "integrity": "sha512-Re491k7ByTVRy0t3EKWajdLIr0gz2kKKfzafkth4Q8A5n1xTHrkqZgLLjFEHVD+AXdUGgQMq+Godfq45mGpCKg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.4.tgz",+ "integrity": "sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==","cpu": ["arm64"],@@ -108,9 +108,9 @@}},"node_modules/@esbuild/darwin-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.3.tgz",- "integrity": "sha512-vHk/hA7/1AckjGzRqi6wbo+jaShzRowYip6rt6q7VYEDX4LEy1pZfDpdxCBnGtl+A5zq8iXDcyuxwtv3hNtHFg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.4.tgz",+ "integrity": "sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==","cpu": ["x64"],@@ -125,9 +125,9 @@}},"node_modules/@esbuild/freebsd-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.3.tgz",- "integrity": "sha512-ipTYM2fjt3kQAYOvo6vcxJx3nBYAzPjgTCk7QEgZG8AUO3ydUhvelmhrbOheMnGOlaSFUoHXB6un+A7q4ygY9w==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.4.tgz",+ "integrity": "sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==","cpu": ["arm64"],@@ -142,9 +142,9 @@}},"node_modules/@esbuild/freebsd-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.3.tgz",- "integrity": "sha512-dDk0X87T7mI6U3K9VjWtHOXqwAMJBNN2r7bejDsc+j03SEjtD9HrOl8gVFByeM0aJksoUuUVU9TBaZa2rgj0oA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.4.tgz",+ "integrity": "sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==","cpu": ["x64"],@@ -159,9 +159,9 @@}},"node_modules/@esbuild/linux-arm": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.3.tgz",- "integrity": "sha512-s6nPv2QkSupJwLYyfS+gwdirm0ukyTFNl3KTgZEAiJDd+iHZcbTPPcWCcRYH+WlNbwChgH2QkE9NSlNrMT8Gfw==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.4.tgz",+ "integrity": "sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==","cpu": ["arm"],@@ -176,9 +176,9 @@}},"node_modules/@esbuild/linux-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.3.tgz",- "integrity": "sha512-sZOuFz/xWnZ4KH3YfFrKCf1WyPZHakVzTiqji3WDc0BCl2kBwiJLCXpzLzUBLgmp4veFZdvN5ChW4Eq/8Fc2Fg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.4.tgz",+ "integrity": "sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==","cpu": ["arm64"],@@ -193,9 +193,9 @@}},"node_modules/@esbuild/linux-ia32": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.3.tgz",- "integrity": "sha512-yGlQYjdxtLdh0a3jHjuwOrxQjOZYD/C9PfdbgJJF3TIZWnm/tMd/RcNiLngiu4iwcBAOezdnSLAwQDPqTmtTYg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.4.tgz",+ "integrity": "sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==","cpu": ["ia32"],@@ -210,9 +210,9 @@}},"node_modules/@esbuild/linux-loong64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.3.tgz",- "integrity": "sha512-WO60Sn8ly3gtzhyjATDgieJNet/KqsDlX5nRC5Y3oTFcS1l0KWba+SEa9Ja1GfDqSF1z6hif/SkpQJbL63cgOA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.4.tgz",+ "integrity": "sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==","cpu": ["loong64"],@@ -227,9 +227,9 @@}},"node_modules/@esbuild/linux-mips64el": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.3.tgz",- "integrity": "sha512-APsymYA6sGcZ4pD6k+UxbDjOFSvPWyZhjaiPyl/f79xKxwTnrn5QUnXR5prvetuaSMsb4jgeHewIDCIWljrSxw==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.4.tgz",+ "integrity": "sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==","cpu": ["mips64el"],@@ -244,9 +244,9 @@}},"node_modules/@esbuild/linux-ppc64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.3.tgz",- "integrity": "sha512-eizBnTeBefojtDb9nSh4vvVQ3V9Qf9Df01PfawPcRzJH4gFSgrObw+LveUyDoKU3kxi5+9RJTCWlj4FjYXVPEA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.4.tgz",+ "integrity": "sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==","cpu": ["ppc64"],@@ -261,9 +261,9 @@}},"node_modules/@esbuild/linux-riscv64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.3.tgz",- "integrity": "sha512-3Emwh0r5wmfm3ssTWRQSyVhbOHvqegUDRd0WhmXKX2mkHJe1SFCMJhagUleMq+Uci34wLSipf8Lagt4LlpRFWQ==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.4.tgz",+ "integrity": "sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==","cpu": ["riscv64"],@@ -278,9 +278,9 @@}},"node_modules/@esbuild/linux-s390x": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.3.tgz",- "integrity": "sha512-pBHUx9LzXWBc7MFIEEL0yD/ZVtNgLytvx60gES28GcWMqil8ElCYR4kvbV2BDqsHOvVDRrOxGySBM9Fcv744hw==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.4.tgz",+ "integrity": "sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==","cpu": ["s390x"],@@ -295,9 +295,9 @@}},"node_modules/@esbuild/linux-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.3.tgz",- "integrity": "sha512-Czi8yzXUWIQYAtL/2y6vogER8pvcsOsk5cpwL4Gk5nJqH5UZiVByIY8Eorm5R13gq+DQKYg0+JyQoytLQas4dA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.4.tgz",+ "integrity": "sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==","cpu": ["x64"],@@ -312,9 +312,9 @@}},"node_modules/@esbuild/netbsd-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.3.tgz",- "integrity": "sha512-sDpk0RgmTCR/5HguIZa9n9u+HVKf40fbEUt+iTzSnCaGvY9kFP0YKBWZtJaraonFnqef5SlJ8/TiPAxzyS+UoA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.4.tgz",+ "integrity": "sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==","cpu": ["arm64"],@@ -329,9 +329,9 @@}},"node_modules/@esbuild/netbsd-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.3.tgz",- "integrity": "sha512-P14lFKJl/DdaE00LItAukUdZO5iqNH7+PjoBm+fLQjtxfcfFE20Xf5CrLsmZdq5LFFZzb5JMZ9grUwvtVYzjiA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.4.tgz",+ "integrity": "sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==","cpu": ["x64"],@@ -346,9 +346,9 @@}},"node_modules/@esbuild/openbsd-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.3.tgz",- "integrity": "sha512-AIcMP77AvirGbRl/UZFTq5hjXK+2wC7qFRGoHSDrZ5v5b8DK/GYpXW3CPRL53NkvDqb9D+alBiC/dV0Fb7eJcw==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.4.tgz",+ "integrity": "sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==","cpu": ["arm64"],@@ -363,9 +363,9 @@}},"node_modules/@esbuild/openbsd-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.3.tgz",- "integrity": "sha512-DnW2sRrBzA+YnE70LKqnM3P+z8vehfJWHXECbwBmH/CU51z6FiqTQTHFenPlHmo3a8UgpLyH3PT+87OViOh1AQ==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.4.tgz",+ "integrity": "sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==","cpu": ["x64"],@@ -380,9 +380,9 @@}},"node_modules/@esbuild/openharmony-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.3.tgz",- "integrity": "sha512-NinAEgr/etERPTsZJ7aEZQvvg/A6IsZG/LgZy+81wON2huV7SrK3e63dU0XhyZP4RKGyTm7aOgmQk0bGp0fy2g==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.4.tgz",+ "integrity": "sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==","cpu": ["arm64"],@@ -397,9 +397,9 @@}},"node_modules/@esbuild/sunos-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.3.tgz",- "integrity": "sha512-PanZ+nEz+eWoBJ8/f8HKxTTD172SKwdXebZ0ndd953gt1HRBbhMsaNqjTyYLGLPdoWHy4zLU7bDVJztF5f3BHA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.4.tgz",+ "integrity": "sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==","cpu": ["x64"],@@ -414,9 +414,9 @@}},"node_modules/@esbuild/win32-arm64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.3.tgz",- "integrity": "sha512-B2t59lWWYrbRDw/tjiWOuzSsFh1Y/E95ofKz7rIVYSQkUYBjfSgf6oeYPNWHToFRr2zx52JKApIcAS/D5TUBnA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.4.tgz",+ "integrity": "sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==","cpu": ["arm64"],@@ -431,9 +431,9 @@}},"node_modules/@esbuild/win32-ia32": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.3.tgz",- "integrity": "sha512-QLKSFeXNS8+tHW7tZpMtjlNb7HKau0QDpwm49u0vUp9y1WOF+PEzkU84y9GqYaAVW8aH8f3GcBck26jh54cX4Q==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.4.tgz",+ "integrity": "sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==","cpu": ["ia32"],@@ -448,9 +448,9 @@}},"node_modules/@esbuild/win32-x64": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.3.tgz",- "integrity": "sha512-4uJGhsxuptu3OcpVAzli+/gWusVGwZZHTlS63hh++ehExkVT8SgiEf7/uC/PclrPPkLhZqGgCTjd0VWLo6xMqA==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.4.tgz",+ "integrity": "sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==","cpu": ["x64"],@@ -849,12 +849,11 @@"license": "MIT"},"node_modules/@types/node": {- "version": "20.19.35",- "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.35.tgz",- "integrity": "sha512-Uarfe6J91b9HAUXxjvSOdiO2UPOKLm07Q1oh0JHxoZ1y8HoqxDAu3gVrsrOHeiio0kSsoVBt4wFrKOm0dKxVPQ==",+ "version": "20.19.37",+ "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",+ "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==","dev": true,"license": "MIT",- "peer": true,"dependencies": {"undici-types": "~6.21.0"}@@ -1109,9 +1108,9 @@}},"node_modules/esbuild": {- "version": "0.27.3",- "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.3.tgz",- "integrity": "sha512-8VwMnyGCONIs6cWue2IdpHxHnAjzxnw2Zr7MkVxB2vjmQ2ivqGFb4LEG3SMnv0Gb2F/G/2yA8zUaiL1gywDCCg==",+ "version": "0.27.4",+ "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.4.tgz",+ "integrity": "sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==","dev": true,"hasInstallScript": true,"license": "MIT",@@ -1122,32 +1121,32 @@"node": ">=18"},"optionalDependencies": {- "@esbuild/aix-ppc64": "0.27.3",- "@esbuild/android-arm": "0.27.3",- "@esbuild/android-arm64": "0.27.3",- "@esbuild/android-x64": "0.27.3",- "@esbuild/darwin-arm64": "0.27.3",- "@esbuild/darwin-x64": "0.27.3",- "@esbuild/freebsd-arm64": "0.27.3",- "@esbuild/freebsd-x64": "0.27.3",- "@esbuild/linux-arm": "0.27.3",- "@esbuild/linux-arm64": "0.27.3",- "@esbuild/linux-ia32": "0.27.3",- "@esbuild/linux-loong64": "0.27.3",- "@esbuild/linux-mips64el": "0.27.3",- "@esbuild/linux-ppc64": "0.27.3",- "@esbuild/linux-riscv64": "0.27.3",- "@esbuild/linux-s390x": "0.27.3",- "@esbuild/linux-x64": "0.27.3",- "@esbuild/netbsd-arm64": "0.27.3",- "@esbuild/netbsd-x64": "0.27.3",- "@esbuild/openbsd-arm64": "0.27.3",- "@esbuild/openbsd-x64": "0.27.3",- "@esbuild/openharmony-arm64": "0.27.3",- "@esbuild/sunos-x64": "0.27.3",- "@esbuild/win32-arm64": "0.27.3",- "@esbuild/win32-ia32": "0.27.3",- "@esbuild/win32-x64": "0.27.3"+ "@esbuild/aix-ppc64": "0.27.4",+ "@esbuild/android-arm": "0.27.4",+ "@esbuild/android-arm64": "0.27.4",+ "@esbuild/android-x64": "0.27.4",+ "@esbuild/darwin-arm64": "0.27.4",+ "@esbuild/darwin-x64": "0.27.4",+ "@esbuild/freebsd-arm64": "0.27.4",+ "@esbuild/freebsd-x64": "0.27.4",+ "@esbuild/linux-arm": "0.27.4",+ "@esbuild/linux-arm64": "0.27.4",+ "@esbuild/linux-ia32": "0.27.4",+ "@esbuild/linux-loong64": "0.27.4",+ "@esbuild/linux-mips64el": "0.27.4",+ "@esbuild/linux-ppc64": "0.27.4",+ "@esbuild/linux-riscv64": "0.27.4",+ "@esbuild/linux-s390x": "0.27.4",+ "@esbuild/linux-x64": "0.27.4",+ "@esbuild/netbsd-arm64": "0.27.4",+ "@esbuild/netbsd-x64": "0.27.4",+ "@esbuild/openbsd-arm64": "0.27.4",+ "@esbuild/openbsd-x64": "0.27.4",+ "@esbuild/openharmony-arm64": "0.27.4",+ "@esbuild/sunos-x64": "0.27.4",+ "@esbuild/win32-arm64": "0.27.4",+ "@esbuild/win32-ia32": "0.27.4",+ "@esbuild/win32-x64": "0.27.4"}},"node_modules/estree-walker": {@@ -1330,16 +1329,16 @@}},"node_modules/mlly": {- "version": "1.8.0",- "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.0.tgz",- "integrity": "sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==",+ "version": "1.8.1",+ "resolved": "https://registry.npmjs.org/mlly/-/mlly-1.8.1.tgz",+ "integrity": "sha512-SnL6sNutTwRWWR/vcmCYHSADjiEesp5TGQQ0pXyLhW5IoeibRlF/CbSLailbB3CNqJUk9cVJ9dUDnbD7GrcHBQ==","dev": true,"license": "MIT","dependencies": {- "acorn": "^8.15.0",+ "acorn": "^8.16.0","pathe": "^2.0.3","pkg-types": "^1.3.1",- "ufo": "^1.6.1"+ "ufo": "^1.6.3"}},"node_modules/mlly/node_modules/pathe": {diff --git a/ix-cli/src/cli/__tests__/explain-pipeline.test.ts b/ix-cli/src/cli/__tests__/explain-pipeline.test.tsindex 17cd52e6..a71421b6 100644--- a/ix-cli/src/cli/__tests__/explain-pipeline.test.ts+++ b/ix-cli/src/cli/__tests__/explain-pipeline.test.ts@@ -2,6 +2,8 @@ import { describe, it, expect } from "vitest";import { inferRole } from "../explain/role-inference.js";import { inferImportance } from "../explain/importance.js";import { renderExplanation } from "../explain/render.js";+import { inferHierarchySemantics, synthesizeSystemRole, hierarchyImpactPhrase } from "../explain/hierarchy-semantics.js";+import { inferSystemMeaning } from "../explain/system-meaning.js";import type { EntityFacts } from "../explain/facts.js";function makeFacts(overrides: Partial<EntityFacts> = {}): EntityFacts {@@ -756,8 +758,8 @@ describe("fixture regression: pickBest", () => {const importance = inferImportance(pickBestFacts);const rendered = renderExplanation(pickBestFacts, role, importance);expect(rendered.whyItMatters).not.toContain("Moderate impact");- expect(rendered.whyItMatters).toContain("downstream dependents");- expect(rendered.whyItMatters).toContain("structurally important");+ expect(rendered.whyItMatters).toContain("downstream");+ expect(rendered.whyItMatters).toContain("critical decision point");});it("includes named usage example", () => {@@ -768,6 +770,386 @@ describe("fixture regression: pickBest", () => {});});+// ── Hierarchy semantics inference ─────────────────────────────────────────────++describe("inferHierarchySemantics", () => {+ it("infers client layer from Cli > Client path", () => {+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Cli / Client", kind: "subsystem" },+ { name: "api.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "api-client");+ expect(sem.layerName).toBe("CLI client layer");+ expect(sem.boundaryRole).toBe("boundary");+ expect(sem.systemRole).toContain("boundary");+ });++ it("infers resolution pipeline from Resolve path", () => {+ const facts = makeFacts({+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Resolve", kind: "subsystem" },+ { name: "resolve.ts", kind: "file" },+ ],+ subsystemName: "Resolve",+ });+ const sem = inferHierarchySemantics(facts, "resolution-helper");+ expect(sem.flowName).toBe("resolution pipeline");+ });++ it("infers impact pipeline from Impact path", () => {+ const facts = makeFacts({+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Impact", kind: "subsystem" },+ { name: "impact.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "orchestrator");+ expect(sem.flowName).toBe("impact pipeline");+ });++ it("infers explanation subsystem from Explain path", () => {+ const facts = makeFacts({+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Explain", kind: "subsystem" },+ { name: "render.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "shared-utility");+ expect(sem.flowName).toBe("explanation pipeline");+ expect(sem.layerName).toBe("explanation subsystem");+ });++ it("infers conflict-resolution flow from Conflict path", () => {+ const facts = makeFacts({+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Conflict", kind: "subsystem" },+ { name: "conflict.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "service-method");+ expect(sem.flowName).toBe("conflict-resolution flow");+ });++ it("infers command layer from Commands path (not more specific)", () => {+ const facts = makeFacts({+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Commands", kind: "module" },+ { name: "locate.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "registration-function");+ expect(sem.layerName).toBe("command layer");+ });++ it("falls back to subsystem name when no specific match", () => {+ const facts = makeFacts({+ subsystemName: "Ingestion",+ systemPath: [+ { name: "IX Memory", kind: "system" },+ { name: "Ingestion", kind: "subsystem" },+ { name: "parser.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "service");+ expect(sem.layerName).toBe("Ingestion subsystem");+ });++ it("returns empty reasons when no systemPath", () => {+ const facts = makeFacts({ systemPath: undefined });+ const sem = inferHierarchySemantics(facts, "unknown");+ expect(sem.reasons).toEqual([]);+ expect(sem.layerName).toBeUndefined();+ });+});++// ── System-aware role synthesis ──────────────────────────────────────────────++describe("synthesizeSystemRole", () => {+ it("produces boundary description for api-client in client layer", () => {+ const facts = makeFacts({ kind: "class", name: "IxClient" });+ const sem = inferHierarchySemantics(+ { ...facts, systemPath: [{ name: "Cli", kind: "system" }, { name: "Client", kind: "subsystem" }, { name: "api.ts", kind: "file" }] },+ "api-client",+ );+ const result = synthesizeSystemRole(facts, "api-client", sem);+ expect(result).toContain("boundary");+ expect(result).toContain("CLI client layer");+ });++ it("produces flow-aware description for selection-helper in resolution pipeline", () => {+ const sem: any = { flowName: "resolution pipeline", layerName: "resolution pipeline", reasons: [] };+ const facts = makeFacts({ name: "pickBest" });+ const result = synthesizeSystemRole(facts, "selection-helper", sem);+ expect(result).toContain("resolution pipeline");+ });++ it("returns null when no hierarchy context", () => {+ const sem: any = { reasons: [] };+ const facts = makeFacts({});+ const result = synthesizeSystemRole(facts, "api-client", sem);+ expect(result).toBeNull();+ });+});++// ── System-aware explanation output ─────────────────────────────────────────++describe("system-aware explanation sentence", () => {+ it("IxClient explanation mentions client layer, not just 'API client for the CLI'", () => {+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ path: "src/client/api.ts",+ memberCount: 15,+ members: ["query", "search", "entity", "expand", "ingest", "post", "get", "patch"],+ callerCount: 12,+ dependentCount: 20,+ downstreamDependents: 35,+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Cli / Client", kind: "subsystem" },+ { name: "api.ts", kind: "file" },+ ],+ subsystemName: "Cli / Client",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("client layer");+ expect(rendered.explanation).toContain("boundary");+ });++ it("pickBest explanation mentions resolution pipeline", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ downstreamDependents: 25,+ downstreamDepth: 3,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Resolution", kind: "subsystem" },+ { name: "resolve.ts", kind: "file" },+ ],+ subsystemName: "Resolution",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("resolution flow");+ });++ it("resolve in ConflictService mentions conflict-resolution flow", () => {+ const facts = makeFacts({+ kind: "method",+ name: "resolve",+ path: "src/cli/conflict.ts",+ container: { kind: "class", name: "ConflictService" },+ callerCount: 3,+ calleeCount: 2,+ dependentCount: 5,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Conflict", kind: "subsystem" },+ { name: "conflict.ts", kind: "file" },+ { name: "ConflictService", kind: "class" },+ ],+ subsystemName: "Conflict",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("conflict-resolution flow");+ });++ it("falls back to local description when no systemPath", () => {+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ path: "src/client/api.ts",+ memberCount: 15,+ members: ["query", "search", "entity", "expand", "ingest", "post", "get", "patch"],+ callerCount: 12,+ dependentCount: 20,+ downstreamDependents: 35,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Should use local-only description+ expect(rendered.explanation).toContain("API client");+ expect(rendered.explanation).not.toContain("client layer");+ });+});++// ── System-aware "Why it matters" ───────────────────────────────────────────++describe("system-aware why-it-matters", () => {+ it("IxClient: mentions backend-facing CLI operations, not generic 'codebase'", () => {+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ path: "src/client/api.ts",+ memberCount: 15,+ members: ["query", "search", "entity", "expand", "ingest", "post", "get", "patch"],+ callerCount: 12,+ dependentCount: 20,+ downstreamDependents: 35,+ systemPath: [+ { name: "Cli", kind: "system" },+ { name: "Cli / Client", kind: "subsystem" },+ { name: "api.ts", kind: "file" },+ ],+ subsystemName: "Cli / Client",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Should mention client layer and backend operations, not generic "codebase"+ expect(rendered.whyItMatters).toContain("client layer");+ expect(rendered.whyItMatters).toContain("backend");+ expect(rendered.whyItMatters).not.toContain("across the codebase");+ });++ it("pickBest: mentions resolution pipeline in choke-point wording", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ dependentCount: 2,+ downstreamDependents: 25,+ downstreamDepth: 3,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Resolution", kind: "subsystem" },+ { name: "resolve.ts", kind: "file" },+ ],+ subsystemName: "Resolution",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ expect(importance.category).toBe("pipeline-choke-point");+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.whyItMatters).toContain("resolution flow");+ expect(rendered.whyItMatters).toContain("decision point");+ });++ it("localized helper: mentions scope when hierarchy context available", () => {+ const facts = makeFacts({+ name: "trimWhitespace",+ callerCount: 1,+ dependentCount: 1,+ importerCount: 0,+ memberCount: 0,+ downstreamDependents: 2,+ downstreamDepth: 1,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Explain", kind: "subsystem" },+ { name: "render.ts", kind: "file" },+ ],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ expect(importance.category).toBe("localized-helper");+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.whyItMatters).toContain("explanation");+ expect(rendered.whyItMatters).toContain("localized");+ });++ it("falls back to generic wording when no hierarchy data", () => {+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ path: "src/client/api.ts",+ memberCount: 15,+ members: ["query", "search", "entity", "expand", "ingest", "post", "get", "patch"],+ callerCount: 12,+ dependentCount: 20,+ downstreamDependents: 35,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Without hierarchy data, generic phrasing is acceptable+ expect(rendered.whyItMatters).toContain("ix impact");+ expect(rendered.whyItMatters).toBeDefined();+ });++ it("medium-importance entity: mentions layer in review advice", () => {+ const facts = makeFacts({+ kind: "function",+ name: "formatDate",+ callerCount: 3,+ dependentCount: 3,+ importerCount: 1,+ downstreamDependents: 5,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Commands", kind: "module" },+ { name: "utils.ts", kind: "file" },+ ],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ expect(importance.level).toBe("medium");+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.whyItMatters).toContain("command layer");+ });+});++// ── Graceful fallback behavior ──────────────────────────────────────────────++describe("graceful fallback without map data", () => {+ it("no systemPath: explanation is still valid", () => {+ const facts = makeFacts({+ systemPath: undefined,+ subsystemName: undefined,+ moduleName: undefined,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.context).not.toContain("System path:");+ expect(rendered.explanation).toBeDefined();+ expect(rendered.whyItMatters).toBeDefined();+ });++ it("empty systemPath: no crash, local behavior", () => {+ const facts = makeFacts({ systemPath: [] });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toBeDefined();+ });++ it("systemPath with only file nodes: no hierarchy claims", () => {+ const facts = makeFacts({+ systemPath: [+ { name: "utils.ts", kind: "file" },+ ],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).not.toContain("subsystem");+ expect(rendered.explanation).not.toContain("pipeline");+ });+});+// ── Distinction from overview ───────────────────────────────────────────────describe("explain vs overview distinction", () => {@@ -791,3 +1173,544 @@ describe("explain vs overview distinction", () => {expect(rendered.notes).toBeDefined();});});++// ── System meaning inference ────────────────────────────────────────────────++describe("inferSystemMeaning", () => {+ it("detects foundation archetype for enum kinds", () => {+ const facts = makeFacts({+ kind: "enum",+ name: "NodeKind",+ importerCount: 8,+ dependentCount: 12,+ });+ const sem = inferHierarchySemantics(facts, "type-definition");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "type-definition", sem, importance);+ expect(meaning).not.toBeNull();+ expect(meaning!.archetype).toBe("foundation");+ });++ it("detects foundation archetype for interface kinds", () => {+ const facts = makeFacts({+ kind: "interface",+ name: "GraphQueryApi",+ importerCount: 5,+ dependentCount: 8,+ });+ const sem = inferHierarchySemantics(facts, "type-definition");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "type-definition", sem, importance);+ expect(meaning).not.toBeNull();+ expect(meaning!.archetype).toBe("foundation");+ expect(meaning!.identitySummary).toContain("contract");+ });++ it("detects boundary archetype for api-client role", () => {+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ path: "src/client/api.ts",+ memberCount: 15,+ members: ["get", "post", "entity"],+ callerCount: 12,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Client", kind: "subsystem" },+ { name: "api.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "api-client");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "api-client", sem, importance);+ expect(meaning).not.toBeNull();+ expect(meaning!.archetype).toBe("boundary");+ });++ it("detects flow archetype for selection-helper in pipeline", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Resolution", kind: "subsystem" },+ { name: "resolve.ts", kind: "file" },+ ],+ });+ const sem = inferHierarchySemantics(facts, "selection-helper");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "selection-helper", sem, importance);+ expect(meaning).not.toBeNull();+ expect(meaning!.archetype).toBe("flow");+ });++ it("returns null for general archetype without hierarchy", () => {+ const facts = makeFacts({+ kind: "function",+ name: "doStuff",+ callerCount: 1,+ calleeCount: 1,+ });+ const sem = inferHierarchySemantics(facts, "localized-helper");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "localized-helper", sem, importance);+ expect(meaning).toBeNull();+ });++ it("infers domain noun from entity name", () => {+ const facts = makeFacts({+ kind: "enum",+ name: "NodeKind",+ importerCount: 8,+ });+ const sem = inferHierarchySemantics(facts, "type-definition");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "type-definition", sem, importance);+ expect(meaning!.identitySummary).toContain("node");+ });++ it("generates responsibility for widely-imported foundation", () => {+ const facts = makeFacts({+ kind: "interface",+ name: "ParseResult",+ importerCount: 6,+ dependentCount: 10,+ });+ const sem = inferHierarchySemantics(facts, "type-definition");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "type-definition", sem, importance);+ expect(meaning!.responsibility).toContain("multiple services");+ });++ it("generates importance narrative for foundation with hierarchy", () => {+ const facts = makeFacts({+ kind: "enum",+ name: "NodeKind",+ importerCount: 8,+ dependentCount: 12,+ systemPath: [+ { name: "IX Memory", kind: "system" },+ { name: "Model", kind: "subsystem" },+ { name: "graph.ts", kind: "file" },+ ],+ subsystemName: "Model",+ });+ const sem = inferHierarchySemantics(facts, "type-definition");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "type-definition", sem, importance);+ expect(meaning!.importanceNarrative).toContain("shared");+ expect(meaning!.importanceNarrative).toContain("ix impact");+ });++ it("generates usage summary for widely-imported foundation", () => {+ const facts = makeFacts({+ kind: "interface",+ name: "GraphQueryApi",+ importerCount: 5,+ callerCount: 5,+ topCallers: ["ContextService", "SearchRoutes", "IngestionService"],+ systemPath: [+ { name: "IX Memory", kind: "system" },+ { name: "API", kind: "subsystem" },+ { name: "query.ts", kind: "file" },+ ],+ subsystemName: "API",+ });+ const sem = inferHierarchySemantics(facts, "type-definition");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "type-definition", sem, importance);+ expect(meaning!.usageSummary).toBeDefined();+ expect(meaning!.usageSummary).toContain("ContextService");+ });++ it("detects foundation for model files with members", () => {+ const facts = makeFacts({+ kind: "file",+ name: "Node.scala",+ path: "memory-layer/src/main/scala/model/Node.scala",+ memberCount: 5,+ importerCount: 6,+ });+ const sem = inferHierarchySemantics(facts, "container");+ const importance = inferImportance(facts);+ const meaning = inferSystemMeaning(facts, "container", sem, importance);+ expect(meaning).not.toBeNull();+ expect(meaning!.archetype).toBe("foundation");+ expect(meaning!.identitySummary).toContain("definition file");+ });+});++// ── System meaning integration with render ──────────────────────────────────++describe("system-meaning render integration", () => {+ it("foundation type: explanation uses domain-aware identity, not generic 'type definition'", () => {+ const facts = makeFacts({+ kind: "enum",+ name: "NodeKind",+ importerCount: 8,+ dependentCount: 12,+ downstreamDependents: 20,+ systemPath: [+ { name: "IX Memory", kind: "system" },+ { name: "Model", kind: "subsystem" },+ { name: "graph.ts", kind: "file" },+ ],+ subsystemName: "Model",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Should mention "node" domain and "classification" or "foundational"+ expect(rendered.explanation).toContain("node");+ expect(rendered.explanation).toContain("foundational");+ // Should NOT just say "a type definition"+ expect(rendered.explanation).not.toBe(expect.stringContaining("a type definition."));+ });++ it("foundation type: whyItMatters explains systemic consequences", () => {+ const facts = makeFacts({+ kind: "enum",+ name: "NodeKind",+ importerCount: 8,+ dependentCount: 12,+ downstreamDependents: 20,+ systemPath: [+ { name: "IX Memory", kind: "system" },+ { name: "Model", kind: "subsystem" },+ { name: "graph.ts", kind: "file" },+ ],+ subsystemName: "Model",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.whyItMatters).toContain("contract");+ expect(rendered.whyItMatters).toContain("ix impact");+ });++ it("foundation type: usedBy uses contextual summary when available", () => {+ const facts = makeFacts({+ kind: "interface",+ name: "GraphQueryApi",+ importerCount: 5,+ callerCount: 5,+ dependentCount: 8,+ topCallers: ["ContextService", "SearchRoutes", "IngestionService"],+ systemPath: [+ { name: "IX Memory", kind: "system" },+ { name: "API", kind: "subsystem" },+ { name: "query.ts", kind: "file" },+ ],+ subsystemName: "API",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Should use system-meaning usage summary, not plain "Used by X, Y, Z"+ expect(rendered.usedBy).toContain("ContextService");+ });++ it("foundation type without hierarchy: still gets domain-aware explanation", () => {+ const facts = makeFacts({+ kind: "enum",+ name: "EdgeKind",+ importerCount: 4,+ dependentCount: 6,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("edge");+ expect(rendered.explanation).toContain("foundational");+ });++ it("foundation model file: gets file-specific explanation", () => {+ const facts = makeFacts({+ kind: "file",+ name: "Node.scala",+ path: "memory-layer/src/main/scala/model/Node.scala",+ memberCount: 5,+ importerCount: 6,+ dependentCount: 10,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("definition file");+ expect(rendered.explanation).toContain("model");+ });++ it("non-foundation entity: explanation unchanged by system meaning", () => {+ // IxClient without hierarchy → should use existing local logic, not system meaning+ const facts = makeFacts({+ kind: "class",+ name: "IxClient",+ path: "src/client/api.ts",+ memberCount: 15,+ members: ["query", "search", "entity", "expand", "ingest", "post", "get", "patch"],+ callerCount: 12,+ dependentCount: 20,+ downstreamDependents: 35,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Should use existing local description+ expect(rendered.explanation).toContain("API client");+ expect(rendered.explanation).not.toContain("foundational");+ });++ it("non-foundation entity with hierarchy: existing pipeline handles it", () => {+ // pickBest with resolution pipeline → flow archetype, but existing render handles it+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ dependentCount: 2,+ downstreamDependents: 25,+ downstreamDepth: 3,+ systemPath: [+ { name: "CLI", kind: "system" },+ { name: "Resolution", kind: "subsystem" },+ { name: "resolve.ts", kind: "file" },+ ],+ subsystemName: "Resolution",+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Should use flow-semantics rendering for callable with high-confidence flow+ expect(rendered.explanation).toContain("resolution flow");+ expect(rendered.whyItMatters).toContain("decision point");+ });++ it("confidence language still applies to foundation types", () => {+ const facts = makeFacts({+ kind: "interface",+ name: "UserProps",+ importerCount: 2,+ });+ const role = inferRole(facts);+ expect(role.confidence).toBe("high");+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("serves as");+ expect(rendered.explanation).not.toContain("appears to be");+ });+});++// ── Flow semantics inference ────────────────────────────────────────────────++import { inferFlowSemantics } from "../explain/flow-semantics.js";++describe("inferFlowSemantics", () => {+ it("pickBest in resolve.ts → resolution flow, selection step, high confidence", () => {+ const facts = makeFacts({+ name: "pickBest",+ path: "ix-cli/src/cli/resolve.ts",+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.flowName).toBe("resolution flow");+ expect(flow.roleInFlow).toBe("selection step");+ expect(flow.confidence).toBe("high");+ });++ it("resolveConflict in conflict.ts + ConflictService → conflict-resolution flow", () => {+ const facts = makeFacts({+ name: "resolveConflict",+ path: "src/cli/conflict.ts",+ container: { kind: "class", name: "ConflictService" },+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.flowName).toBe("conflict-resolution flow");+ expect(flow.roleInFlow).toBe("conflict resolver");+ expect(flow.confidence).toBe("high");+ });++ it("parseInput in parser.ts → parsing pipeline, parsing step", () => {+ const facts = makeFacts({+ name: "parseInput",+ path: "src/parser.ts",+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.flowName).toBe("parsing pipeline");+ expect(flow.roleInFlow).toBe("parsing step");+ expect(flow.confidence).toBe("high");+ });++ it("scoreCandidate → scoring pipeline, scoring step", () => {+ const facts = makeFacts({+ name: "scoreCandidate",+ path: "src/scoring.ts",+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.flowName).toBe("scoring pipeline");+ expect(flow.roleInFlow).toBe("scoring step");+ });++ it("doStuff in utils.ts → low confidence, no flow", () => {+ const facts = makeFacts({+ name: "doStuff",+ path: "src/utils.ts",+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.confidence).toBe("low");+ expect(flow.flowName).toBeUndefined();+ });++ it("container-based: execute in IngestionService → ingestion pipeline", () => {+ const facts = makeFacts({+ name: "execute",+ container: { kind: "class", name: "IngestionService" },+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.flowName).toBe("ingestion pipeline");+ });++ it("priority: resolve in ConflictService + conflict.ts → conflict wins over resolution", () => {+ const facts = makeFacts({+ name: "resolve",+ path: "src/conflict.ts",+ container: { kind: "class", name: "ConflictService" },+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.flowName).toBe("conflict-resolution flow");+ });++ it("upstream/downstream hints populated correctly", () => {+ const facts = makeFacts({+ name: "pickBest",+ path: "ix-cli/src/cli/resolve.ts",+ topCallers: ["resolveFileOrEntity"],+ downstreamDependents: 25,+ });+ const flow = inferFlowSemantics(facts);+ expect(flow.upstreamHint).toBe("called from resolveFileOrEntity");+ expect(flow.downstreamHint).toContain("25 downstream");+ });+});++// ── Flow-aware rendering for callables ──────────────────────────────────────++describe("flow-aware rendering for callables", () => {+ it("pickBest: explanation says 'selection step in the resolution flow'", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "ix-cli/src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ downstreamDependents: 25,+ downstreamDepth: 3,+ topCallers: ["resolveFileOrEntity"],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("selection step");+ expect(rendered.explanation).toContain("resolution flow");+ expect(rendered.explanation).not.toContain("CLI client layer");+ });++ it("pickBest: context includes 'Called from:' and 'Feeds into:'", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "ix-cli/src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ downstreamDependents: 25,+ downstreamDepth: 3,+ topCallers: ["resolveFileOrEntity"],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.context).toContain("Called from:");+ expect(rendered.context).toContain("Feeds into:");+ });++ it("pickBest: whyItMatters references 'selection step' and 'resolution'", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "ix-cli/src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ downstreamDependents: 25,+ downstreamDepth: 3,+ topCallers: ["resolveFileOrEntity"],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.whyItMatters).toContain("selection step");+ expect(rendered.whyItMatters).toContain("resolution flow");+ });++ it("resolveConflict in ConflictService: explanation says 'conflict'", () => {+ const facts = makeFacts({+ kind: "method",+ name: "resolveConflict",+ path: "src/cli/conflict.ts",+ container: { kind: "class", name: "ConflictService" },+ callerCount: 3,+ calleeCount: 2,+ dependentCount: 5,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("conflict");+ });++ it("weak signal (doStuff): falls back, no 'Called from:' or 'Feeds into:'", () => {+ const facts = makeFacts({+ kind: "function",+ name: "doStuff",+ path: "src/utils.ts",+ callerCount: 2,+ topCallers: ["main"],+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.context).not.toContain("Called from:");+ expect(rendered.context).not.toContain("Feeds into:");+ });++ it("non-callable (interface ResolveOptions): no flow rendering despite file name", () => {+ const facts = makeFacts({+ kind: "interface",+ name: "ResolveOptions",+ path: "src/cli/resolve.ts",+ importerCount: 4,+ });+ const role = inferRole(facts);+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ // Interface is foundation type, not callable → no flow rendering+ expect(rendered.context).not.toContain("Called from:");+ expect(rendered.context).not.toContain("Feeds into:");+ });++ it("confidence language preserved for flow-rendered callables", () => {+ const facts = makeFacts({+ kind: "function",+ name: "pickBest",+ path: "ix-cli/src/cli/resolve.ts",+ callerCount: 1,+ calleeCount: 3,+ });+ const role = inferRole(facts);+ expect(role.confidence).toBe("high");+ const importance = inferImportance(facts);+ const rendered = renderExplanation(facts, role, importance);+ expect(rendered.explanation).toContain("serves as");+ });+});diff --git a/ix-cli/src/cli/explain/facts.ts b/ix-cli/src/cli/explain/facts.tsindex f25aedd5..fd096c97 100644--- a/ix-cli/src/cli/explain/facts.ts+++ b/ix-cli/src/cli/explain/facts.ts@@ -3,6 +3,7 @@ import type { EntityRef, Diagnostic } from "../format.js";import { isRawId } from "../resolve.js";import { isFileStale } from "../stale.js";import { buildDependencyTree } from "../commands/depends.js";+import { getSystemPath } from "../hierarchy.js";export interface EntityFacts {// Identity@@ -39,6 +40,11 @@ export interface EntityFacts {// Call detailscallList?: EntityRef[];+ // Hierarchy (scene graph)+ systemPath?: Array<{ name: string; kind: string }>;+ subsystemName?: string;+ moduleName?: string;+// Stalenessstale: boolean;@@ -55,7 +61,7 @@ export async function collectFacts(const diagnostics: Diagnostic[] = [];// Run parallel graph queries (including bounded downstream tree)- const [details, callersResult, calleesResult, dependentsResult, importersResult, membersResult, provenance, downstream] =+ const [details, callersResult, calleesResult, dependentsResult, importersResult, membersResult, provenance, downstream, hierarchyPath] =await Promise.all([client.entity(targetId),client.expand(targetId, { direction: "in", predicates: ["CALLS"] }),@@ -67,6 +73,7 @@ export async function collectFacts(buildDependencyTree(client, targetId, { maxDepth: 4, maxNodes: 100 }).catch(() => ({tree: [], truncated: false, nodesVisited: 0, maxDepthReached: 0,})),+ getSystemPath(client, targetId).catch(() => []),]);const node = details.node as any;@@ -187,6 +194,13 @@ export async function collectFacts(const docstring = node.attrs?.docstring || node.attrs?.description || undefined;const history = provenance as any;+ // Extract hierarchy info+ const systemPathMapped = hierarchyPath.length > 0+ ? hierarchyPath.map((n: any) => ({ name: n.name, kind: n.kind }))+ : undefined;+ const subsystemName = hierarchyPath.find((n: any) => n.kind === "subsystem")?.name;+ const moduleName = hierarchyPath.find((n: any) => n.kind === "module")?.name;+return {id: targetId,name: node.name || node.attrs?.name || targetName,@@ -208,6 +222,9 @@ export async function collectFacts(introducedRev: node.createdRev ?? node.created_rev,historyLength: history?.chain?.length ?? 0,callList,+ systemPath: systemPathMapped,+ subsystemName,+ moduleName,stale,diagnostics,};diff --git a/ix-cli/src/cli/explain/render.ts b/ix-cli/src/cli/explain/render.tsindex 88b1753e..3a9c2bed 100644--- a/ix-cli/src/cli/explain/render.ts+++ b/ix-cli/src/cli/explain/render.ts@@ -1,6 +1,14 @@import type { EntityFacts } from "./facts.js";import type { RoleInference, RoleLabel } from "./role-inference.js";import type { ImportanceInference } from "./importance.js";+import {+ type HierarchySemantics,+ inferHierarchySemantics,+ synthesizeSystemRole,+ hierarchyImpactPhrase,+} from "./hierarchy-semantics.js";+import { inferSystemMeaning } from "./system-meaning.js";+import { type FlowSemantics, inferFlowSemantics } from "./flow-semantics.js";export interface ExplanationOutput {explanation: string;@@ -10,10 +18,10 @@ export interface ExplanationOutput {notes: string[];}-// ── Role description templates ──────────────────────────────────────────────+// ── Role description templates (local-only fallback) ────────────────────────-/** Build a role description that incorporates container/file context when available. */-function describeRole(role: RoleLabel, facts: EntityFacts): string {+/** Build a role description from local signals only (no hierarchy). */+function describeRoleLocal(role: RoleLabel, facts: EntityFacts): string {const containerName = facts.container?.name;const file = fileBaseName(facts.path);@@ -69,7 +77,6 @@ function describeRole(role: RoleLabel, facts: EntityFacts): string {if (file) return `a localized helper defined in ${file}`;return "a localized internal helper";case "unknown":- // Context-aware fallback — never say "role could not be determined"if (containerName) return `a member of ${containerName}`;if (file) return `a localized helper defined in ${file}`;return "a localized internal helper";@@ -82,6 +89,133 @@ function fileBaseName(path?: string): string {return base.replace(/\.[^.]+$/, "");}+// ── Callable detection ──────────────────────────────────────────────────────++const CALLABLE_KINDS = new Set(["function", "method", "def", "fun", "constructor"]);++function isCallable(kind: string, role: RoleLabel): boolean {+ if (CALLABLE_KINDS.has(kind.toLowerCase())) return true;+ return ([+ "selection-helper", "resolution-helper", "scoring-helper",+ "service-method", "entry-point", "registration-function",+ "orchestrator", "localized-helper", "shared-utility",+ ] as RoleLabel[]).includes(role);+}++// ── Flow rendering helpers ──────────────────────────────────────────────────++const FLOW_RESPONSIBILITIES: Record<string, string> = {+ "selection step": "chooses the best candidate from multiple possible matches",+ "resolution step": "resolves ambiguous references to concrete entities",+ "conflict resolver": "processes and resolves conflicts between competing changes",+ "conflict detection step": "detects conflicting changes across the graph",+ "conflict resolution step": "handles conflict resolution logic",+ "merge step": "merges competing changes into a consistent state",+ "parsing step": "transforms raw input into structured data",+ "input processing step": "reads and decodes input for further processing",+ "tokenization step": "breaks input into discrete tokens for analysis",+ "traversal step": "walks the dependency graph to discover affected nodes",+ "impact analysis step": "analyzes the impact of changes across the graph",+ "rendering step": "transforms structured data into human-readable output",+ "inference step": "infers semantic properties from structural signals",+ "explanation step": "generates explanations from inferred semantics",+ "ingestion step": "ingests source files into the knowledge graph",+ "persistence step": "persists data to the backing store",+ "scoring step": "assigns numeric scores to candidates for ranking",+ "ranking step": "orders candidates by computed scores",+ "weighting step": "applies weights to scoring signals",+};++const FLOW_BEHAVIOR_VERBS: Record<string, string> = {+ "selection step": "determines which candidate is selected",+ "resolution step": "determines how references are resolved",+ "conflict resolver": "determines how conflicts are handled",+ "conflict detection step": "determines which conflicts are detected",+ "conflict resolution step": "determines how conflicts are resolved",+ "merge step": "determines how changes are merged",+ "parsing step": "determines how input is parsed",+ "input processing step": "determines how input is processed",+ "tokenization step": "determines how input is tokenized",+ "traversal step": "determines how the graph is traversed",+ "impact analysis step": "determines how impact is analyzed",+ "rendering step": "determines how output is rendered",+ "inference step": "determines what semantics are inferred",+ "explanation step": "determines how explanations are generated",+ "ingestion step": "determines how files are ingested",+ "persistence step": "determines how data is persisted",+ "scoring step": "determines how candidates are scored",+ "ranking step": "determines how candidates are ranked",+ "weighting step": "determines how weights are applied",+};++function flowActionNoun(flowName: string): string {+ if (flowName.includes("conflict")) return "conflict resolution";+ if (flowName.includes("resolution")) return "entity resolution";+ if (flowName.includes("parsing")) return "input parsing";+ if (flowName.includes("impact")) return "impact analysis";+ if (flowName.includes("explanation")) return "explanation generation";+ if (flowName.includes("ingestion")) return "file ingestion";+ if (flowName.includes("scoring")) return "candidate scoring";+ return "processing";+}++function renderFlowExplanation(+ facts: EntityFacts,+ flow: FlowSemantics,+ phrasing: { roleVerb: string; impactVerb: string },+): string {+ const role = flow.roleInFlow ?? "step";+ const flowName = flow.flowName ?? "pipeline";+ const responsibility = FLOW_RESPONSIBILITIES[role] ?? `performs a step in the ${flowName}`;+ return `\`${facts.name}\` ${phrasing.roleVerb} a ${role} in the ${flowName}. It ${responsibility}.`;+}++function renderFlowWhyItMatters(+ facts: EntityFacts,+ flow: FlowSemantics,+ importance: ImportanceInference,+ phrasing: { roleVerb: string; impactVerb: string },+): string {+ const role = flow.roleInFlow ?? "step";+ const flowName = flow.flowName ?? "pipeline";+ const verb = phrasing.impactVerb;+ const behaviorVerb = FLOW_BEHAVIOR_VERBS[role] ?? `affects the ${flowName}`;+ const actionNoun = flowActionNoun(flowName);++ if (importance.category === "pipeline-choke-point") {+ const callerPhrase = facts.callerCount === 1+ ? "only 1 direct caller"+ : `only ${facts.callerCount} direct callers`;+ const downstream = flow.downstreamHint+ ? flow.downstreamHint.replace(/^feeds /, "")+ : `${facts.downstreamDependents} downstream dependents`;+ return (+ `Although it has ${callerPhrase}, this ${role} sits in the ${flowName} ` ++ `and feeds ${downstream}, ` ++ `making it a critical decision point in that flow. ` ++ `Consider running \`ix impact ${facts.name}\` before modifying.`+ );+ }++ if (importance.level === "high") {+ return (+ `Because this ${role} ${behaviorVerb}, changes here ${verb} affect how ` ++ `${actionNoun} behaves across the system. ` ++ `Run \`ix impact ${facts.name}\` before modifying.`+ );+ }++ if (importance.level === "low") {+ return `This ${role} in the ${flowName} has limited inbound connections.`;+ }++ // medium+ return (+ `Because this ${role} ${behaviorVerb}, changes here ${verb} affect how ` ++ `${actionNoun} behaves.`+ );+}+// ── Confidence-to-language mapping ───────────────────────────────────────────function phrasingForConfidence(confidence: "low" | "medium" | "high"): {@@ -100,10 +234,32 @@ export function renderExplanation(role: RoleInference,importance: ImportanceInference,): ExplanationOutput {- // ── Explanation ────────────────────────────────────────────────────────- const roleDesc = describeRole(role.role, facts);+ // Infer hierarchy semantics and system meaning+ const sem = inferHierarchySemantics(facts, role.role);+ const meaning = inferSystemMeaning(facts, role.role, sem, importance);+ const isFoundation = meaning?.archetype === "foundation";const phrasing = phrasingForConfidence(role.confidence);- let explanation = `\`${facts.name}\` ${phrasing.roleVerb} ${roleDesc}.`;++ // Infer flow semantics for callable entities+ const callable = isCallable(facts.kind, role.role);+ const flow = callable ? inferFlowSemantics(facts) : undefined;+ const useFlow = callable && flow?.confidence === "high" && !!flow.flowName;++ // ── Explanation ────────────────────────────────────────────────────────+ let explanation: string;++ if (isFoundation) {+ // Foundation types (interfaces, enums, models) get system-meaning identity + responsibility+ explanation = `\`${facts.name}\` ${phrasing.roleVerb} ${meaning!.identitySummary}. ${meaning!.responsibility}`;+ } else if (useFlow) {+ // Flow-first rendering for callable entities with high-confidence flow+ explanation = renderFlowExplanation(facts, flow!, phrasing);+ } else {+ // Prefer system-aware role description when hierarchy context is strong+ const systemRoleDesc = synthesizeSystemRole(facts, role.role, sem);+ const roleDesc = systemRoleDesc ?? describeRoleLocal(role.role, facts);+ explanation = `\`${facts.name}\` ${phrasing.roleVerb} ${roleDesc}.`;+ }if (facts.signature) {explanation += ` Signature: \`${facts.signature}\`.`;@@ -124,6 +280,10 @@ export function renderExplanation(contextLines.push(`Container: ${facts.container.kind} ${facts.container.name}`);}+ if (facts.systemPath && facts.systemPath.length > 1) {+ contextLines.push(`System path: ${facts.systemPath.slice(0, -1).map(n => n.name).join(" > ")}`);+ }+if (facts.callerCount > 0) {contextLines.push(`Called by: ${facts.callerCount} entities`);}@@ -132,6 +292,14 @@ export function renderExplanation(contextLines.push(`Calls: ${facts.calleeCount} entities`);}+ if (useFlow && flow!.upstreamHint) {+ contextLines.push(`Called from: ${flow!.upstreamHint.replace(/^called from /, "")}`);+ }++ if (useFlow && flow!.downstreamHint) {+ contextLines.push(`Feeds into: ${flow!.downstreamHint.replace(/^feeds /, "")}`);+ }+if (facts.memberCount > 0) {contextLines.push(`Contains: ${facts.memberCount} members`);}@@ -155,10 +323,16 @@ export function renderExplanation(const context = contextLines.join("\n");// ── Used by (named examples) ──────────────────────────────────────────- const usedBy = renderUsedBy(facts);+ const usedBy = (isFoundation && meaning!.usageSummary)+ ? meaning!.usageSummary+ : renderUsedBy(facts);- // ── Why it matters (role + importance fusion) ─────────────────────────- const whyItMatters = renderWhyItMatters(facts, role, importance, phrasing);+ // ── Why it matters (role + importance + hierarchy fusion) ─────────────+ const whyItMatters = (isFoundation && meaning!.importanceNarrative)+ ? meaning!.importanceNarrative+ : useFlow+ ? renderFlowWhyItMatters(facts, flow!, importance, phrasing)+ : renderWhyItMatters(facts, role, importance, phrasing, sem);// ── Notes (clean diagnostics) ─────────────────────────────────────────const notes = renderNotes(facts);@@ -199,14 +373,27 @@ function renderWhyItMatters(role: RoleInference,importance: ImportanceInference,phrasing: { roleVerb: string; impactVerb: string },+ sem: HierarchySemantics,): string {const { level, category } = importance;- const verb = phrasing.impactVerb; // "will" for high confidence, "may" for medium/low+ const verb = phrasing.impactVerb;+ const hasHierarchy = !!(sem.layerName || sem.flowName);if (category === "pipeline-choke-point") {const callerPhrase = facts.callerCount === 1? "only 1 direct caller": `only ${facts.callerCount} direct callers`;++ if (hasHierarchy) {+ const location = sem.flowName ?? sem.layerName!;+ return (+ `Although it has ${callerPhrase}, it sits inside the ${location} ` ++ `and feeds ${facts.downstreamDependents} downstream dependents, ` ++ `making it a critical decision point in that flow. ` ++ `Consider running \`ix impact ${facts.name}\` before modifying.`+ );+ }+return (`Although it has ${callerPhrase}, it sits in a path with ` +`${facts.downstreamDependents} downstream dependents, making it a ` +@@ -216,13 +403,24 @@ function renderWhyItMatters(}if (category === "broad-shared-dependency") {- const roleContext = roleFusionPhrase(role.role, facts);+ // Try hierarchy-aware phrasing first+ const hierPhrase = hierarchyImpactPhrase(facts, sem);+ if (hierPhrase) {+ return (+ `Because ${hierPhrase}. ` ++ `Run \`ix impact ${facts.name}\` before modifying.`+ );+ }++ // Fall back to local role fusion+ const roleContext = roleFusionPhraseLocal(role.role, facts);if (roleContext) {return (`${roleContext}, changes here ${verb} propagate across the codebase. ` +`Run \`ix impact ${facts.name}\` before modifying.`);}+const reasonStr = importance.reasons.length > 0? importance.reasons[0]: "High connectivity";@@ -233,6 +431,13 @@ function renderWhyItMatters(}if (category === "localized-helper") {+ if (hasHierarchy) {+ const location = sem.flowName ?? sem.layerName!;+ return (+ `Its usage is localized within the ${location}, suggesting it is a narrow internal helper ` ++ `with limited impact beyond that scope.`+ );+ }return ("Its usage is localized, suggesting it is a narrow internal helper " +"with limited system-wide impact."@@ -241,13 +446,22 @@ function renderWhyItMatters(// normal categoryif (level === "high") {- const roleContext = roleFusionPhrase(role.role, facts);+ const hierPhrase = hierarchyImpactPhrase(facts, sem);+ if (hierPhrase) {+ return (+ `Because ${hierPhrase}. ` ++ `Run \`ix impact ${facts.name}\` before modifying.`+ );+ }++ const roleContext = roleFusionPhraseLocal(role.role, facts);if (roleContext) {return (`${roleContext}, changes here ${verb} have wide impact. ` +`Run \`ix impact ${facts.name}\` before modifying.`);}+const reasonStr = importance.reasons.length > 0? importance.reasons[0]: "This entity has high connectivity";@@ -265,6 +479,17 @@ function renderWhyItMatters(}// medium / normal+ if (hasHierarchy) {+ const location = sem.flowName ?? sem.layerName!;+ const reasonStr = importance.reasons.length > 0+ ? importance.reasons[0]+ : "Moderate connectivity";+ return (+ `${reasonStr}. ` ++ `Review callers in the ${location} before making breaking changes.`+ );+ }+const reasonStr = importance.reasons.length > 0? importance.reasons[0]: "Moderate connectivity";@@ -274,8 +499,8 @@ function renderWhyItMatters();}-/** Generate a role-specific lead phrase for why-it-matters. */-function roleFusionPhrase(role: RoleLabel, facts: EntityFacts): string | null {+/** Local-only role fusion phrases (no hierarchy context). */+function roleFusionPhraseLocal(role: RoleLabel, facts: EntityFacts): string | null {switch (role) {case "api-client":return `As the central API client used across ${facts.callerCount > 0 ? facts.callerCount + " commands" : "the codebase"}`;