diamond-detect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayesh Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# diamond-detect
+
+A static analyzer for [EIP-2535 Diamond](https://eips.ethereum.org/EIPS/eip-2535) storage-slot collisions. Reads your Foundry build artifacts and reports cases where two facets would silently corrupt each other through the proxy's shared storage.
+
+```sh
+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.
+
+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.
+
+## Should you use it?
+
+You should use it if:
+
+- Your project deploys an EIP-2535 Diamond, or treats some contracts as facets sharing a single proxy's storage.
+- You use Foundry to build (`out/` artifacts).
+- You want to catch namespace, AppStorage, EIP-7201, or inline-assembly slot collisions before they hit mainnet.
+
+You probably don't need it if you have only a handful of facets that all consume one canonical `LibAppStorage` and you read every storage layout diff manually. Even then, it's a 5-minute install — worth running once.
+
+## Install
+
+```sh
+npm install -g diamond-detect    # global, then run `diamond-detect`
+# or:
+npx diamond-detect <path>        # no install
+```
+
+Requires Node 20+ and Foundry.
+
+## First run
+
+### 1. Configure Foundry to emit AST + storage layout
+
+`diamond-detect` needs both. Easiest way is via `foundry.toml`:
+
+```toml
+[profile.default]
+ast = true
+extra_output = ["storageLayout"]
+```
+
+(Or pass `--ast --extra-output storageLayout` to `forge build` each time.)
+
+### 2. Build
+
+```sh
+forge build
+```
+
+This populates `out/` with artifact JSON files that include the AST and storage layout for every contract.
+
+### 3. Scan
+
+```sh
+diamond-detect .
+```
+
+If everything is fine you'll see:
+
+```
+scanned 12 contract artifact(s)
+✓ no storage collisions detected
+```
+
+If something is wrong you'll see one or more findings with the slot, the colliding contracts, 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
+
+1 error(s), 0 warning(s)
+```
+
+Exit code is `1` whenever a finding meets your `--severity` threshold (default `warn`), `0` otherwise, `2` on internal errors.
+
+## What it detects
+
+Run [`examples/`](./examples/) to see each one in action — every example ships a buggy `before/` and a fixed `after/`.
+
+| 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/)) |
+| `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`. |
+| `inline-assembly-slot` | info | A literal slot is written via `sstore(0x42, …)`. Usually intentional, but reported so you can confirm it doesn't overlap a computed Diamond Storage slot. |
+
+A clean baseline that exercises every analyzer and produces no findings is in [`examples/04-clean/`](./examples/04-clean/).
+
+## Configuring for your project
+
+### Scope to your real facets with `--facets`
+
+By default `diamond-detect` analyzes every contract in `src/`. Diamond projects often have non-facet contracts there too — registries, factories, libraries — and the inheritance-overlap analyzer can produce noisy advisories for them. Tell it where your facets actually live:
+
+```sh
+diamond-detect --facets 'src/facets/**' .
+```
+
+This restricts the facet-shared-storage analyzers (`inheritance-overlap`, `appstorage-fingerprint`) to that glob. Other analyzers still scan the whole project.
+
+### Default ignores
+
+These paths are skipped automatically because they're never facets:
+
+```
+lib/**
+test/**
+script/**
+**/*.t.sol
+**/*.s.sol
+```
+
+Add your own with `--ignore <glob>` (repeatable). Disable the defaults entirely with `--no-default-ignore`.
+
+### Severity thresholds in CI
+
+```sh
+diamond-detect --severity error .   # exit 1 only on errors
+diamond-detect --severity warn .    # default: exit 1 on warns + errors
+diamond-detect --severity info .    # exit 1 on anything
+```
+
+## CLI reference
+
+```
+diamond-detect <path>                    Foundry project root or src/ folder
+  --json                                 Machine-readable JSON
+  --markdown                             GitHub-flavored Markdown (PR-friendly)
+  --severity <info|warn|error>           Exit-code threshold (default: warn)
+  --ignore <glob>                        Skip source paths matching this glob (repeatable)
+  --no-default-ignore                    Don't skip lib/, test/, script/, *.t.sol, *.s.sol
+  --facets <glob>                        Restrict facet-shared-storage analyzers
+                                         (inheritance-overlap, appstorage-fingerprint)
+                                         to source paths matching this glob (repeatable)
+```
+
+## Output formats
+
+- **Terminal** (default): coloured, one block per finding, summary footer.
+- **JSON** (`--json`): a stable shape suitable for piping into other tools.
+
+  ```json
+  {
+    "summary": { "facetCount": 12, "errors": 1, "warnings": 0, "info": 0 },
+    "findings": [
+      {
+        "kind": "diamond-storage-namespace",
+        "severity": "error",
+        "slot": "0x...",
+        "message": "...",
+        "facets": ["LibStrategies", "LibVaults"],
+        "locations": [{ "file": "src/LibStrategies.sol" }],
+        "detail": { "namespaces": ["myapp.strategies"], "declarations": [...] }
+      }
+    ]
+  }
+  ```
+
+- **Markdown** (`--markdown`): findings grouped by kind into severity-tagged `<details>` blocks. Designed for posting as a PR comment.
+
+## CI integration
+
+Drop this into `.github/workflows/diamond-detect.yml`:
+
+```yaml
+name: diamond-detect
+
+on:
+  pull_request:
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: foundry-rs/foundry-toolchain@v1
+      - run: forge build
+      - run: npx -y diamond-detect --markdown --facets 'src/facets/**' . > diamond-detect.md
+      - uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          path: diamond-detect.md
+```
+
+Tighten with `--severity error` if you only want to fail CI on hard collisions.
+
+## Troubleshooting
+
+**"warning: no AST found in any artifact"** — your build didn't include AST output. Set `ast = true` in `foundry.toml` (under `[profile.default]`) and rebuild. Without AST, the namespace, EIP-7201, and inline-assembly analyzers can't run; only storage-layout-based ones (`appstorage-fingerprint`, `inheritance-overlap`) will fire.
+
+**"Foundry out/ directory not found"** — you haven't run `forge build` yet, or you pointed `diamond-detect` at the wrong directory. Pass either the project root (the directory with `foundry.toml`) or any subdirectory of it.
+
+**Scans `0` artifacts** — the loader is filtering everything. If your facets live under non-standard paths (e.g. `src/diamond/**` and you also have files in `lib/diamond-3-hardhat/`), check whether the default-ignore is hiding them. Use `--no-default-ignore` to confirm, then add narrower `--ignore` patterns.
+
+**Lots of `inheritance-overlap` warnings on registries / factories** — those are non-facet contracts. Scope the analyzer with `--facets 'src/facets/**'` (or wherever your facets live).
+
+**Findings only when I rebuild?** — `forge build` is incremental. If you change a struct definition but don't touch the consumers, their artifacts stay stale and the analyzer doesn't see the new layout. Wipe with `forge clean && forge build` if you suspect drift.
+
+## 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 |
+
+Slither remains excellent for general Solidity static analysis. Use both.
+
+## Roadmap
+
+- **Onchain mode**: point at a deployed Diamond address; resolve facets through the [Diamond Loupe](https://eips.ethereum.org/EIPS/eip-2535#diamond-loupe), pull source from Etherscan, and run the same checks against what's actually live.
+- **Facet auto-detection**: infer the facet set by walking deployment scripts or naming conventions, so `--facets` becomes optional.
+- **Slither plugin**: surface findings inside an existing Slither pipeline.
+- **VS Code extension**: inline diagnostics on save.
+
+Issues and PRs welcome at the [repo](https://github.com/jayeshy14/Diamond-Storage-Detector).
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/cli.js

@@ -0,0 +1,875 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+import pc2 from "picocolors";
+
+// src/detector/parseArtifacts.ts
+import { promises as fs } from "fs";
+import path from "path";
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveFoundryRoot(input) {
+  const abs = path.resolve(input);
+  const stat = await fs.stat(abs);
+  const candidate = stat.isDirectory() ? abs : path.dirname(abs);
+  let cur = candidate;
+  for (let i = 0; i < 6; i++) {
+    if (await fileExists(path.join(cur, "foundry.toml"))) {
+      return { root: cur, outDir: path.join(cur, "out") };
+    }
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  if (await fileExists(path.join(candidate, "out"))) {
+    return { root: candidate, outDir: path.join(candidate, "out") };
+  }
+  throw new Error(
+    `Could not locate a Foundry project root from "${input}". Run \`forge build\` first, or pass the project root.`
+  );
+}
+async function walkJson(dir, acc = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) await walkJson(full, acc);
+    else if (e.isFile() && e.name.endsWith(".json") && !e.name.endsWith(".metadata.json")) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+function extractContractName(artifactPath) {
+  return path.basename(artifactPath, ".json");
+}
+function extractSourcePath(artifactPath, parsed) {
+  if (typeof parsed.metadata === "object" && parsed.metadata?.settings?.compilationTarget) {
+    const targets = parsed.metadata.settings.compilationTarget;
+    const first = Object.keys(targets)[0];
+    if (first) return first;
+  }
+  if (typeof parsed.metadata === "string") {
+    try {
+      const md = JSON.parse(parsed.metadata);
+      if (typeof md === "object" && md?.settings?.compilationTarget) {
+        const first = Object.keys(md.settings.compilationTarget)[0];
+        if (first) return first;
+      }
+    } catch {
+    }
+  }
+  return path.basename(path.dirname(artifactPath));
+}
+async function loadFoundryArtifacts(inputPath, opts = {}) {
+  const { outDir } = await resolveFoundryRoot(inputPath);
+  if (!await fileExists(outDir)) {
+    throw new Error(
+      `Foundry out/ directory not found at ${outDir}. Run \`forge build\` first, with \`ast = true\` and \`extra_output = ["storageLayout"]\` in foundry.toml (or pass \`--ast\` to forge).`
+    );
+  }
+  const files = await walkJson(outDir);
+  const artifacts = [];
+  for (const file of files) {
+    const text = await fs.readFile(file, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    if (!parsed.ast && !parsed.storageLayout) continue;
+    const contractName = extractContractName(file);
+    const sourcePath = extractSourcePath(file, parsed);
+    if (opts.ignoreSourcePath?.(sourcePath)) continue;
+    artifacts.push({
+      contractName,
+      sourcePath,
+      artifactPath: file,
+      storageLayout: parsed.storageLayout ?? null,
+      ast: parsed.ast,
+      bytecodeHash: parsed.bytecode?.object ? parsed.bytecode.object.slice(0, 18) : void 0
+    });
+  }
+  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 } from "@noble/hashes/sha3";
+function keccak256Hex(input) {
+  const bytes = keccak_256(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 lineFromSrc(src, sourceText) {
+  if (typeof src !== "string" || !sourceText) 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 < sourceText.length; i++) {
+    if (sourceText.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+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 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({
+        variableName,
+        namespace,
+        slot: keccak256Hex(namespace),
+        contract,
+        sourcePath: artifact.sourcePath,
+        src
+      });
+    });
+  }
+  return out;
+}
+var diamondStorageAnalyzer = {
+  name: "diamond-storage-namespace",
+  run(ctx) {
+    const constants = collectSlotConstants(ctx);
+    const bySlot = /* @__PURE__ */ new Map();
+    for (const c of constants) {
+      const list = bySlot.get(c.slot) ?? [];
+      list.push(c);
+      bySlot.set(c.slot, list);
+    }
+    const findings = [];
+    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 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) };
+      });
+      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.`,
+        facets,
+        locations,
+        detail: { namespaces, 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",
+  "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;
+}
+var erc7201Analyzer = {
+  name: "erc7201-namespace",
+  run(ctx) {
+    const annotations = collectErc7201Annotations(ctx.artifacts);
+    const bySlot = /* @__PURE__ */ new Map();
+    for (const a of annotations) {
+      const list = bySlot.get(a.slot) ?? [];
+      list.push(a);
+      bySlot.set(a.slot, list);
+    }
+    const findings = [];
+    for (const [slot, group] of bySlot) {
+      const distinctSources = new Set(group.map((g) => g.sourcePath));
+      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 }));
+      findings.push({
+        kind: "erc7201-namespace",
+        severity: "error",
+        slot,
+        message: ids.length === 1 ? `EIP-7201 namespace "${ids[0]}" is declared in ${distinctSources.size} different sources, all resolving to the same slot.` : `Distinct EIP-7201 namespaces ${ids.map((n) => `"${n}"`).join(", ")} hash to the same slot.`,
+        facets,
+        locations,
+        detail: { namespaceIds: ids, annotations: group }
+      });
+    }
+    return findings;
+  }
+};
+
+// src/detector/analyzers/appStorage.ts
+function memberFingerprint(m) {
+  return { label: m.label, offset: m.offset, slot: m.slot, type: m.type };
+}
+function structFingerprint(label, numberOfBytes, members) {
+  const ordered = [...members].map(memberFingerprint).sort((a, b) => {
+    if (a.slot !== b.slot) return a.slot.localeCompare(b.slot);
+    return a.offset - b.offset;
+  });
+  return { label, numberOfBytes, members: ordered };
+}
+function hashFingerprint(fp) {
+  return JSON.stringify(fp);
+}
+function collectStructFingerprints(artifacts) {
+  const byLabel = /* @__PURE__ */ new Map();
+  for (const artifact of artifacts) {
+    const types = artifact.storageLayout?.types;
+    if (!types) continue;
+    for (const entry of Object.values(types)) {
+      if (!entry.members || entry.members.length === 0) continue;
+      if (entry.encoding !== "inplace") continue;
+      const fingerprint = structFingerprint(entry.label, entry.numberOfBytes, entry.members);
+      const hash = hashFingerprint(fingerprint);
+      const list = byLabel.get(entry.label) ?? [];
+      list.push({ fingerprint, hash, artifact });
+      byLabel.set(entry.label, list);
+    }
+  }
+  return byLabel;
+}
+function dedupeByHash(items) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = `${item.hash}::${item.artifact.sourcePath}`;
+    if (!seen.has(key)) seen.set(key, item);
+  }
+  return Array.from(seen.values());
+}
+function diffSummary(a, b) {
+  const aFields = new Set(a.members.map((m) => `${m.label}@${m.slot}+${m.offset}:${m.type}`));
+  const bFields = new Set(b.members.map((m) => `${m.label}@${m.slot}+${m.offset}:${m.type}`));
+  const onlyA = [...aFields].filter((f) => !bFields.has(f));
+  const onlyB = [...bFields].filter((f) => !aFields.has(f));
+  const parts = [];
+  if (onlyA.length > 0) parts.push(`only in version A: ${onlyA.join(", ")}`);
+  if (onlyB.length > 0) parts.push(`only in version B: ${onlyB.join(", ")}`);
+  if (a.numberOfBytes !== b.numberOfBytes) {
+    parts.push(`size differs (${a.numberOfBytes} vs ${b.numberOfBytes} bytes)`);
+  }
+  return parts.join("; ");
+}
+var appStorageAnalyzer = {
+  name: "appstorage-fingerprint",
+  run(ctx) {
+    const findings = [];
+    const scoped = ctx.isFacet ? ctx.artifacts.filter(ctx.isFacet) : ctx.artifacts;
+    const grouped = collectStructFingerprints(scoped);
+    for (const [label, items] of grouped) {
+      const variants = /* @__PURE__ */ new Map();
+      for (const item of dedupeByHash(items)) {
+        const list = variants.get(item.hash) ?? [];
+        list.push(item);
+        variants.set(item.hash, list);
+      }
+      if (variants.size < 2) continue;
+      const variantArr = [...variants.values()];
+      const sources = /* @__PURE__ */ new Set();
+      const facets = /* @__PURE__ */ new Set();
+      const locations = [];
+      for (const v of variantArr) {
+        for (const item of v) {
+          sources.add(item.artifact.sourcePath);
+          facets.add(item.artifact.contractName);
+          locations.push({ file: item.artifact.sourcePath });
+        }
+      }
+      const a = variantArr[0][0].fingerprint;
+      const b = variantArr[1][0].fingerprint;
+      const summary = diffSummary(a, b);
+      findings.push({
+        kind: "appstorage-fingerprint",
+        severity: "error",
+        slot: "n/a",
+        message: `${label} has ${variants.size} divergent layouts across ${sources.size} sources \u2014 ${summary || "member ordering differs"}.`,
+        facets: [...facets],
+        locations,
+        detail: {
+          structLabel: label,
+          variants: variantArr.map((v) => ({
+            fingerprint: v[0].fingerprint,
+            artifacts: v.map((x) => ({
+              contractName: x.artifact.contractName,
+              sourcePath: x.artifact.sourcePath
+            }))
+          }))
+        }
+      });
+    }
+    return findings;
+  }
+};
+
+// src/detector/analyzers/inlineAssembly.ts
+function walkAst3(ast, visit) {
+  if (!ast || typeof ast !== "object") return;
+  const node = ast;
+  if (typeof node.nodeType === "string") visit(node);
+  for (const key of Object.keys(node)) {
+    const value = node[key];
+    if (Array.isArray(value)) {
+      for (const child of value) walkAst3(child, visit);
+    } else if (value && typeof value === "object") {
+      walkAst3(value, visit);
+    }
+  }
+}
+function normalizeSlot(value) {
+  const trimmed = value.trim();
+  let big;
+  try {
+    if (trimmed.startsWith("0x") || trimmed.startsWith("0X")) {
+      big = BigInt(trimmed);
+    } else {
+      big = BigInt(trimmed);
+    }
+  } catch {
+    return trimmed;
+  }
+  return "0x" + big.toString(16).padStart(64, "0");
+}
+function collectSstoreLiterals(artifacts) {
+  const out = [];
+  for (const artifact of artifacts) {
+    if (!artifact.ast) continue;
+    walkAst3(artifact.ast, (node) => {
+      if (node.nodeType !== "YulFunctionCall") return;
+      const fnName = node.functionName?.name;
+      if (fnName !== "sstore") return;
+      const args = node.arguments;
+      if (!Array.isArray(args) || args.length < 2) return;
+      const arg0 = args[0];
+      if (arg0?.nodeType !== "YulLiteral" || arg0.kind !== "number") return;
+      const rawValue = String(arg0.value ?? "");
+      out.push({
+        slot: normalizeSlot(rawValue),
+        rawValue,
+        artifact,
+        src: node.src
+      });
+    });
+  }
+  return out;
+}
+var inlineAssemblyAnalyzer = {
+  name: "inline-assembly-slot",
+  run(ctx) {
+    const literals = collectSstoreLiterals(ctx.artifacts);
+    return literals.map((lit) => ({
+      kind: "inline-assembly-slot",
+      severity: "info",
+      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 }],
+      detail: { rawValue: lit.rawValue, src: lit.src }
+    }));
+  }
+};
+
+// src/detector/analyzers/inheritance.ts
+function keyOf(s) {
+  return `${s.slot}@${s.offset}`;
+}
+function declarationKey(s) {
+  return `${s.label}::${s.type}`;
+}
+function collectSlotEntries(artifacts) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const artifact of artifacts) {
+    const layout = artifact.storageLayout?.storage;
+    if (!layout || layout.length === 0) continue;
+    for (const slot of layout) {
+      const k = keyOf(slot);
+      const list = byKey.get(k) ?? [];
+      list.push({ artifact, slot });
+      byKey.set(k, list);
+    }
+  }
+  return byKey;
+}
+var inheritanceAnalyzer = {
+  name: "inheritance-overlap",
+  run(ctx) {
+    const findings = [];
+    const scoped = ctx.isFacet ? ctx.artifacts.filter(ctx.isFacet) : ctx.artifacts;
+    const grouped = collectSlotEntries(scoped);
+    for (const [_slotKey, entries] of grouped) {
+      const facetNames = new Set(entries.map((e) => e.artifact.contractName));
+      if (facetNames.size < 2) continue;
+      const declarations = /* @__PURE__ */ new Map();
+      for (const e of entries) {
+        const k = declarationKey(e.slot);
+        const list = declarations.get(k) ?? [];
+        list.push(e);
+        declarations.set(k, list);
+      }
+      if (declarations.size < 2) continue;
+      const sample = entries[0].slot;
+      const slotHex = "0x" + BigInt(sample.slot).toString(16).padStart(64, "0");
+      const facets = Array.from(facetNames).sort();
+      const declarationsForMessage = Array.from(declarations.entries()).map(
+        ([_, items]) => {
+          const sample2 = items[0].slot;
+          return `${sample2.label}:${sample2.type} (declared in ${sample2.contract})`;
+        }
+      );
+      const locations = entries.map((e) => ({
+        file: e.artifact.sourcePath
+      }));
+      findings.push({
+        kind: "inheritance-overlap",
+        severity: "warn",
+        slot: slotHex,
+        message: `Slot ${sample.slot}+${sample.offset} is occupied by ${declarations.size} different declarations across ${facetNames.size} contracts: ${declarationsForMessage.join(" vs ")}. If these are Diamond facets sharing the proxy's storage, this is a collision; if they are independent contracts, ignore.`,
+        facets,
+        locations,
+        detail: {
+          slot: sample.slot,
+          offset: sample.offset,
+          declarations: Array.from(declarations.entries()).map(([_, items]) => ({
+            contract: items[0].slot.contract,
+            label: items[0].slot.label,
+            type: items[0].slot.type,
+            facets: items.map((i) => i.artifact.contractName)
+          }))
+        }
+      });
+    }
+    return findings;
+  }
+};
+
+// src/detector/analyzers/index.ts
+var defaultAnalyzers = [
+  diamondStorageAnalyzer,
+  erc7201Analyzer,
+  appStorageAnalyzer,
+  inlineAssemblyAnalyzer,
+  inheritanceAnalyzer
+];
+
+// 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 ");
+}
+function renderTerminal(findings, facetCount) {
+  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 sorted = [...findings].sort(
+    (a, b) => SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity]
+  );
+  for (const f of sorted) {
+    lines.push("");
+    lines.push(`${colorSeverity(f.severity)} ${pc.bold(f.kind)}  ${pc.dim(f.slot)}`);
+    lines.push(`  ${f.message}`);
+    if (f.facets.length > 0) {
+      lines.push(`  ${pc.dim("facets:")} ${f.facets.join(", ")}`);
+    }
+    for (const loc of f.locations) {
+      const where = loc.line ? `${loc.file}:${loc.line}` : loc.file;
+      lines.push(`  ${pc.dim("at")} ${where}`);
+    }
+  }
+  const errors = findings.filter((f) => f.severity === "error").length;
+  const warns = findings.filter((f) => f.severity === "warn").length;
+  lines.push("");
+  lines.push(pc.bold(`${errors} error(s), ${warns} warning(s)`));
+  return lines.join("\n");
+}
+
+// src/reporter/json.ts
+function renderJson(findings, facetCount) {
+  return JSON.stringify(
+    {
+      summary: {
+        facetCount,
+        errors: findings.filter((f) => f.severity === "error").length,
+        warnings: findings.filter((f) => f.severity === "warn").length,
+        info: findings.filter((f) => f.severity === "info").length
+      },
+      findings
+    },
+    null,
+    2
+  );
+}
+
+// src/reporter/markdown.ts
+var SEVERITY_LABEL = {
+  error: "\u{1F534} error",
+  warn: "\u{1F7E1} warn",
+  info: "\u{1F535} info"
+};
+var SEVERITY_RANK2 = { info: 0, warn: 1, error: 2 };
+var KIND_TITLE = {
+  "diamond-storage-namespace": "Diamond Storage namespace collisions",
+  "appstorage-fingerprint": "AppStorage struct drift",
+  "erc7201-namespace": "EIP-7201 namespace collisions",
+  "inline-assembly-slot": "Inline-assembly hardcoded sstore slots",
+  "inheritance-overlap": "Inheritance / cross-contract slot overlap",
+  "mapping-overlap": "Mapping / Diamond Storage overlap"
+};
+function escape(text) {
+  return text.replace(/\|/g, "\\|").replace(/`/g, "\\`");
+}
+function renderFinding(f) {
+  const lines = [];
+  lines.push(`- **\`${f.slot}\`** \u2014 ${SEVERITY_LABEL[f.severity]}`);
+  lines.push(`  - ${escape(f.message)}`);
+  if (f.facets.length > 0) {
+    lines.push(`  - facets: ${f.facets.map((x) => `\`${x}\``).join(", ")}`);
+  }
+  if (f.locations.length > 0) {
+    const locs = Array.from(new Set(f.locations.map((l) => l.file))).slice(0, 8);
+    lines.push(`  - sources: ${locs.map((l) => `\`${l}\``).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function groupByKind(findings) {
+  const map = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    const list = map.get(f.kind) ?? [];
+    list.push(f);
+    map.set(f.kind, list);
+  }
+  return map;
+}
+function maxSeverity(findings) {
+  let max = "info";
+  for (const f of findings) {
+    if (SEVERITY_RANK2[f.severity] > SEVERITY_RANK2[max]) max = f.severity;
+  }
+  return max;
+}
+function renderMarkdown(findings, facetCount) {
+  const errs = findings.filter((f) => f.severity === "error").length;
+  const warns = findings.filter((f) => f.severity === "warn").length;
+  const infos = findings.filter((f) => f.severity === "info").length;
+  if (findings.length === 0) {
+    return `### diamond-detect
+
+\u2705 No storage collisions detected across ${facetCount} contract(s).`;
+  }
+  const lines = [];
+  lines.push(`### diamond-detect`);
+  lines.push("");
+  lines.push(
+    `Scanned **${facetCount}** contract(s). Found **${errs}** error(s), **${warns}** warning(s), **${infos}** info(s).`
+  );
+  const grouped = groupByKind(findings);
+  const orderedKinds = [
+    "diamond-storage-namespace",
+    "erc7201-namespace",
+    "appstorage-fingerprint",
+    "inheritance-overlap",
+    "inline-assembly-slot",
+    "mapping-overlap"
+  ];
+  for (const kind of orderedKinds) {
+    const items = grouped.get(kind);
+    if (!items || items.length === 0) continue;
+    const title = KIND_TITLE[kind];
+    const max = maxSeverity(items);
+    const open = max === "error" ? " open" : "";
+    lines.push("");
+    lines.push(
+      `<details${open}><summary>${SEVERITY_LABEL[max]} \u2014 ${title} (${items.length})</summary>`
+    );
+    lines.push("");
+    for (const f of items) lines.push(renderFinding(f));
+    lines.push("");
+    lines.push("</details>");
+  }
+  return lines.join("\n");
+}
+
+// src/cli.ts
+var SEVERITY_RANK3 = { info: 0, warn: 1, error: 2 };
+async function run(target, opts) {
+  const result = await detect(
+    {
+      path: target,
+      ignoreGlobs: opts.ignore,
+      noDefaultIgnore: opts.noDefaultIgnore,
+      facetGlobs: opts.facets.length > 0 ? opts.facets : void 0
+    },
+    defaultAnalyzers
+  );
+  const withAst = result.artifacts.filter((a) => a.ast).length;
+  if (result.artifacts.length > 0 && withAst === 0 && !opts.json) {
+    process.stderr.write(
+      pc2.yellow(
+        "warning: no AST found in any artifact. Set `ast = true` in foundry.toml (or pass `--ast` to forge) and rebuild \u2014 AST-based analyzers depend on it.\n"
+      )
+    );
+  }
+  const output = opts.json ? renderJson(result.findings, result.artifacts.length) : opts.markdown ? renderMarkdown(result.findings, result.artifacts.length) : renderTerminal(result.findings, result.artifacts.length);
+  process.stdout.write(output + "\n");
+  const threshold = SEVERITY_RANK3[opts.severity];
+  const hit = result.findings.some((f) => SEVERITY_RANK3[f.severity] >= threshold);
+  process.exit(hit ? 1 : 0);
+}
+var program = new Command();
+program.name("diamond-detect").description("Static analyzer for EIP-2535 Diamond storage-slot collisions").argument("<path>", "Foundry project root or src/ folder").option("--json", "Emit machine-readable JSON").option("--markdown", "Emit GitHub-flavored Markdown (PR-friendly)").option(
+  "--severity <level>",
+  "Exit-code threshold: info | warn | error",
+  (v) => {
+    if (v !== "info" && v !== "warn" && v !== "error") {
+      throw new Error(`invalid severity: ${v}`);
+    }
+    return v;
+  },
+  "warn"
+).option(
+  "--ignore <glob>",
+  "Skip source files matching this glob. Repeat for multiple. Defaults: lib/**, test/**, script/**, **/*.t.sol, **/*.s.sol",
+  (v, prev = []) => prev.concat(v),
+  []
+).option(
+  "--no-default-ignore",
+  "Disable the built-in lib/test/script ignore list and scan everything in out/"
+).option(
+  "--facets <glob>",
+  "Restrict facet-shared-storage analyzers (inheritance-overlap, appstorage-fingerprint) to source paths matching this glob. Repeat for multiple.",
+  (v, prev = []) => prev.concat(v),
+  []
+).action(async (target, opts) => {
+  try {
+    await run(target, opts);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(pc2.red(`diamond-detect: ${msg}
+`));
+    process.exit(2);
+  }
+});
+program.parseAsync(process.argv);

package/dist/index.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+// src/detector/parseArtifacts.ts
+import { promises as fs } from "fs";
+import path from "path";
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveFoundryRoot(input) {
+  const abs = path.resolve(input);
+  const stat = await fs.stat(abs);
+  const candidate = stat.isDirectory() ? abs : path.dirname(abs);
+  let cur = candidate;
+  for (let i = 0; i < 6; i++) {
+    if (await fileExists(path.join(cur, "foundry.toml"))) {
+      return { root: cur, outDir: path.join(cur, "out") };
+    }
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  if (await fileExists(path.join(candidate, "out"))) {
+    return { root: candidate, outDir: path.join(candidate, "out") };
+  }
+  throw new Error(
+    `Could not locate a Foundry project root from "${input}". Run \`forge build\` first, or pass the project root.`
+  );
+}
+async function walkJson(dir, acc = []) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) await walkJson(full, acc);
+    else if (e.isFile() && e.name.endsWith(".json") && !e.name.endsWith(".metadata.json")) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+function extractContractName(artifactPath) {
+  return path.basename(artifactPath, ".json");
+}
+function extractSourcePath(artifactPath, parsed) {
+  if (typeof parsed.metadata === "object" && parsed.metadata?.settings?.compilationTarget) {
+    const targets = parsed.metadata.settings.compilationTarget;
+    const first = Object.keys(targets)[0];
+    if (first) return first;
+  }
+  if (typeof parsed.metadata === "string") {
+    try {
+      const md = JSON.parse(parsed.metadata);
+      if (typeof md === "object" && md?.settings?.compilationTarget) {
+        const first = Object.keys(md.settings.compilationTarget)[0];
+        if (first) return first;
+      }
+    } catch {
+    }
+  }
+  return path.basename(path.dirname(artifactPath));
+}
+async function loadFoundryArtifacts(inputPath, opts = {}) {
+  const { outDir } = await resolveFoundryRoot(inputPath);
+  if (!await fileExists(outDir)) {
+    throw new Error(
+      `Foundry out/ directory not found at ${outDir}. Run \`forge build\` first, with \`ast = true\` and \`extra_output = ["storageLayout"]\` in foundry.toml (or pass \`--ast\` to forge).`
+    );
+  }
+  const files = await walkJson(outDir);
+  const artifacts = [];
+  for (const file of files) {
+    const text = await fs.readFile(file, "utf8");
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    if (!parsed.ast && !parsed.storageLayout) continue;
+    const contractName = extractContractName(file);
+    const sourcePath = extractSourcePath(file, parsed);
+    if (opts.ignoreSourcePath?.(sourcePath)) continue;
+    artifacts.push({
+      contractName,
+      sourcePath,
+      artifactPath: file,
+      storageLayout: parsed.storageLayout ?? null,
+      ast: parsed.ast,
+      bytecodeHash: parsed.bytecode?.object ? parsed.bytecode.object.slice(0, 18) : void 0
+    });
+  }
+  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/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 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_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;
+}
+export {
+  detect,
+  erc7201Slot,
+  loadFoundryArtifacts,
+  parseErc7201Annotation
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "diamond-detect",
+  "version": "0.1.0",
+  "description": "Static analyzer for EIP-2535 Diamond storage-slot collisions across facets",
+  "homepage": "https://github.com/jayeshy14/Diamond-Storage-Detector#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayeshy14/Diamond-Storage-Detector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jayeshy14/Diamond-Storage-Detector/issues"
+  },
+  "keywords": [
+    "solidity",
+    "diamond-proxy",
+    "eip-2535",
+    "eip-7201",
+    "static-analysis",
+    "foundry",
+    "smart-contracts",
+    "security-tools"
+  ],
+  "license": "MIT",
+  "author": "Jayesh Yadav",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "diamond-detect": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "@noble/hashes": "^1.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}