diamond-detect 0.1.1 → 0.2.1

package/README.md

@@ -8,7 +8,7 @@ npx diamond-detect .
 
 ## Why this tool exists
 
-A Diamond proxy `delegatecall`s into many facet contracts, and **every facet shares the proxy's storage**. When two facets accidentally land at the same slot — by reusing a Diamond Storage namespace, by drifting AppStorage layouts, by reusing an EIP-7201 id, or by writing literal slots in inline assembly — the result is silent corruption: one facet's writes overwrite another's data with no error and no revert.
+A Diamond proxy `delegatecall`s into many facet contracts, and **every facet shares the proxy's storage**. When two facets accidentally land at the same slot, whether by reusing a Diamond Storage namespace string, by hardcoding the same precomputed slot, by computing the same ERC-7201 namespace inline, by drifting AppStorage layouts, by reusing an EIP-7201 id, or by writing a literal slot directly in inline assembly, the result is silent corruption where one facet's writes overwrite another's data with no error and no revert.
 
 Slither catches general storage issues but doesn't speak Diamond. Most teams either hand-audit by spreadsheet or rely on a one-off script. `diamond-detect` is a focused, Diamond-specific analyzer you can drop into CI in three lines of YAML.
 
@@ -60,23 +60,40 @@ This populates `out/` with artifact JSON files that include the AST and storage
 diamond-detect .
 ```
 
-If everything is fine you'll see:
+If everything is fine you'll see a confirmation, plus every storage region the tool verified so you can see it actually inspected each one and that they all sit on distinct slots:
 
 ```
-scanned 12 contract artifact(s)
-✓ no storage collisions detected
+✔ no storage collisions detected  ·  8 artifacts scanned
+
+Verified 4 storage regions, each on its own slot:
+
+  • myapp.vaults                       erc7201      0x84d86c…b71bab  LibVaults    src/LibVaults.sol:12
+  • myapp.strategies                   namespace    0xa1b2c3…445566  LibStrategies  src/LibStrategies.sol:9
+  • AAVE_STORAGE_SLOT                   precomputed  0x340080…215700  AaveFacet    src/facets/AaveFacet.sol:28
+  • diamond.standard.diamond.storage   namespace    0xc8fcad…2c131c  LibDiamond   src/libraries/LibDiamond.sol:8
+
+Every facet keeps to its own namespace, and no two regions share a slot. Nicely done.
 ```
 
-If something is wrong you'll see one or more findings with the slot, the colliding contracts, and a hint at the cause:
+If something is wrong you'll get one diagnostic per collision, with a code frame pointing at the exact line in every colliding file, the shared slot, and a hint at the cause:
 
 ```
-ERROR diamond-storage-namespace  0x84d86c34a05b71953e57fe7dafea685384b33934d9ddaebd0cf7709e74b71bab
-  Diamond Storage namespace "myapp.strategies" is declared in 2 different sources, all resolving to the same slot.
-  facets: LibStrategies, LibVaults
-  at src/LibStrategies.sol
-  at src/LibVaults.sol
+error[diamond-storage-namespace]: Diamond Storage namespace "myapp.strategies" is declared in 2 different sources, all resolving to the same slot.
+  ╭─[src/LibStrategies.sol:5:5]
+    │
+  5 │     bytes32 internal constant POSITION = keccak256("myapp.strategies");
+    ·     ────────────────────────────────────────────────────────────────── slot 0x84d86c…b71bab
+    ╰─
+  ╭─[src/LibVaults.sol:8:5]
+    │
+  8 │     bytes32 internal constant POSITION = keccak256("myapp.strategies");
+    ·     ────────────────────────────────────────────────────────────────── same slot here
+    ╰─
+  = facets: LibStrategies, LibVaults
+  = slot:   0x84d86c34a05b71953e57fe7dafea685384b33934d9ddaebd0cf7709e74b71bab
+  = help:   give every facet a unique storage seed; never reuse a namespace string, precomputed slot, or formula across facets
 
-1 error(s), 0 warning(s)
+✖ 1 error  ·  2 artifacts scanned
 ```
 
 Exit code is `1` whenever a finding meets your `--severity` threshold (default `warn`), `0` otherwise, `2` on internal errors.
@@ -87,7 +104,7 @@ Run [`examples/`](./examples/) to see each one in action — every example ships
 
 | Kind | Severity | What it catches |
 |---|---|---|
-| `diamond-storage-namespace` | error | Two libraries declare `bytes32 constant POSITION = keccak256("...")` with the same string. ([01-namespace-collision](./examples/01-namespace-collision/)) |
+| `diamond-storage-namespace` | error | Two facets resolve to the same Diamond Storage slot, whether the slot comes from `keccak256("...")`, a hardcoded precomputed literal (`bytes32 constant S = 0x..`), the inline ERC-7201 formula written without an annotation, or a direct `assembly { x.slot := <literal> }`. All four representations are compared in one space, so a literal in one facet that matches a formula or namespace in another is caught too. ([01-namespace-collision](./examples/01-namespace-collision/)) |
 | `appstorage-fingerprint` | error | The same fully-qualified struct (e.g. `struct LibAppStorage.AppStorage`) has different layouts across facets — the stale-artifact / forgot-to-rebuild bug. ([02-appstorage-shift](./examples/02-appstorage-shift/)) |
 | `erc7201-namespace` | error | Two contracts annotate `@custom:storage-location erc7201:<id>` with the same id. ([03-erc7201-collision](./examples/03-erc7201-collision/)) |
 | `inheritance-overlap` | warn | Two facets have state at the same slot whose `(label, type)` differ — e.g. `Ownable._owner` vs `MyOwnable.owner`. |
@@ -145,7 +162,7 @@ diamond-detect <path>                    Foundry project root or src/ folder
 
 ## Output formats
 
-- **Terminal** (default): coloured, one block per finding, summary footer.
+- **Terminal** (default): a code-frame diagnostic per collision that underlines the exact slot declaration in every colliding file, with `= facets / = slot / = help` notes and a coloured summary footer. A clean run instead lists every storage region it verified, with its slot and location, so you can confirm nothing was skipped. Colour is auto-disabled when the output is piped or running in CI.
 - **JSON** (`--json`): a stable shape suitable for piping into other tools.
 
   ```json
@@ -158,8 +175,8 @@ diamond-detect <path>                    Foundry project root or src/ folder
         "slot": "0x...",
         "message": "...",
         "facets": ["LibStrategies", "LibVaults"],
-        "locations": [{ "file": "src/LibStrategies.sol" }],
-        "detail": { "namespaces": ["myapp.strategies"], "declarations": [...] }
+        "locations": [{ "file": "src/LibStrategies.sol", "line": 5, "src": "120:54:0" }],
+        "detail": { "namespaces": ["myapp.strategies"], "variableNames": ["POSITION"], "declarations": [...] }
       }
     ]
   }
@@ -206,13 +223,13 @@ Tighten with `--severity error` if you only want to fail CI on hard collisions.
 
 ## Comparison
 
