@mandujs/core 0.33.0 → 0.34.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@mandujs/core",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./a11y": "./src/a11y/index.ts",
     "./auth": "./src/auth/index.ts",
     "./auth/login": "./src/auth/login.ts",
     "./auth/password": "./src/auth/password.ts",
@@ -43,6 +44,7 @@
     "./observability": "./src/observability/index.ts",
     "./perf": "./src/perf/index.ts",
     "./perf/hmr-markers": "./src/perf/hmr-markers.ts",
+    "./perf/user-marks": "./src/perf/user-marks.ts",
     "./routes": "./src/routes/index.ts",
     "./scheduler": "./src/scheduler/index.ts",
     "./storage/s3": "./src/storage/s3/index.ts",
@@ -55,6 +57,7 @@
     "./bundler/vendor-cache-types": "./src/bundler/vendor-cache-types.ts",
     "./bundler/manifest-schema": "./src/bundler/manifest-schema.ts",
     "./bundler/analyzer": "./src/bundler/analyzer.ts",
+    "./bundler/budget": "./src/bundler/budget.ts",
     "./bundler/plugins": "./src/bundler/plugins/index.ts",
     "./bundler/plugins/block-generated-imports": "./src/bundler/plugins/block-generated-imports.ts",
     "./bundler/generate-static-params": "./src/bundler/generate-static-params.ts",
@@ -104,7 +107,10 @@
     "react-dom": "^19.0.0",
     "react-refresh": ">=0.18.0",
     "@tailwindcss/cli": ">=4.0.0",
