dslinter 0.2.3 → 0.3.0

package/src/dashboard/aggregate.test.ts

@@ -1,6 +1,15 @@
 import { describe, expect, it } from "vitest";
 import type { WorkspaceReport } from "../types/report";
-import { componentCatalogFamiliesFromReport, componentCatalogTreeFromReport } from "./aggregate";
+import {
+  componentCatalogFamiliesFromReport,
+  componentCatalogNamesFromReport,
+  componentCatalogTreeFromReport,
+  fileStemToCatalogGroupLabel,
+  findingsForGovernanceTab,
+  governanceTabCounts,
+  resolveFamilyNavigationTarget,
+  unusedComponentsFromReport,
+} from "./aggregate";
 
 function reportWithDefinitions(
   definitions: WorkspaceReport["files"][number]["definitions"],
@@ -28,8 +37,16 @@ function reportWithDefinitions(
   };
 }
 
+describe("fileStemToCatalogGroupLabel", () => {
+  it("converts kebab-case file stems to PascalCase group labels", () => {
+    expect(fileStemToCatalogGroupLabel("hover-card")).toBe("HoverCard");
+    expect(fileStemToCatalogGroupLabel("dropdown-menu")).toBe("DropdownMenu");
+    expect(fileStemToCatalogGroupLabel("icons")).toBe("Icons");
+  });
+});
+
 describe("componentCatalogFamiliesFromReport", () => {
-  it("groups shadcn-style kebab filename exports under the normalized root", () => {
+  it("groups multi-export files under the filename stem", () => {
     const report = reportWithDefinitions([
       { name: "DropdownMenu", kind: "function", line: 1 },
       { name: "DropdownMenuContent", kind: "function", line: 2 },
@@ -40,12 +57,36 @@ describe("componentCatalogFamiliesFromReport", () => {
     expect(componentCatalogFamiliesFromReport(report)).toEqual([
       {
         parent: "DropdownMenu",
-        children: ["DropdownMenuContent", "DropdownMenuItem", "DropdownMenuTrigger"],
+        children: [
+          "DropdownMenu",
+          "DropdownMenuContent",
+          "DropdownMenuItem",
+          "DropdownMenuTrigger",
+        ],
         path: "/repo/src/components/ui/dropdown-menu.tsx",
       },
     ]);
   });
 
+  it("groups icon-style sibling exports under the filename stem", () => {
+    const report = reportWithDefinitions(
+      [
+        { name: "IconSearch", kind: "wrapped_component", line: 15 },
+        { name: "IconCheck", kind: "wrapped_component", line: 31 },
+        { name: "IconChevronDown", kind: "wrapped_component", line: 46 },
+      ],
+      "/repo/src/components/icons.tsx",
+    );
+
+    expect(componentCatalogFamiliesFromReport(report)).toEqual([
+      {
+        parent: "Icons",
+        children: ["IconCheck", "IconChevronDown", "IconSearch"],
+        path: "/repo/src/components/icons.tsx",
+      },
+    ]);
+  });
+
   it("leaves single export files flat", () => {
     const report = reportWithDefinitions(
       [{ name: "Button", kind: "function", line: 1 }],
@@ -53,22 +94,350 @@ describe("componentCatalogFamiliesFromReport", () => {
     );
 
     expect(componentCatalogFamiliesFromReport(report)).toEqual([]);
-    expect(componentCatalogTreeFromReport(report)).toEqual([{ type: "component", name: "Button" }]);
+    expect(componentCatalogTreeFromReport(report)).toEqual([
+      { type: "component", name: "Button" },
+    ]);
   });
 
-  it("does not group sibling exports when no export matches the filename root", () => {
+  it("folds usage-only root exports into the file group instead of duplicating the label", () => {
+    const selectPath = "/repo/src/components/ui/select.tsx";
+    const report: WorkspaceReport = {
+      root: "/repo",
+      files: [
+        {
+          path: selectPath,
+          definitions: [
+            { name: "SelectTrigger", kind: "wrapped_component", line: 12 },
+            { name: "SelectContent", kind: "wrapped_component", line: 60 },
+            { name: "SelectItem", kind: "wrapped_component", line: 104 },
+          ],
+          usages: [],
+          parse_errors: [],
+        },
+      ],
+      findings: [],
+      duplicate_components: [],
+      usage_by_component: [
+        {
+          component: "Select",
+          reference_count: 2,
+          file_count: 1,
+          max_props_on_single_use: 1,
+          files: ["/repo/src/components/PlaygroundControlField.tsx"],
+        },
+        {
+          component: "SelectValue",
+          reference_count: 1,
+          file_count: 1,
+          max_props_on_single_use: 1,
+          files: ["/repo/src/components/PlaygroundControlField.tsx"],
+        },
+      ],
+      scores: {
+        design_system_health: 0,
+        ux_consistency: 0,
+        accessibility: 0,
+        maintainability: 0,
+      },
+    };
+
+    expect(componentCatalogFamiliesFromReport(report)).toEqual([
+      {
+        parent: "Select",
+        children: [
+          "Select",
+          "SelectContent",
+          "SelectItem",
+          "SelectTrigger",
+          "SelectValue",
+        ],
+        path: selectPath,
+      },
+    ]);
+    expect(componentCatalogTreeFromReport(report)).toEqual([
+      {
+        type: "family",
+        parent: "Select",
+        children: [
+          "Select",
+          "SelectContent",
+          "SelectItem",
+          "SelectTrigger",
+          "SelectValue",
+        ],
+        path: selectPath,
+      },
+    ]);
+  });
+
+  it("groups sibling exports even when no export matches the filename root", () => {
+    const report = reportWithDefinitions([
+      { name: "MenuRoot", kind: "function", line: 1 },
+      { name: "MenuItem", kind: "function", line: 2 },
+    ]);
+
+    expect(componentCatalogFamiliesFromReport(report)).toEqual([
+      {
+        parent: "DropdownMenu",
+        children: ["MenuItem", "MenuRoot"],
+        path: "/repo/src/components/ui/dropdown-menu.tsx",
+      },
+    ]);
+    expect(componentCatalogTreeFromReport(report)).toEqual([
+      {
+        type: "family",
+        parent: "DropdownMenu",
+        children: ["MenuItem", "MenuRoot"],
+        path: "/repo/src/components/ui/dropdown-menu.tsx",
+      },
+    ]);
+  });
+});
+
+describe("componentCatalogTreeFromReport", () => {
+  it("includes file-stem families when the parent label is not a catalog name", () => {
     const report = reportWithDefinitions(
       [
-        { name: "MenuRoot", kind: "function", line: 1 },
-        { name: "MenuItem", kind: "function", line: 2 },
+        { name: "IconSearch", kind: "wrapped_component", line: 15 },
+        { name: "IconCheck", kind: "wrapped_component", line: 31 },
       ],
-      "/repo/src/components/ui/dropdown-menu.tsx",
+      "/repo/src/components/icons.tsx",
     );
 
-    expect(componentCatalogFamiliesFromReport(report)).toEqual([]);
-    expect(componentCatalogTreeFromReport(report)).toEqual([
-      { type: "component", name: "MenuItem" },
-      { type: "component", name: "MenuRoot" },
+    const names = componentCatalogNamesFromReport(report);
+    expect(names).toEqual(["IconCheck", "IconSearch"]);
+    expect(names).not.toContain("Icons");
+
+    const tree = componentCatalogTreeFromReport(report);
+    expect(tree).toEqual([
+      {
+        type: "family",
+        parent: "Icons",
+        children: ["IconCheck", "IconSearch"],
+        path: "/repo/src/components/icons.tsx",
+      },
     ]);
   });
 });
+
+describe("resolveFamilyNavigationTarget", () => {
+  it("prefers a child export whose normalized name matches the file stem", () => {
+    const family = {
+      parent: "DropdownMenu",
+      children: [
+        "DropdownMenu",
+        "DropdownMenuContent",
+        "DropdownMenuItem",
+        "DropdownMenuTrigger",
+      ],
+      path: "/repo/src/components/ui/dropdown-menu.tsx",
+    };
+    const names = componentCatalogNamesFromReport(reportWithDefinitions([]));
+
+    expect(
+      resolveFamilyNavigationTarget(family, [
+        ...names,
+        "DropdownMenu",
+        "DropdownMenuContent",
+        "DropdownMenuItem",
+        "DropdownMenuTrigger",
+      ]),
+    ).toBe("DropdownMenu");
+  });
+
+  it("falls back to the first child when no export matches the file stem", () => {
+    const family = {
+      parent: "Icons",
+      children: ["IconCheck", "IconSearch"],
+      path: "/repo/src/components/icons.tsx",
+    };
+
+    expect(resolveFamilyNavigationTarget(family, ["IconCheck", "IconSearch"])).toBe(
+      "IconCheck",
+    );
+  });
+});
+
+describe("unusedComponentsFromReport", () => {
+  it("returns defined components with zero references", () => {
+    const report: WorkspaceReport = {
+      root: "/repo",
+      files: [
+        {
+          path: "/repo/src/components/ui/button.tsx",
+          definitions: [{ name: "Button", kind: "function", line: 1 }],
+          usages: [],
+          parse_errors: [],
+        },
+        {
+          path: "/repo/src/components/ui/badge.tsx",
+          definitions: [{ name: "Badge", kind: "function", line: 1 }],
+          usages: [],
+          parse_errors: [],
+        },
+      ],
+      findings: [],
+      duplicate_components: [],
+      usage_by_component: [
+        {
+          component: "Button",
+          reference_count: 12,
+          file_count: 4,
+          max_props_on_single_use: 2,
+          files: ["/repo/src/pages/home.tsx"],
+        },
+      ],
+      scores: {
+        design_system_health: 0,
+        ux_consistency: 0,
+        accessibility: 0,
+        maintainability: 0,
+      },
+    };
+
+    expect(unusedComponentsFromReport(report)).toEqual([
+      {
+        name: "Badge",
+        definitionPaths: ["/repo/src/components/ui/badge.tsx"],
+      },
+    ]);
+  });
+
+  it("excludes hidden components", () => {
+    const report: WorkspaceReport = {
+      root: "/repo",
+      files: [
+        {
+          path: "/repo/src/components/ui/ghost.tsx",
+          definitions: [{ name: "Ghost", kind: "function", line: 1 }],
+          usages: [],
+          parse_errors: [],
+        },
+      ],
+      findings: [],
+      duplicate_components: [],
+      usage_by_component: [],
+      scores: {
+        design_system_health: 0,
+        ux_consistency: 0,
+        accessibility: 0,
+        maintainability: 0,
+      },
+      config: { hidden_components: ["Ghost"] },
+    };
+
+    expect(unusedComponentsFromReport(report)).toEqual([]);
+  });
+});
+
+describe("governanceTabCounts", () => {
+  it("counts findings by pillar and unused components", () => {
+    const report: WorkspaceReport = {
+      root: "/repo",
+      files: [
+        {
+          path: "/repo/src/components/ui/badge.tsx",
+          definitions: [
+            { name: "Badge", kind: "function", line: 1 },
+            { name: "Ghost", kind: "function", line: 2 },
+          ],
+          usages: [],
+          parse_errors: [],
+        },
+      ],
+      findings: [
+        {
+          rule_id: "a11y-missing-alt",
+          message: "Missing alt text",
+          path: "/repo/src/pages/home.tsx",
+          line: 1,
+          severity: "error",
+        },
+        {
+          rule_id: "code-console",
+          message: "Console statement",
+          path: "/repo/src/pages/home.tsx",
+          line: 2,
+          severity: "warning",
+        },
+        {
+          rule_id: "token-tailwind-arbitrary",
+          message: "Arbitrary token",
+          path: "/repo/src/pages/home.tsx",
+          line: 3,
+          severity: "warning",
+        },
+      ],
+      duplicate_components: [],
+      usage_by_component: [],
+      scores: {
+        design_system_health: 0,
+        ux_consistency: 0,
+        accessibility: 0,
+        maintainability: 0,
+      },
+    };
+
+    expect(governanceTabCounts(report)).toEqual({
+      all: 3,
+      a11y: 1,
+      code: 1,
+      token: 1,
+      unused: 2,
+    });
+  });
+});
+
+describe("findingsForGovernanceTab", () => {
+  const findings: WorkspaceReport["findings"] = [
+    {
+      rule_id: "a11y-missing-alt",
+      message: "Missing alt text",
+      path: "/repo/src/pages/home.tsx",
+      line: 1,
+      severity: "error",
+    },
+    {
+      rule_id: "code-console",
+      message: "Console statement",
+      path: "/repo/src/pages/home.tsx",
+      line: 2,
+      severity: "warning",
+    },
+    {
+      rule_id: "token-tailwind-arbitrary",
+      message: "Arbitrary token",
+      path: "/repo/src/pages/home.tsx",
+      line: 3,
+      severity: "warning",
+    },
+  ];
+
+  const report: WorkspaceReport = {
+    root: "/repo",
+    files: [],
+    findings,
+    duplicate_components: [],
+    usage_by_component: [],
+    scores: {
+      design_system_health: 0,
+      ux_consistency: 0,
+      accessibility: 0,
+      maintainability: 0,
+    },
+  };
+
+  it("returns all findings for the all tab", () => {
+    expect(findingsForGovernanceTab(report, "all")).toEqual(findings);
+  });
+
+  it("filters findings by pillar", () => {
+    expect(findingsForGovernanceTab(report, "a11y")).toEqual([findings[0]]);
+    expect(findingsForGovernanceTab(report, "code")).toEqual([findings[1]]);
+    expect(findingsForGovernanceTab(report, "token")).toEqual([findings[2]]);
+  });
+
+  it("returns an empty list for the unused tab", () => {
+    expect(findingsForGovernanceTab(report, "unused")).toEqual([]);
+  });
+});

package/src/dashboard/aggregate.ts

@@ -1,4 +1,11 @@
-import type { ComponentDefinition, FileScan, UsageSummary, WorkspaceReport } from "../types/report";
+import { pillarForRule } from "../mcp/rule-catalog";
+import type {
+  ComponentDefinition,
+  FileScan,
+  LintFinding,
+  UsageSummary,
+  WorkspaceReport,
+} from "../types/report";
 import {
   definitionPathsForName,
   isCatalogComponentHidden,
@@ -42,6 +49,15 @@ function fileStem(path: string): string {
   return base.replace(/\.(tsx|jsx)$/i, "");
 }
 
+/** `hover-card.tsx` → `HoverCard`, `icons.tsx` → `Icons`. */
+export function fileStemToCatalogGroupLabel(stem: string): string {
+  return stem
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join("");
+}
+
 function normalizedName(value: string): string {
   return value
     .replace(/\.playground$/i, "")
@@ -135,6 +151,70 @@ export function componentCatalogNamesFromReport(
   return catalogComponentNames(aggregateDefinitions(report), usageMap(report), report);
 }
 
+export type UnusedComponent = {
+  name: string;
+  definitionPaths: string[];
+};
+
+/** Defined components with zero JSX references in the scanned workspace. */
+export function unusedComponentsFromReport(
+  report: WorkspaceReport | null | undefined,
+): UnusedComponent[] {
+  if (!report) return [];
+  const defs = aggregateDefinitions(report);
+  const usages = usageMap(report);
+  const out: UnusedComponent[] = [];
+
+  for (const [name, sites] of defs) {
+    if (!isVisibleCatalogName(report, name)) continue;
+    const usage = usages.get(name);
+    if (usage && usage.reference_count > 0) continue;
+    out.push({
+      name,
+      definitionPaths: sites.map((s) => s.path),
+    });
+  }
+
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+export type GovernanceInventoryTab = "all" | "a11y" | "code" | "token" | "unused";
+
+export function governanceTabCounts(
+  report: WorkspaceReport | null | undefined,
+): Record<GovernanceInventoryTab, number> {
+  const counts: Record<GovernanceInventoryTab, number> = {
+    all: 0,
+    a11y: 0,
+    code: 0,
+    token: 0,
+    unused: 0,
+  };
+  if (!report) return counts;
+
+  for (const finding of report.findings ?? []) {
+    counts.all += 1;
+    const pillar = pillarForRule(finding.rule_id);
+    if (pillar === "a11y") counts.a11y += 1;
+    else if (pillar === "code") counts.code += 1;
+    else if (pillar === "token") counts.token += 1;
+  }
+
+  counts.unused = unusedComponentsFromReport(report).length;
+  return counts;
+}
+
+export function findingsForGovernanceTab(
+  report: WorkspaceReport | null | undefined,
+  tab: GovernanceInventoryTab,
+): LintFinding[] {
+  if (!report || tab === "unused") return [];
+  const findings = report.findings ?? [];
+  if (tab === "all") return findings;
+  return findings.filter((f) => pillarForRule(f.rule_id) === tab);
+}
+
 function familyFromFile(file: FileScan, report: WorkspaceReport): CatalogFamily | null {
   const defs = (file.definitions ?? []).filter((d) => {
     if (!isPlayableDefinition(d)) return false;
@@ -142,40 +222,82 @@ function familyFromFile(file: FileScan, report: WorkspaceReport): CatalogFamily
   });
   if (defs.length < 2) return null;
 
-  const stem = normalizedName(fileStem(file.path));
-  const root = defs.find((d) => normalizedName(d.name) === stem);
-  if (!root) return null;
+  const children = defs.map((d) => d.name).sort((a, b) => a.localeCompare(b));
+  return { parent: fileStemToCatalogGroupLabel(fileStem(file.path)), children, path: file.path };
+}
 
-  const children = defs
-    .map((d) => d.name)
-    .filter((name) => name !== root.name && name.startsWith(root.name))
-    .sort((a, b) => a.localeCompare(b));
-  if (children.length === 0) return null;
+/** `Select` + `Value` yes; `Selector` no. */
+function isCompoundFamilyMember(parent: string, name: string): boolean {
+  if (name === parent) return true;
+  if (!name.startsWith(parent) || name.length <= parent.length) return false;
+  const next = name.charAt(parent.length);
+  return next === next.toUpperCase() && next !== next.toLowerCase();
+}
+
+function shouldAttachNameToFamily(
+  name: string,
+  family: CatalogFamily,
+  definitionPaths: string[],
+): boolean {
+  if (family.children.includes(name)) return false;
+  if (name === family.parent) return true;
+  if (definitionPaths.length > 0) {
+    return definitionPaths.every((p) => p === family.path);
+  }
+  return isCompoundFamilyMember(family.parent, name);
+}
 
-  return { parent: root.name, children, path: file.path };
+function enrichCatalogFamily(
+  family: CatalogFamily,
+  catalogNames: string[],
+  report: WorkspaceReport,
+): CatalogFamily {
+  const children = new Set(family.children);
+  for (const name of catalogNames) {
+    if (
+      shouldAttachNameToFamily(
+        name,
+        family,
+        definitionPathsForName(report, name),
+      )
+    ) {
+      children.add(name);
+    }
+  }
+  return {
+    ...family,
+    children: [...children].sort((a, b) => a.localeCompare(b)),
+  };
 }
 
 export function componentCatalogFamiliesFromReport(
   report: WorkspaceReport | null | undefined,
 ): CatalogFamily[] {
   if (!report) return [];
-  const byParent = new Map<string, CatalogFamily>();
+  const catalogNames = componentCatalogNamesFromReport(report);
+  const byPath = new Map<string, CatalogFamily>();
   for (const file of report.files ?? []) {
     const family = familyFromFile(file, report);
     if (!family) continue;
-    if (!isVisibleCatalogName(report, family.parent)) continue;
-    const existing = byParent.get(family.parent);
-    if (!existing) {
-      byParent.set(family.parent, family);
-      continue;
-    }
-    const children = new Set([...existing.children, ...family.children]);
-    byParent.set(family.parent, {
-      ...existing,
-      children: [...children].sort((a, b) => a.localeCompare(b)),
-    });
+    byPath.set(family.path, enrichCatalogFamily(family, catalogNames, report));
   }
-  return [...byParent.values()].sort((a, b) => a.parent.localeCompare(b.parent));
+  return [...byPath.values()].sort((a, b) => a.parent.localeCompare(b.parent));
+}
+
+/** Best component id when navigating to a file-stem group label. */
+export function resolveFamilyNavigationTarget(
+  family: CatalogFamily,
+  catalogNames: string[],
+): string {
+  if (catalogNames.includes(family.parent)) return family.parent;
+  const stem = normalizedName(fileStem(family.path));
+  const stemMatch = family.children.find((c) => normalizedName(c) === stem);
+  if (stemMatch) return stemMatch;
+  return family.children[0] ?? family.parent;
+}
+
+function catalogTreeSortKey(item: CatalogTreeItem): string {
+  return item.type === "family" ? item.parent : item.name;
 }
 
 export function componentCatalogTreeFromReport(
@@ -183,21 +305,23 @@ export function componentCatalogTreeFromReport(
 ): CatalogTreeItem[] {
   const names = componentCatalogNamesFromReport(report);
   const families = componentCatalogFamiliesFromReport(report);
-  const familyByParent = new Map(families.map((f) => [f.parent, f]));
   const childNames = new Set(families.flatMap((f) => f.children));
+  const familyParentLabels = new Set(families.map((f) => f.parent));
   const items: CatalogTreeItem[] = [];
 
+  for (const family of families) {
+    items.push({ type: "family", ...family });
+  }
+
   for (const name of names) {
-    const family = familyByParent.get(name);
-    if (family) {
-      items.push({ type: "family", ...family });
-      continue;
-    }
     if (childNames.has(name)) continue;
+    if (familyParentLabels.has(name)) continue;
     items.push({ type: "component", name });
   }
 
-  return items;
+  return items.sort((a, b) =>
+    catalogTreeSortKey(a).localeCompare(catalogTreeSortKey(b)),
+  );
 }
 
 export function componentCatalogFamilyForName(
@@ -208,3 +332,16 @@ export function componentCatalogFamilyForName(
     (family) => family.parent === name || family.children.includes(name),
   );
 }
+
+/** Sibling/child exports to show for a compound component family. */
+export function catalogChildComponentsFor(
+  family: CatalogFamily | undefined,
+  componentId: string,
+): string[] {
+  if (!family) return [];
+  if (family.children.includes(componentId)) {
+    return family.children.filter((child) => child !== componentId);
+  }
+  if (family.parent === componentId) return family.children;
+  return [];
+}

package/src/dashboard/mergeTokenCatalog.ts

@@ -139,6 +139,11 @@ export function buildMergedTokenView(
   };
 }
 
+/** Stable React key — cssName alone is not unique across scope/path. */
+export function scannedTokenRowKey(row: ScannedTokenRow): string {
+  return `${row.cssName}|${row.scope}|${row.path}|${row.line}`;
+}
+
 export function filterTokenRows(
   rows: ScannedTokenRow[],
   filter: TokenUsageFilter,