@mandujs/core 0.51.0 → 0.53.0

package/src/design/diff.ts

@@ -0,0 +1,138 @@
+/**
+ * DESIGN.md upstream diff (Issue #245 M4 §3.5 external loop).
+ *
+ * Compare a local DESIGN.md against an upstream source (typically a
+ * brand spec from awesome-design-md). The diff is computed at the
+ * **structured-token level** — added / changed / removed entries per
+ * section — so agents can patch only the sections the user wants to
+ * sync without touching free-form prose.
+ *
+ * The diff is intentionally narrow: it ignores prose changes inside
+ * `rawBody`, comment shifts, and heading wording differences. It
+ * answers one question — "did the upstream catalog gain, change, or
+ * drop a token compared to my local file?".
+ */
+
+import type { ColorToken, DesignSpec, ShadowToken, SpacingToken, TypographyToken } from "./types";
+
+export interface DiffEntryAddedRemoved<T> {
+  kind: "added" | "removed";
+  name: string;
+  token: T;
+}
+
+export interface DiffEntryChanged<T> {
+  kind: "changed";
+  name: string;
+  before: T;
+  after: T;
+}
+
+export type DiffEntry<T> =
+  | DiffEntryAddedRemoved<T>
+  | DiffEntryChanged<T>;
+
+export interface DesignSpecDiff {
+  /** Per-section diff arrays (only structured sections). */
+  colorPalette: DiffEntry<ColorToken>[];
+  typography: DiffEntry<TypographyToken>[];
+  layout: DiffEntry<SpacingToken>[];
+  shadows: DiffEntry<ShadowToken>[];
+  /** Total count of differences across all sections — convenience. */
+  totalChanges: number;
+  /** Sections whose `present` flag flipped between local and upstream. */
+  sectionPresenceChanged: string[];
+}
+
+/**
+ * Compute the diff. Pure — accepts already-parsed specs so callers
+ * own fetching / caching of the upstream source.
+ */
+export function diffDesignSpecs(local: DesignSpec, upstream: DesignSpec): DesignSpecDiff {
+  const colorPalette = diffByName(
+    local.sections["color-palette"].tokens,
+    upstream.sections["color-palette"].tokens,
+    (a, b) => a.value === b.value && a.role === b.role,
+  );
+  const typography = diffByName(
+    local.sections.typography.tokens,
+    upstream.sections.typography.tokens,
+    (a, b) =>
+      a.fontFamily === b.fontFamily &&
+      a.size === b.size &&
+      a.weight === b.weight &&
+      a.lineHeight === b.lineHeight,
+  );
+  const layout = diffByName(
+    local.sections.layout.tokens,
+    upstream.sections.layout.tokens,
+    (a, b) => a.value === b.value,
+  );
+  const shadows = diffByName(
+    local.sections.shadows.tokens,
+    upstream.sections.shadows.tokens,
+    (a, b) => a.value === b.value,
+  );
+
+  const sectionPresenceChanged: string[] = [];
+  for (const id of [
+    "theme",
+    "color-palette",
+    "typography",
+    "components",
+    "layout",
+    "shadows",
+    "dos-donts",
+    "responsive",
+    "agent-prompts",
+  ] as const) {
+    if (local.sections[id].present !== upstream.sections[id].present) {
+      sectionPresenceChanged.push(id);
+    }
+  }
+
+  const totalChanges = colorPalette.length + typography.length + layout.length + shadows.length;
+  return { colorPalette, typography, layout, shadows, totalChanges, sectionPresenceChanged };
+}
+
+interface NamedToken {
+  name: string;
+}
+
+function diffByName<T extends NamedToken>(
+  local: readonly T[],
+  upstream: readonly T[],
+  same: (a: T, b: T) => boolean,
+): DiffEntry<T>[] {
+  const localByKey = new Map<string, T>();
+  for (const t of local) localByKey.set(slug(t.name), t);
+  const upstreamByKey = new Map<string, T>();
+  for (const t of upstream) upstreamByKey.set(slug(t.name), t);
+
+  const entries: DiffEntry<T>[] = [];
+  for (const [key, upstreamToken] of upstreamByKey) {
+    const localToken = localByKey.get(key);
+    if (!localToken) {
+      entries.push({ kind: "added", name: upstreamToken.name, token: upstreamToken });
+      continue;
+    }
+    if (!same(localToken, upstreamToken)) {
+      entries.push({ kind: "changed", name: upstreamToken.name, before: localToken, after: upstreamToken });
+    }
+  }
+  for (const [key, localToken] of localByKey) {
+    if (!upstreamByKey.has(key)) {
+      entries.push({ kind: "removed", name: localToken.name, token: localToken });
+    }
+  }
+  return entries;
+}
+
+function slug(name: string): string {
+  return name
+    .normalize("NFKD")
+    .replace(/[^\w\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .toLowerCase();
+}

package/src/design/extract.ts

@@ -0,0 +1,284 @@
+/**
+ * DESIGN.md token extractor — scan project source for tokens that
+ * should be promoted into DESIGN.md (Issue #245 M4 §3.5 internal loop).
+ *
+ * Scope:
+ *   - **color**: `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb(...)`, `rgba(...)`,
+ *     `hsl(...)`, `oklch(...)` literals in TS/TSX/JSX/CSS/MDX sources.
+ *   - **font-family**: `font-family: "X", sans-serif` declarations and
+ *     Tailwind v4-style `--font-<slug>: ...;` tokens that don't yet
+ *     appear in DESIGN.md typography.
+ *   - **component**: identifier-style className combos that recur 3+
+ *     times across files, suggesting a missing extraction.
+ *
+ * The extractor is **proposal-only**: it never edits anything.
+ * Callers (CLI / MCP `mandu.design.extract`) decide whether to flow
+ * the proposals into DESIGN.md via `patchDesignMd`. Confidence is a
+ * coarse 0..1 score driven by occurrence count; agents can filter on
+ * it before showing the user.
+ *
+ * Performance: the walker bounds itself to the conventional source
+ * roots and skips dotfile dirs / node_modules. Large monorepos can
+ * narrow further with the `scope` option.
+ */
+
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import type { DesignSpec } from "./types";
+
+// ─── Public surface ───────────────────────────────────────────────────
+
+export type ExtractKind = "color" | "typography" | "spacing" | "component";
+
+export interface ExtractProposal {
+  kind: ExtractKind;
+  /** DESIGN.md section the proposal would land in. */
+  section: "color-palette" | "typography" | "layout" | "components";
+  /** Stable key to compare against existing tokens (slug or literal). */
+  key: string;
+  /** Suggested DESIGN.md value (`#FF8C42`, `Inter sans-serif`, …). */
+  value: string;
+  /** Total occurrences across the scanned tree. */
+  occurrences: number;
+  /** Up to 5 distinct file paths the literal/pattern was found in. */
+  files: string[];
+  /** Coarse 0..1 confidence — higher = more occurrences. */
+  confidence: number;
+  /** Optional human note ("seen in ButtonPrimary, ButtonGhost"). */
+  note?: string;
+}
+
+export interface ExtractOptions {
+  /** Glob-rooted scopes (relative). Defaults to `["src", "app"]`. */
+  scope?: readonly string[];
+  /** Filter the kinds emitted. Defaults to all four. */
+  kinds?: readonly ExtractKind[];
+  /** Minimum occurrence threshold for color/font/component. Default 3. */
+  minOccurrences?: number;
+  /**
+   * When provided, proposals already represented by an existing
+   * DesignSpec token are dropped (so agents only see "new" candidates).
+   */
+  existing?: DesignSpec;
+}
+
+export interface ExtractResult {
+  proposals: ExtractProposal[];
+  /** Total source files scanned. */
+  scannedFiles: number;
+}
+
+/**
+ * Walk the project and collect proposals. Pure async — no caching, no
+ * side effects beyond reads.
+ */
+export async function extractDesignTokens(
+  rootDir: string,
+  options: ExtractOptions = {},
+): Promise<ExtractResult> {
+  const scope = options.scope ?? ["src", "app"];
+  const kinds = new Set<ExtractKind>(options.kinds ?? ["color", "typography", "spacing", "component"]);
+  const minOccurrences = options.minOccurrences ?? 3;
+
+  const colorOccurrences = new Map<string, { files: Set<string>; count: number }>();
+  const fontFamilyOccurrences = new Map<string, { files: Set<string>; count: number }>();
+  const classnameComboOccurrences = new Map<string, { files: Set<string>; count: number }>();
+
+  let scannedFiles = 0;
+  for (const dir of scope) {
+    const root = path.join(rootDir, dir);
+    const files = await collectFiles(root);
+    scannedFiles += files.length;
+    for (const file of files) {
+      let content: string;
+      try {
+        content = await fs.readFile(file, "utf8");
+      } catch {
+        continue;
+      }
+      const rel = path.relative(rootDir, file).replace(/\\/g, "/");
+      if (kinds.has("color")) collectColors(content, rel, colorOccurrences);
+      if (kinds.has("typography")) collectFontFamilies(content, rel, fontFamilyOccurrences);
+      if (kinds.has("component")) collectClassNameCombos(content, rel, classnameComboOccurrences);
+    }
+  }
+
+  const proposals: ExtractProposal[] = [];
+  if (kinds.has("color")) {
+    proposals.push(
+      ...buildProposals({
+        section: "color-palette",
+        kind: "color",
+        keyer: (literal) => literal,
+        valuer: (literal) => literal,
+        seed: colorOccurrences,
+        minOccurrences,
+        existingKeys: collectExistingColorValues(options.existing),
+      }),
+    );
+  }
+  if (kinds.has("typography")) {
+    proposals.push(
+      ...buildProposals({
+        section: "typography",
+        kind: "typography",
+        keyer: (literal) => literal,
+        valuer: (literal) => literal,
+        seed: fontFamilyOccurrences,
+        minOccurrences,
+        existingKeys: collectExistingFontFamilies(options.existing),
+      }),
+    );
+  }
+  if (kinds.has("component")) {
+    proposals.push(
+      ...buildProposals({
+        section: "components",
+        kind: "component",
+        keyer: (literal) => literal,
+        valuer: (literal) => literal,
+        seed: classnameComboOccurrences,
+        minOccurrences,
+        existingKeys: new Set(),
+      }),
+    );
+  }
+
+  proposals.sort((a, b) => b.occurrences - a.occurrences);
+  return { proposals, scannedFiles };
+}
+
+// ─── Walker ───────────────────────────────────────────────────────────
+
+const SOURCE_RX = /\.(?:tsx?|jsx?|mdx?|css)$/;
+
+async function collectFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+        await walk(full);
+      } else if (entry.isFile() && SOURCE_RX.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+// ─── Collectors ───────────────────────────────────────────────────────
+
+const COLOR_RX = /#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|(?:rgba?|hsla?|oklch|hwb|lab|lch)\([^)]+\)/g;
+
+function collectColors(
+  content: string,
+  rel: string,
+  bucket: Map<string, { files: Set<string>; count: number }>,
+): void {
+  let m: RegExpExecArray | null;
+  while ((m = COLOR_RX.exec(content)) !== null) {
+    const literal = m[0]!.toLowerCase();
+    const entry = bucket.get(literal) ?? { files: new Set(), count: 0 };
+    entry.files.add(rel);
+    entry.count++;
+    bucket.set(literal, entry);
+  }
+}
+
+const FONT_FAMILY_RX = /font-family\s*:\s*([^;\n}]+)/gi;
+
+function collectFontFamilies(
+  content: string,
+  rel: string,
+  bucket: Map<string, { files: Set<string>; count: number }>,
+): void {
+  let m: RegExpExecArray | null;
+  while ((m = FONT_FAMILY_RX.exec(content)) !== null) {
+    const value = m[1]!.trim().replace(/[`'"]/g, "");
+    if (!value || value.length > 200) continue;
+    const entry = bucket.get(value) ?? { files: new Set(), count: 0 };
+    entry.files.add(rel);
+    entry.count++;
+    bucket.set(value, entry);
+  }
+}
+
+const CLASSNAME_RX = /className\s*=\s*["']([^"']{16,200})["']/g;
+
+function collectClassNameCombos(
+  content: string,
+  rel: string,
+  bucket: Map<string, { files: Set<string>; count: number }>,
+): void {
+  let m: RegExpExecArray | null;
+  while ((m = CLASSNAME_RX.exec(content)) !== null) {
+    const literal = m[1]!.trim().split(/\s+/).sort().join(" ");
+    if (!literal) continue;
+    // Skip combos that are mostly variant prefixes — they're rarely
+    // good extraction candidates.
+    const tokenCount = literal.split(/\s+/).length;
+    if (tokenCount < 3) continue;
+    const entry = bucket.get(literal) ?? { files: new Set(), count: 0 };
+    entry.files.add(rel);
+    entry.count++;
+    bucket.set(literal, entry);
+  }
+}
+
+// ─── Proposal builder ────────────────────────────────────────────────
+
+interface BuildProposalsArgs {
+  section: ExtractProposal["section"];
+  kind: ExtractKind;
+  keyer: (literal: string) => string;
+  valuer: (literal: string) => string;
+  seed: Map<string, { files: Set<string>; count: number }>;
+  minOccurrences: number;
+  existingKeys: Set<string>;
+}
+
+function buildProposals(args: BuildProposalsArgs): ExtractProposal[] {
+  const out: ExtractProposal[] = [];
+  for (const [literal, info] of args.seed) {
+    if (info.count < args.minOccurrences) continue;
+    const key = args.keyer(literal).toLowerCase();
+    if (args.existingKeys.has(key)) continue;
+    out.push({
+      kind: args.kind,
+      section: args.section,
+      key: literal,
+      value: args.valuer(literal),
+      occurrences: info.count,
+      files: [...info.files].slice(0, 5),
+      confidence: Math.min(1, info.count / 10),
+    });
+  }
+  return out;
+}
+
+function collectExistingColorValues(spec: DesignSpec | undefined): Set<string> {
+  const out = new Set<string>();
+  if (!spec) return out;
+  for (const t of spec.sections["color-palette"].tokens) {
+    if (t.value) out.add(t.value.toLowerCase());
+  }
+  return out;
+}
+
+function collectExistingFontFamilies(spec: DesignSpec | undefined): Set<string> {
+  const out = new Set<string>();
+  if (!spec) return out;
+  for (const t of spec.sections.typography.tokens) {
+    if (t.fontFamily) out.add(t.fontFamily.toLowerCase());
+  }
+  return out;
+}

package/src/design/index.ts

@@ -34,6 +34,45 @@ export {
   type ThemeMergeResult,
 } from "./tailwind-theme";
 
+export {
+  extractDesignTokens,
+  type ExtractKind,
+  type ExtractOptions,
+  type ExtractProposal,
+  type ExtractResult,
+} from "./extract";
+
+export {
+  patchDesignMd,
+  patchDesignMdBatch,
+  type PatchableSection,
+  type PatchOperation,
+  type PatchResult,
+  type PatchBatchResult,
+} from "./patch";
+
+export {
+  diffDesignSpecs,
+  type DesignSpecDiff,
+  type DiffEntry,
+} from "./diff";
+
+export {
+  buildAgentsDesignBlock,
+  linkAgentsToDesignMd,
+  DESIGN_LINK_MARKER_START,
+  DESIGN_LINK_MARKER_END,
+  type LinkAgentsOptions,
+  type LinkAgentsResult,
+} from "./agents-link";
+
+export {
+  lintDesignSpec,
+  type LintIssue,
+  type LintResult,
+  type LintSeverity,
+} from "./lint";
+
 export type {
   AgentPrompt,
   AgentPromptsSection,

package/src/design/lint.ts

@@ -0,0 +1,209 @@
+/**
+ * DESIGN.md self-consistency lint (Issue #245 M5).
+ *
+ * Different from `validateDesignSpec` (M1), which reports section
+ * presence / shape. The linter checks the *content* for issues that
+ * compile fine but waste reader time:
+ *
+ *   - color-palette: hex values that aren't 3/6/8 digits, duplicate
+ *     hex values across distinct names, slug collisions across names
+ *   - typography: tokens missing both `fontFamily` and `size`,
+ *     duplicate display-name slugs
+ *   - layout / shadows: tokens with no value, duplicate slugs
+ *   - components: duplicate H3 names
+ *   - dos-donts: rules under §7 with no `do` / `don't` mode marker
+ *
+ * The linter is conservative — every rule is opt-out via severity
+ * filtering at the call site. The tool returns `{ ok, issues[] }`
+ * so CLIs can produce exit codes and MCP tools can stream the issue
+ * list.
+ */
+
+import { slugifyTokenName } from "./tailwind-theme";
+import type { DesignSpec } from "./types";
+
+export type LintSeverity = "error" | "warning" | "info";
+
+export interface LintIssue {
+  rule: string;
+  section:
+    | "color-palette"
+    | "typography"
+    | "layout"
+    | "shadows"
+    | "components"
+    | "dos-donts"
+    | "agent-prompts"
+    | "responsive";
+  severity: LintSeverity;
+  message: string;
+  /** Token / row name when the issue is per-row. */
+  name?: string;
+}
+
+export interface LintResult {
+  ok: boolean;
+  issues: LintIssue[];
+}
+
+const HEX_RX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const COLOR_FN_RX = /^(rgba?|hsla?|oklch|hwb|lab|lch)\(/i;
+
+export function lintDesignSpec(spec: DesignSpec): LintResult {
+  const issues: LintIssue[] = [];
+
+  // ─── color-palette ────────────────────────────────────────────────
+  const seenColorSlug = new Map<string, string>();
+  const seenColorValue = new Map<string, string>();
+  for (const token of spec.sections["color-palette"].tokens) {
+    if (!token.value) {
+      issues.push({
+        rule: "color-missing-value",
+        section: "color-palette",
+        severity: "warning",
+        message: `Color "${token.name}" has no parseable value — Tailwind sync will skip it.`,
+        name: token.name,
+      });
+      continue;
+    }
+    if (!HEX_RX.test(token.value) && !COLOR_FN_RX.test(token.value)) {
+      issues.push({
+        rule: "color-malformed-value",
+        section: "color-palette",
+        severity: "error",
+        message: `Color "${token.name}" value "${token.value}" is not a recognised hex/rgb/hsl/oklch literal.`,
+        name: token.name,
+      });
+    }
+    const sl = slugifyTokenName(token.name);
+    const prevByName = seenColorSlug.get(sl);
+    if (prevByName) {
+      issues.push({
+        rule: "color-slug-collision",
+        section: "color-palette",
+        severity: "warning",
+        message: `Color "${token.name}" slugifies to the same id as "${prevByName}" — Tailwind sync keeps only the first.`,
+        name: token.name,
+      });
+    } else {
+      seenColorSlug.set(sl, token.name);
+    }
+    const prevByValue = seenColorValue.get(token.value.toLowerCase());
+    if (prevByValue && prevByValue !== token.name) {
+      issues.push({
+        rule: "color-duplicate-value",
+        section: "color-palette",
+        severity: "info",
+        message: `Color "${token.name}" shares value ${token.value} with "${prevByValue}" — consider a single canonical name.`,
+        name: token.name,
+      });
+    } else {
+      seenColorValue.set(token.value.toLowerCase(), token.name);
+    }
+  }
+
+  // ─── typography ──────────────────────────────────────────────────
+  const seenTypoSlug = new Map<string, string>();
+  for (const token of spec.sections.typography.tokens) {
+    if (!token.fontFamily && !token.size) {
+      issues.push({
+        rule: "typography-empty-token",
+        section: "typography",
+        severity: "warning",
+        message: `Typography token "${token.name}" has neither fontFamily nor size — nothing to sync.`,
+        name: token.name,
+      });
+    }
+    const sl = slugifyTokenName(token.name);
+    const prev = seenTypoSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "typography-slug-collision",
+        section: "typography",
+        severity: "warning",
+        message: `Typography "${token.name}" collides with "${prev}" on slug "${sl}".`,
+        name: token.name,
+      });
+    } else {
+      seenTypoSlug.set(sl, token.name);
+    }
+  }
+
+  // ─── layout (spacing) ────────────────────────────────────────────
+  const seenLayoutSlug = new Map<string, string>();
+  for (const token of spec.sections.layout.tokens) {
+    if (!token.value) {
+      issues.push({
+        rule: "spacing-missing-value",
+        section: "layout",
+        severity: "warning",
+        message: `Spacing "${token.name}" has no value.`,
+        name: token.name,
+      });
+      continue;
+    }
+    const sl = slugifyTokenName(token.name);
+    const prev = seenLayoutSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "spacing-slug-collision",
+        section: "layout",
+        severity: "warning",
+        message: `Spacing "${token.name}" collides with "${prev}" on slug "${sl}".`,
+        name: token.name,
+      });
+    } else {
+      seenLayoutSlug.set(sl, token.name);
+    }
+  }
+
+  // ─── shadows ─────────────────────────────────────────────────────
+  const seenShadowSlug = new Map<string, string>();
+  for (const token of spec.sections.shadows.tokens) {
+    if (!token.value) {
+      issues.push({
+        rule: "shadow-missing-value",
+        section: "shadows",
+        severity: "warning",
+        message: `Shadow "${token.name}" has no value.`,
+        name: token.name,
+      });
+      continue;
+    }
+    const sl = slugifyTokenName(token.name);
+    const prev = seenShadowSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "shadow-slug-collision",
+        section: "shadows",
+        severity: "warning",
+        message: `Shadow "${token.name}" collides with "${prev}" on slug "${sl}".`,
+        name: token.name,
+      });
+    } else {
+      seenShadowSlug.set(sl, token.name);
+    }
+  }
+
+  // ─── components ──────────────────────────────────────────────────
+  const seenComponentSlug = new Map<string, string>();
+  for (const token of spec.sections.components.tokens) {
+    const sl = slugifyTokenName(token.name);
+    const prev = seenComponentSlug.get(sl);
+    if (prev) {
+      issues.push({
+        rule: "component-duplicate",
+        section: "components",
+        severity: "warning",
+        message: `Component "${token.name}" appears twice (also as "${prev}").`,
+        name: token.name,
+      });
+    } else {
+      seenComponentSlug.set(sl, token.name);
+    }
+  }
+
+  // The most critical level of severity wins for the `ok` flag.
+  const ok = !issues.some((i) => i.severity === "error");
+  return { ok, issues };
+}