-    "webview-bun": "^2.4.0"
+    "webview-bun": "^2.4.0",
+    "axe-core": ">=4.8.0",
+    "jsdom": ">=24.0.0",
+    "happy-dom": ">=15.0.0"
   },
   "peerDependenciesMeta": {
     "@tailwindcss/cli": {
@@ -115,6 +121,15 @@
     },
     "webview-bun": {
       "optional": true
+    },
+    "axe-core": {
+      "optional": true
+    },
+    "jsdom": {
+      "optional": true
+    },
+    "happy-dom": {
+      "optional": true
     }
   },
   "dependencies": {

package/src/a11y/__tests__/run-audit.test.ts

@@ -0,0 +1,333 @@
+/**
+ * Tests for the Phase 18.χ accessibility audit runner.
+ *
+ * Philosophy: we never actually install axe-core/jsdom in the test
+ * environment — that would both contradict the "optional peerDep"
+ * contract and slow every `bun test` run by a full second. Instead
+ * each test injects `axeLoader` + `domLoader` fakes and asserts on the
+ * report shape. A single "no deps installed" case exercises the real
+ * resolution path by leaving both loaders undefined.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { runAudit, formatAuditReport } from "../run-audit";
+import type { AuditImpact } from "../types";
+
+async function mkTmp(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), "mandu-a11y-"));
+}
+
+async function writeHtml(dir: string, name: string, html: string): Promise<string> {
+  const full = path.join(dir, name);
+  await fs.mkdir(path.dirname(full), { recursive: true });
+  await fs.writeFile(full, html, "utf-8");
+  return full;
+}
+
+/**
+ * Fake axe-core handle. Returns the violations that the test preloads
+ * into `queued` for the next `.run()` call. Enables multi-file
+ * scenarios where each file yields a different result.
+ */
+function createFakeAxe(queued: Array<unknown>) {
+  let i = 0;
+  return {
+    default: {
+      async run() {
+        const next = queued[i] ?? { violations: [] };
+        i += 1;
+        return next;
+      },
+    },
+  };
+}
+
+/** A DOM provider stub that returns a no-op window. axe never touches
+ *  it because the fake axe above ignores its `context` argument. */
+const fakeDom = {
+  kind: "jsdom" as const,
+  async fromHtml() {
+    return {
+      window: { document: {} },
+      dispose() { /* no-op */ },
+    };
+  },
+};
+
+describe("runAudit — dependency resolution", () => {
+  it("returns axe-missing when axeLoader rejects (graceful degradation)", async () => {
+    const report = await runAudit([], {
+      axeLoader: async () => { throw new Error("Cannot find module 'axe-core'"); },
+    });
+    expect(report.outcome).toBe("axe-missing");
+    expect(report.filesScanned).toBe(0);
+    expect(report.violations).toEqual([]);
+    expect(report.note).toMatch(/axe-core not installed/);
+    expect(report.durationMs).toBe(0);
+  });
+
+  it("returns axe-missing when no DOM provider is available", async () => {
+    const report = await runAudit([], {
+      axeLoader: async () => createFakeAxe([]),
+      domLoader: async () => null,
+    });
+    expect(report.outcome).toBe("axe-missing");
+    expect(report.note).toMatch(/DOM provider/);
+  });
+
+  it("treats loader returning non-axe-shape as missing", async () => {
+    const report = await runAudit([], {
+      axeLoader: async () => ({ notAxe: true }),
+    });
+    expect(report.outcome).toBe("axe-missing");
+  });
+});
+
+describe("runAudit — real audit flow", () => {
+  let tmp: string;
+  beforeEach(async () => { tmp = await mkTmp(); });
+  afterEach(async () => { await fs.rm(tmp, { recursive: true, force: true }); });
+
+  it("reports outcome=ok when no violations fire", async () => {
+    const file = await writeHtml(tmp, "clean.html", "<html><body><h1>Hi</h1></body></html>");
+    const report = await runAudit([file], {
+      axeLoader: async () => createFakeAxe([{ violations: [] }]),
+      domLoader: async () => fakeDom,
+    });
+    expect(report.outcome).toBe("ok");
+    expect(report.filesScanned).toBe(1);
+    expect(report.violations).toEqual([]);
+  });
+
+  it("aggregates violations across multiple files with per-file attribution", async () => {
+    const a = await writeHtml(tmp, "a.html", "<html></html>");
+    const b = await writeHtml(tmp, "b.html", "<html></html>");
+    const violationA = {
+      id: "image-alt",
+      impact: "serious" as AuditImpact,
+      help: "Images must have alternate text",
+      helpUrl: "https://axe.dev/image-alt",
+      nodes: [{ target: ["html > body > img"], failureSummary: "missing alt" }],
+    };
+    const violationB = {
+      id: "color-contrast",
+      impact: "critical" as AuditImpact,
+      help: "Elements must have sufficient contrast",
+      nodes: [{ target: "html > body > p", failureSummary: "1.2:1 ratio" }],
+    };
+    const report = await runAudit([a, b], {
+      axeLoader: async () =>
+        createFakeAxe([
+          { violations: [violationA] },
+          { violations: [violationB] },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    expect(report.outcome).toBe("violations");
+    expect(report.filesScanned).toBe(2);
+    expect(report.violations.length).toBe(2);
+    expect(report.violations[0].file).toBe(path.resolve(a));
+    expect(report.violations[1].file).toBe(path.resolve(b));
+    expect(report.impactCounts.serious).toBe(1);
+    expect(report.impactCounts.critical).toBe(1);
+    expect(report.impactCounts.minor).toBe(0);
+  });
+
+  it("drops violations below minImpact threshold", async () => {
+    const file = await writeHtml(tmp, "page.html", "<html></html>");
+    const report = await runAudit([file], {
+      minImpact: "serious",
+      axeLoader: async () =>
+        createFakeAxe([
+          {
+            violations: [
+              { id: "minor-rule", impact: "minor", help: "x", nodes: [] },
+              { id: "moderate-rule", impact: "moderate", help: "y", nodes: [] },
+              { id: "serious-rule", impact: "serious", help: "z", nodes: [{ target: "x" }] },
+              { id: "critical-rule", impact: "critical", help: "w", nodes: [{ target: "y" }] },
+            ],
+          },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    expect(report.violations.map((v) => v.rule)).toEqual([
+      "serious-rule",
+      "critical-rule",
+    ]);
+    expect(report.impactCounts.minor).toBe(0);
+    expect(report.impactCounts.moderate).toBe(0);
+  });
+
+  it("attaches fixHint for recognised rule ids", async () => {
+    const file = await writeHtml(tmp, "form.html", "<html></html>");
+    const report = await runAudit([file], {
+      axeLoader: async () =>
+        createFakeAxe([
+          {
+            violations: [
+              { id: "label", impact: "serious", help: "Labels", nodes: [{ target: "input" }] },
+              { id: "unknown-rule-xyz", impact: "critical", help: "?", nodes: [{ target: "div" }] },
+            ],
+          },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    const labelV = report.violations.find((v) => v.rule === "label")!;
+    const unknownV = report.violations.find((v) => v.rule === "unknown-rule-xyz")!;
+    expect(labelV.fixHint).toMatch(/label/i);
+    expect(unknownV.fixHint).toBeUndefined();
+  });
+
+  it("caps node list at 10 per violation and truncates long HTML snippets", async () => {
+    const file = await writeHtml(tmp, "big.html", "<html></html>");
+    const manyNodes = Array.from({ length: 25 }, (_, i) => ({
+      target: [`#node${i}`],
+      failureSummary: "x",
+      html: "<div>" + "a".repeat(500) + "</div>",
+    }));
+    const report = await runAudit([file], {
+      axeLoader: async () =>
+        createFakeAxe([
+          { violations: [{ id: "landmark-one-main", impact: "moderate", help: "m", nodes: manyNodes }] },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    const v = report.violations[0];
+    expect(v.nodes.length).toBe(10);
+    for (const n of v.nodes) {
+      expect(n.html!.length).toBeLessThanOrEqual(300);
+      expect(n.html!.endsWith("...")).toBe(true);
+    }
+  });
+
+  it("skips unreadable files without failing the whole run", async () => {
+    const good = await writeHtml(tmp, "good.html", "<html></html>");
+    const missing = path.join(tmp, "does-not-exist.html");
+    const report = await runAudit([missing, good], {
+      axeLoader: async () =>
+        createFakeAxe([
+          { violations: [] },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    expect(report.filesScanned).toBe(1);
+    expect(report.outcome).toBe("ok");
+  });
+
+  it("honours maxFiles cap", async () => {
+    const files: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      files.push(await writeHtml(tmp, `p${i}.html`, "<html></html>"));
+    }
+    const report = await runAudit(files, {
+      maxFiles: 2,
+      axeLoader: async () =>
+        createFakeAxe([
+          { violations: [] },
+          { violations: [] },
+          { violations: [] },
+          { violations: [] },
+          { violations: [] },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    expect(report.filesScanned).toBe(2);
+  });
+
+  it("produces a JSON-serialisable report (stable shape contract)", async () => {
+    const file = await writeHtml(tmp, "x.html", "<html></html>");
+    const report = await runAudit([file], {
+      axeLoader: async () =>
+        createFakeAxe([
+          {
+            violations: [
+              {
+                id: "image-alt",
+                impact: "serious",
+                help: "Images",
+                helpUrl: "https://x",
+                nodes: [{ target: ["img"], failureSummary: "s" }],
+              },
+            ],
+          },
+        ]),
+      domLoader: async () => fakeDom,
+    });
+    const roundtrip = JSON.parse(JSON.stringify(report));
+    expect(roundtrip).toMatchObject({
+      outcome: "violations",
+      filesScanned: 1,
+      minImpact: "minor",
+    });
+    expect(roundtrip.violations[0]).toMatchObject({
+      rule: "image-alt",
+      impact: "serious",
+      help: "Images",
+      fixHint: expect.any(String),
+    });
+    expect(Array.isArray(roundtrip.violations[0].nodes)).toBe(true);
+  });
+});
+
+describe("formatAuditReport", () => {
+  it("renders an actionable message when deps are missing", () => {
+    const text = formatAuditReport({
+      outcome: "axe-missing",
+      filesScanned: 0,
+      violations: [],
+      impactCounts: { minor: 0, moderate: 0, serious: 0, critical: 0 },
+      minImpact: "minor",
+      durationMs: 0,
+      note: "axe-core not installed — skipping audit",
+    });
+    expect(text).toMatch(/bun add -d axe-core jsdom/);
+  });
+
+  it("prints a PASS summary when there are zero violations", () => {
+    const text = formatAuditReport({
+      outcome: "ok",
+      filesScanned: 4,
+      violations: [],
+      impactCounts: { minor: 0, moderate: 0, serious: 0, critical: 0 },
+      minImpact: "minor",
+      durationMs: 12,
+    });
+    expect(text).toMatch(/PASS/);
+    expect(text).toMatch(/Files scanned: 4/);
+  });
+
+  it("groups violations by rule and surfaces fix hints + doc links", () => {
+    const text = formatAuditReport({
+      outcome: "violations",
+      filesScanned: 2,
+      violations: [
+        {
+          file: "a.html",
+          rule: "image-alt",
+          impact: "serious",
+          help: "Images must have alt",
+          helpUrl: "https://example/image-alt",
+          nodes: [{ target: "img", failureSummary: "x" }],
+          fixHint: "Add alt attribute",
+        },
+        {
+          file: "b.html",
+          rule: "image-alt",
+          impact: "serious",
+          help: "Images must have alt",
+          nodes: [{ target: "img", failureSummary: "x" }],
+        },
+      ],
+      impactCounts: { minor: 0, moderate: 0, serious: 2, critical: 0 },
+      minImpact: "minor",
+      durationMs: 45,
+    });
+    expect(text).toMatch(/\[SERIOUS\] image-alt/);
+    expect(text).toMatch(/Fix: Add alt attribute/);
+    expect(text).toMatch(/Docs: https:\/\/example\/image-alt/);
+    expect(text).toMatch(/2 file\(s\)/);
+  });
+});

package/src/a11y/fix-hints.ts

@@ -0,0 +1,76 @@
+/**
+ * Curated fix hints for the most common axe-core rules we see in the
+ * wild during framework dogfooding. Each hint is a single actionable
+ * sentence — long enough to be useful, short enough to fit in a CI
+ * table cell. When a rule is not in this map the runner simply omits
+ * `fixHint` and callers fall back to axe's `helpUrl` link.
+ *
+ * Rule ids mirror axe-core's canonical list:
+ *   https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
+ */
+export const AXE_RULE_FIX_HINTS: Record<string, string> = {
+  "color-contrast":
+    "Increase foreground/background contrast to meet WCAG AA 4.5:1 for normal text (3:1 for large).",
+  "image-alt":
+    "Add an `alt` attribute to every <img>. Decorative images should use `alt=\"\"`.",
+  "label":
+    "Associate every form control with a <label for=\"id\"> or wrap it in <label>.",
+  "link-name":
+    "Ensure <a> elements contain accessible text (visible, aria-label, or aria-labelledby).",
+  "button-name":
+    "Give every <button> an accessible name: visible text, aria-label, or aria-labelledby.",
+  "document-title":
+    "Render a non-empty <title> inside <head>. Mandu's `metadata.title` exports auto-populate this.",
+  "html-has-lang":
+    "Set `lang` on <html>. In Mandu, configure via `metadata.lang` or the root layout.",
+  "html-lang-valid":
+    "Use a BCP-47 language code (`en`, `ko`, `en-US`) — case-sensitive region subtag matters.",
+  "landmark-one-main":
+    "Wrap primary content in exactly one <main> landmark per page.",
+  "region":
+    "Place all content inside a landmark (<header>, <main>, <nav>, <footer>, or role=\"region\").",
+  "duplicate-id":
+    "Every `id` must be unique in the DOM. Check island + SSR output for collisions.",
+  "duplicate-id-active":
+    "Focusable elements must have unique ids — screen readers cannot resolve duplicates.",
+  "duplicate-id-aria":
+    "ids referenced by aria-* attributes must be unique (one target per reference).",
+  "meta-viewport":
+    "Do not disable user scaling: avoid `user-scalable=no` or `maximum-scale<2` in <meta name=viewport>.",
+  "aria-valid-attr":
+    "Remove unknown aria-* attributes. Check for typos (`aria-labeledby` → `aria-labelledby`).",
+  "aria-valid-attr-value":
+    "aria-* attribute values must match the allowed set for that attribute.",
+  "aria-required-attr":
+    "The ARIA role you used requires additional attributes (e.g. role=\"slider\" needs aria-valuenow).",
+  "aria-roles":
+    "Use a valid ARIA role. Custom roles (`role=\"card\"`) are ignored by screen readers.",
+  "list":
+    "<ul>/<ol> must contain only <li> children (plus script/template). Wrap other content inside <li>.",
+  "listitem":
+    "<li> must have a parent <ul>, <ol>, or <menu>.",
+  "heading-order":
+    "Headings must increase by one level at a time — don't skip from <h2> to <h4>.",
+  "empty-heading":
+    "Remove empty heading tags or add text content — they confuse screen-reader navigation.",
+  "tabindex":
+    "Avoid tabindex values greater than 0 — they break the natural focus order.",
+  "frame-title":
+    "Give every <iframe> a `title` attribute describing its contents.",
+  "object-alt":
+    "Provide fallback text for <object> via its text content or `aria-label`.",
+  "video-caption":
+    "Every <video> must have at least one <track kind=\"captions\">.",
+  "bypass":
+    "Include a skip-link or a landmark so keyboard users can bypass repeated blocks.",
+} as const;
+
+/**
+ * Return the fix hint for a rule id, or `undefined` when we don't have
+ * one. Kept as a function (rather than direct map access) so the
+ * lookup layer can evolve (e.g. add localization) without rippling
+ * through call sites.
+ */
+export function getFixHint(ruleId: string): string | undefined {
+  return AXE_RULE_FIX_HINTS[ruleId];
+}

package/src/a11y/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @mandujs/core/a11y — public surface.
+ *
+ * Accessibility audit runner (Phase 18.χ). Consumers typically reach
+ * for `runAudit` + `formatAuditReport`; the type exports are there so
+ * CI tooling can build typed gates on top of the report shape.
+ */
+
+export { runAudit, formatAuditReport } from "./run-audit";
+export { AXE_RULE_FIX_HINTS, getFixHint } from "./fix-hints";
+export { AUDIT_IMPACT_ORDER, impactAtLeast } from "./types";
+export type {
+  AuditImpact,
+  AuditNode,
+  AuditViolation,
+  AuditReport,
+  RunAuditOptions,
+} from "./types";