whale-igniter 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Whale Igniter contributors
+
+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,275 @@
+# Whale Igniter
+
+**CLI-first operational intelligence for AI-assisted product workflows.**
+
+Whale gives your project a machine-readable memory so AI agents like
+Claude Code, Codex, Cursor and Copilot understand your design system,
+conventions and decisions from the first commit — without you having
+to re-explain everything every session.
+
+> AI-native, not AI-dependent. The core is deterministic and runs
+> offline. AI is an enrichment layer — opt-in via API key, or via the
+> built-in MCP server.
+
+---
+
+## Install
+
+```bash
+npm install -g whale-igniter
+# or use it directly without installing
+npx whale-igniter ignite my-app
+```
+
+Requires Node 20 or newer.
+
+---
+
+## The two-minute version
+
+```bash
+# Brand new project
+whale ignite my-app
+
+# Existing React + Tailwind codebase
+cd my-existing-app
+whale adopt
+whale adopt review        # accept/reject scanner proposals
+```
+
+Either path produces a `CLAUDE.md` at the project root plus a
+`llm-wiki/` folder. Open the project in Claude Code (or any AI
+assistant) and it picks up the context automatically.
+
+---
+
+## What Whale does
+
+### 1. Bootstraps AI context for new projects
+
+`whale ignite` creates a workspace with foundations, a config, the
+intelligence stores, and a fully-generated `CLAUDE.md`. Three modes:
+opinionated default, `--minimal` skeleton, or `--interactive` wizard.
+
+### 2. Adopts existing projects
+
+`whale adopt` parses your React/Tailwind source with a real AST, infers
+foundations (grid, radii, paleta), detects components, and stages
+proposals you can review and accept. Idempotent — re-runs don't
+duplicate or overwrite your decisions.
+
+### 3. Records operational context as you work
+
+Three structured stores capture what would otherwise live in your head:
+
+- **`intelligence/components.json`** — component catalog
+- **`intelligence/decisions.json`** — architectural and product decisions
+- **`intelligence/refinements.json`** — approved exceptions to the system
+
+Every write auto-regenerates `CLAUDE.md` so agents always read current state.
+
+### 4. Surfaces accountable insights
+
+`whale insights` runs deterministic analyzers over your stores and code:
+refinement clusters, decision tension, orphan components, token drift,
+grid drift, catalog coverage gaps. No AI in the loop — local,
+explainable, machine-checkable.
+
+### 5. Generates code that respects your foundations
+
+`whale create component Card --variants primary,outline` produces a
+typed React component using your actual grid, radii, and accent color.
+No invented values. Auto-registers in the catalog.
+
+### 6. Bridges to any AI agent (Selene)
+
+Three composable commands — `describe`, `audit`, `suggest` — package
+your full project context into a structured prompt. They work three ways:
+
+- **Prompt mode** (default, offline): writes the prompt to clipboard;
+  paste into Claude/ChatGPT/Cursor; paste response back with
+  `whale selene apply`.
+- **API mode** (opt-in): if `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+  is set, Whale calls the provider directly and auto-applies the result.
+  Transparent fallback to prompt mode on any failure.
+- **MCP mode** (new in v1.0): Whale exposes its capabilities as MCP
+  tools that Claude Code, Cursor, Zed and any MCP client use natively.
+
+### 7. Stays in sync automatically
+
+`whale watch` regenerates `CLAUDE.md` and the wiki when your foundations
+or stores change. Plays well with pre-commit hooks and CI.
+
+---
+
+## MCP server
+
+The most powerful integration in v1.0. Wire Whale into your AI tool:
+
+```bash
+whale mcp config --client claude-code
+# Prints the JSON snippet for ~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Once configured, the agent gets tools like:
+
+- `whale_project_overview` — read foundations, packs, counts in one call
+- `whale_list_components` — see what already exists before creating duplicates
+- `whale_list_decisions` — understand why the project is structured this way
+- `whale_register_component` — record components the agent creates
+- `whale_record_decision` — record non-obvious choices as they happen
+- `whale_validate`, `whale_insights` — check state mid-session
+
+Available client snippets: `--client claude-code | cursor | zed | raw`.
+
+---
+
+## Command reference
+
+| Command | What it does |
+| --- | --- |
+| `whale ignite [name]` | Bootstrap a workspace. Flags: `--interactive`, `--minimal`. |
+| `whale adopt [target]` | Scan an existing project and stage proposals. |
+| `whale adopt review` | Walk through pending proposals interactively. |
+| `whale adopt status` | List proposals without entering review. |
+| `whale sync` | Regenerate CLAUDE.md + wiki from `intelligence/*.json`. |
+| `whale watch` | Auto-regenerate on changes. Flags: `--once`, `--verbose`, `--debounce`. |
+| `whale validate` | Run validators. Non-zero exit on errors. |
+| `whale insights` | Local analyzers + recommendations. Flags: `--json`, `--category`, `--min-severity`. |
+| `whale refine "<note>"` | Record a validator override. |
+| `whale decision` | Record an architectural / product decision. |
+| `whale component add <name>` | Register a component. |
+| `whale create component <name>` | Generate a typed component scaffold. |
+| `whale selene describe <component>` | AI-assisted catalog description. |
+| `whale selene audit <file>` | AI-assisted audit against foundations. |
+| `whale selene suggest` | AI-suggested patterns and decisions. |
+| `whale selene apply <kind>` | Apply pasted LLM response. |
+| `whale selene status` | Show provider state, mode, cache. |
+| `whale mcp serve` | Start the MCP server on stdio. |
+| `whale mcp config` | Print client configuration snippets. |
+| `whale docs` | Generate human-facing reports. |
+
+---
+
+## Project structure
+
+```
+my-app/
+├── whale.config.json              foundations, packs, AI targets
+├── CLAUDE.md                      AI entry point (auto-generated)
+├── AGENTS.md                      if "codex" in aiTargets
+├── .cursorrules                   if "cursor" in aiTargets
+├── intelligence/                  source of truth (JSON)
+│   ├── refinements.json
+│   ├── decisions.json
+│   └── components.json
+├── llm-wiki/                      rendered view (markdown)
+│   ├── FOUNDATIONS.md
+│   ├── CONVENTIONS.md
+│   ├── DECISIONS.md
+│   ├── COMPONENTS.md
+│   └── WORKFLOWS.md
+└── .whale/                        runtime caches and Selene stash
+    └── selene/
+        ├── cache/
+        └── *.prompt.md / *.response.md
+```
+
+**JSON is the source of truth. Markdown is rendered.** Edit a JSON
+store by hand, run `whale sync` (or have `whale watch` running), and
+everything else catches up.
+
+---
+
+## Selene configuration
+
+Optional block in `whale.config.json` for API mode:
+
+```json
+{
+  "selene": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "temperature": 0.2,
+    "maxTokens": 1500,
+    "autoCall": true,
+    "confirmCost": false,
+    "noCache": false
+  }
+}
+```
+
+Everything is optional. With no config and no key, Selene runs in
+prompt mode forever. Adding a key (env or here) flips it to API mode.
+Set `autoCall: false` to keep prompt mode even with a key available.
+
+---
+
+## Presentation
+
+Whale's terminal output is built on a semantic UI layer: commands describe
+*intent* (success, warning, section header, key/value pair) and the active
+theme decides what each intent looks like. One result is that the same
+command produces premium output in a real terminal and clean, grep-friendly
+output in CI.
+
+Three environment variables control presentation:
+
+| Variable | Effect |
+| --- | --- |
+| `WHALE_PLAIN=1` | Disable color *and* Unicode glyphs. The output becomes ASCII-only and grep-friendly. Recommended for CI logs and pipelines. |
+| `WHALE_UNICODE=0` | Keep color, fall back to ASCII glyphs (`*`, `v`, `x`, `->`). Useful for terminals that render color but mangle Unicode. |
+| `NO_COLOR=1` / `FORCE_COLOR=0` | Standard environment overrides — chalk respects them, so does Whale. |
+
+In normal terminals Whale auto-detects capabilities and uses Unicode + color.
+In non-TTY contexts (piping, CI, scripts) it strips both automatically. You
+don't need to opt in unless you want to override the default.
+
+---
+
+## CI usage
+
+```yaml
+- run: npx whale-igniter validate .       # exits non-zero on errors
+- run: npx whale-igniter sync              # ensure CLAUDE.md is current
+- run: git diff --exit-code                # fail if sync produced uncommitted changes
+```
+
+This turns "is the AI context current?" into a checkable property of
+the repo. Combine with `whale insights --json --min-severity warning`
+for automated quality reports.
+
+---
+
+## Design principles
+
+1. **CLI-first.** Whale is a CLI and the MCP server. No dashboard, no SaaS.
+2. **Local-first.** Intelligence lives in your repo, in git. No accounts.
+3. **AI-native, not AI-dependent.** Core works offline. AI is opt-in at
+   every level.
+4. **Source of truth in JSON; rendered views in Markdown.** One direction.
+5. **Idempotent everywhere.** Re-running adopt, sync, watch, or
+   register doesn't duplicate or corrupt anything.
+6. **Honest fallbacks.** API down? Falls back to prompt mode. Scan
+   fails? Insights skip orphan/drift but still run. Watcher recursive
+   not supported? Falls back to non-recursive. The user is never stuck.
+
+---
+
+## What v1.1 doesn't do (and why)
+
+- **Vue / Svelte parsing.** Scanner is React + Tailwind only. Other
+  frameworks need their own parsers; that's post-v1.0.
+- **Hosted SaaS.** Whale is a tool, not a service. By design.
+- **Real-time team sync.** Today everything is local + git. Team
+  workflows happen through PRs against `intelligence/*.json`.
+- **Generic linting.** ESLint and Stylelint exist. Whale only checks
+  what's tied to operational context.
+
+See [docs/ROADMAP.md](docs/ROADMAP.md) for what's planned next.
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/analyzer/imports.js

