@mandujs/core 0.44.0 → 0.45.0

package/src/design/types.ts

@@ -0,0 +1,210 @@
+/**
+ * DESIGN.md type surface.
+ *
+ * The 9-section schema is borrowed verbatim from Google Stitch's
+ * DESIGN.md convention (also used by VoltAgent's awesome-design-md
+ * catalog of 69 brand spec files). Mandu adopts it as a first-class
+ * format rather than inventing its own — see Issue #245 v2 plan.
+ *
+ * Parsing is **permissive**: a DESIGN.md may include any subset of
+ * sections, in any order, with arbitrary free-form content between
+ * structured tokens. The parser populates the sections it understands
+ * and stores the rest as `rawBody` so round-trips don't lose user
+ * prose. Tools (Guard, MCP, token bridge) consume only the structured
+ * fields they care about.
+ *
+ * @module core/design/types
+ */
+
+export const DESIGN_SECTION_IDS = [
+  "theme",
+  "color-palette",
+  "typography",
+  "components",
+  "layout",
+  "shadows",
+  "dos-donts",
+  "responsive",
+  "agent-prompts",
+] as const;
+
+export type DesignSectionId = (typeof DESIGN_SECTION_IDS)[number];
+
+/**
+ * Color palette entry. `hex` may be missing when a row only carries a
+ * semantic role (e.g. "primary — brand color, see Stripe docs"); the
+ * Guard rule and the token bridge skip rows without a parseable value.
+ */
+export interface ColorToken {
+  name: string;
+  /** `#rrggbb`, `#rrggbbaa`, `rgb(...)`, `rgba(...)`, `oklch(...)`, etc. */
+  value?: string;
+  /** Functional role — "primary", "surface", "text-muted", … (free-form). */
+  role?: string;
+}
+
+export interface TypographyToken {
+  name: string;
+  fontFamily?: string;
+  weight?: string;
+  size?: string;
+  lineHeight?: string;
+  /** Free-form usage hint ("h1 hero", "body small", …). */
+  usage?: string;
+}
+
+export interface ComponentToken {
+  name: string;
+  /** Variants surfaced as a `name → list` map. Empty when not declared. */
+  variants: Record<string, string[]>;
+  /** Free-form description / props notes from markdown body. */
+  notes?: string;
+}
+
+export interface SpacingToken {
+  /** "xs", "sm", "md", "lg", "xl" — caller-defined. */
+  name: string;
+  value?: string;
+}
+
+export interface ShadowToken {
+  /** "card", "popover", "modal" — caller-defined elevation name. */
+  name: string;
+  value?: string;
+  /** Free-form usage hint. */
+  usage?: string;
+}
+
+export interface DoDontRule {
+  /** "do" or "dont" — Guard rule consumes "dont" as `forbidInlineClasses` candidates. */
+  kind: "do" | "dont";
+  /** Plain-text rule body. */
+  text: string;
+}
+
+export interface ResponsiveBreakpoint {
+  name: string;
+  value?: string;
+  /** Free-form notes (touch target, scaling strategy, …). */
+  notes?: string;
+}
+
+export interface AgentPrompt {
+  /** Heading or first sentence used as a label. */
+  title: string;
+  /** Body of the prompt — passed through verbatim. */
+  body: string;
+}
+
+/**
+ * Per-section payload. Every section carries:
+ *   - `present`: whether the heading was found at all
+ *   - `rawBody`: original markdown body for round-trip / fallback
+ *   - structured fields where applicable (`tokens`, `rules`, …)
+ *
+ * Tools that only care about presence (e.g. `mandu design validate`)
+ * read `present`; structured consumers (Guard, token bridge) read the
+ * typed fields and treat empties as "not declared".
+ */
+export interface DesignSection {
+  id: DesignSectionId;
+  present: boolean;
+  /** Heading line as written by the user (e.g. "## Color Palette"). */
+  headingText?: string;
+  /** Raw markdown body between this heading and the next H2. */
+  rawBody: string;
+}
+
+export interface ThemeSection extends DesignSection {
+  id: "theme";
+  /** First non-empty paragraph — quick "vibe" answer. */
+  summary?: string;
+}
+
+export interface ColorPaletteSection extends DesignSection {
+  id: "color-palette";
+  tokens: ColorToken[];
+}
+
+export interface TypographySection extends DesignSection {
+  id: "typography";
+  tokens: TypographyToken[];
+}
+
+export interface ComponentsSection extends DesignSection {
+  id: "components";
+  tokens: ComponentToken[];
+}
+
+export interface LayoutSection extends DesignSection {
+  id: "layout";
+  tokens: SpacingToken[];
+}
+
+export interface ShadowsSection extends DesignSection {
+  id: "shadows";
+  tokens: ShadowToken[];
+}
+
+export interface DosDontsSection extends DesignSection {
+  id: "dos-donts";
+  rules: DoDontRule[];
+}
+
+export interface ResponsiveSection extends DesignSection {
+  id: "responsive";
+  breakpoints: ResponsiveBreakpoint[];
+}
+
+export interface AgentPromptsSection extends DesignSection {
+  id: "agent-prompts";
+  prompts: AgentPrompt[];
+}
+
+export type AnyDesignSection =
+  | ThemeSection
+  | ColorPaletteSection
+  | TypographySection
+  | ComponentsSection
+  | LayoutSection
+  | ShadowsSection
+  | DosDontsSection
+  | ResponsiveSection
+  | AgentPromptsSection;
+
+export interface DesignSpec {
+  /** Original source string (for round-trip). */
+  source: string;
+  /**
+   * Sections in canonical order. `present: false` when the user omitted
+   * the section — Mandu still reserves the slot so consumers can index
+   * by id without `find()`.
+   */
+  sections: {
+    theme: ThemeSection;
+    "color-palette": ColorPaletteSection;
+    typography: TypographySection;
+    components: ComponentsSection;
+    layout: LayoutSection;
+    shadows: ShadowsSection;
+    "dos-donts": DosDontsSection;
+    responsive: ResponsiveSection;
+    "agent-prompts": AgentPromptsSection;
+  };
+  /** Extra H2 sections the user wrote that don't map to the 9-section spec. */
+  extraSections: Array<{ heading: string; body: string }>;
+  /** Optional H1 title at the top of the file. */
+  title?: string;
+}
+
+export interface ValidationIssue {
+  /** "missing" — section absent. "empty" — section present but no structured tokens. "malformed" — parse error inside a section. */
+  kind: "missing" | "empty" | "malformed";
+  section: DesignSectionId;
+  message: string;
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  issues: ValidationIssue[];
+}

