Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.json
index 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.json
index 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.ts
index 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.ts
index 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 details
callList?: EntityRef[];
+ // Hierarchy (scene graph)
+ systemPath?: Array<{ name: string; kind: string }>;
+ subsystemName?: string;
+ moduleName?: string;
+
// Staleness
stale: 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.ts
index 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 category
if (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"}`;