dslinter 0.1.13 → 0.2.0

package/src/playground/appPreviewTheme.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildAppPreviewTheme,
+  cssVariablesForPreviewTheme,
+  isConsumerThemeDefinition,
+  isDashboardThemePath,
+} from "./appPreviewTheme";
+import type { CssTokenDefinition, CssTokenSummary } from "../types/report";
+
+const root = "/Users/dev/demo-inertia";
+
+function def(
+  partial: Partial<CssTokenDefinition> & Pick<CssTokenDefinition, "name" | "value" | "scope">,
+): CssTokenDefinition {
+  return {
+    category: "other",
+    path: `${root}/resources/css/app.css`,
+    line: 1,
+    ...partial,
+  };
+}
+
+describe("isDashboardThemePath", () => {
+  it("flags dslinter dashboard theme files", () => {
+    expect(
+      isDashboardThemePath(
+        "/repo/packages/dashboard/src/styles/dashboard-theme.css",
+      ),
+    ).toBe(true);
+    expect(isDashboardThemePath("/repo/node_modules/dslinter/theme.css")).toBe(
+      true,
+    );
+  });
+});
+
+describe("isConsumerThemeDefinition", () => {
+  it("accepts app css under report root", () => {
+    expect(
+      isConsumerThemeDefinition(
+        def({ name: "--primary", value: "black", scope: "root" }),
+        root,
+      ),
+    ).toBe(true);
+  });
+
+  it("rejects dashboard theme paths", () => {
+    expect(
+      isConsumerThemeDefinition(
+        def({
+          name: "--primary",
+          value: "blue",
+          scope: "root",
+          path: "/repo/packages/dashboard/src/styles/dashboard-theme.css",
+        }),
+        root,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("buildAppPreviewTheme", () => {
+  it("extracts light root and dark selector tokens from consumer css", () => {
+    const summary: CssTokenSummary = {
+      definitions: [
+        def({
+          name: "--primary",
+          value: "oklch(0.205 0 0)",
+          scope: "root",
+          line: 71,
+        }),
+        def({
+          name: "--background",
+          value: "oklch(1 0 0)",
+          scope: "root",
+          line: 65,
+        }),
+        def({
+          name: "--color-primary",
+          value: "var(--primary)",
+          scope: "theme",
+          line: 29,
+        }),
+        def({
+          name: "--primary",
+          value: "oklch(0.985 0 0)",
+          scope: "selector",
+          line: 107,
+        }),
+        def({
+          name: "--background",
+          value: "oklch(0.145 0 0)",
+          scope: "selector",
+          line: 101,
+        }),
+        def({
+          name: "--primary",
+          value: "oklch(0.488 0.243 264.376)",
+          scope: "root",
+          path: "/repo/packages/dashboard/src/styles/dashboard-theme.css",
+          line: 100,
+        }),
+      ],
+      usage_by_token: [],
+    };
+
+    const theme = buildAppPreviewTheme(summary, root);
+    expect(theme).not.toBeNull();
+    expect(theme!.light["--primary"]).toBe("oklch(0.205 0 0)");
+    expect(theme!.light["--color-primary"]).toBe("oklch(0.205 0 0)");
+    expect(theme!.dark["--primary"]).toBe("oklch(0.985 0 0)");
+    expect(theme!.sourcePaths).toEqual([`${root}/resources/css/app.css`]);
+  });
+
+  it("returns null when only dashboard theme tokens exist", () => {
+    const summary: CssTokenSummary = {
+      definitions: [
+        def({
+          name: "--primary",
+          value: "blue",
+          scope: "root",
+          path: "/repo/packages/dashboard/src/styles/dashboard-theme.css",
+        }),
+      ],
+      usage_by_token: [],
+    };
+
+    expect(buildAppPreviewTheme(summary, root)).toBeNull();
+  });
+});
+
+describe("cssVariablesForPreviewTheme", () => {
+  it("merges dark overrides on top of light tokens", () => {
+    const theme = {
+      light: { "--background": "white", "--primary": "black" },
+      dark: { "--background": "black", "--primary": "white" },
+      sourcePaths: [],
+    };
+
+    expect(cssVariablesForPreviewTheme(theme, "light")).toEqual({
+      "--background": "white",
+      "--primary": "black",
+    });
+    expect(cssVariablesForPreviewTheme(theme, "dark")).toEqual({
+      "--background": "black",
+      "--primary": "white",
+    });
+  });
+});

package/src/playground/appPreviewTheme.ts

@@ -0,0 +1,137 @@
+import type { CssTokenDefinition, CssTokenSummary, WorkspaceReport } from "../types/report";
+
+const DASHBOARD_THEME_PATH_MARKERS = [
+  "dashboard-theme.css",
+  "dslinter/theme.css",
+] as const;
+
+export type AppPreviewTheme = {
+  light: Record<string, string>;
+  dark: Record<string, string>;
+  sourcePaths: string[];
+};
+
+export function isDashboardThemePath(path: string): boolean {
+  const normalized = path.replace(/\\/g, "/");
+  return DASHBOARD_THEME_PATH_MARKERS.some((marker) =>
+    normalized.includes(marker),
+  );
+}
+
+export function isConsumerThemeDefinition(
+  def: CssTokenDefinition,
+  reportRoot?: string,
+): boolean {
+  if (isDashboardThemePath(def.path)) return false;
+
+  const normalizedPath = def.path.replace(/\\/g, "/");
+  if (normalizedPath.includes("/packages/dashboard/")) return false;
+
+  if (reportRoot) {
+    const normalizedRoot = reportRoot.replace(/\\/g, "/").replace(/\/$/, "");
+    if (normalizedPath.startsWith(normalizedRoot)) return true;
+  }
+
+  return /(?:^|\/)(resources\/css|src\/|app\/|styles\/)/.test(normalizedPath);
+}
+
+function definitionsForMode(
+  definitions: CssTokenDefinition[],
+  mode: "light" | "dark",
+  reportRoot?: string,
+): Map<string, string> {
+  const scopes =
+    mode === "light"
+      ? new Set<CssTokenDefinition["scope"]>(["root", "theme"])
+      : new Set<CssTokenDefinition["scope"]>(["selector"]);
+
+  const vars = new Map<string, string>();
+  for (const def of definitions) {
+    if (!isConsumerThemeDefinition(def, reportRoot)) continue;
+    if (!scopes.has(def.scope)) continue;
+    if (!vars.has(def.name)) {
+      vars.set(def.name, def.value);
+    }
+  }
+  return vars;
+}
+
+function resolveCssVariables(vars: Map<string, string>): Record<string, string> {
+  const resolved = new Map<string, string>();
+  const varRefRe = /var\(\s*(--[a-zA-Z0-9_-]+)(?:\s*,[^)]+)?\s*\)/g;
+
+  const resolveOne = (name: string, seen: Set<string>): string => {
+    const cached = resolved.get(name);
+    if (cached != null) return cached;
+
+    const raw = vars.get(name);
+    if (raw == null) return `var(${name})`;
+    if (seen.has(name)) return raw;
+
+    seen.add(name);
+    const next = raw.replace(varRefRe, (_match, ref: string) => {
+      if (!vars.has(ref)) return `var(${ref})`;
+      return resolveOne(ref, seen);
+    });
+    seen.delete(name);
+    resolved.set(name, next);
+    return next;
+  };
+
+  for (const name of vars.keys()) {
+    resolveOne(name, new Set());
+  }
+
+  return Object.fromEntries(resolved);
+}
+
+export function buildAppPreviewTheme(
+  summary: CssTokenSummary | null | undefined,
+  reportRoot?: string,
+): AppPreviewTheme | null {
+  const definitions = summary?.definitions;
+  if (!definitions?.length) return null;
+
+  const light = resolveCssVariables(
+    definitionsForMode(definitions, "light", reportRoot),
+  );
+  const dark = resolveCssVariables(
+    definitionsForMode(definitions, "dark", reportRoot),
+  );
+
+  const sourcePaths = [
+    ...new Set(
+      definitions
+        .filter((def) => isConsumerThemeDefinition(def, reportRoot))
+        .map((def) => def.path.replace(/\\/g, "/")),
+    ),
+  ].sort();
+
+  const hasLightSemantic = Object.keys(light).some(
+    (name) => !name.startsWith("--color-") && !name.startsWith("--spacing-"),
+  );
+  const hasDarkSemantic = Object.keys(dark).some(
+    (name) => !name.startsWith("--color-") && !name.startsWith("--spacing-"),
+  );
+
+  if (!hasLightSemantic && !hasDarkSemantic) return null;
+
+  return { light, dark, sourcePaths };
+}
+
+export function buildAppPreviewThemeFromReport(
+  report: WorkspaceReport | null | undefined,
+): AppPreviewTheme | null {
+  if (!report?.css_tokens) return null;
+  return buildAppPreviewTheme(report.css_tokens, report.root);
+}
+
+export function cssVariablesForPreviewTheme(
+  theme: AppPreviewTheme,
+  mode: "light" | "dark",
+): Record<string, string> {
+  if (mode === "dark" && Object.keys(theme.dark).length > 0) {
+    return { ...theme.light, ...theme.dark };
+  }
+  return theme.light;
+}

package/src/playground/buildCompoundPlaygroundEntries.test.ts

@@ -0,0 +1,348 @@
+import { createElement, forwardRef, type ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import type { WorkspaceReport } from "../types/report";
+import {
+  buildCompoundPlaygroundEntries,
+  detectCompoundFamily,
+  findCompoundFamilies,
+} from "./buildCompoundPlaygroundEntries";
+import { buildPlaygroundEntriesFromReportWithSkips } from "./buildPlaygroundEntriesFromReport";
+import { resolvePlaygroundEntry } from "./buildPlaygroundEntriesFromReport";
+
+function dropdownModule() {
+  return {
+    Dropdown: ({ children }: { children?: ReactNode }) =>
+      createElement("div", { "data-root": "dropdown" }, children),
+    DropdownTrigger: ({ children }: { children?: ReactNode }) =>
+      createElement("button", { type: "button" }, children),
+    DropdownMenu: forwardRef(
+      (
+        {
+          children,
+          align,
+        }: {
+          children?: ReactNode;
+          align?: string;
+        },
+        _ref,
+      ) => createElement("div", { "data-menu": true, "data-align": align }, children),
+    ),
+    DropdownItem: forwardRef(({ children }: { children?: ReactNode }, _ref) =>
+      createElement("div", { "data-item": true }, children),
+    ),
+    DropdownSeparator: () => createElement("hr"),
+  };
+}
+
+describe("detectCompoundFamily", () => {
+  it("detects Dropdown compound family", () => {
+    const exports = new Map([
+      [
+        "Dropdown",
+        {
+          name: "Dropdown",
+          kind: "function" as const,
+          line: 1,
+          declared_props: ["open"],
+        },
+      ],
+      [
+        "DropdownTrigger",
+        {
+          name: "DropdownTrigger",
+          kind: "function" as const,
+          line: 2,
+          declared_props: ["children"],
+        },
+      ],
+      [
+        "DropdownMenu",
+        {
+          name: "DropdownMenu",
+          kind: "wrapped_component" as const,
+          line: 3,
+        },
+      ],
+      [
+        "DropdownItem",
+        {
+          name: "DropdownItem",
+          kind: "wrapped_component" as const,
+          line: 4,
+        },
+      ],
+    ]);
+
+    const family = detectCompoundFamily("resources/js/Components/Dropdown.jsx", exports);
+    expect(family).toMatchObject({
+      root: "Dropdown",
+      trigger: "DropdownTrigger",
+      content: "DropdownMenu",
+    });
+  });
+
+  it("detects shadcn-style kebab filenames with PascalCase root exports", () => {
+    const exports = new Map([
+      [
+        "DropdownMenu",
+        {
+          name: "DropdownMenu",
+          kind: "function" as const,
+          line: 1,
+        },
+      ],
+      [
+        "DropdownMenuTrigger",
+        {
+          name: "DropdownMenuTrigger",
+          kind: "function" as const,
+          line: 2,
+        },
+      ],
+      [
+        "DropdownMenuContent",
+        {
+          name: "DropdownMenuContent",
+          kind: "function" as const,
+          line: 3,
+        },
+      ],
+      [
+        "DropdownMenuItem",
+        {
+          name: "DropdownMenuItem",
+          kind: "function" as const,
+          line: 4,
+        },
+      ],
+    ]);
+
+    const family = detectCompoundFamily(
+      "resources/js/components/ui/dropdown-menu.tsx",
+      exports,
+      "ui",
+    );
+    expect(family).toMatchObject({
+      root: "DropdownMenu",
+      trigger: "DropdownMenuTrigger",
+      content: "DropdownMenuContent",
+      group: "ui",
+    });
+  });
+
+  it("returns null for single-export file", () => {
+    const exports = new Map([
+      [
+        "Button",
+        {
+          name: "Button",
+          kind: "function" as const,
+          line: 1,
+        },
+      ],
+    ]);
+    expect(detectCompoundFamily("src/components/Button.tsx", exports)).toBeNull();
+  });
+});
+
+describe("buildCompoundPlaygroundEntries", () => {
+  const report: WorkspaceReport = {
+    root: "/repo",
+    files: [
+      {
+        path: "/repo/resources/js/Components/Dropdown.jsx",
+        definitions: [
+          {
+            name: "Dropdown",
+            kind: "function",
+            line: 1,
+            declared_props: ["open"],
+          },
+          {
+            name: "DropdownTrigger",
+            kind: "function",
+            line: 2,
+            declared_props: ["children"],
+          },
+          {
+            name: "DropdownMenu",
+            kind: "wrapped_component",
+            line: 3,
+          },
+          {
+            name: "DropdownItem",
+            kind: "wrapped_component",
+            line: 4,
+          },
+          {
+            name: "DropdownSeparator",
+            kind: "wrapped_component",
+            line: 5,
+          },
+        ],
+        usages: [],
+        parse_errors: [],
+      },
+    ],
+    findings: [],
+    scores: {
+      design_system_health: 0,
+      ux_consistency: 0,
+      accessibility: 0,
+      maintainability: 0,
+    },
+    duplicate_components: [],
+    usage_by_component: [
+      {
+        component: "DropdownMenu",
+        reference_count: 10,
+        file_count: 5,
+        max_props_on_single_use: 2,
+        files: [],
+        prop_frequencies: { align: 10, children: 10 },
+        prop_value_frequencies: { align: { end: 8, start: 2 } },
+      },
+    ],
+    playgrounds: [
+      {
+        id: "Dropdown",
+        export_name: "Dropdown",
+        rel_path: "resources/js/Components/Dropdown.jsx",
+        declared_props: ["open"],
+      },
+    ],
+  };
+
+  const modules = {
+    "@dslinter-scan/resources/js/Components/Dropdown.jsx": dropdownModule(),
+  };
+
+  it("finds compound families from report", () => {
+    const families = findCompoundFamilies(report);
+    expect(families).toHaveLength(1);
+    expect(families[0]?.root).toBe("Dropdown");
+  });
+
+  it("builds DropdownMenu compound entry with align select control", () => {
+    const entries = buildCompoundPlaygroundEntries(report, modules, {
+      globKeyFromRelPath: (rel) => `@dslinter-scan/${rel}`,
+      existingIds: new Set(["Dropdown"]),
+    });
+    const menu = entries.find((e) => e.id === "DropdownMenu");
+    expect(menu).toBeDefined();
+    const align = menu!.controls.find((c) => c.key === "align");
+    expect(align?.type).toBe("select");
+    if (align?.type === "select") {
+      expect(align.options.map((o) => o.value)).toEqual(["end", "start"]);
+    }
+  });
+
+  it("renders compound tree for DropdownMenu", () => {
+    const entries = buildCompoundPlaygroundEntries(report, modules, {
+      globKeyFromRelPath: (rel) => `@dslinter-scan/${rel}`,
+      existingIds: new Set(["Dropdown"]),
+    });
+    const menu = entries.find((e) => e.id === "DropdownMenu")!;
+    const html = renderToStaticMarkup(createElement(menu.Preview, { values: { align: "end" } }));
+    expect(html).toContain('data-root="dropdown"');
+    expect(html).toContain("Open menu");
+    expect(html).toContain('data-menu="true"');
+    expect(html).toContain('data-align="end"');
+  });
+
+  it("merges compound entries in buildPlaygroundEntriesFromReportWithSkips", () => {
+    const { entries } = buildPlaygroundEntriesFromReportWithSkips(report, modules, {
+      logJoinSkips: false,
+    });
+    expect(resolvePlaygroundEntry(entries, "Dropdown")).toBeDefined();
+    expect(resolvePlaygroundEntry(entries, "DropdownMenu")).toBeDefined();
+    expect(resolvePlaygroundEntry(entries, "DropdownItem")).toBeDefined();
+  });
+
+  it("upgrades shadcn DropdownMenu root to composed content preview", () => {
+    const relPath = "resources/js/components/ui/dropdown-menu.tsx";
+    const shadcnReport: WorkspaceReport = {
+      root: "/repo",
+      files: [
+        {
+          path: `/repo/${relPath}`,
+          definitions: [
+            { name: "DropdownMenu", kind: "function", line: 1, declared_props: ["open"] },
+            {
+              name: "DropdownMenuTrigger",
+              kind: "function",
+              line: 2,
+              declared_props: ["children"],
+            },
+            {
+              name: "DropdownMenuContent",
+              kind: "function",
+              line: 3,
+              declared_props: ["align"],
+            },
+            { name: "DropdownMenuItem", kind: "function", line: 4, declared_props: [] },
+          ],
+          usages: [],
+          parse_errors: [],
+        },
+      ],
+      findings: [],
+      scores: {
+        design_system_health: 0,
+        ux_consistency: 0,
+        accessibility: 0,
+        maintainability: 0,
+      },
+      duplicate_components: [],
+      usage_by_component: [
+        {
+          component: "DropdownMenuContent",
+          reference_count: 5,
+          file_count: 2,
+          max_props_on_single_use: 1,
+          files: [],
+          prop_frequencies: { align: 5 },
+          prop_value_frequencies: { align: { end: 4, start: 1 } },
+        },
+      ],
+      playgrounds: [
+        {
+          id: "DropdownMenu",
+          export_name: "DropdownMenu",
+          rel_path: relPath,
+          declared_props: ["open"],
+        },
+      ],
+    };
+    const shadcnModules = {
+      "@dslinter-scan/resources/js/components/ui/dropdown-menu.tsx": {
+        DropdownMenu: ({ children }: { children?: ReactNode }) =>
+          createElement("div", { "data-root": "dropdown-menu" }, children),
+        DropdownMenuTrigger: ({ children }: { children?: ReactNode }) =>
+          createElement("button", { type: "button" }, children),
+        DropdownMenuContent: ({
+          children,
+          align,
+        }: {
+          children?: ReactNode;
+          align?: string;
+        }) => createElement("div", { "data-content": true, "data-align": align }, children),
+        DropdownMenuItem: ({ children }: { children?: ReactNode }) =>
+          createElement("div", { "data-item": true }, children),
+      },
+    };
+    const { entries } = buildPlaygroundEntriesFromReportWithSkips(shadcnReport, shadcnModules, {
+      globKeyFromRelPath: (rel) => `@dslinter-scan/${rel}`,
+      logJoinSkips: false,
+    });
+    const root = resolvePlaygroundEntry(entries, "DropdownMenu");
+    expect(root?.id).toBe("DropdownMenu");
+    const align = root!.controls.find((c) => c.key === "align");
+    expect(align?.type).toBe("select");
+    const html = renderToStaticMarkup(createElement(root!.Preview, { values: { align: "end" } }));
+    expect(html).toContain('data-root="dropdown-menu"');
+    expect(html).toContain('data-content="true"');
+    expect(html).toContain('data-align="end"');
+  });
+});