package/src/guard/__tests__/design-inline-class.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Guard `DESIGN_INLINE_CLASS` rule tests (Issue #245 M2).
+ *
+ * Cover the three forbid-list sources (explicit / DESIGN.md auto /
+ * combined), the exclude paths (canonical component dirs), and the
+ * regex matcher's variant-prefix handling.
+ */
+import { describe, it, expect } from "bun:test";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { checkDesignInlineClasses } from "../design-inline-class";
+
+async function makeRoot(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), `mandu-design-guard-${prefix}-`));
+}
+
+async function writeFile(root: string, rel: string, content: string): Promise<void> {
+  const full = path.join(root, rel);
+  await fs.mkdir(path.dirname(full), { recursive: true });
+  await fs.writeFile(full, content);
+}
+
+describe("checkDesignInlineClasses", () => {
+  it("returns no violations when guard.design is undefined", async () => {
+    const root = await makeRoot("undef");
+    await writeFile(
+      root,
+      "src/client/page.tsx",
+      `export default () => <div className="btn-hard">x</div>;\n`,
+    );
+    const out = await checkDesignInlineClasses(root, undefined);
+    expect(out).toHaveLength(0);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("flags an inline forbidden class with line number", async () => {
+    const root = await makeRoot("flag");
+    await writeFile(
+      root,
+      "src/client/page.tsx",
+      `import * as React from 'react';
+
+export default () => (
+  <div className="px-4 py-2 btn-hard rounded-md">x</div>
+);
+`,
+    );
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+    });
+    expect(out).toHaveLength(1);
+    expect(out[0]?.ruleId).toBe("DESIGN_INLINE_CLASS");
+    expect(out[0]?.file.replace(/\\/g, "/")).toBe("src/client/page.tsx");
+    expect(out[0]?.line).toBe(4);
+    expect(out[0]?.message).toContain("btn-hard");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("surfaces the replacement component in the message + suggestion", async () => {
+    const root = await makeRoot("hint");
+    await writeFile(
+      root,
+      "src/client/page.tsx",
+      `<div className="btn-hard">x</div>`,
+    );
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+      requireComponent: { "btn-hard": "@/client/shared/ui#MButton" },
+    });
+    expect(out[0]?.message).toContain("@/client/shared/ui#MButton");
+    expect(out[0]?.suggestion).toContain("@/client/shared/ui#MButton");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("excludes the canonical component dirs by default", async () => {
+    const root = await makeRoot("exclude-default");
+    // The component definition itself uses btn-hard — that's where it
+    // legitimately lives. Default exclude must skip this file.
+    await writeFile(
+      root,
+      "src/client/shared/ui/m-button.tsx",
+      `<button className="btn-hard">x</button>`,
+    );
+    // A page that imports it must still be flagged.
+    await writeFile(
+      root,
+      "src/client/pages/home.tsx",
+      `<div className="btn-hard">x</div>`,
+    );
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+    });
+    const files = out.map((v) => v.file.replace(/\\/g, "/"));
+    expect(files).toContain("src/client/pages/home.tsx");
+    expect(files).not.toContain("src/client/shared/ui/m-button.tsx");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("strips Tailwind variant prefixes (hover:btn-hard matches btn-hard)", async () => {
+    const root = await makeRoot("variant");
+    await writeFile(
+      root,
+      "src/client/page.tsx",
+      `<div className="hover:btn-hard focus:btn-hard">x</div>`,
+    );
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+    });
+    expect(out.length).toBeGreaterThanOrEqual(1);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("auto-extracts forbid tokens from DESIGN.md §7 Don't section", async () => {
+    const root = await makeRoot("auto-design");
+    await writeFile(
+      root,
+      "DESIGN.md",
+      `# X
+
+## Do's & Don'ts
+
+### Do
+- Use the \`MButton\` component.
+
+### Don't
+- Inline \`btn-hard\` directly in pages.
+- Don't use \`shadow-hard\` outside ui/.
+`,
+    );
+    await writeFile(
+      root,
+      "src/client/page.tsx",
+      `<div className="btn-hard shadow-hard">x</div>`,
+    );
+    const out = await checkDesignInlineClasses(root, {
+      autoFromDesignMd: true,
+    });
+    const tokens = out.map((v) => v.message.match(/"([\w-]+)"/)?.[1]);
+    expect(tokens).toContain("btn-hard");
+    expect(tokens).toContain("shadow-hard");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("merges explicit forbid + DESIGN.md auto", async () => {
+    const root = await makeRoot("merge");
+    await writeFile(
+      root,
+      "DESIGN.md",
+      `## Do's & Don'ts
+
+### Don't
+- Avoid \`shadow-hard\`.
+`,
+    );
+    await writeFile(
+      root,
+      "src/client/page.tsx",
+      `<div className="btn-hard shadow-hard">x</div>`,
+    );
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+      autoFromDesignMd: true,
+    });
+    const tokens = out.map((v) => v.message.match(/"([\w-]+)"/)?.[1]);
+    expect(tokens).toContain("btn-hard");
+    expect(tokens).toContain("shadow-hard");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("scans both src/ and app/ when present", async () => {
+    const root = await makeRoot("dual-roots");
+    await writeFile(root, "src/x.tsx", `<div className="btn-hard">x</div>`);
+    await writeFile(root, "app/y.tsx", `<div className="btn-hard">y</div>`);
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+    });
+    const files = out.map((v) => v.file.replace(/\\/g, "/")).sort();
+    expect(files).toEqual(["app/y.tsx", "src/x.tsx"]);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("respects custom exclude patterns", async () => {
+    const root = await makeRoot("custom-exclude");
+    await writeFile(root, "src/legacy/old-page.tsx", `<div className="btn-hard">x</div>`);
+    const out = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+      exclude: ["src/legacy/**"],
+    });
+    expect(out).toHaveLength(0);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("honours severity setting on emitted violations", async () => {
+    const root = await makeRoot("severity");
+    await writeFile(root, "src/x.tsx", `<div className="btn-hard">x</div>`);
+    const errors = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+      severity: "error",
+    });
+    expect(errors[0]?.severity).toBe("error");
+    const warnings = await checkDesignInlineClasses(root, {
+      forbidInlineClasses: ["btn-hard"],
+      severity: "warning",
+    });
+    expect(warnings[0]?.severity).toBe("warning");
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it("returns nothing when forbid list resolves to empty", async () => {
+    const root = await makeRoot("empty-forbid");
+    await writeFile(root, "src/x.tsx", `<div className="btn-hard">x</div>`);
+    // No explicit list, autoFromDesignMd false → nothing to enforce.
+    const out = await checkDesignInlineClasses(root, {});
+    expect(out).toHaveLength(0);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+});

package/src/guard/check.ts

@@ -453,6 +453,21 @@ export async function runGuardCheck(
   violations.push(...slotContentViolations);
   violations.push(...contractViolations);
 
+  // ============================================
+  // Issue #245 — DESIGN.md-driven inline-class enforcement.
+  // Skipped silently when guard.design is undefined or has nothing
+  // to enforce (no explicit forbid list + autoFromDesignMd off).
+  // ============================================
+  const designConfig = (config.guard as { design?: unknown } | undefined)?.design;
+  if (designConfig && typeof designConfig === "object") {
+    const { checkDesignInlineClasses } = await import("./design-inline-class");
+    const designViolations = await checkDesignInlineClasses(
+      rootDir,
+      designConfig as Parameters<typeof checkDesignInlineClasses>[1],
+    );
+    violations.push(...designViolations);
+  }
+
   // ============================================
   // Phase 18.ν — Consumer-defined custom rules
   // ============================================