whale-igniter 1.1.0

package/dist/scanner/componentScanner.js

@@ -0,0 +1,522 @@
+import fs from "fs-extra";
+import path from "node:path";
+import { glob } from "glob";
+import { parse } from "@babel/parser";
+import * as t from "@babel/types";
+const DEFAULT_GLOB = "src/**/*.{tsx,jsx}";
+const DEFAULT_IGNORE = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/coverage/**",
+    "**/*.test.{tsx,jsx}",
+    "**/*.spec.{tsx,jsx}",
+    "**/*.stories.{tsx,jsx}"
+];
+/**
+ * Heuristics used to decide whether a `PascalCase` identifier is a component:
+ *
+ * - Must contain JSX in its body (we walk the function/class body and look
+ *   for any JSXElement). This is the strongest signal and rules out hooks
+ *   like `useFoo` (lowercase anyway) and utility classes like `EventBus`.
+ * - Filename pattern matters: files in `/hooks/`, `/utils/`, `/lib/`,
+ *   `/context/` are deprioritised even if they have PascalCase exports.
+ * - Identifier name must start with uppercase ASCII letter (React rule).
+ *
+ * Returning early via `false` keeps the scanner conservative; the v0.8
+ * done criterion explicitly says zero false positives in fixtures.
+ */
+/**
+ * Identifiers that look like components but are almost always project
+ * entry points, not reusable components. We exclude them from the
+ * catalog by default. Users who really want them can add manually
+ * with `whale component add`.
+ */
+const ENTRY_POINT_NAMES = new Set([
+    "App", "Root", "Main", "Index", "Layout", "Page", "Document", "RootLayout",
+    "ErrorBoundary", "Providers", "Provider"
+]);
+function isLikelyComponentName(name) {
+    if (!/^[A-Z][A-Za-z0-9]*$/.test(name))
+        return false;
+    if (ENTRY_POINT_NAMES.has(name))
+        return false;
+    return true;
+}
+function fileLooksLikeUtility(file) {
+    const normalized = file.replace(/\\/g, "/").toLowerCase();
+    return (/\/hooks?\//.test(normalized) ||
+        /\/utils?\//.test(normalized) ||
+        /\/lib\//.test(normalized) ||
+        /\/context\//.test(normalized) ||
+        /\/contexts\//.test(normalized) ||
+        /\/types?\//.test(normalized) ||
+        /\.types\.(t|j)sx?$/.test(normalized));
+}
+/**
+ * Walks an arbitrary AST node and returns true if it contains JSX. We use
+ * this instead of `path.traverse` because we sometimes need to inspect
+ * standalone expressions (default export of an arrow, for example).
+ */
+function containsJsx(node) {
+    if (!node)
+        return false;
+    // Manual stack walk. @babel/traverse needs a File/NodePath context that
+    // we don't always have for standalone subtrees (e.g. an arrow body),
+    // so we walk children ourselves. This is fast enough for v0.8 — each
+    // component body is small.
+    const stack = [node];
+    while (stack.length) {
+        const cur = stack.pop();
+        if (t.isJSXElement(cur) || t.isJSXFragment(cur))
+            return true;
+        for (const key of Object.keys(cur)) {
+            const child = cur[key];
+            if (!child)
+                continue;
+            if (Array.isArray(child)) {
+                for (const c of child)
+                    if (c && typeof c.type === "string")
+                        stack.push(c);
+            }
+            else if (typeof child.type === "string") {
+                stack.push(child);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Heuristic: does a string look like a Tailwind class list?
+ *
+ * Used to opportunistically capture classes that live in `const base = "..."`
+ * variables outside the JSX. We can't statically resolve template literals
+ * like `${base} ${variants[v]}` without scope analysis, so we accept some
+ * over-capture in exchange for not silently dropping all the styling.
+ *
+ * A string qualifies if it has at least two whitespace-separated tokens
+ * AND at least one of them matches a known Tailwind shape (prefix-suffix,
+ * arbitrary value, or variant:prefix-suffix).
+ */
+function looksLikeClassList(s) {
+    if (!s || s.length < 4)
+        return false;
+    const tokens = s.trim().split(/\s+/);
+    if (tokens.length < 2)
+        return false;
+    const tailwindish = /^(?:[a-z]+:)*-?[a-z]+(?:-[a-z0-9]+)*(?:\[[^\]]+\])?(?:\/\d+)?$/i;
+    let matched = 0;
+    for (const tok of tokens) {
+        if (tailwindish.test(tok))
+            matched += 1;
+        if (matched >= 2)
+            return true;
+    }
+    return false;
+}
+/**
+ * Pull every literal class string out of a component subtree. We currently
+ * support:
+ *   - `className="..."`              (StringLiteral)
+ *   - `className={"..."}`            (StringLiteral inside JSXExpressionContainer)
+ *   - `className={`...`}`            (template literal — static fragments)
+ *   - `const x = "..."`              (any string in the body that looks like a class list)
+ *
+ * The last one is a heuristic — see `looksLikeClassList`. Without it,
+ * components that compose classes via local variables (a very common
+ * Tailwind pattern) would have most of their styling invisible to us.
+ */
+function extractClassNamesFromComponent(node) {
+    const out = [];
+    const seen = new Set();
+    const push = (s) => {
+        const v = s.trim();
+        if (!v || seen.has(v))
+            return;
+        seen.add(v);
+        out.push(v);
+    };
+    const stack = [node];
+    while (stack.length) {
+        const cur = stack.pop();
+        // Direct className attributes — high confidence.
+        if (t.isJSXAttribute(cur) && t.isJSXIdentifier(cur.name) && cur.name.name === "className") {
+            const value = cur.value;
+            if (value && t.isStringLiteral(value)) {
+                push(value.value);
+            }
+            else if (value && t.isJSXExpressionContainer(value)) {
+                const expr = value.expression;
+                if (t.isStringLiteral(expr)) {
+                    push(expr.value);
+                }
+                else if (t.isTemplateLiteral(expr)) {
+                    // Static fragments only. We rely on the body-level string sweep
+                    // below to capture the interpolated variables.
+                    for (const q of expr.quasis)
+                        push(q.value.cooked ?? q.value.raw);
+                }
+            }
+        }
+        // Body-level string literals that look like class lists.
+        if (t.isStringLiteral(cur) && looksLikeClassList(cur.value)) {
+            push(cur.value);
+        }
+        for (const key of Object.keys(cur)) {
+            const child = cur[key];
+            if (!child)
+                continue;
+            if (Array.isArray(child)) {
+                for (const c of child)
+                    if (c && typeof c.type === "string")
+                        stack.push(c);
+            }
+            else if (typeof child.type === "string") {
+                stack.push(child);
+            }
+        }
+    }
+    return out;
+}
+function extractJsxIdentifiers(node) {
+    const seen = new Set();
+    const stack = [node];
+    while (stack.length) {
+        const cur = stack.pop();
+        if (t.isJSXOpeningElement(cur)) {
+            const name = cur.name;
+            if (t.isJSXIdentifier(name) && /^[A-Z]/.test(name.name)) {
+                seen.add(name.name);
+            }
+            else if (t.isJSXMemberExpression(name)) {
+                // e.g. <Form.Field> — record the root identifier
+                let head = name;
+                while (t.isJSXMemberExpression(head))
+                    head = head.object;
+                if (t.isJSXIdentifier(head) && /^[A-Z]/.test(head.name))
+                    seen.add(head.name);
+            }
+        }
+        for (const key of Object.keys(cur)) {
+            const child = cur[key];
+            if (!child)
+                continue;
+            if (Array.isArray(child)) {
+                for (const c of child)
+                    if (c && typeof c.type === "string")
+                        stack.push(c);
+            }
+            else if (typeof child.type === "string") {
+                stack.push(child);
+            }
+        }
+    }
+    return Array.from(seen);
+}
+async function scanFile(absPath, relPath) {
+    let source;
+    try {
+        source = await fs.readFile(absPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let ast;
+    try {
+        ast = parse(source, {
+            sourceType: "module",
+            plugins: ["typescript", "jsx", "decorators-legacy"],
+            errorRecovery: true
+        });
+    }
+    catch {
+        // Skip files we can't parse — common with experimental syntax or non-standard plugins.
+        return [];
+    }
+    const found = [];
+    const isUtilityFile = fileLooksLikeUtility(relPath);
+    const candidates = [];
+    const bindings = new Map();
+    const recordBinding = (name, init) => {
+        if (t.isArrowFunctionExpression(init) || t.isFunctionExpression(init)) {
+            bindings.set(name, { name, declarationKind: "arrow", bodyNode: init.body });
+            return;
+        }
+        if (t.isCallExpression(init)) {
+            const callee = init.callee;
+            const calleeName = (t.isIdentifier(callee) && callee.name) ||
+                (t.isMemberExpression(callee) && t.isIdentifier(callee.property) && callee.property.name) ||
+                null;
+            if (calleeName === "forwardRef" || calleeName === "memo") {
+                const inner = init.arguments[0];
+                if (inner && (t.isArrowFunctionExpression(inner) || t.isFunctionExpression(inner))) {
+                    bindings.set(name, {
+                        name,
+                        declarationKind: calleeName === "forwardRef" ? "forwardRef" : "memo",
+                        bodyNode: inner.body
+                    });
+                }
+            }
+        }
+    };
+    for (const node of ast.program.body) {
+        if (t.isVariableDeclaration(node)) {
+            for (const d of node.declarations) {
+                if (t.isIdentifier(d.id) && d.init)
+                    recordBinding(d.id.name, d.init);
+            }
+        }
+        else if (t.isFunctionDeclaration(node) && node.id) {
+            bindings.set(node.id.name, { name: node.id.name, declarationKind: "function", bodyNode: node.body });
+        }
+        else if (t.isClassDeclaration(node) && node.id) {
+            bindings.set(node.id.name, { name: node.id.name, declarationKind: "class", bodyNode: node.body });
+        }
+    }
+    for (const node of ast.program.body) {
+        // export default function Foo() {...}
+        // export default () => ...
+        // export default Foo                       <- new: resolves via bindings
+        if (t.isExportDefaultDeclaration(node)) {
+            const decl = node.declaration;
+            if (t.isFunctionDeclaration(decl) && decl.id) {
+                candidates.push({
+                    name: decl.id.name,
+                    declarationKind: "function",
+                    bodyNode: decl.body,
+                    isExported: true,
+                    isDefault: true
+                });
+            }
+            else if (t.isArrowFunctionExpression(decl) || t.isFunctionExpression(decl)) {
+                // Anonymous default — use the file's basename as the name.
+                const base = path.basename(relPath).replace(/\.[jt]sx$/, "");
+                if (isLikelyComponentName(base)) {
+                    candidates.push({
+                        name: base,
+                        declarationKind: "arrow",
+                        bodyNode: decl.body,
+                        isExported: true,
+                        isDefault: true
+                    });
+                }
+            }
+            else if (t.isClassDeclaration(decl) && decl.id) {
+                candidates.push({
+                    name: decl.id.name,
+                    declarationKind: "class",
+                    bodyNode: decl.body,
+                    isExported: true,
+                    isDefault: true
+                });
+            }
+            else if (t.isIdentifier(decl)) {
+                // `export default Foo` — resolve via earlier bindings.
+                const binding = bindings.get(decl.name);
+                if (binding) {
+                    candidates.push({
+                        name: binding.name,
+                        declarationKind: binding.declarationKind,
+                        bodyNode: binding.bodyNode,
+                        isExported: true,
+                        isDefault: true
+                    });
+                }
+            }
+            else if (t.isCallExpression(decl)) {
+                // export default forwardRef(...) / memo(...)
+                const callee = decl.callee;
+                const calleeName = (t.isIdentifier(callee) && callee.name) ||
+                    (t.isMemberExpression(callee) && t.isIdentifier(callee.property) && callee.property.name) ||
+                    null;
+                if (calleeName === "forwardRef" || calleeName === "memo") {
+                    const inner = decl.arguments[0];
+                    if (inner &&
+                        (t.isArrowFunctionExpression(inner) || t.isFunctionExpression(inner)) &&
+                        inner.body) {
+                        const base = path.basename(relPath).replace(/\.[jt]sx$/, "");
+                        if (isLikelyComponentName(base)) {
+                            candidates.push({
+                                name: base,
+                                declarationKind: calleeName === "forwardRef" ? "forwardRef" : "memo",
+                                bodyNode: inner.body,
+                                isExported: true,
+                                isDefault: true
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // export function Foo() {...}
+        // export const Foo = () => {...}
+        // export const Foo = forwardRef(...) / memo(...)
+        if (t.isExportNamedDeclaration(node) && node.declaration) {
+            const decl = node.declaration;
+            if (t.isFunctionDeclaration(decl) && decl.id) {
+                candidates.push({
+                    name: decl.id.name,
+                    declarationKind: "function",
+                    bodyNode: decl.body,
+                    isExported: true,
+                    isDefault: false
+                });
+            }
+            else if (t.isVariableDeclaration(decl)) {
+                for (const d of decl.declarations) {
+                    if (!t.isIdentifier(d.id))
+                        continue;
+                    const init = d.init;
+                    if (!init)
+                        continue;
+                    if (t.isArrowFunctionExpression(init) || t.isFunctionExpression(init)) {
+                        candidates.push({
+                            name: d.id.name,
+                            declarationKind: "arrow",
+                            bodyNode: init.body,
+                            isExported: true,
+                            isDefault: false
+                        });
+                    }
+                    else if (t.isCallExpression(init)) {
+                        const callee = init.callee;
+                        const calleeName = (t.isIdentifier(callee) && callee.name) ||
+                            (t.isMemberExpression(callee) && t.isIdentifier(callee.property) && callee.property.name) ||
+                            null;
+                        if (calleeName === "forwardRef" || calleeName === "memo") {
+                            const inner = init.arguments[0];
+                            if (inner &&
+                                (t.isArrowFunctionExpression(inner) || t.isFunctionExpression(inner))) {
+                                candidates.push({
+                                    name: d.id.name,
+                                    declarationKind: calleeName === "forwardRef" ? "forwardRef" : "memo",
+                                    bodyNode: inner.body,
+                                    isExported: true,
+                                    isDefault: false
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            else if (t.isClassDeclaration(decl) && decl.id) {
+                candidates.push({
+                    name: decl.id.name,
+                    declarationKind: "class",
+                    bodyNode: decl.body,
+                    isExported: true,
+                    isDefault: false
+                });
+            }
+        }
+    }
+    /**
+     * Collect class-list-looking string literals at the module top level.
+     *
+     * Why: a common Tailwind pattern is to declare base classes as constants
+     * outside the component body:
+     *
+     *   const baseClasses = "px-4 py-2 rounded-md ...";
+     *   export function Button() { return <button className={baseClasses}/> }
+     *
+     * The per-component extractor only walks the body, so without this pass
+     * we'd miss the most important classes in the file. We collect them
+     * once per module and union them into every component's classNames.
+     */
+    function collectModuleLevelClassStrings(programBody) {
+        const out = [];
+        const seen = new Set();
+        for (const node of programBody) {
+            if (!t.isVariableDeclaration(node))
+                continue;
+            for (const d of node.declarations) {
+                if (!d.init)
+                    continue;
+                // const x = "...";
+                if (t.isStringLiteral(d.init) && looksLikeClassList(d.init.value)) {
+                    if (!seen.has(d.init.value)) {
+                        seen.add(d.init.value);
+                        out.push(d.init.value);
+                    }
+                    continue;
+                }
+                // const variantClasses = { primary: "...", secondary: "..." }
+                if (t.isObjectExpression(d.init)) {
+                    for (const prop of d.init.properties) {
+                        if (!t.isObjectProperty(prop))
+                            continue;
+                        if (t.isStringLiteral(prop.value) && looksLikeClassList(prop.value.value)) {
+                            if (!seen.has(prop.value.value)) {
+                                seen.add(prop.value.value);
+                                out.push(prop.value.value);
+                            }
+                        }
+                    }
+                }
+                // const x = `template ${y} parts`
+                if (t.isTemplateLiteral(d.init)) {
+                    for (const q of d.init.quasis) {
+                        const raw = (q.value.cooked ?? q.value.raw).trim();
+                        if (raw && looksLikeClassList(raw) && !seen.has(raw)) {
+                            seen.add(raw);
+                            out.push(raw);
+                        }
+                    }
+                }
+            }
+        }
+        return out;
+    }
+    // Pre-compute once per file. These classes get unioned into every
+    // component candidate found in this module.
+    const moduleLevelClasses = collectModuleLevelClassStrings(ast.program.body);
+    for (const c of candidates) {
+        if (!isLikelyComponentName(c.name))
+            continue;
+        if (!containsJsx(c.bodyNode))
+            continue;
+        if (isUtilityFile)
+            continue;
+        const bodyClasses = extractClassNamesFromComponent(c.bodyNode);
+        // Union module-level classes — same dedupe logic.
+        const all = new Set(bodyClasses);
+        for (const s of moduleLevelClasses)
+            all.add(s);
+        found.push({
+            name: c.name,
+            file: relPath,
+            exportKind: c.isDefault ? "default" : "named",
+            declarationKind: c.declarationKind,
+            classNames: Array.from(all),
+            jsxIdentifiers: extractJsxIdentifiers(c.bodyNode)
+        });
+    }
+    return found;
+}
+export async function scanComponents(target, options = {}) {
+    const pattern = options.pattern ?? DEFAULT_GLOB;
+    const ignore = [...DEFAULT_IGNORE, ...(options.ignore ?? [])];
+    const files = await glob(pattern, {
+        cwd: target,
+        ignore,
+        absolute: false,
+        nodir: true
+    });
+    const results = [];
+    for (const rel of files) {
+        const abs = path.join(target, rel);
+        const found = await scanFile(abs, rel);
+        results.push(...found);
+    }
+    // Deduplicate by name+file. If a component is both a named export and a
+    // re-export from elsewhere we'll catch it twice; keep the first.
+    const seen = new Set();
+    return results.filter((c) => {
+        const key = `${c.name}::${c.file}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/scanner/foundationInferrer.js

@@ -0,0 +1,174 @@
+/**
+ * Greatest common divisor — used to find the most likely grid unit.
+ * Operates on the set of observed spacing pixel values.
+ */
+function gcd(a, b) {
+    a = Math.abs(a);
+    b = Math.abs(b);
+    while (b) {
+        [a, b] = [b, a % b];
+    }
+    return a;
+}
+/**
+ * Infer the grid unit. Strategy:
+ *
+ * 1. Collect all spacing observations with non-null px values, excluding 0.
+ * 2. Weight each by its count: a value used 50 times is much more evidence
+ *    than one used twice.
+ * 3. Find the largest N (between 2 and 16) such that the *weighted majority*
+ *    of pixels are multiples of N.
+ *
+ * Why weighted majority and not GCD: a single `p-[3px]` shouldn't drop the
+ * inferred grid from 8 to 1. GCD is brittle to outliers; coverage is robust.
+ *
+ * We bias upward: if both 4 and 8 explain ≥80% of usage, we pick 8 because
+ * the larger grid is more informative. If neither hits 80%, we fall back
+ * to 4 (the most common Tailwind default).
+ */
+function inferGrid(spacings) {
+    const totalWeight = spacings.reduce((sum, s) => sum + (s.pxValue && s.pxValue > 0 ? s.count : 0), 0);
+    if (totalWeight === 0) {
+        return {
+            value: 8,
+            confidence: "low",
+            evidence: "No spacing classes observed — defaulting to 8px."
+        };
+    }
+    let bestN = 4;
+    let bestCoverage = 0;
+    for (const n of [16, 12, 10, 8, 6, 5, 4, 3, 2]) {
+        const matching = spacings.reduce((sum, s) => {
+            if (s.pxValue && s.pxValue > 0 && s.pxValue % n === 0)
+                return sum + s.count;
+            return sum;
+        }, 0);
+        const coverage = matching / totalWeight;
+        if (coverage >= 0.8 && n > bestN) {
+            bestN = n;
+            bestCoverage = coverage;
+        }
+        else if (coverage > bestCoverage && bestCoverage < 0.8) {
+            // Keep tracking the best so we can report it if nothing hits 0.8.
+            bestN = n;
+            bestCoverage = coverage;
+        }
+    }
+    const confidence = bestCoverage >= 0.95 ? "high" : bestCoverage >= 0.8 ? "medium" : "low";
+    const evidence = bestCoverage >= 0.8
+        ? `${Math.round(bestCoverage * 100)}% of ${totalWeight} spacing usages are multiples of ${bestN}px.`
+        : `No clean grid emerged. Best fit: ${bestN}px covers ${Math.round(bestCoverage * 100)}% of usage.`;
+    return { value: bestN, confidence, evidence };
+}
+/**
+ * Infer radii. Strategy:
+ *
+ * 1. Collect radius observations with px values > 0.
+ * 2. Group by px value and sort by frequency.
+ * 3. The most-used non-extreme value (excluding 0 and 9999/full) is likely
+ *    one of the two radii. If there are two clearly-used values, the
+ *    smaller is "control" (buttons, inputs) and the larger is "container"
+ *    (cards, modals). If there's only one, it's used for both.
+ *
+ * We're cautious here: many projects use a single radius. We don't invent
+ * a second one — we report null and let the user fill it in during review.
+ */
+function inferRadii(radii) {
+    const usableValues = radii
+        .filter((r) => r.pxValue !== null && r.pxValue > 0 && r.pxValue < 100)
+        .reduce((map, r) => {
+        map.set(r.pxValue, (map.get(r.pxValue) ?? 0) + r.count);
+        return map;
+    }, new Map());
+    const observed = Array.from(usableValues.entries())
+        .map(([value, count]) => ({ value, count }))
+        .sort((a, b) => b.count - a.count);
+    if (observed.length === 0) {
+        return {
+            control: null,
+            container: null,
+            confidence: "low",
+            evidence: "No radius classes observed.",
+            observed: []
+        };
+    }
+    // If one value dominates (≥70% of radius usage), it's the project radius.
+    // Otherwise, top two values are control and container.
+    const total = observed.reduce((sum, o) => sum + o.count, 0);
+    const dominant = observed[0].count / total;
+    let control = null;
+    let container = null;
+    let evidence = "";
+    let confidence = "medium";
+    if (dominant >= 0.7) {
+        control = observed[0].value;
+        container = observed[0].value;
+        evidence = `Single radius ${observed[0].value}px dominates (${Math.round(dominant * 100)}% of ${total} usages). Using it for both control and container — adjust in review if needed.`;
+        confidence = dominant >= 0.9 ? "high" : "medium";
+    }
+    else if (observed.length >= 2) {
+        const [a, b] = observed;
+        control = Math.min(a.value, b.value);
+        container = Math.max(a.value, b.value);
+        evidence = `Two main radii observed: ${a.value}px (${a.count}×) and ${b.value}px (${b.count}×). Smaller is control, larger is container.`;
+        confidence = "medium";
+    }
+    else {
+        control = observed[0].value;
+        container = observed[0].value;
+        evidence = `Only ${observed[0].value}px observed (${observed[0].count}× across all radius usage).`;
+        confidence = "low";
+    }
+    return { control, container, confidence, evidence, observed };
+}
+function inferColors(colors) {
+    const grouped = new Map();
+    let arbitraryCount = 0;
+    for (const c of colors) {
+        if (c.colorToken === null)
+            continue;
+        if (c.isArbitrary) {
+            arbitraryCount += c.count;
+            continue;
+        }
+        // Strip the property prefix already, but normalise opacity modifiers
+        // like `blue-500/50` → `blue-500`.
+        const token = c.colorToken.split("/")[0];
+        grouped.set(token, (grouped.get(token) ?? 0) + c.count);
+    }
+    const palette = Array.from(grouped.entries())
+        .map(([token, count]) => ({ token, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 30);
+    const evidence = palette.length === 0
+        ? `No color classes observed${arbitraryCount > 0 ? ` (${arbitraryCount} arbitrary values)` : ""}.`
+        : `${palette.length} distinct tokens observed${arbitraryCount > 0 ? `, plus ${arbitraryCount} arbitrary value(s) — consider tokenising them` : ""}.`;
+    return { palette, arbitraryCount, evidence };
+}
+export function inferFoundations(observations) {
+    const spacings = observations.filter((o) => o.kind === "spacing");
+    const radii = observations.filter((o) => o.kind === "radius");
+    const colors = observations.filter((o) => o.kind === "color");
+    const grid = inferGrid(spacings);
+    const radiiInferred = inferRadii(radii);
+    const colorsInferred = inferColors(colors);
+    const hints = [];
+    if (grid.confidence === "low") {
+        hints.push("Grid inference is uncertain. Review spacing usage and confirm the value manually.");
+    }
+    if (radiiInferred.control === null) {
+        hints.push("No radius observed. Whale will leave radii unset; set them via the review flow or whale.config.json.");
+    }
+    else if (radiiInferred.control === radiiInferred.container) {
+        hints.push(`Project uses a single radius (${radiiInferred.control}px). If controls and containers should differ, edit during review.`);
+    }
+    if (colorsInferred.arbitraryCount > 0) {
+        hints.push(`${colorsInferred.arbitraryCount} arbitrary color value(s) found. These bypass the design system — consider extracting them as tokens.`);
+    }
+    return {
+        grid,
+        radii: radiiInferred,
+        colors: colorsInferred,
+        hints
+    };
+}