-| Tool | Diamond Storage namespaces | EIP-7201 ids | AppStorage drift | Hardcoded sstore slots |
-|---|---|---|---|---|
-| Slither | partial — general slot detector, not Diamond-aware | no | no | yes (separate detector) |
-| Hand-audit / spreadsheet | yes, manually | yes, manually | hard to spot | yes |
-| `diamond-detect` | yes | yes | yes | yes |
+| Tool | Diamond Storage namespaces | Precomputed / inline-formula slots | EIP-7201 ids | AppStorage drift | Hardcoded assembly slots |
+|---|---|---|---|---|---|
+| Slither | partial, a general slot detector that is not Diamond-aware | no | no | no | partial, raw `sstore` only |
+| Hand-audit / spreadsheet | yes, manually | error-prone by hand | yes, manually | hard to spot | yes, manually |
+| `diamond-detect` | yes | yes | yes | yes | yes |
 
-Slither remains excellent for general Solidity static analysis. Use both.
+Slither's storage layout does not model Diamond namespaced storage, which lives at hashed slots reached through assembly, so it cannot see a Diamond storage collision at all. It remains excellent for general Solidity static analysis, so run both.
 
 ## Roadmap
 

package/dist/cli.js

@@ -72,6 +72,18 @@ function extractSourcePath(artifactPath, parsed) {
   }
   return path.basename(path.dirname(artifactPath));
 }