@@ -0,0 +1,88 @@
+/**
+ * Collect every relative file path imported in the project's source tree.
+ * Returns a Set of normalized paths (relative to project root) without
+ * extensions, since imports usually omit them. The caller normalizes
+ * the catalog's `files` entries the same way before checking.
+ */
+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 IGNORE = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/coverage/**"
+];
+function stripExt(p) {
+    return p.replace(/\.(t|j)sx?$/, "");
+}
+/**
+ * Resolve an import specifier relative to the importing file, returning
+ * a project-relative path without extension. Returns null for bare
+ * specifiers (`react`, `lodash`) and `node:*` imports.
+ */
+function resolveSpecifier(spec, fromFileRel, root) {
+    if (!spec.startsWith(".") && !spec.startsWith("/"))
+        return null; // bare specifier
+    const fromDir = path.dirname(path.join(root, fromFileRel));
+    const abs = path.resolve(fromDir, spec);
+    const rel = path.relative(root, abs).replace(/\\/g, "/");
+    if (rel.startsWith(".."))
+        return null; // outside the project
+    return stripExt(rel);
+}
+export async function collectReferencedFiles(target, pattern = "src/**/*.{ts,tsx,js,jsx}") {
+    const files = await glob(pattern, { cwd: target, ignore: IGNORE, nodir: true });
+    const refs = new Set();
+    for (const rel of files) {
+        let src;
+        try {
+            src = await fs.readFile(path.join(target, rel), "utf8");
+        }
+        catch {
+            continue;
+        }
+        let ast;
+        try {
+            ast = parse(src, {
+                sourceType: "module",
+                plugins: ["typescript", "jsx", "decorators-legacy"],
+                errorRecovery: true
+            });
+        }
+        catch {
+            continue;
+        }
+        for (const node of ast.program.body) {
+            // import x from "..."  /  import {x} from "..."
+            if (t.isImportDeclaration(node)) {
+                const resolved = resolveSpecifier(node.source.value, rel, target);
+                if (resolved)
+                    refs.add(resolved);
+            }
+            // export {x} from "..."
+            if (t.isExportNamedDeclaration(node) && node.source) {
+                const resolved = resolveSpecifier(node.source.value, rel, target);
+                if (resolved)
+                    refs.add(resolved);
+            }
+            // export * from "..."
+            if (t.isExportAllDeclaration(node)) {
+                const resolved = resolveSpecifier(node.source.value, rel, target);
+                if (resolved)
+                    refs.add(resolved);
+            }
+        }
+    }
+    return refs;
+}
+/**
+ * Normalise a path the same way collectReferencedFiles does. Useful to
+ * check whether a catalog entry's `files` are in the referenced set.
+ */
+export function normalizePath(p) {
+    return stripExt(p.replace(/\\/g, "/"));
+}

