@dropins/mcp 0.1.0

package/dist/operations/check-block-health.js

@@ -0,0 +1,1149 @@
+import { readFileSync, existsSync, readdirSync } from "fs";
+import { join } from "path";
+import { z } from "zod";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+import { projectDirGuard, readBlockFile, readInitializerFile, initializerCandidates, INITIALIZER_ALIASES, } from "../common/project-reader.js";
+const KNOWN_HTML_ATTRIBUTES = new Set([
+    "id",
+    "class",
+    "className",
+    "style",
+    "title",
+    "lang",
+    "dir",
+    "hidden",
+    "tabIndex",
+    "tabindex",
+    "draggable",
+    "spellCheck",
+    "spellcheck",
+    "contentEditable",
+    "contenteditable",
+    "translate",
+    "accessKey",
+    "accesskey",
+    "slot",
+    "part",
+    "exportparts",
+    "is",
+    "itemID",
+    "itemid",
+    "itemProp",
+    "itemprop",
+    "itemRef",
+    "itemref",
+    "itemScope",
+    "itemscope",
+    "itemType",
+    "itemtype",
+    "nonce",
+    "inputMode",
+    "inputmode",
+    "enterKeyHint",
+    "enterkeyhint",
+    "autoCapitalize",
+    "autocapitalize",
+    "autoCorrect",
+    "autocorrect",
+    "autoSave",
+    "autosave",
+    "color",
+    "results",
+    "security",
+    "unselectable",
+    "name",
+    "role",
+    "popover",
+    "popoverTarget",
+    "popoverTargetAction",
+    "inert",
+    "autofocus",
+    "form",
+    "loading",
+    "srcSet",
+    "srcset",
+    "alt",
+    "src",
+    "href",
+    "target",
+    "rel",
+    "width",
+    "height",
+    "placeholder",
+    "value",
+    "checked",
+    "disabled",
+    "readOnly",
+    "readonly",
+    "required",
+    "min",
+    "max",
+    "step",
+    "pattern",
+    "maxLength",
+    "maxlength",
+    "minLength",
+    "minlength",
+    "type",
+    "action",
+    "method",
+    "encType",
+    "enctype",
+    "accept",
+    "multiple",
+    "noValidate",
+    "novalidate",
+    "autoComplete",
+    "autocomplete",
+    "wrap",
+    "rows",
+    "cols",
+    "for",
+    "htmlFor",
+    "open",
+    "defer",
+    "async",
+    "crossOrigin",
+    "crossorigin",
+    "integrity",
+    "media",
+    "sizes",
+    "download",
+    "ref",
+    "key",
+]);
+function isValidHtmlAttribute(prop) {
+    if (KNOWN_HTML_ATTRIBUTES.has(prop))
+        return true;
+    if (prop.startsWith("aria-"))
+        return true;
+    if (prop.startsWith("data-"))
+        return true;
+    if (/^on[A-Z]/.test(prop))
+        return true;
+    return false;
+}
+export const CheckBlockHealthSchema = z.object({
+    projectDir: z
+        .string()
+        .describe("Absolute path to the merchant's AEM project root (e.g. aem-boilerplate-commerce)"),
+    block: z
+        .string()
+        .optional()
+        .describe('Block directory name, e.g. "commerce-cart", "product-details". Omit to scan all blocks that use dropins.'),
+    fix: z
+        .boolean()
+        .optional()
+        .describe("When true, each finding includes a concrete fix suggestion: the closest valid replacement or a removal hint."),
+});
+const REGISTRY_DIR = join(import.meta.dirname ?? new URL(".", import.meta.url).pathname, "..", "registry");
+function loadJson(filename) {
+    const filePath = join(REGISTRY_DIR, filename);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+const BOOT_FUNCTIONS = new Set([
+    "initialize",
+    "setEndpoint",
+    "setFetchGraphQlHeader",
+    "enableLogger",
+]);
+function dropinFromImport(importPath) {
+    const match = importPath.match(/@dropins\/(storefront-[\w-]+)/);
+    return match?.[1] ?? null;
+}
+function extractDropinImports(source) {
+    const results = [];
+    const importRegex = /import\s+(?:(\w+)|(\*\s+as\s+\w+)|\{([^}]+)\})\s+from\s+['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = importRegex.exec(source)) !== null) {
+        const importPath = match[4];
+        const dropin = dropinFromImport(importPath);
+        if (!dropin)
+            continue;
+        const names = [];
+        if (match[1])
+            names.push(match[1]);
+        if (match[2])
+            names.push(match[2].replace(/\*\s+as\s+/, ""));
+        if (match[3]) {
+            match[3].split(",").forEach((n) => {
+                const cleaned = n.trim().split(/\s+as\s+/);
+                if (cleaned[0])
+                    names.push(cleaned[cleaned.length - 1].trim());
+            });
+        }
+        results.push({ dropin, importPath, importedNames: names });
+    }
+    return results;
+}
+function extractBlockUsage(sources) {
+    const combined = sources.join("\n");
+    const imports = extractDropinImports(combined);
+    const detectedDropins = [...new Set(imports.map((i) => i.dropin))];
+    const containers = [];
+    const containerLocalNames = new Map();
+    for (const imp of imports) {
+        if (imp.importPath.includes("/containers/")) {
+            const containerName = imp.importPath
+                .split("/containers/")
+                .pop()
+                ?.replace(".js", "");
+            if (containerName) {
+                containers.push({ dropin: imp.dropin, name: containerName });
+                for (const localName of imp.importedNames) {
+                    containerLocalNames.set(localName, {
+                        dropin: imp.dropin,
+                        name: containerName,
+                    });
+                }
+            }
+        }
+    }
+    const containerProps = [];
+    const slots = [];
+    for (const [localName, { dropin, name }] of containerLocalNames) {
+        const renderRegex = new RegExp(`(?<![\\w$])render\\(\\s*${localName}\\s*,\\s*\\{`, "g");
+        let renderMatch;
+        while ((renderMatch = renderRegex.exec(combined)) !== null) {
+            const startIdx = renderMatch.index + renderMatch[0].length;
+            const propsBlock = extractBalancedBlock(combined, startIdx - 1);
+            if (propsBlock) {
+                extractPropsAndSlots(propsBlock, dropin, name, containerProps, slots);
+            }
+        }
+    }
+    const events = [];
+    const eventRegex = /events\.\s*(?:on|emit)\s*\(\s*['"]([^'"]+)['"]/g;
+    let eventMatch;
+    while ((eventMatch = eventRegex.exec(combined)) !== null) {
+        const eventName = eventMatch[1];
+        const eventDropin = guessDropinFromEventName(eventName, detectedDropins);
+        events.push({ dropin: eventDropin, event: eventName });
+    }
+    const apiFunctions = [];
+    const apiNamespaces = new Map();
+    const starImportRegex = /import\s+\*\s+as\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g;
+    let starMatch;
+    while ((starMatch = starImportRegex.exec(combined)) !== null) {
+        const ns = starMatch[1];
+        const d = dropinFromImport(starMatch[2]);
+        if (d &&
+            (starMatch[2].endsWith("/api.js") || starMatch[2].includes("/api"))) {
+            apiNamespaces.set(ns, d);
+        }
+    }
+    for (const imp of imports) {
+        if (imp.importPath.endsWith("/api.js") || imp.importPath.includes("/api")) {
+            for (const name of imp.importedNames) {
+                if (BOOT_FUNCTIONS.has(name))
+                    continue;
+                if (apiNamespaces.has(name))
+                    continue;
+                apiFunctions.push({ dropin: imp.dropin, fn: name });
+            }
+        }
+    }
+    for (const [ns, dropin] of apiNamespaces) {
+        const nsCallRegex = new RegExp(`(?<![\\w$])${ns}\\.(\\w+)\\s*\\(`, "g");
+        let nsMatch;
+        while ((nsMatch = nsCallRegex.exec(combined)) !== null) {
+            if (BOOT_FUNCTIONS.has(nsMatch[1]))
+                continue;
+            apiFunctions.push({ dropin, fn: nsMatch[1] });
+        }
+    }
+    const toolsComponentProps = [];
+    const toolsImportRegex = /import\s+\{([^}]+)\}\s+from\s+['"]@dropins\/tools\/components(?:\.js)?['"]/g;
+    let toolsMatch;
+    const toolsLocalNames = new Map();
+    while ((toolsMatch = toolsImportRegex.exec(combined)) !== null) {
+        const names = toolsMatch[1].split(",");
+        for (const raw of names) {
+            const parts = raw.trim().split(/\s+as\s+/);
+            const originalName = parts[0].trim();
+            const localName = parts[parts.length - 1].trim();
+            if (originalName === "provider")
+                continue;
+            toolsLocalNames.set(localName, originalName);
+        }
+    }
+    for (const [localName, componentName] of toolsLocalNames) {
+        const renderRegex = new RegExp(`(?<![\\w$])render\\(\\s*${localName}\\s*,\\s*\\{`, "g");
+        let renderHit;
+        while ((renderHit = renderRegex.exec(combined)) !== null) {
+            const startIdx = renderHit.index + renderHit[0].length;
+            const propsBlock = extractBalancedBlock(combined, startIdx - 1);
+            if (propsBlock) {
+                const propNames = extractTopLevelKeys(propsBlock);
+                for (const prop of propNames) {
+                    toolsComponentProps.push({ component: componentName, prop });
+                }
+            }
+        }
+    }
+    return {
+        detectedDropins,
+        containers,
+        containerProps,
+        slots,
+        events,
+        apiFunctions: dedupeBy(apiFunctions, (a) => `${a.dropin}:${a.fn}`),
+        toolsComponentProps: dedupeBy(toolsComponentProps, (a) => `${a.component}:${a.prop}`),
+    };
+}
+function extractBalancedBlock(source, startIdx) {
+    if (source[startIdx] !== "{")
+        return null;
+    let depth = 0;
+    for (let i = startIdx; i < source.length; i++) {
+        if (source[i] === "{")
+            depth++;
+        else if (source[i] === "}") {
+            depth--;
+            if (depth === 0)
+                return source.slice(startIdx + 1, i);
+        }
+    }
+    return null;
+}
+function extractPropsAndSlots(propsBlock, dropin, container, containerProps, slots) {
+    const topKeys = extractTopLevelKeys(propsBlock);
+    for (const key of topKeys) {
+        if (key === "slots") {
+            const slotsRegex = /\bslots\s*:\s*\{/;
+            const slotsMatch = slotsRegex.exec(propsBlock);
+            if (slotsMatch) {
+                const slotsStart = slotsMatch.index + slotsMatch[0].length - 1;
+                const slotsContent = extractBalancedBlock(propsBlock, slotsStart);
+                if (slotsContent) {
+                    const slotNames = extractTopLevelKeys(slotsContent);
+                    for (const slot of slotNames) {
+                        slots.push({ dropin, container, slot });
+                    }
+                }
+            }
+        }
+        else {
+            containerProps.push({ dropin, container, prop: key });
+        }
+    }
+}
+function extractTopLevelKeys(body) {
+    const keys = [];
+    let depth = 0;
+    let expectKey = true;
+    let i = 0;
+    while (i < body.length) {
+        const ch = body[i];
+        if (ch === "'" || ch === '"' || ch === "`") {
+            i++;
+            while (i < body.length && body[i] !== ch) {
+                if (body[i] === "\\")
+                    i++;
+                i++;
+            }
+            i++;
+            continue;
+        }
+        if (ch === "{" || ch === "(" || ch === "[") {
+            depth++;
+            i++;
+            continue;
+        }
+        if (ch === "}" || ch === ")" || ch === "]") {
+            depth--;
+            i++;
+            continue;
+        }
+        if (depth === 0) {
+            if (ch === ",") {
+                expectKey = true;
+                i++;
+                continue;
+            }
+            if (expectKey) {
+                const remaining = body.slice(i);
+                const keyMatch = remaining.match(/^([\w-]+)\s*:/);
+                if (keyMatch) {
+                    keys.push(keyMatch[1]);
+                    i += keyMatch[0].length;
+                    expectKey = false;
+                    continue;
+                }
+                const isWordStart = i === 0 || (!/\w/.test(body[i - 1]) && body[i - 1] !== ".");
+                if (isWordStart) {
+                    const shorthandMatch = remaining.match(/^([a-zA-Z_$][\w]*)(?=\s*[,}])/);
+                    if (shorthandMatch) {
+                        keys.push(shorthandMatch[1]);
+                        i += shorthandMatch[1].length;
+                        continue;
+                    }
+                }
+            }
+        }
+        i++;
+    }
+    return keys;
+}
+function guessDropinFromEventName(eventName, detectedDropins) {
+    const prefix = eventName.split("/")[0];
+    const mapping = {
+        cart: "storefront-cart",
+        checkout: "storefront-checkout",
+        order: "storefront-order",
+        auth: "storefront-auth",
+        account: "storefront-account",
+        pdp: "storefront-pdp",
+        search: "storefront-product-discovery",
+        wishlist: "storefront-wishlist",
+        recommendations: "storefront-recommendations",
+        payment: "storefront-payment-services",
+        personalization: "storefront-personalization",
+    };
+    const mapped = mapping[prefix];
+    if (mapped)
+        return mapped;
+    return "unknown";
+}
+function dedupeBy(arr, key) {
+    const seen = new Set();
+    return arr.filter((item) => {
+        const k = key(item);
+        if (seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    });
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) => Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] =
+                a[i - 1] === b[j - 1]
+                    ? dp[i - 1][j - 1]
+                    : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+function findClosest(name, candidates, threshold = 3) {
+    if (candidates.includes(name))
+        return null;
+    let best = null;
+    let bestDist = Infinity;
+    for (const candidate of candidates) {
+        const dist = levenshtein(name, candidate);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = candidate;
+        }
+    }
+    return bestDist <= threshold ? best : null;
+}
+function findClosestDropin(name, knownDropins) {
+    return findClosest(name, knownDropins, 3);
+}
+function augmentFindingsWithFixes(findings, containerReg, slotReg, eventCatalog, apiReg, toolsComponentsReg) {
+    const toolsComponentMap = buildToolsComponentMap(toolsComponentsReg);
+    return findings.map((f) => {
+        let fix;
+        switch (f.category) {
+            case "dropin": {
+                const knownDropins = containerReg
+                    ? Object.keys(containerReg.dropins)
+                    : [];
+                const suggestion = findClosest(f.what, knownDropins, 3);
+                fix = suggestion
+                    ? {
+                        action: "rename",
+                        suggestion,
+                        hint: `Update all imports: replace "@dropins/${f.what}/..." with "@dropins/${suggestion}/..."`,
+                    }
+                    : {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Remove or replace all imports from "@dropins/${f.what}" — package is not recognised.`,
+                    };
+                break;
+            }
+            case "container": {
+                const dropinData = containerReg?.dropins[f.dropin];
+                const candidates = dropinData?.containers.map((c) => c.name) ?? [];
+                const suggestion = findClosest(f.what, candidates, 4);
+                fix = suggestion
+                    ? {
+                        action: "rename",
+                        suggestion,
+                        hint: `Update import: replace "@dropins/${f.dropin}/containers/${f.what}.js" with "@dropins/${f.dropin}/containers/${suggestion}.js" and rename the local identifier.`,
+                    }
+                    : {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Remove the import for "${f.what}" and its render call — it no longer exists in ${f.dropin}.`,
+                    };
+                break;
+            }
+            case "prop": {
+                const [container, prop] = f.what.split(".");
+                let candidates;
+                if (f.dropin === "tools/components") {
+                    const schema = toolsComponentMap[container];
+                    candidates = schema ? schema.props : [];
+                }
+                else {
+                    const dropinData = containerReg?.dropins[f.dropin];
+                    const containerEntry = dropinData?.containers.find((c) => c.name === container);
+                    candidates = containerEntry ? Object.keys(containerEntry.props) : [];
+                }
+                const suggestion = findClosest(prop, candidates, 4);
+                if (suggestion) {
+                    fix = {
+                        action: "rename",
+                        suggestion,
+                        hint: `In the render call for ${container}: rename prop "${prop}" to "${suggestion}".`,
+                    };
+                }
+                else if (f.severity === "info" &&
+                    f.detail.includes("but exists on")) {
+                    const rightContainer = f.detail.match(/exists on "(\w+)"/)?.[1];
+                    fix = {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Move prop "${prop}" from the ${container} render call to ${rightContainer ?? "the correct container"} — it does not belong to ${container}.`,
+                    };
+                }
+                else {
+                    fix = {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Remove prop "${prop}" from the render call for ${container} — it is not in the current registry.`,
+                    };
+                }
+                break;
+            }
+            case "slot": {
+                const [container, slot] = f.what.split(".");
+                const dropinSlotData = slotReg?.dropins[f.dropin];
+                const containerSlots = dropinSlotData?.containers[container];
+                const candidates = containerSlots?.slots.map((s) => s.name) ?? [];
+                const suggestion = findClosest(slot, candidates, 4);
+                fix = suggestion
+                    ? {
+                        action: "rename",
+                        suggestion,
+                        hint: `In the slots object for ${container}: rename "${slot}" to "${suggestion}".`,
+                    }
+                    : {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Remove slot "${slot}" from the slots object for ${container} — it no longer exists.`,
+                    };
+                break;
+            }
+            case "event": {
+                const allEvents = eventCatalog?.events.map((e) => e.name) ?? [];
+                const suggestion = findClosest(f.what, allEvents, 5);
+                fix = suggestion
+                    ? {
+                        action: "rename",
+                        suggestion,
+                        hint: `Replace '${f.what}' with '${suggestion}' in all events.on/events.emit calls.`,
+                    }
+                    : {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Remove or comment out the handler for '${f.what}' — it is not in the current event registry.`,
+                    };
+                break;
+            }
+            case "api-function": {
+                const dropinData = apiReg?.dropins[f.dropin];
+                const candidates = dropinData?.functions.map((fn) => fn.name) ?? [];
+                const suggestion = findClosest(f.what, candidates, 4);
+                fix = suggestion
+                    ? {
+                        action: "rename",
+                        suggestion,
+                        hint: `Replace ${f.what}() with ${suggestion}() — update the import and all call sites.`,
+                    }
+                    : {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Remove ${f.what} from the import statement and all its call sites — it is not in the current ${f.dropin} API.`,
+                    };
+                break;
+            }
+            case "initializer": {
+                if (f.what.endsWith(":import")) {
+                    fix = {
+                        action: "rename",
+                        suggestion: `@dropins/${f.dropin}/api.js`,
+                        hint: `Update the import to: import { initialize, setEndpoint } from '@dropins/${f.dropin}/api.js';`,
+                    };
+                }
+                else if (f.what.endsWith(":initialize")) {
+                    fix = {
+                        action: "rename",
+                        suggestion: "initializers.mountImmediately(initialize, { ... })",
+                        hint: `Add: import { initialize } from '@dropins/${f.dropin}/api.js'; then call initializers.mountImmediately(initialize, { langDefinitions });`,
+                    };
+                }
+                else if (f.what.endsWith(":setEndpoint")) {
+                    fix = {
+                        action: "rename",
+                        suggestion: "setEndpoint(FETCH_GRAPHQL)",
+                        hint: `Add: import { setEndpoint } from '@dropins/${f.dropin}/api.js'; then call setEndpoint(CORE_FETCH_GRAPHQL) or setEndpoint(CS_FETCH_GRAPHQL).`,
+                    };
+                }
+                else if (f.detail.includes("No initializer file found")) {
+                    const initName = INITIALIZER_ALIASES[f.dropin] ??
+                        f.dropin.replace("storefront-", "");
+                    fix = {
+                        action: "rename",
+                        suggestion: `scripts/initializers/${initName}.js`,
+                        hint: `Create scripts/initializers/${initName}.js with: import { initialize, setEndpoint } from '@dropins/${f.dropin}/api.js'; setEndpoint(CORE_FETCH_GRAPHQL); initializers.mountImmediately(initialize, {});`,
+                    };
+                }
+                else if (f.detail.includes("no block imports")) {
+                    fix = {
+                        action: "remove",
+                        suggestion: null,
+                        hint: `Delete ${f.what} if the dropin is no longer used, or add a block that imports from ${f.dropin}.`,
+                    };
+                }
+                else if (f.detail.includes("does not import from any")) {
+                    fix = {
+                        action: "rename",
+                        suggestion: `@dropins/${f.dropin}/api.js`,
+                        hint: `Add: import { initialize, setEndpoint } from '@dropins/${f.dropin}/api.js';`,
+                    };
+                }
+                break;
+            }
+        }
+        return fix ? { ...f, fix } : f;
+    });
+}
+function loadRegistries() {
+    return {
+        containerReg: loadJson("containers.json"),
+        slotReg: loadJson("slots.json"),
+        eventCatalog: loadJson("events.json"),
+        apiReg: loadJson("api-functions.json"),
+        toolsComponentsReg: loadJson("tools-components.json"),
+    };
+}
+function buildToolsComponentMap(reg) {
+    const map = {};
+    if (!reg)
+        return map;
+    for (const c of reg.components) {
+        map[c.name] = {
+            props: c.props,
+            extendsHTMLAttributes: c.extendsHTMLAttributes,
+        };
+    }
+    return map;
+}
+function compareAgainstRegistry(usage, regs) {
+    const findings = [];
+    const { containerReg, slotReg, eventCatalog, apiReg, toolsComponentsReg } = regs;
+    const toolsComponentMap = buildToolsComponentMap(toolsComponentsReg);
+    const knownDropins = containerReg ? Object.keys(containerReg.dropins) : [];
+    if (containerReg) {
+        const checkedDropins = new Set();
+        for (const { dropin } of usage.detectedDropins.map((d) => ({
+            dropin: d,
+        }))) {
+            if (checkedDropins.has(dropin))
+                continue;
+            checkedDropins.add(dropin);
+            if (!(dropin in containerReg.dropins)) {
+                const suggestion = findClosestDropin(dropin, knownDropins);
+                findings.push({
+                    severity: "error",
+                    category: "dropin",
+                    dropin,
+                    what: dropin,
+                    detail: suggestion
+                        ? `Dropin "@dropins/${dropin}" is not recognised — did you mean "@dropins/${suggestion}"? Check the import path for a typo.`
+                        : `Dropin "@dropins/${dropin}" is not recognised. Verify the package name matches an installed @dropins package.`,
+                });
+            }
+        }
+    }
+    if (containerReg) {
+        for (const { dropin, name } of usage.containers) {
+            const dropinData = containerReg.dropins[dropin];
+            if (!dropinData)
+                continue;
+            const exists = dropinData.containers.some((c) => c.name === name);
+            if (!exists) {
+                findings.push({
+                    severity: "error",
+                    category: "container",
+                    dropin,
+                    what: name,
+                    detail: `Container "${name}" is not found in the current ${dropin} registry. It may have been removed or renamed.`,
+                });
+            }
+        }
+        for (const { dropin, container, prop } of usage.containerProps) {
+            const dropinData = containerReg.dropins[dropin];
+            if (!dropinData)
+                continue;
+            const containerEntry = dropinData.containers.find((c) => c.name === container);
+            if (!containerEntry)
+                continue;
+            const propExists = Object.keys(containerEntry.props).includes(prop) || prop === "slots";
+            if (!propExists) {
+                if (containerEntry.extendsHTMLAttributes && isValidHtmlAttribute(prop))
+                    continue;
+                const dropinContainers = containerReg.dropins[dropin]?.containers ?? [];
+                const otherContainer = dropinContainers.find((c) => c.name !== container && Object.keys(c.props).includes(prop));
+                if (otherContainer) {
+                    findings.push({
+                        severity: "info",
+                        category: "prop",
+                        dropin,
+                        what: `${container}.${prop}`,
+                        detail: `Prop "${prop}" is not on container "${container}" but exists on "${otherContainer.name}" in ${dropin}. It may be passed to the wrong container.`,
+                    });
+                }
+                else {
+                    const htmlNote = containerEntry.extendsHTMLAttributes
+                        ? ` "${container}" extends HTMLAttributes but "${prop}" is not a recognised HTML attribute — it will be silently ignored at runtime.`
+                        : "";
+                    findings.push({
+                        severity: "warning",
+                        category: "prop",
+                        dropin,
+                        what: `${container}.${prop}`,
+                        detail: `Prop "${prop}" on container "${container}" is not found in the current ${dropin} registry. It may have been removed, renamed, or is undocumented.${htmlNote}`,
+                    });
+                }
+            }
+        }
+    }
+    for (const { component, prop } of usage.toolsComponentProps) {
+        const schema = toolsComponentMap[component];
+        if (!schema)
+            continue;
+        if (schema.props.includes(prop))
+            continue;
+        if (schema.extendsHTMLAttributes && isValidHtmlAttribute(prop))
+            continue;
+        const htmlNote = schema.extendsHTMLAttributes
+            ? ` "${component}" extends HTMLAttributes but "${prop}" is not a recognised HTML attribute — it will be silently ignored at runtime.`
+            : "";
+        findings.push({
+            severity: "warning",
+            category: "prop",
+            dropin: "tools/components",
+            what: `${component}.${prop}`,
+            detail: `Prop "${prop}" on UI component "${component}" (@dropins/tools/components.js) is not a known prop.${htmlNote}`,
+        });
+    }
+    if (slotReg) {
+        for (const { dropin, container, slot } of usage.slots) {
+            const dropinData = slotReg.dropins[dropin];
+            if (!dropinData)
+                continue;
+            const containerSlots = dropinData.containers[container];
+            if (!containerSlots)
+                continue;
+            const slotExists = containerSlots.slots.some((s) => s.name === slot);
+            if (!slotExists) {
+                findings.push({
+                    severity: "error",
+                    category: "slot",
+                    dropin,
+                    what: `${container}.${slot}`,
+                    detail: `Slot "${slot}" on container "${container}" is not found in the current ${dropin} registry. It may have been removed or renamed.`,
+                });
+            }
+        }
+    }
+    if (eventCatalog) {
+        const registryEventNames = new Set(eventCatalog.events.map((e) => e.name));
+        for (const { dropin, event } of usage.events) {
+            if (!registryEventNames.has(event)) {
+                findings.push({
+                    severity: "error",
+                    category: "event",
+                    dropin,
+                    what: event,
+                    detail: `Event "${event}" is not found in the current registry. It may have been removed or renamed.`,
+                });
+            }
+        }
+    }
+    if (apiReg) {
+        for (const { dropin, fn } of usage.apiFunctions) {
+            const dropinData = apiReg.dropins[dropin];
+            if (!dropinData)
+                continue;
+            const fnExists = dropinData.functions.some((f) => f.name === fn);
+            if (!fnExists) {
+                const isShared = fn in (apiReg.sharedFunctions ?? {});
+                if (!isShared) {
+                    findings.push({
+                        severity: "error",
+                        category: "api-function",
+                        dropin,
+                        what: fn,
+                        detail: `API function "${fn}" is not found in the current ${dropin} registry. It may have been removed or renamed.`,
+                    });
+                }
+            }
+        }
+    }
+    return findings;
+}
+function collectBlockSources(projectDir, blockName, mainSource, detectedDropins) {
+    const sources = [mainSource];
+    const fileList = [`blocks/${blockName}/${blockName}.js`];
+    const blockDir = join(projectDir, "blocks", blockName);
+    if (existsSync(blockDir)) {
+        try {
+            for (const file of readdirSync(blockDir)) {
+                if (file.endsWith(".js") &&
+                    file !== `${blockName}.js` &&
+                    !file.endsWith(".test.js")) {
+                    const content = readFileSync(join(blockDir, file), "utf8");
+                    sources.push(content);
+                    fileList.push(`blocks/${blockName}/${file}`);
+                }
+            }
+        }
+        catch {
+        }
+    }
+    const initDir = join(projectDir, "scripts", "initializers");
+    for (const dropin of detectedDropins) {
+        const initContent = readInitializerFile(projectDir, dropin);
+        if (initContent) {
+            fileList.push(resolveInitializerPath(initDir, dropin));
+            sources.push(initContent);
+        }
+    }
+    return { sources, fileList };
+}
+function resolveInitializerPath(initDir, dropinName) {
+    for (const candidate of initializerCandidates(dropinName)) {
+        if (existsSync(join(initDir, candidate))) {
+            return `scripts/initializers/${candidate}`;
+        }
+    }
+    const shortName = dropinName.replace("storefront-", "");
+    return `scripts/initializers/${shortName}.js`;
+}
+function checkInitializerHealth(projectDir, usedDropins, regs, fix) {
+    const initDir = join(projectDir, "scripts", "initializers");
+    const reports = [];
+    const findings = [];
+    const knownDropins = regs.containerReg
+        ? Object.keys(regs.containerReg.dropins)
+        : [];
+    for (const dropin of usedDropins) {
+        const shortName = dropin.replace("storefront-", "");
+        const content = readInitializerFile(projectDir, dropin);
+        if (!content) {
+            findings.push({
+                severity: "warning",
+                category: "initializer",
+                dropin,
+                what: `scripts/initializers/${shortName}.js`,
+                detail: `No initializer file found for ${dropin}. Blocks import from this dropin but it has no initializer to call setEndpoint/initialize.`,
+            });
+            continue;
+        }
+        const filePath = resolveInitializerPath(initDir, dropin);
+        const fileFindings = [];
+        const namedImportRegex = /import\s+\{[^}]*\}\s+from\s+['"]@dropins\/(storefront-[\w-]+)\/api(?:\.js)?['"]/g;
+        const nsImportRegex = /import\s+\*\s+as\s+(\w+)\s+from\s+['"]@dropins\/(storefront-[\w-]+)\/api(?:\.js)?['"]/g;
+        const importedDropins = [];
+        const nsAliases = [];
+        for (const m of content.matchAll(namedImportRegex)) {
+            importedDropins.push(m[1]);
+        }
+        for (const m of content.matchAll(nsImportRegex)) {
+            importedDropins.push(m[2]);
+            nsAliases.push(m[1]);
+        }
+        if (importedDropins.length === 0) {
+            fileFindings.push({
+                severity: "warning",
+                category: "initializer",
+                dropin,
+                what: filePath,
+                detail: `Initializer "${filePath}" does not import from any @dropins/*/api module. Expected an import from "@dropins/${dropin}/api.js".`,
+            });
+        }
+        else if (!importedDropins.includes(dropin)) {
+            const actual = importedDropins[0];
+            fileFindings.push({
+                severity: "error",
+                category: "initializer",
+                dropin,
+                what: `${filePath}:import`,
+                detail: `Initializer "${filePath}" imports from "@dropins/${actual}/api.js" but should import from "@dropins/${dropin}/api.js".`,
+            });
+        }
+        const mountImmediatelyBare = /\binitializers\s*\.\s*mountImmediately\s*\(\s*initialize\b/.test(content);
+        const mountImmediatelyNs = nsAliases.some((ns) => new RegExp(`\\binitializers\\s*\\.\\s*mountImmediately\\s*\\(\\s*${ns}\\.initialize\\b`).test(content));
+        const hasMountImmediately = mountImmediatelyBare || mountImmediatelyNs;
+        const hasRawInitialize = !hasMountImmediately && /\binitialize\s*\(/.test(content);
+        if (!hasMountImmediately && !hasRawInitialize) {
+            fileFindings.push({
+                severity: "error",
+                category: "initializer",
+                dropin,
+                what: `${filePath}:initialize`,
+                detail: `Initializer "${filePath}" does not call initialize(). The dropin will not start. Expected: initializers.mountImmediately(initialize, { ... })`,
+            });
+        }
+        else if (hasRawInitialize) {
+            fileFindings.push({
+                severity: "warning",
+                category: "initializer",
+                dropin,
+                what: `${filePath}:initialize`,
+                detail: `Initializer "${filePath}" calls initialize() directly instead of initializers.mountImmediately(initialize, { ... }). The dropin may not integrate correctly with the framework lifecycle.`,
+            });
+        }
+        const hasSetEndpoint = /\bsetEndpoint\s*\(/.test(content);
+        if (!hasSetEndpoint && nsAliases.length === 0) {
+            fileFindings.push({
+                severity: "warning",
+                category: "initializer",
+                dropin,
+                what: `${filePath}:setEndpoint`,
+                detail: `Initializer "${filePath}" does not call setEndpoint(). The dropin may not reach the correct GraphQL backend.`,
+            });
+        }
+        reports.push({ file: filePath, dropin, findings: fileFindings });
+        findings.push(...fileFindings);
+    }
+    const reverseAliases = new Map();
+    for (const [dropin, alias] of Object.entries(INITIALIZER_ALIASES)) {
+        reverseAliases.set(alias, dropin);
+    }
+    const claimedFiles = new Set();
+    for (const d of usedDropins) {
+        for (const c of initializerCandidates(d)) {
+            claimedFiles.add(c);
+        }
+    }
+    if (existsSync(initDir)) {
+        try {
+            const files = readdirSync(initDir).filter((f) => f.endsWith(".js") && f !== "index.js");
+            for (const file of files) {
+                if (claimedFiles.has(file))
+                    continue;
+                const name = file.replace(".js", "");
+                const dropinName = reverseAliases.get(name) ??
+                    (name.startsWith("storefront-") ? name : `storefront-${name}`);
+                const filePath = join(initDir, file);
+                let content;
+                try {
+                    content = readFileSync(filePath, "utf8");
+                }
+                catch {
+                    continue;
+                }
+                const hasDropinImport = /@dropins\/storefront-/.test(content);
+                if (hasDropinImport) {
+                    findings.push({
+                        severity: "info",
+                        category: "initializer",
+                        dropin: dropinName,
+                        what: `scripts/initializers/${file}`,
+                        detail: `Initializer "${file}" references ${dropinName} but no block imports from this dropin. It may be unused or the block has been removed.`,
+                    });
+                }
+            }
+        }
+        catch {
+        }
+    }
+    if (fix) {
+        return {
+            reports,
+            findings: augmentFindingsWithFixes(findings, regs.containerReg, regs.slotReg, regs.eventCatalog, regs.apiReg, regs.toolsComponentsReg),
+        };
+    }
+    return { reports, findings };
+}
+async function checkSingleBlock(projectDir, blockName, regs, fix) {
+    const mainSource = readBlockFile(projectDir, blockName);
+    if (!mainSource)
+        return null;
+    const quickImports = extractDropinImports(mainSource);
+    const hasToolsComponents = mainSource.includes("@dropins/tools/components");
+    if (quickImports.length === 0 && !hasToolsComponents)
+        return null;
+    const detectedDropins = [...new Set(quickImports.map((i) => i.dropin))];
+    const { sources, fileList } = collectBlockSources(projectDir, blockName, mainSource, detectedDropins);
+    const usage = extractBlockUsage(sources);
+    let findings = compareAgainstRegistry(usage, regs);
+    if (fix) {
+        findings = augmentFindingsWithFixes(findings, regs.containerReg, regs.slotReg, regs.eventCatalog, regs.apiReg, regs.toolsComponentsReg);
+    }
+    const errors = findings.filter((f) => f.severity === "error");
+    const warnings = findings.filter((f) => f.severity === "warning");
+    return {
+        block: blockName,
+        healthy: errors.length === 0 && warnings.length === 0,
+        filesAnalyzed: fileList,
+        detectedDropins: usage.detectedDropins,
+        summary: {
+            containersUsed: usage.containers.length,
+            eventsSubscribed: usage.events.length,
+            apiFunctionsUsed: usage.apiFunctions.length,
+            slotsConfigured: usage.slots.length,
+            errors: errors.length,
+            warnings: warnings.length,
+        },
+        findings,
+    };
+}
+async function scanAllBlocks(projectDir, fix) {
+    const regs = loadRegistries();
+    const allBlocks = listAvailableBlocks(projectDir);
+    const results = [];
+    let totalErrors = 0;
+    let totalWarnings = 0;
+    for (const blockName of allBlocks) {
+        const result = await checkSingleBlock(projectDir, blockName, regs, fix);
+        if (!result)
+            continue;
+        results.push(result);
+        totalErrors += result.summary.errors;
+        totalWarnings += result.summary.warnings;
+    }
+    const allUsedDropins = [
+        ...new Set(results.flatMap((r) => r.detectedDropins)),
+    ];
+    const initHealth = checkInitializerHealth(projectDir, allUsedDropins, regs, fix);
+    const initErrors = initHealth.findings.filter((f) => f.severity === "error").length;
+    const initWarnings = initHealth.findings.filter((f) => f.severity === "warning").length;
+    totalErrors += initErrors;
+    totalWarnings += initWarnings;
+    const healthy = results.filter((r) => r.healthy);
+    const unhealthy = results.filter((r) => !r.healthy);
+    const hasInitIssues = initErrors > 0 || initWarnings > 0;
+    const allHealthy = unhealthy.length === 0 && !hasInitIssues;
+    const parts = [];
+    if (unhealthy.length > 0) {
+        parts.push(`${unhealthy.length} of ${results.length} dropin block(s) have issues`);
+    }
+    if (hasInitIssues) {
+        parts.push(`${initHealth.findings.length} initializer finding(s)`);
+    }
+    const message = allHealthy
+        ? `All ${results.length} dropin block(s) and initializers are healthy.`
+        : `${parts.join("; ")} (${totalErrors} error(s), ${totalWarnings} warning(s)).`;
+    return formatSuccessResponse(message, {
+        scanned: results.length,
+        allHealthy,
+        summary: {
+            healthy: healthy.length,
+            unhealthy: unhealthy.length,
+            totalErrors,
+            totalWarnings,
+        },
+        blocks: results,
+        initializers: {
+            checked: allUsedDropins.length,
+            findings: initHealth.findings,
+            reports: initHealth.reports,
+        },
+    });
+}
+export async function checkBlockHealth(params) {
+    try {
+        const guard = projectDirGuard(params.projectDir);
+        if (guard)
+            return guard;
+        const fix = params.fix ?? false;
+        if (!params.block) {
+            return scanAllBlocks(params.projectDir, fix);
+        }
+        const mainSource = readBlockFile(params.projectDir, params.block);
+        if (!mainSource) {
+            const blockDir = join(params.projectDir, "blocks", params.block);
+            return formatSuccessResponse(existsSync(blockDir)
+                ? `Block "${params.block}" has no JS file`
+                : `Block "${params.block}" not found in ${params.projectDir}/blocks/`, {
+                error: existsSync(blockDir)
+                    ? `blocks/${params.block}/${params.block}.js not found`
+                    : `Block directory does not exist: blocks/${params.block}/`,
+                availableBlocks: listAvailableBlocks(params.projectDir),
+            });
+        }
+        const quickImports = extractDropinImports(mainSource);
+        const detectedDropins = [...new Set(quickImports.map((i) => i.dropin))];
+        const { sources, fileList } = collectBlockSources(params.projectDir, params.block, mainSource, detectedDropins);
+        const usage = extractBlockUsage(sources);
+        const regs = loadRegistries();
+        let findings = compareAgainstRegistry(usage, regs);
+        if (fix) {
+            findings = augmentFindingsWithFixes(findings, regs.containerReg, regs.slotReg, regs.eventCatalog, regs.apiReg, regs.toolsComponentsReg);
+        }
+        const errors = findings.filter((f) => f.severity === "error");
+        const warnings = findings.filter((f) => f.severity === "warning");
+        const healthy = errors.length === 0 && warnings.length === 0;
+        return formatSuccessResponse(healthy
+            ? `Block "${params.block}" is healthy — all usage matches the current registry.`
+            : `Block "${params.block}" has ${errors.length} error(s) and ${warnings.length} warning(s).`, {
+            block: params.block,
+            healthy,
+            filesAnalyzed: fileList,
+            detectedDropins: usage.detectedDropins,
+            summary: {
+                containersUsed: usage.containers.length,
+                eventsSubscribed: usage.events.length,
+                apiFunctionsUsed: usage.apiFunctions.length,
+                slotsConfigured: usage.slots.length,
+                errors: errors.length,
+                warnings: warnings.length,
+            },
+            findings,
+            usage: {
+                containers: usage.containers,
+                containerProps: usage.containerProps,
+                slots: usage.slots,
+                events: usage.events,
+                apiFunctions: usage.apiFunctions,
+            },
+        });
+    }
+    catch (error) {
+        return formatExceptionResponse(error, "check_block_health");
+    }
+}
+function listAvailableBlocks(projectDir) {
+    const blocksDir = join(projectDir, "blocks");
+    if (!existsSync(blocksDir))
+        return [];
+    try {
+        return readdirSync(blocksDir).filter((name) => {
+            const jsFile = join(blocksDir, name, `${name}.js`);
+            return existsSync(jsFile);
+        });
+    }
+    catch {
+        return [];
+    }
+}