+async function loadRawSources(inputPath, sourcePaths) {
+  const { root } = await resolveFoundryRoot(inputPath);
+  const out = /* @__PURE__ */ new Map();
+  for (const sourcePath of new Set(sourcePaths)) {
+    if (out.has(sourcePath)) continue;
+    try {
+      out.set(sourcePath, await fs.readFile(path.join(root, sourcePath), "utf8"));
+    } catch {
+    }
+  }
+  return out;
+}
 async function loadFoundryArtifacts(inputPath, opts = {}) {
   const { outDir } = await resolveFoundryRoot(inputPath);
   if (!await fileExists(outDir)) {
@@ -105,55 +117,58 @@ async function loadFoundryArtifacts(inputPath, opts = {}) {
   return artifacts;
 }
 
-// src/detector/index.ts
-var DEFAULT_IGNORE_GLOBS = [
-  "lib/**",
-  "test/**",
-  "script/**",
-  "**/*.t.sol",
-  "**/*.s.sol"
-];
-function compilePatterns(globs) {
-  return globs.map((g) => {
-    const escaped = g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::DOUBLESTAR::").replace(/\*/g, "[^/]*").replace(/::DOUBLESTAR::/g, ".*").replace(/\?/g, ".");
-    return new RegExp(`^${escaped}$`);
-  });
-}
-function buildIgnore(userGlobs, noDefault) {
-  const globs = [
-    ...noDefault ? [] : DEFAULT_IGNORE_GLOBS,
-    ...userGlobs ?? []
-  ];
-  if (globs.length === 0) return void 0;
-  const patterns = compilePatterns(globs);
-  return (sourcePath) => patterns.some((p) => p.test(sourcePath));
+// src/detector/analyzers/diamondStorage.ts
+import { keccak_256 as keccak_2562 } from "@noble/hashes/sha3";
+
+// src/lib/eip7201.ts
+import { keccak_256 } from "@noble/hashes/sha3";
+var MASK_LAST_BYTE = (() => {
+  const m = new Uint8Array(32).fill(255);
+  m[31] = 0;
+  return m;
+})();
+function utf8(s) {
+  return new TextEncoder().encode(s);
 }
-function buildIsFacet(globs) {
-  if (!globs || globs.length === 0) return void 0;
-  const patterns = compilePatterns(globs);
-  return (artifact) => patterns.some((p) => p.test(artifact.sourcePath));
+function toHex(bytes) {
+  let out = "0x";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
 }
-async function detect(options, analyzers) {
-  const artifacts = await loadFoundryArtifacts(options.path, {
-    ignoreSourcePath: buildIgnore(options.ignoreGlobs, options.noDefaultIgnore)
-  });
-  const ctx = {
-    artifacts,
-    rawSources: /* @__PURE__ */ new Map(),
-    isFacet: buildIsFacet(options.facetGlobs)
-  };
-  const findings = [];
-  for (const analyzer of analyzers) {
-    const out = await analyzer.run(ctx);
-    findings.push(...out);
+function subOne(bytes) {
+  const out = new Uint8Array(bytes);
+  for (let i = out.length - 1; i >= 0; i--) {
+    if (out[i] > 0) {
+      out[i] = out[i] - 1;
+      return out;
+    }
+    out[i] = 255;
   }
-  return { artifacts, findings };
+  return out;
+}
+function maskLastByte(bytes) {
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 32; i++) out[i] = bytes[i] & MASK_LAST_BYTE[i];
+  return out;
+}
+function erc7201Slot(namespaceId) {
+  const inner = keccak_256(utf8(namespaceId));
+  const decremented = subOne(inner);
+  const outer = keccak_256(decremented);
+  return toHex(maskLastByte(outer));
+}
+var ERC7201_PREFIX = "erc7201:";
+function parseErc7201Annotation(text) {
+  const idx = text.indexOf(ERC7201_PREFIX);
+  if (idx === -1) return null;
+  const rest = text.slice(idx + ERC7201_PREFIX.length);
+  const match = rest.match(/^[A-Za-z0-9_.\-]+/);
+  return match ? match[0] : null;
 }
 
 // src/detector/analyzers/diamondStorage.ts
-import { keccak_256 } from "@noble/hashes/sha3";
 function keccak256Hex(input) {
-  const bytes = keccak_256(new TextEncoder().encode(input));
+  const bytes = keccak_2562(new TextEncoder().encode(input));
   let out = "0x";
   for (const b of bytes) out += b.toString(16).padStart(2, "0");
   return out;
@@ -176,6 +191,61 @@ function extractKeccakStringArg(value) {
   if (arg.nodeType !== "Literal" || arg.kind !== "string") return null;
   return typeof arg.value === "string" ? arg.value : null;
 }
+function extractBytes32HexLiteral(value) {
+  if (!value || typeof value !== "object") return null;
+  const v = value;
+  if (v.nodeType !== "Literal" || v.kind !== "number") return null;
+  if (typeof v.value !== "string") return null;
+  try {
+    const big = BigInt(v.value);
+    if (big < 0n) return null;
+    return "0x" + big.toString(16).padStart(64, "0");
+  } catch {
+    return null;
+  }
+}
+function findKeccakStringArg(node) {
+  if (!node || typeof node !== "object") return null;
+  const v = node;
+  if (v.nodeType !== "FunctionCall") return null;
+  const expr = v.expression;
+  if (expr?.nodeType !== "Identifier" || expr.name !== "keccak256") return null;
+  const args = v.arguments;
+  if (!Array.isArray(args) || args.length !== 1) return null;
+  const arg = args[0];
+  if (arg.nodeType !== "Literal" || arg.kind !== "string") return null;
+  return typeof arg.value === "string" ? arg.value : null;
+}
+function someNode(node, pred) {
+  if (!node || typeof node !== "object") return false;
+  const n = node;
+  if (typeof n.nodeType === "string" && pred(n)) return true;
+  for (const key of Object.keys(n)) {
+    const value = n[key];
+    if (Array.isArray(value)) {
+      if (value.some((c) => someNode(c, pred))) return true;
+    } else if (value && typeof value === "object") {
+      if (someNode(value, pred)) return true;
+    }
+  }
+  return false;
+}
+function extractErc7201FormulaNamespace(value) {
+  const strings = [];
+  someNode(value, (n) => {
+    const s = findKeccakStringArg(n);
+    if (s !== null) strings.push(s);
+    return false;
+  });
+  if (strings.length !== 1) return null;
+  const hasSubOne = someNode(
+    value,
+    (n) => n.nodeType === "BinaryOperation" && n.operator === "-" && n.rightExpression?.nodeType === "Literal" && n.rightExpression.value === "1"
+  );
+  const hasMask = someNode(value, (n) => n.nodeType === "BinaryOperation" && n.operator === "&");
+  if (!hasSubOne || !hasMask) return null;
+  return strings[0];
+}
 function lineFromSrc(src, sourceText) {
   if (typeof src !== "string" || !sourceText) return void 0;
   const [startStr] = src.split(":");
@@ -237,6 +307,105 @@ function collectSlotConstants(ctx) {
   }
   return out;
 }
+function collectLiteralSlotConstants(ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of ctx.artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (!isBytes32Constant(node)) return;
+      if (extractKeccakStringArg(node.value) !== null) return;
+      const slot = extractBytes32HexLiteral(node.value);
+      if (slot === null) return;
+      const declarationId = typeof node.id === "number" ? node.id : -1;
+      const variableName = node.name ?? "<anon>";
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${variableName}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId,
+        variableName,
+        namespace: null,
+        slot,
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+function collectFormulaSlotConstants(ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of ctx.artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (!isBytes32Constant(node)) return;
+      if (extractKeccakStringArg(node.value) !== null) return;
+      const namespace = extractErc7201FormulaNamespace(node.value);
+      if (namespace === null) return;
+      const declarationId = typeof node.id === "number" ? node.id : -1;
+      const variableName = node.name ?? "<anon>";
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${variableName}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId,
+        variableName,
+        namespace,
+        slot: erc7201Slot(namespace),
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+function collectAssemblyLiteralSlots(artifacts) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (node.nodeType !== "YulAssignment") return;
+      const targets = node.variableNames;
+      const targetsSlot = Array.isArray(targets) && targets.some((t) => typeof t.name === "string" && t.name.endsWith(".slot"));
+      if (!targetsSlot) return;
+      const value = node.value;
+      if (value?.nodeType !== "YulLiteral" || value.kind !== "number") return;
+      if (typeof value.value !== "string") return;
+      let slot;
+      try {
+        const big = BigInt(value.value);
+        if (big < 0n) return;
+        slot = "0x" + big.toString(16).padStart(64, "0");
+      } catch {
+        return;
+      }
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${slot}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId: -1,
+        variableName: "<assembly literal>",
+        namespace: null,
+        slot,
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
 function collectSlotAssignmentValueSrcs(yulNode, srcs) {
   if (!yulNode || typeof yulNode !== "object") return;
   const node = yulNode;
@@ -308,15 +477,23 @@ function isUsedAsSlot(constantId, slotUsedIds, aliases) {
   }
   return false;
 }
+function collectGatedSlotConstants(ctx) {
+  const constants = [
+    ...collectSlotConstants(ctx),
+    ...collectLiteralSlotConstants(ctx),
+    ...collectFormulaSlotConstants(ctx)
+  ];
+  const slotUsedIds = collectSlotUsedDeclarationIds(ctx.artifacts);
+  const aliases = collectAliases(ctx.artifacts);
+  return [
+    ...constants.filter((c) => isUsedAsSlot(c.declarationId, slotUsedIds, aliases)),
+    ...collectAssemblyLiteralSlots(ctx.artifacts)
+  ];
+}
 var diamondStorageAnalyzer = {
   name: "diamond-storage-namespace",
   run(ctx) {
-    const constants = collectSlotConstants(ctx);
-    const slotUsedIds = collectSlotUsedDeclarationIds(ctx.artifacts);
-    const aliases = collectAliases(ctx.artifacts);
-    const slotConstants = constants.filter(
-      (c) => isUsedAsSlot(c.declarationId, slotUsedIds, aliases)
-    );
+    const slotConstants = collectGatedSlotConstants(ctx);
     const bySlot = /* @__PURE__ */ new Map();
     for (const c of slotConstants) {
       const list = bySlot.get(c.slot) ?? [];
@@ -327,72 +504,38 @@ var diamondStorageAnalyzer = {
     for (const [slot, group] of bySlot) {
       const distinctSources = new Set(group.map((g) => g.sourcePath));
       if (distinctSources.size < 2) continue;
-      const namespaces = Array.from(new Set(group.map((g) => g.namespace)));
+      const namespaces = Array.from(
+        new Set(group.map((g) => g.namespace).filter((n) => n !== null))
+      );
+      const variableNames = Array.from(new Set(group.map((g) => g.variableName)));
+      const hasLiteral = group.some((g) => g.namespace === null);
       const facets = Array.from(new Set(group.map((g) => g.contract)));
       const locations = group.map((g) => {
         const sourceText = ctx.rawSources.get(g.sourcePath);
-        return { file: g.sourcePath, line: lineFromSrc(g.src, sourceText) };
+        return { file: g.sourcePath, line: lineFromSrc(g.src, sourceText), src: g.src };
       });
+      let message;
+      if (!hasLiteral) {
+        message = namespaces.length === 1 ? `Diamond Storage namespace "${namespaces[0]}" is declared in ${distinctSources.size} different sources, all resolving to the same slot.` : `Distinct namespaces ${namespaces.map((n) => `"${n}"`).join(", ")} hash to the same slot.`;
+      } else if (namespaces.length === 0) {
+        message = `Hardcoded storage slot ${slot} is used as a Diamond Storage pointer by ${distinctSources.size} different sources (${variableNames.join(", ")}), so distinct facets share the same slot.`;
+      } else {
+        message = `Hardcoded slot ${slot} collides with namespace(s) ${namespaces.map((n) => `"${n}"`).join(", ")} \u2014 they resolve to the same storage slot.`;
+      }
       findings.push({
         kind: "diamond-storage-namespace",
         severity: "error",
         slot,
-        message: namespaces.length === 1 ? `Diamond Storage namespace "${namespaces[0]}" is declared in ${distinctSources.size} different sources, all resolving to the same slot.` : `Distinct namespaces ${namespaces.map((n) => `"${n}"`).join(", ")} hash to the same slot.`,
+        message,
         facets,
         locations,
-        detail: { namespaces, declarations: group }
+        detail: { namespaces, variableNames, declarations: group }
       });
     }
     return findings;
   }
 };
 
-// src/lib/eip7201.ts
-import { keccak_256 as keccak_2562 } from "@noble/hashes/sha3";
-var MASK_LAST_BYTE = (() => {
-  const m = new Uint8Array(32).fill(255);
-  m[31] = 0;
-  return m;
-})();
-function utf8(s) {
-  return new TextEncoder().encode(s);
-}
-function toHex(bytes) {
-  let out = "0x";
-  for (const b of bytes) out += b.toString(16).padStart(2, "0");
-  return out;
-}
-function subOne(bytes) {
-  const out = new Uint8Array(bytes);
-  for (let i = out.length - 1; i >= 0; i--) {
-    if (out[i] > 0) {
-      out[i] = out[i] - 1;
-      return out;
-    }
-    out[i] = 255;
-  }
-  return out;
-}
-function maskLastByte(bytes) {
-  const out = new Uint8Array(32);
-  for (let i = 0; i < 32; i++) out[i] = bytes[i] & MASK_LAST_BYTE[i];
-  return out;
-}
-function erc7201Slot(namespaceId) {
-  const inner = keccak_2562(utf8(namespaceId));
-  const decremented = subOne(inner);
-  const outer = keccak_2562(decremented);
-  return toHex(maskLastByte(outer));
-}
-var ERC7201_PREFIX = "erc7201:";
-function parseErc7201Annotation(text) {
-  const idx = text.indexOf(ERC7201_PREFIX);
-  if (idx === -1) return null;
-  const rest = text.slice(idx + ERC7201_PREFIX.length);
-  const match = rest.match(/^[A-Za-z0-9_.\-]+/);
-  return match ? match[0] : null;
-}
-
 // src/detector/analyzers/erc7201.ts
 var NAMED_NODE_TYPES = /* @__PURE__ */ new Set([
   "ContractDefinition",
@@ -480,7 +623,7 @@ var erc7201Analyzer = {
       if (distinctSources.size < 2) continue;
       const ids = Array.from(new Set(group.map((g) => g.namespaceId)));
       const facets = Array.from(new Set(group.map((g) => g.contract)));
-      const locations = group.map((g) => ({ file: g.sourcePath }));
+      const locations = group.map((g) => ({ file: g.sourcePath, src: g.src }));
       findings.push({
         kind: "erc7201-namespace",
         severity: "error",
@@ -495,6 +638,102 @@ var erc7201Analyzer = {
   }
 };
 
+// src/detector/inventory.ts
+function lineOf(src, text) {
+  if (!src || !text) return void 0;
+  const [startStr] = src.split(":");
+  const start = Number(startStr);
+  if (!Number.isFinite(start)) return void 0;
+  let line = 1;
+  for (let i = 0; i < start && i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+var PRIORITY = { erc7201: 0, namespace: 1, hardcoded: 2 };
+function buildInventory(ctx) {
+  const bySlot = /* @__PURE__ */ new Map();
+  const add = (region) => {
+    const existing = bySlot.get(region.slot);
+    if (!existing || PRIORITY[region.kind] < PRIORITY[existing.kind]) {
+      bySlot.set(region.slot, region);
+    }
+  };
+  for (const c of collectGatedSlotConstants(ctx)) {
+    add({
+      slot: c.slot,
+      label: c.namespace ?? c.variableName,
+      kind: c.namespace ? "namespace" : "hardcoded",
+      contract: c.contract,
+      file: c.sourcePath,
+      line: lineOf(c.src, ctx.rawSources.get(c.sourcePath))
+    });
+  }
+  for (const a of collectErc7201Annotations(ctx.artifacts)) {
+    add({
+      slot: a.slot,
+      label: a.namespaceId,
+      kind: "erc7201",
+      contract: a.contract,
+      file: a.sourcePath,
+      line: lineOf(a.src, ctx.rawSources.get(a.sourcePath))
+    });
+  }
+  return [...bySlot.values()].sort(
+    (x, y) => x.file.localeCompare(y.file) || x.slot.localeCompare(y.slot)
+  );
+}
+
+// src/detector/index.ts
+var DEFAULT_IGNORE_GLOBS = [
+  "lib/**",
+  "test/**",
+  "script/**",
+  "**/*.t.sol",
+  "**/*.s.sol"
+];
+function compilePatterns(globs) {
+  return globs.map((g) => {
+    const escaped = g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::DOUBLESTAR::").replace(/\*/g, "[^/]*").replace(/::DOUBLESTAR::/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+  });
+}
+function buildIgnore(userGlobs, noDefault) {
+  const globs = [
+    ...noDefault ? [] : DEFAULT_IGNORE_GLOBS,
+    ...userGlobs ?? []
+  ];
+  if (globs.length === 0) return void 0;
+  const patterns = compilePatterns(globs);
+  return (sourcePath) => patterns.some((p) => p.test(sourcePath));
+}
+function buildIsFacet(globs) {
+  if (!globs || globs.length === 0) return void 0;
+  const patterns = compilePatterns(globs);
+  return (artifact) => patterns.some((p) => p.test(artifact.sourcePath));
+}
+async function detect(options, analyzers) {
+  const artifacts = await loadFoundryArtifacts(options.path, {
+    ignoreSourcePath: buildIgnore(options.ignoreGlobs, options.noDefaultIgnore)
+  });
+  const rawSources = await loadRawSources(
+    options.path,
+    artifacts.map((a) => a.sourcePath)
+  );
+  const ctx = {
+    artifacts,
+    rawSources,
+    isFacet: buildIsFacet(options.facetGlobs)
+  };
+  const findings = [];
+  for (const analyzer of analyzers) {
+    const out = await analyzer.run(ctx);
+    findings.push(...out);
+  }
+  const inventory = buildInventory(ctx);
+  return { artifacts, findings, rawSources, inventory };
+}
+
 // src/detector/analyzers/appStorage.ts
 function memberFingerprint(m) {
   return { label: m.label, offset: m.offset, slot: m.slot, type: m.type };
@@ -659,7 +898,7 @@ var inlineAssemblyAnalyzer = {
       slot: lit.slot,
       message: `inline assembly writes to a hardcoded slot (sstore(${lit.rawValue}, \u2026)) \u2014 confirm no overlap with computed storage slots.`,
       facets: [lit.artifact.contractName],
-      locations: [{ file: lit.artifact.sourcePath }],
+      locations: [{ file: lit.artifact.sourcePath, src: lit.src }],
       detail: { rawValue: lit.rawValue, src: lit.src }
     }));
   }
@@ -750,37 +989,140 @@ var defaultAnalyzers = [
 // src/reporter/terminal.ts
 import pc from "picocolors";
 var SEVERITY_RANK = { info: 0, warn: 1, error: 2 };
-function colorSeverity(sev) {
-  if (sev === "error") return pc.red(pc.bold("ERROR"));
-  if (sev === "warn") return pc.yellow("WARN ");
-  return pc.cyan("INFO ");
+var SEV = {
+  error: { label: "error", glyph: "\u2716", paint: (s) => pc.red(s) },
+  warn: { label: "warning", glyph: "\u26A0", paint: (s) => pc.yellow(s) },
+  info: { label: "note", glyph: "\u25CF", paint: (s) => pc.cyan(s) }
+};
+var HELP = {
+  "diamond-storage-namespace": "give every facet a unique storage seed; never reuse a namespace string, precomputed slot, or formula across facets",
+  "erc7201-namespace": "use a distinct erc7201 namespace id per facet",
+  "appstorage-fingerprint": "keep the shared struct layout identical across all facets; append fields, never reorder or insert",
+  "inheritance-overlap": "facets must not declare sequential state variables; move state into namespaced Diamond Storage",
+  "inline-assembly-slot": "confirm this hardcoded slot cannot overlap any namespaced storage region",
+  "mapping-overlap": "ensure mapping base slots are derived from distinct, collision-resistant seeds"
+};
+function shortSlot(slot) {
+  if (!slot.startsWith("0x") || slot.length <= 14) return slot;
+  return `${slot.slice(0, 8)}\u2026${slot.slice(-6)}`;
+}
+function expandTabs(s) {
+  return s.replace(/\t/g, "    ");
+}
+function resolveSpan(loc, sourceText) {
+  if (!sourceText || !loc.src) return null;
+  const [offStr, lenStr] = loc.src.split(":");
+  const offset = Number(offStr);
+  const length = Number(lenStr);
+  if (!Number.isFinite(offset) || offset < 0 || offset > sourceText.length) return null;
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < offset; i++) {
+    if (sourceText.charCodeAt(i) === 10) {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  const nl = sourceText.indexOf("\n", lineStart);
+  const lineEnd = nl === -1 ? sourceText.length : nl;
+  const rawLine = sourceText.slice(lineStart, lineEnd);
+  const rawPrefix = sourceText.slice(lineStart, offset);
+  const column = expandTabs(rawPrefix).length + 1;
+  const visibleLen = expandTabs(rawLine).length;
+  const rawCaret = Number.isFinite(length) && length > 0 ? length : 1;
+  const caretLen = Math.max(1, Math.min(rawCaret, visibleLen - (column - 1)));
+  return { line, column, lineText: expandTabs(rawLine), caretLen };
+}
+function renderFrame(loc, span, sev, note) {
+  const gutter = String(span.line);
+  const pad = " ".repeat(gutter.length);
+  const bar = pc.dim("\u2502");
+  const arrow = pc.dim("\u256D\u2500[");
+  const close = pc.dim("]");
+  const caret = sev.paint("\u2500".repeat(span.caretLen));
+  const caretPad = " ".repeat(span.column - 1);
+  const label = note ? " " + sev.paint(note) : "";
+  return [
+    `  ${arrow}${pc.cyan(`${loc.file}:${span.line}:${span.column}`)}${close}`,
+    `  ${pad} ${bar}`,
+    `  ${pc.dim(gutter)} ${bar} ${span.lineText}`,
+    `  ${pad} ${pc.dim("\xB7")} ${caretPad}${caret}${label}`,
+    `  ${pad} ${pc.dim("\u2570\u2500")}`
+  ];
 }
-function renderTerminal(findings, facetCount) {
+var KIND_TAG = {
+  erc7201: "erc7201",
+  namespace: "namespace",
+  hardcoded: "precomputed"
+};
+function renderInventory(inventory) {
   const lines = [];
-  lines.push(pc.dim(`scanned ${facetCount} contract artifact(s)`));
-  if (findings.length === 0) {
-    lines.push(pc.green("\u2713 no storage collisions detected"));
-    return lines.join("\n");
+  const shown = inventory.slice(0, 60);
+  const labelW = Math.max(...shown.map((r) => r.label.length), 0);
+  const tagW = Math.max(...shown.map((r) => KIND_TAG[r.kind].length), 0);
+  const contractW = Math.max(...shown.map((r) => r.contract.length), 0);
+  lines.push("");
+  lines.push(
+    pc.bold(`Verified ${inventory.length} storage region${inventory.length === 1 ? "" : "s"}`) + pc.dim(", each on its own slot:")
+  );
+  lines.push("");
+  for (const r of shown) {
+    const where = r.line ? `${r.file}:${r.line}` : r.file;
+    lines.push(
+      `  ${pc.green("\u2022")} ${pc.green(r.label.padEnd(labelW))}  ${pc.dim(KIND_TAG[r.kind].padEnd(tagW))}  ${pc.cyan(shortSlot(r.slot))}  ${r.contract.padEnd(contractW)}  ${pc.dim(where)}`
+    );
+  }
+  if (inventory.length > shown.length) {
+    lines.push(`  ${pc.dim(`\u2026 and ${inventory.length - shown.length} more`)}`);
   }
-  const sorted = [...findings].sort(
-    (a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]
+  lines.push("");
+  lines.push(
+    pc.green("Every facet keeps to its own namespace, and no two regions share a slot. ") + pc.green(pc.bold("Nicely done."))
   );
+  return lines;
+}
+function renderTerminal(findings, facetCount, rawSources, inventory = []) {
+  const artifactsNote = pc.dim(`${facetCount} artifact${facetCount === 1 ? "" : "s"} scanned`);
+  if (findings.length === 0) {
+    const header = `${pc.green(pc.bold("\u2714 no storage collisions detected"))}  ${pc.dim("\xB7")}  ${artifactsNote}`;
+    if (inventory.length === 0) return header;
+    return [header, ...renderInventory(inventory)].join("\n");
+  }
+  const sorted = [...findings].sort((a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]);
+  const lines = [];
   for (const f of sorted) {
+    const sev = SEV[f.severity];
+    const tag = `${pc.bold(sev.paint(sev.label))}${pc.dim(`[${f.kind}]`)}`;
     lines.push("");
-    lines.push(`${colorSeverity(f.severity)} ${pc.bold(f.kind)}  ${pc.dim(f.slot)}`);
-    lines.push(`  ${f.message}`);
+    lines.push(`${tag}: ${pc.bold(f.message)}`);
+    f.locations.forEach((loc, i) => {
+      const span = resolveSpan(loc, rawSources?.get(loc.file));
+      const note = i === 0 ? `slot ${shortSlot(f.slot)}` : "same slot here";
+      if (span) {
+        lines.push(...renderFrame(loc, span, sev, f.slot === "n/a" ? "here" : note));
+      } else {
+        const where = loc.line ? `${loc.file}:${loc.line}` : loc.file;
+        lines.push(`  ${pc.dim("\u256D\u2500[")}${pc.cyan(where)}${pc.dim("]")}`);
+      }
+    });
     if (f.facets.length > 0) {
-      lines.push(`  ${pc.dim("facets:")} ${f.facets.join(", ")}`);
+      lines.push(`  ${pc.dim("= facets:")} ${f.facets.join(pc.dim(", "))}`);
     }
-    for (const loc of f.locations) {
-      const where = loc.line ? `${loc.file}:${loc.line}` : loc.file;
-      lines.push(`  ${pc.dim("at")} ${where}`);
+    if (f.slot && f.slot !== "n/a") {
+      lines.push(`  ${pc.dim("= slot:  ")} ${pc.dim(f.slot)}`);
     }
+    lines.push(`  ${pc.dim("= help:  ")} ${pc.dim(HELP[f.kind] ?? "")}`);
   }
   const errors = findings.filter((f) => f.severity === "error").length;
   const warns = findings.filter((f) => f.severity === "warn").length;
+  const notes = findings.filter((f) => f.severity === "info").length;
+  const parts = [];
+  if (errors > 0) parts.push(pc.red(`${SEV.error.glyph} ${errors} error${errors === 1 ? "" : "s"}`));
+  if (warns > 0)
+    parts.push(pc.yellow(`${SEV.warn.glyph} ${warns} warning${warns === 1 ? "" : "s"}`));
+  if (notes > 0) parts.push(pc.cyan(`${SEV.info.glyph} ${notes} note${notes === 1 ? "" : "s"}`));
   lines.push("");
-  lines.push(pc.bold(`${errors} error(s), ${warns} warning(s)`));
+  lines.push(`${parts.join(pc.dim("  \xB7  "))}  ${pc.dim("\xB7")}  ${artifactsNote}`);
   return lines.join("\n");
 }
 
@@ -910,7 +1252,12 @@ async function run(target, opts) {
       )
     );
   }
-  const output = opts.json ? renderJson(result.findings, result.artifacts.length) : opts.markdown ? renderMarkdown(result.findings, result.artifacts.length) : renderTerminal(result.findings, result.artifacts.length);
+  const output = opts.json ? renderJson(result.findings, result.artifacts.length) : opts.markdown ? renderMarkdown(result.findings, result.artifacts.length) : renderTerminal(
+    result.findings,
+    result.artifacts.length,
+    result.rawSources,
+    result.inventory
+  );
   process.stdout.write(output + "\n");
   const threshold = SEVERITY_RANK3[opts.severity];
   const hit = result.findings.some((f) => SEVERITY_RANK3[f.severity] >= threshold);

package/dist/index.js

@@ -68,6 +68,18 @@ function extractSourcePath(artifactPath, parsed) {
   }
   return path.basename(path.dirname(artifactPath));
 }
+async function loadRawSources(inputPath, sourcePaths) {
+  const { root } = await resolveFoundryRoot(inputPath);
+  const out = /* @__PURE__ */ new Map();
+  for (const sourcePath of new Set(sourcePaths)) {
+    if (out.has(sourcePath)) continue;
+    try {
+      out.set(sourcePath, await fs.readFile(path.join(root, sourcePath), "utf8"));
+    } catch {
+    }
+  }
+  return out;
+}
 async function loadFoundryArtifacts(inputPath, opts = {}) {
   const { outDir } = await resolveFoundryRoot(inputPath);
   if (!await fileExists(outDir)) {
@@ -101,50 +113,8 @@ async function loadFoundryArtifacts(inputPath, opts = {}) {
   return artifacts;
 }
 
-// src/detector/index.ts
-var DEFAULT_IGNORE_GLOBS = [
-  "lib/**",
-  "test/**",
-  "script/**",
-  "**/*.t.sol",
-  "**/*.s.sol"
-];
-function compilePatterns(globs) {
-  return globs.map((g) => {
-    const escaped = g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::DOUBLESTAR::").replace(/\*/g, "[^/]*").replace(/::DOUBLESTAR::/g, ".*").replace(/\?/g, ".");
-    return new RegExp(`^${escaped}$`);
-  });
-}
-function buildIgnore(userGlobs, noDefault) {
-  const globs = [
-    ...noDefault ? [] : DEFAULT_IGNORE_GLOBS,
-    ...userGlobs ?? []
-  ];
-  if (globs.length === 0) return void 0;
-  const patterns = compilePatterns(globs);
-  return (sourcePath) => patterns.some((p) => p.test(sourcePath));
-}
-function buildIsFacet(globs) {
-  if (!globs || globs.length === 0) return void 0;
-  const patterns = compilePatterns(globs);
-  return (artifact) => patterns.some((p) => p.test(artifact.sourcePath));
-}
-async function detect(options, analyzers) {
-  const artifacts = await loadFoundryArtifacts(options.path, {
-    ignoreSourcePath: buildIgnore(options.ignoreGlobs, options.noDefaultIgnore)
-  });
-  const ctx = {
-    artifacts,
-    rawSources: /* @__PURE__ */ new Map(),
-    isFacet: buildIsFacet(options.facetGlobs)
-  };
-  const findings = [];
-  for (const analyzer of analyzers) {
-    const out = await analyzer.run(ctx);
-    findings.push(...out);
-  }
-  return { artifacts, findings };
-}
+// src/detector/analyzers/diamondStorage.ts
+import { keccak_256 as keccak_2562 } from "@noble/hashes/sha3";
 
 // src/lib/eip7201.ts
 import { keccak_256 } from "@noble/hashes/sha3";
@@ -191,6 +161,488 @@ function parseErc7201Annotation(text) {
   const match = rest.match(/^[A-Za-z0-9_.\-]+/);
   return match ? match[0] : null;
 }
+
+// src/detector/analyzers/diamondStorage.ts
+function keccak256Hex(input) {
+  const bytes = keccak_2562(new TextEncoder().encode(input));
+  let out = "0x";
+  for (const b of bytes) out += b.toString(16).padStart(2, "0");
+  return out;
+}
+function isBytes32Constant(node) {
+  if (node.nodeType !== "VariableDeclaration") return false;
+  if (node.constant !== true) return false;
+  const typeName = node.typeName;
+  return typeName?.nodeType === "ElementaryTypeName" && typeName.name === "bytes32";
+}
+function extractKeccakStringArg(value) {
+  if (!value || typeof value !== "object") return null;
+  const v = value;
+  if (v.nodeType !== "FunctionCall") return null;
+  const expr = v.expression;
+  if (expr?.nodeType !== "Identifier" || expr.name !== "keccak256") return null;
+  const args = v.arguments;
+  if (!Array.isArray(args) || args.length !== 1) return null;
+  const arg = args[0];
+  if (arg.nodeType !== "Literal" || arg.kind !== "string") return null;
+  return typeof arg.value === "string" ? arg.value : null;
+}
+function extractBytes32HexLiteral(value) {
+  if (!value || typeof value !== "object") return null;
+  const v = value;
+  if (v.nodeType !== "Literal" || v.kind !== "number") return null;
+  if (typeof v.value !== "string") return null;
+  try {
+    const big = BigInt(v.value);
+    if (big < 0n) return null;
+    return "0x" + big.toString(16).padStart(64, "0");
+  } catch {
+    return null;
+  }
+}
+function findKeccakStringArg(node) {
+  if (!node || typeof node !== "object") return null;
+  const v = node;
+  if (v.nodeType !== "FunctionCall") return null;
+  const expr = v.expression;
+  if (expr?.nodeType !== "Identifier" || expr.name !== "keccak256") return null;
+  const args = v.arguments;
+  if (!Array.isArray(args) || args.length !== 1) return null;
+  const arg = args[0];
+  if (arg.nodeType !== "Literal" || arg.kind !== "string") return null;
+  return typeof arg.value === "string" ? arg.value : null;
+}
+function someNode(node, pred) {
+  if (!node || typeof node !== "object") return false;
+  const n = node;
+  if (typeof n.nodeType === "string" && pred(n)) return true;
+  for (const key of Object.keys(n)) {
+    const value = n[key];
+    if (Array.isArray(value)) {
+      if (value.some((c) => someNode(c, pred))) return true;
+    } else if (value && typeof value === "object") {
+      if (someNode(value, pred)) return true;
+    }
+  }
+  return false;
+}
+function extractErc7201FormulaNamespace(value) {
+  const strings = [];
+  someNode(value, (n) => {
+    const s = findKeccakStringArg(n);
+    if (s !== null) strings.push(s);
+    return false;
+  });
+  if (strings.length !== 1) return null;
+  const hasSubOne = someNode(
+    value,
+    (n) => n.nodeType === "BinaryOperation" && n.operator === "-" && n.rightExpression?.nodeType === "Literal" && n.rightExpression.value === "1"
+  );
+  const hasMask = someNode(value, (n) => n.nodeType === "BinaryOperation" && n.operator === "&");
+  if (!hasSubOne || !hasMask) return null;
+  return strings[0];
+}
+function walkAst(ast, visit, parents = []) {
+  if (!ast || typeof ast !== "object") return;
+  const node = ast;
+  if (typeof node.nodeType === "string") visit(node, parents);
+  const nextParents = typeof node.nodeType === "string" ? [...parents, node] : parents;
+  for (const key of Object.keys(node)) {
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const child of value) walkAst(child, visit, nextParents);
+    } else if (value && typeof value === "object") {
+      walkAst(value, visit, nextParents);
+    }
+  }
+}
+function declaringContract(parents) {
+  for (let i = parents.length - 1; i >= 0; i--) {
+    const p = parents[i];
+    if (p.nodeType === "ContractDefinition") return p.name ?? null;
+  }
+  return null;
+}
+function collectSlotConstants(ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of ctx.artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (!isBytes32Constant(node)) return;
+      const namespace = extractKeccakStringArg(node.value);
+      if (namespace === null) return;
+      const declarationId = typeof node.id === "number" ? node.id : -1;
+      const variableName = node.name ?? "<anon>";
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${variableName}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId,
+        variableName,
+        namespace,
+        slot: keccak256Hex(namespace),
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+function collectLiteralSlotConstants(ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of ctx.artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (!isBytes32Constant(node)) return;
+      if (extractKeccakStringArg(node.value) !== null) return;
+      const slot = extractBytes32HexLiteral(node.value);
+      if (slot === null) return;
+      const declarationId = typeof node.id === "number" ? node.id : -1;
+      const variableName = node.name ?? "<anon>";
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${variableName}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId,
+        variableName,
+        namespace: null,
+        slot,
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+function collectFormulaSlotConstants(ctx) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of ctx.artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (!isBytes32Constant(node)) return;
+      if (extractKeccakStringArg(node.value) !== null) return;
+      const namespace = extractErc7201FormulaNamespace(node.value);
+      if (namespace === null) return;
+      const declarationId = typeof node.id === "number" ? node.id : -1;
+      const variableName = node.name ?? "<anon>";
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${variableName}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId,
+        variableName,
+        namespace,
+        slot: erc7201Slot(namespace),
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+function collectAssemblyLiteralSlots(artifacts) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node, parents) => {
+      if (node.nodeType !== "YulAssignment") return;
+      const targets = node.variableNames;
+      const targetsSlot = Array.isArray(targets) && targets.some((t) => typeof t.name === "string" && t.name.endsWith(".slot"));
+      if (!targetsSlot) return;
+      const value = node.value;
+      if (value?.nodeType !== "YulLiteral" || value.kind !== "number") return;
+      if (typeof value.value !== "string") return;
+      let slot;
+      try {
+        const big = BigInt(value.value);
+        if (big < 0n) return;
+        slot = "0x" + big.toString(16).padStart(64, "0");
+      } catch {
+        return;
+      }
+      const contract = declaringContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${contract}::${slot}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        declarationId: -1,
+        variableName: "<assembly literal>",
+        namespace: null,
+        slot,
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+function collectSlotAssignmentValueSrcs(yulNode, srcs) {
+  if (!yulNode || typeof yulNode !== "object") return;
+  const node = yulNode;
+  if (node.nodeType === "YulAssignment") {
+    const targets = node.variableNames;
+    const targetsSlot = Array.isArray(targets) && targets.some((t) => typeof t.name === "string" && t.name.endsWith(".slot"));
+    if (targetsSlot) {
+      const value = node.value;
+      if (value?.nodeType === "YulIdentifier" && typeof value.src === "string") {
+        srcs.add(value.src);
+      }
+    }
+  }
+  for (const key of Object.keys(node)) {
+    const v = node[key];
+    if (Array.isArray(v)) {
+      for (const child of v) collectSlotAssignmentValueSrcs(child, srcs);
+    } else if (v && typeof v === "object") {
+      collectSlotAssignmentValueSrcs(v, srcs);
+    }
+  }
+}
+function collectSlotUsedDeclarationIds(artifacts) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const artifact of artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node) => {
+      if (node.nodeType !== "InlineAssembly") return;
+      const yulAst = node.AST;
+      if (!yulAst) return;
+      const slotValueSrcs = /* @__PURE__ */ new Set();
+      collectSlotAssignmentValueSrcs(yulAst, slotValueSrcs);
+      if (slotValueSrcs.size === 0) return;
+      const refs = node.externalReferences;
+      if (!Array.isArray(refs)) return;
+      for (const ref of refs) {
+        if (typeof ref.src === "string" && slotValueSrcs.has(ref.src) && typeof ref.declaration === "number") {
+          ids.add(ref.declaration);
+        }
+      }
+    });
+  }
+  return ids;
+}
+function collectAliases(artifacts) {
+  const aliases = /* @__PURE__ */ new Map();
+  for (const artifact of artifacts) {
+    if (!artifact.ast) continue;
+    walkAst(artifact.ast, (node) => {
+      if (node.nodeType !== "VariableDeclarationStatement") return;
+      const initialValue = node.initialValue;
+      if (initialValue?.nodeType !== "Identifier") return;
+      const referenced = initialValue.referencedDeclaration;
+      if (typeof referenced !== "number") return;
+      const decls = node.declarations;
+      if (!Array.isArray(decls)) return;
+      for (const d of decls) {
+        if (typeof d?.id === "number") aliases.set(d.id, referenced);
+      }
+    });
+  }
+  return aliases;
+}
+function isUsedAsSlot(constantId, slotUsedIds, aliases) {
+  if (constantId < 0) return false;
+  if (slotUsedIds.has(constantId)) return true;
+  for (const [aliasId, refId] of aliases) {
+    if (refId === constantId && slotUsedIds.has(aliasId)) return true;
+  }
+  return false;
+}
+function collectGatedSlotConstants(ctx) {
+  const constants = [
+    ...collectSlotConstants(ctx),
+    ...collectLiteralSlotConstants(ctx),
+    ...collectFormulaSlotConstants(ctx)
+  ];
+  const slotUsedIds = collectSlotUsedDeclarationIds(ctx.artifacts);
+  const aliases = collectAliases(ctx.artifacts);
+  return [
+    ...constants.filter((c) => isUsedAsSlot(c.declarationId, slotUsedIds, aliases)),
+    ...collectAssemblyLiteralSlots(ctx.artifacts)
+  ];
+}
+
+// src/detector/analyzers/erc7201.ts
+var NAMED_NODE_TYPES = /* @__PURE__ */ new Set([
+  "ContractDefinition",
+  "StructDefinition",
+  "FunctionDefinition",
+  "VariableDeclaration",
+  "ErrorDefinition",
+  "EventDefinition",
+  "ModifierDefinition",
+  "EnumDefinition"
+]);
+function getDocText(node) {
+  const doc = node.documentation;
+  if (!doc) return null;
+  if (typeof doc === "string") return doc;
+  if (typeof doc === "object" && doc !== null) {
+    const text = doc.text;
+    if (typeof text === "string") return text;
+  }
+  return null;
+}
+function nearestContract(parents) {
+  for (let i = parents.length - 1; i >= 0; i--) {
+    const p = parents[i];
+    if (p.nodeType === "ContractDefinition") return p.name ?? null;
+  }
+  return null;
+}
+function walkAst2(ast, visit, parents = []) {
+  if (!ast || typeof ast !== "object") return;
+  const node = ast;
+  if (typeof node.nodeType === "string") visit(node, parents);
+  const nextParents = typeof node.nodeType === "string" ? [...parents, node] : parents;
+  for (const key of Object.keys(node)) {
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const child of value) walkAst2(child, visit, nextParents);
+    } else if (value && typeof value === "object") {
+      walkAst2(value, visit, nextParents);
+    }
+  }
+}
+function collectErc7201Annotations(artifacts) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const artifact of artifacts) {
+    if (!artifact.ast) continue;
+    walkAst2(artifact.ast, (node, parents) => {
+      if (!node.nodeType || !NAMED_NODE_TYPES.has(node.nodeType)) return;
+      const text = getDocText(node);
+      if (!text || !text.includes("erc7201:")) return;
+      const namespaceId = parseErc7201Annotation(text);
+      if (!namespaceId) return;
+      const attachedTo = `${node.nodeType}:${node.name ?? "<anon>"}`;
+      const contract = node.nodeType === "ContractDefinition" ? node.name ?? artifact.contractName : nearestContract(parents) ?? artifact.contractName;
+      const src = node.src;
+      const dedupeKey = `${artifact.sourcePath}::${attachedTo}::${src ?? ""}`;
+      if (seen.has(dedupeKey)) return;
+      seen.add(dedupeKey);
+      out.push({
+        namespaceId,
+        slot: erc7201Slot(namespaceId),
+        attachedTo,
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+
+// src/detector/inventory.ts
+function lineOf(src, text) {
+  if (!src || !text) return void 0;
+  const [startStr] = src.split(":");
+  const start = Number(startStr);
+  if (!Number.isFinite(start)) return void 0;
+  let line = 1;
+  for (let i = 0; i < start && i < text.length; i++) {
+    if (text.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+var PRIORITY = { erc7201: 0, namespace: 1, hardcoded: 2 };
+function buildInventory(ctx) {
+  const bySlot = /* @__PURE__ */ new Map();
+  const add = (region) => {
+    const existing = bySlot.get(region.slot);
+    if (!existing || PRIORITY[region.kind] < PRIORITY[existing.kind]) {
+      bySlot.set(region.slot, region);
+    }
+  };
+  for (const c of collectGatedSlotConstants(ctx)) {
+    add({
+      slot: c.slot,
+      label: c.namespace ?? c.variableName,
+      kind: c.namespace ? "namespace" : "hardcoded",
+      contract: c.contract,
+      file: c.sourcePath,
+      line: lineOf(c.src, ctx.rawSources.get(c.sourcePath))
+    });
+  }
+  for (const a of collectErc7201Annotations(ctx.artifacts)) {
+    add({
+      slot: a.slot,
+      label: a.namespaceId,
+      kind: "erc7201",
+      contract: a.contract,
+      file: a.sourcePath,
+      line: lineOf(a.src, ctx.rawSources.get(a.sourcePath))
+    });
+  }
+  return [...bySlot.values()].sort(
+    (x, y) => x.file.localeCompare(y.file) || x.slot.localeCompare(y.slot)
+  );
+}
+
+// src/detector/index.ts
+var DEFAULT_IGNORE_GLOBS = [
+  "lib/**",
+  "test/**",
+  "script/**",
+  "**/*.t.sol",
+  "**/*.s.sol"
+];
+function compilePatterns(globs) {
+  return globs.map((g) => {
+    const escaped = g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::DOUBLESTAR::").replace(/\*/g, "[^/]*").replace(/::DOUBLESTAR::/g, ".*").replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+  });
+}
+function buildIgnore(userGlobs, noDefault) {
+  const globs = [
+    ...noDefault ? [] : DEFAULT_IGNORE_GLOBS,
+    ...userGlobs ?? []
+  ];
+  if (globs.length === 0) return void 0;
+  const patterns = compilePatterns(globs);
+  return (sourcePath) => patterns.some((p) => p.test(sourcePath));
+}
+function buildIsFacet(globs) {
+  if (!globs || globs.length === 0) return void 0;
+  const patterns = compilePatterns(globs);
+  return (artifact) => patterns.some((p) => p.test(artifact.sourcePath));
+}
+async function detect(options, analyzers) {
+  const artifacts = await loadFoundryArtifacts(options.path, {
+    ignoreSourcePath: buildIgnore(options.ignoreGlobs, options.noDefaultIgnore)
+  });
+  const rawSources = await loadRawSources(
+    options.path,
+    artifacts.map((a) => a.sourcePath)
+  );
+  const ctx = {
+    artifacts,
+    rawSources,
+    isFacet: buildIsFacet(options.facetGlobs)
+  };
+  const findings = [];
+  for (const analyzer of analyzers) {
+    const out = await analyzer.run(ctx);
+    findings.push(...out);
+  }
+  const inventory = buildInventory(ctx);
+  return { artifacts, findings, rawSources, inventory };
+}
 export {
   detect,
   erc7201Slot,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diamond-detect",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Static analyzer for EIP-2535 Diamond storage-slot collisions across facets",
   "homepage": "https://github.com/jayeshy14/Diamond-Storage-Detector#readme",
   "repository": {