package/dist/analyzer/insights.js

@@ -0,0 +1,276 @@
+/**
+ * Insight engine.
+ *
+ * Pure functions: takes the intelligence stores in memory and returns
+ * a list of insights. No filesystem IO, no console output. The command
+ * layer (commands/insights.ts) wires this to the real data.
+ *
+ * Why pure? Two reasons. First, it's trivially testable — pass in a
+ * fixture state, assert on the output. Second, the same engine will be
+ * reused by future tools (Selene prompt composition, MCP server,
+ * `whale docs` enrichment) where the inputs aren't necessarily disk
+ * state.
+ */
+// ---------------------------------------------------------------------------
+// Individual analyzers. Each returns 0+ insights.
+// ---------------------------------------------------------------------------
+/**
+ * Repeated refinements with the same inferred issue type may indicate a
+ * convention that should be promoted to config, not patched per-site.
+ *
+ * We look at issueType (the strongest scope signal) and bucket by it.
+ * Threshold of 3 is deliberate — 2 is coincidence, 3 is a pattern.
+ */
+function analyzeRefinementClusters(refinements) {
+    const buckets = new Map();
+    for (const r of refinements) {
+        const type = r.scope?.issueType;
+        if (!type)
+            continue;
+        if (!buckets.has(type))
+            buckets.set(type, []);
+        buckets.get(type).push(r);
+    }
+    const insights = [];
+    for (const [type, items] of buckets) {
+        if (items.length < 3)
+            continue;
+        insights.push({
+            id: `refinements.cluster.${type}`,
+            category: "refinements",
+            severity: "warning",
+            title: `${items.length} refinements share the same issue type (${type})`,
+            detail: `Recurring overrides suggest the foundation may not match how the project is actually built. ` +
+                `Consider adjusting \`whale.config.json\` instead of patching individual cases.`,
+            evidence: items.map((r) => `${r.timestamp.slice(0, 10)} — ${r.note}`).slice(0, 5),
+            action: `Review the ${type} foundation in whale.config.json and consider widening it.`
+        });
+    }
+    return insights;
+}
+/**
+ * Refinements logged without an inferred scope produce no validation
+ * effect — they're notes, not rules. Worth surfacing because users
+ * often think they've created an exception when they haven't.
+ */
+function analyzeScopelessRefinements(refinements) {
+    const scopeless = refinements.filter((r) => !r.scope);
+    if (scopeless.length === 0)
+        return [];
+    return [
+        {
+            id: "refinements.scopeless",
+            category: "refinements",
+            severity: "info",
+            title: `${scopeless.length} refinement(s) have no active scope`,
+            detail: `These are recorded as context but the validator won't act on them. ` +
+                `Mention an issue type (radius, spacing, hex, focus) in the note to activate scoping.`,
+            evidence: scopeless.map((r) => `${r.timestamp.slice(0, 10)} — ${r.note}`).slice(0, 5),
+            action: "Rephrase the notes or use `whale refine` with more specific wording."
+        }
+    ];
+}
+/**
+ * Components that exist in the catalog but the user hasn't populated
+ * with the basics. The CLAUDE.md is materially less useful for agents
+ * when a third of components have no description.
+ */
+function analyzeCatalogCoverage(components) {
+    if (components.length === 0)
+        return [];
+    const missingDescription = components.filter((c) => !c.description || c.description.trim().length === 0);
+    const missingCategory = components.filter((c) => !c.category);
+    const missingVariants = components.filter((c) => !c.variants || c.variants.length === 0);
+    const insights = [];
+    const pct = (n) => Math.round((n / components.length) * 100);
+    if (missingDescription.length > 0) {
+        const p = pct(missingDescription.length);
+        insights.push({
+            id: "components.coverage.description",
+            category: "coverage",
+            severity: p >= 50 ? "warning" : "info",
+            title: `${missingDescription.length}/${components.length} component(s) (${p}%) have no description`,
+            detail: `Descriptions are the single field agents rely on to disambiguate similar components. ` +
+                `Even one sentence per component meaningfully improves AI context quality.`,
+            evidence: missingDescription.map((c) => c.name).slice(0, 10),
+            action: "Edit `intelligence/components.json` or use `whale component add <name> --description ...`."
+        });
+    }
+    if (missingCategory.length > 0) {
+        insights.push({
+            id: "components.coverage.category",
+            category: "coverage",
+            severity: "info",
+            title: `${missingCategory.length} component(s) have no category`,
+            detail: `Categories help agents pick the right component for a task ` +
+                `(form vs. navigation vs. feedback, etc.).`,
+            evidence: missingCategory.map((c) => c.name).slice(0, 10)
+        });
+    }
+    if (missingVariants.length > 0) {
+        insights.push({
+            id: "components.coverage.variants",
+            category: "coverage",
+            severity: "info",
+            title: `${missingVariants.length} component(s) list no variants`,
+            detail: `If a component has multiple visual styles (primary/secondary/ghost), ` +
+                `declaring them in the catalog prevents agents from inventing names.`,
+            evidence: missingVariants.map((c) => c.name).slice(0, 10)
+        });
+    }
+    return insights;
+}
+/**
+ * Components in the catalog with a `files` entry that no other file imports.
+ * Useful for spotting dead code, but only when we have referencedFiles.
+ *
+ * Conservative: only flags components whose ALL declared files are unreferenced.
+ * If one of a component's files is referenced, we assume it's in use.
+ */
+function analyzeOrphanComponents(components, referencedFiles) {
+    if (!referencedFiles || referencedFiles.size === 0)
+        return [];
+    const orphans = components.filter((c) => {
+        if (!c.files || c.files.length === 0)
+            return false;
+        return c.files.every((f) => !referencedFiles.has(f));
+    });
+    if (orphans.length === 0)
+        return [];
+    return [
+        {
+            id: "components.orphans",
+            category: "components",
+            severity: "info",
+            title: `${orphans.length} catalogued component(s) appear unreferenced`,
+            detail: `These components are in the catalog but no other source file imports them. ` +
+                `They may be dead code, top-level pages, or referenced through dynamic paths the scanner can't follow.`,
+            evidence: orphans.map((c) => `${c.name} (${c.files?.join(", ")})`).slice(0, 10),
+            action: "Verify these are still in use; remove from the catalog if not."
+        }
+    ];
+}
+/**
+ * If `observations` was passed (i.e. a scan ran), flag arbitrary color
+ * values that bypass the design system. This is the v0.9 version of
+ * token drift — full bidirectional drift (declared but unused) needs
+ * tailwind.config resolution which is out of scope.
+ */
+function analyzeTokenDrift(observations) {
+    if (!observations || observations.length === 0)
+        return [];
+    const arbitraryColors = observations.filter((o) => o.kind === "color" && o.isArbitrary);
+    if (arbitraryColors.length === 0)
+        return [];
+    const totalUses = arbitraryColors.reduce((sum, o) => sum + o.count, 0);
+    return [
+        {
+            id: "tokens.arbitrary-colors",
+            category: "tokens",
+            severity: totalUses >= 5 ? "warning" : "info",
+            title: `${arbitraryColors.length} distinct arbitrary color value(s) (${totalUses} use(s))`,
+            detail: `Arbitrary values like \`bg-[#0a84ff]\` bypass the design system. ` +
+                `Consider declaring these as tokens so they're consistent and reusable.`,
+            evidence: arbitraryColors.slice(0, 10).map((o) => `${o.raw} (${o.count}×)`),
+            action: "Promote these values into your Tailwind config or `whale.config.json` foundations."
+        }
+    ];
+}
+/**
+ * Two active decisions whose titles share substantive keywords might
+ * be in tension. Conservative heuristic — only flags strict overlap of
+ * meaningful tokens, never claims contradiction without user review.
+ */
+function analyzeDecisionTension(decisions) {
+    const active = decisions.filter((d) => d.status === "active");
+    if (active.length < 2)
+        return [];
+    const stopwords = new Set([
+        "the", "a", "an", "and", "or", "of", "to", "for", "in", "on",
+        "with", "use", "using", "is", "be", "we", "our", "as", "by",
+        "this", "that", "from", "all", "any", "are"
+    ]);
+    const tokenize = (s) => s
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length >= 4 && !stopwords.has(t));
+    const insights = [];
+    for (let i = 0; i < active.length; i += 1) {
+        for (let j = i + 1; j < active.length; j += 1) {
+            const a = active[i];
+            const b = active[j];
+            if (a.category !== b.category)
+                continue;
+            const ta = new Set(tokenize(a.title));
+            const tb = new Set(tokenize(b.title));
+            const overlap = [];
+            for (const t of ta)
+                if (tb.has(t))
+                    overlap.push(t);
+            if (overlap.length >= 2) {
+                insights.push({
+                    id: `decisions.tension.${a.id.slice(0, 6)}.${b.id.slice(0, 6)}`,
+                    category: "decisions",
+                    severity: "info",
+                    title: `Two active ${a.category} decisions share keywords: ${overlap.join(", ")}`,
+                    detail: `"${a.title}" and "${b.title}" both touch the same topic. ` +
+                        `If the newer supersedes the older, mark it with the \`status\` and \`supersedes\` fields.`,
+                    evidence: [a.title, b.title]
+                });
+            }
+        }
+    }
+    return insights;
+}
+/**
+ * Foundations declared in the config that the project barely follows.
+ * Only runs if observations are available.
+ */
+function analyzeGridDrift(config, observations) {
+    const grid = config.foundations?.grid;
+    if (!grid || !observations)
+        return [];
+    const spacings = observations.filter((o) => o.kind === "spacing" && o.pxValue !== null && o.pxValue !== 0);
+    const total = spacings.reduce((s, o) => s + o.count, 0);
+    if (total < 10)
+        return []; // not enough data to be meaningful
+    const onGrid = spacings.reduce((s, o) => (o.pxValue % grid === 0 ? s + o.count : s), 0);
+    const coverage = onGrid / total;
+    if (coverage < 0.7) {
+        return [
+            {
+                id: "foundations.grid-drift",
+                category: "foundations",
+                severity: "warning",
+                title: `Declared grid (${grid}px) covers only ${Math.round(coverage * 100)}% of observed spacing`,
+                detail: `${total - onGrid} of ${total} spacing usages don't fit the declared grid. ` +
+                    `Either the grid is wrong for this project or there's significant drift to clean up.`,
+                action: "Run `whale adopt` to re-infer the grid, or audit the off-grid usage."
+            }
+        ];
+    }
+    return [];
+}
+// ---------------------------------------------------------------------------
+// Main entry
+// ---------------------------------------------------------------------------
+export function analyze(input) {
+    const all = [];
+    all.push(...analyzeRefinementClusters(input.refinements));
+    all.push(...analyzeScopelessRefinements(input.refinements));
+    all.push(...analyzeCatalogCoverage(input.components));
+    all.push(...analyzeOrphanComponents(input.components, input.referencedFiles));
+    all.push(...analyzeTokenDrift(input.observations));
+    all.push(...analyzeDecisionTension(input.decisions));
+    all.push(...analyzeGridDrift(input.config, input.observations));
+    // Sort by severity (critical > warning > info), then by category for stable output.
+    const sevRank = { critical: 0, warning: 1, info: 2 };
+    all.sort((a, b) => {
+        const sa = sevRank[a.severity] - sevRank[b.severity];
+        if (sa !== 0)
+            return sa;
+        return a.category.localeCompare(b.category);
+    });
+    return all;
+}