dslinter 0.3.0 → 0.5.0

package/src/components/Section.tsx

@@ -12,7 +12,7 @@ export function Section({
   id: string;
   className?: string;
   children: ReactNode;
-  title: string;
+  title?: string;
   description?: string;
   actions?: ReactNode;
 }) {

package/src/components/ui/badge.tsx

@@ -18,7 +18,7 @@ const badgeVariants = cva(
         outline: "text-foreground",
       },
       size: {
-        default: "px-3 py-0.5 text-xs",
+        default: "px-2 py-0.5 text-xs",
         sm: "px-2 py-0.5 font-mono text-xs font-normal leading-tight",
       },
     },

package/src/dashboard/ComponentUsageDetails.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from "react";
+import { useMemo } from "react";
 import {
   Table,
   TableBody,
@@ -9,10 +9,8 @@ import {
 } from "../components/ui/table";
 import type { UsageLocation, WorkspaceReport } from "../types/report";
 import { usageMap } from "./aggregate";
-import { openSourceFile } from "./editorLink";
-import { resolveReportAbsolutePath, shortPath } from "./paths";
 import { EmptyCard } from "../components/EmptyCard";
-import { TruncatedPath } from "../components/TruncatedPath";
+import { SourceLocationLink } from "./SourceLocationLink";
 
 function formatCallSiteProps(loc: UsageLocation): string {
   if (!loc.props.length) return "—";
@@ -33,40 +31,6 @@ function sortedLocations(
   return list;
 }
 
-function UsageLocationLink({
-  root,
-  loc,
-}: {
-  root: string;
-  loc: UsageLocation;
-}) {
-  const fileText = shortPath(root, loc.path);
-  const locationText = `${fileText}:${loc.line}`;
-  const absolutePath = resolveReportAbsolutePath(root, loc.path);
-
-  const handleClick = useCallback(() => {
-    void openSourceFile(absolutePath, loc.line).catch((err) => {
-      const message = err instanceof Error ? err.message : String(err);
-      window.alert(`Could not open file: ${message}`);
-    });
-  }, [absolutePath, loc.line]);
-
-  return (
-    <button
-      type="button"
-      onClick={handleClick}
-      className="block min-w-0 w-full text-left text-xs text-muted-foreground transition-colors hover:text-foreground hover:underline"
-      title={locationText}
-    >
-      <TruncatedPath
-        path={`${fileText}:${loc.line}`}
-        className="text-xs"
-        title={undefined}
-      />
-    </button>
-  );
-}
-
 export function ComponentUsageDetails({
   report,
   componentId,
@@ -117,7 +81,11 @@ export function ComponentUsageDetails({
           return (
             <TableRow key={`${loc.path}-${loc.line}-${i}`}>
               <TableCell className="min-w-0">
-                <UsageLocationLink root={report.root} loc={loc} />
+                <SourceLocationLink
+                  root={report.root}
+                  path={loc.path}
+                  line={loc.line}
+                />
               </TableCell>
               <TableCell className="min-w-0">
                 <span

package/src/dashboard/DashboardBody.tsx

@@ -79,11 +79,7 @@ export function DashboardBody({
 
       <GovernanceInventoryTabs value={tab} onChange={setTab} counts={counts} />
 
-      <Section
-        id={section.id}
-        title={section.title}
-        description={section.description}
-      >
+      <Section id={section.id}>
         {tab === "unused" ? (
           <UnusedComponentsList
             components={unusedComponents}
@@ -103,8 +99,7 @@ export function DashboardBody({
             className="font-medium text-foreground underline decoration-dotted underline-offset-2 transition hover:decoration-solid"
           >
             View all components
-          </button>
-          {" "}
+          </button>{" "}
           for prop usage and app reference details.
         </p>
       ) : null}

package/src/dashboard/FindingsList.tsx

@@ -7,11 +7,11 @@ import {
   TableHeader,
   TableRow,
 } from "../components/ui/table";
-import { shortPath } from "./paths";
 import type { LintFinding, Severity } from "../types/report";
 import { Badge } from "../components/ui/badge";
+import { EmptyCard } from "../components/EmptyCard";
 import { ToggleGroup, ToggleGroupItem } from "../components/ui/toggle-group";
-import { TruncatedPath } from "../components/TruncatedPath";
+import { SourceLocationLink } from "./SourceLocationLink";
 
 type Filter = "all" | Severity;
 
@@ -24,6 +24,12 @@ function isFilter(value: string): value is Filter {
   );
 }
 
+function emptyFilterMessage(filter: Exclude<Filter, "all">): string {
+  if (filter === "error") return "No errors in these findings.";
+  if (filter === "warning") return "No warnings in these findings.";
+  return "No info findings in these findings.";
+}
+
 export function FindingsList({
   findings,
   root,
@@ -44,16 +50,15 @@ export function FindingsList({
   }, [findings]);
 
   const filtered = useMemo(
-    () => (filter === "all" ? findings : findings.filter((f) => f.severity === filter)),
+    () =>
+      filter === "all"
+        ? findings
+        : findings.filter((f) => f.severity === filter),
     [findings, filter],
   );
 
   if (findings.length === 0) {
-    return (
-      <p className="rounded-lg border border-dashed border-border bg-muted/30 px-4 py-8 text-center text-sm text-muted-foreground">
-        No findings
-      </p>
-    );
+    return <EmptyCard>No findings</EmptyCard>;
   }
 
   return (
@@ -107,55 +112,58 @@ export function FindingsList({
         </ToggleGroupItem>
       </ToggleGroup>
 
-      <Table className="mt-4">
-        <TableHeader>
-          <TableRow>
-            <TableHead scope="col">Severity</TableHead>
-            <TableHead scope="col">Rule</TableHead>
-            <TableHead scope="col">Message</TableHead>
-            <TableHead scope="col">File</TableHead>
-          </TableRow>
-        </TableHeader>
-        <TableBody className="align-top text-foreground">
-          {filtered.map((f, i) => (
-            <TableRow
-              key={`${f.rule_id}-${f.path}-${f.line ?? "x"}-${i}`}
-              className="border-border hover:bg-transparent"
-            >
-              <TableCell className="px-3 py-2">
-                <Badge
-                  variant={
-                    f.severity === "error"
-                      ? "destructive"
-                      : f.severity === "warning"
-                        ? "secondary"
-                        : "outline"
-                  }
-                >
-                  {f.severity}
-                </Badge>
-              </TableCell>
-              <TableCell className="px-3 py-2 font-mono text-xs text-muted-foreground">
-                {f.rule_id}
-              </TableCell>
-              <TableCell className="whitespace-normal px-3 py-2 text-sm">
-                {f.message}
-              </TableCell>
-              <TableCell className="min-w-0 px-3 py-2 font-mono text-xs text-muted-foreground">
-                <div className="flex min-w-0 items-baseline">
-                  <TruncatedPath
-                    path={shortPath(root, f.path)}
-                    className="min-w-0 flex-1 text-xs"
-                  />
-                  <span className="shrink-0">
-                    :{f.line != null ? f.line : "—"}
-                  </span>
-                </div>
-              </TableCell>
+      {filtered.length === 0 ? (
+        <EmptyCard className="mt-4">
+          {filter === "all" ? "No findings" : emptyFilterMessage(filter)}
+        </EmptyCard>
+      ) : (
+        <Table className="mt-4">
+          <TableHeader>
+            <TableRow>
+              <TableHead scope="col">Severity</TableHead>
+              <TableHead scope="col">Rule</TableHead>
+              <TableHead scope="col">File</TableHead>
             </TableRow>
-          ))}
-        </TableBody>
-      </Table>
+          </TableHeader>
+          <TableBody className="align-top text-foreground">
+            {filtered.map((f, i) => (
+              <TableRow
+                key={`${f.rule_id}-${f.path}-${f.line ?? "x"}-${i}`}
+                className="border-border hover:bg-transparent"
+              >
+                <TableCell className="px-3 py-2">
+                  <Badge
+                    variant={
+                      f.severity === "error"
+                        ? "destructive"
+                        : f.severity === "warning"
+                          ? "secondary"
+                          : "outline"
+                    }
+                  >
+                    {f.severity}
+                  </Badge>
+                </TableCell>
+                <TableCell className="min-w-0 whitespace-normal px-3 py-2">
+                  <div className="font-mono text-xs text-muted-foreground">
+                    {f.rule_id}
+                  </div>
+                  <div className="mt-0.5 text-xs text-pretty text-foreground">
+                    {f.message}
+                  </div>
+                </TableCell>
+                <TableCell className="min-w-0 px-3 py-2">
+                  <SourceLocationLink
+                    root={root}
+                    path={f.path}
+                    line={f.line}
+                  />
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      )}
     </div>
   );
 }

package/src/dashboard/ScannedTokenWall.tsx

@@ -5,6 +5,7 @@ import {
   HoverCardTrigger,
 } from "../components/ui/hover-card";
 import { cn } from "../lib/utils";
+import { EmptyCard } from "../components/EmptyCard";
 import { TruncatedPath } from "../components/TruncatedPath";
 import {
   filterTokenRows,
@@ -20,6 +21,14 @@ const filterTabs: { id: TokenUsageFilter; label: string }[] = [
   { id: "unused", label: "Unused" },
 ];
 
+function emptyFilterMessage(filter: TokenUsageFilter): string {
+  if (filter === "used") return "No used theme tokens match this filter.";
+  if (filter === "unused") {
+    return "No unused theme tokens — every scanned token is referenced in the workspace.";
+  }
+  return "No theme tokens found.";
+}
+
 function TokenSection({
   title,
   subtitle,
@@ -215,31 +224,37 @@ export function ScannedTokenWall({ view }: { view: MergedTokenView }) {
         </div>
       </div>
 
-      <ColorSection rows={filtered} />
-      <ListSection
-        title="Spacing"
-        subtitle="--spacing-* custom properties."
-        rows={filtered}
-        category="spacing"
-      />
-      <ListSection
-        title="Radius"
-        subtitle="--radius-* custom properties."
-        rows={filtered}
-        category="radius"
-      />
-      <ListSection
-        title="Typography"
-        subtitle="--font-* custom properties."
-        rows={filtered}
-        category="typography"
-      />
-      <ListSection
-        title="Other"
-        subtitle="Additional CSS variables."
-        rows={filtered}
-        category="other"
-      />
+      {filtered.length === 0 ? (
+        <EmptyCard>{emptyFilterMessage(filter)}</EmptyCard>
+      ) : (
+        <>
+          <ColorSection rows={filtered} />
+          <ListSection
+            title="Spacing"
+            subtitle="--spacing-* custom properties."
+            rows={filtered}
+            category="spacing"
+          />
+          <ListSection
+            title="Radius"
+            subtitle="--radius-* custom properties."
+            rows={filtered}
+            category="radius"
+          />
+          <ListSection
+            title="Typography"
+            subtitle="--font-* custom properties."
+            rows={filtered}
+            category="typography"
+          />
+          <ListSection
+            title="Other"
+            subtitle="Additional CSS variables."
+            rows={filtered}
+            category="other"
+          />
+        </>
+      )}
     </section>
   );
 }

package/src/dashboard/SourceLocationLink.tsx

@@ -0,0 +1,40 @@
+import { useCallback } from "react";
+import { TruncatedPath } from "../components/TruncatedPath";
+import { openSourceFile } from "./editorLink";
+import { resolveReportAbsolutePath, shortPath } from "./paths";
+
+export function SourceLocationLink({
+  root,
+  path,
+  line,
+}: {
+  root: string;
+  path: string;
+  line?: number | null;
+}) {
+  const fileText = shortPath(root, path);
+  const locationText = line != null ? `${fileText}:${line}` : fileText;
+  const absolutePath = resolveReportAbsolutePath(root, path);
+
+  const handleClick = useCallback(() => {
+    void openSourceFile(absolutePath, line ?? undefined).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      window.alert(`Could not open file: ${message}`);
+    });
+  }, [absolutePath, line]);
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      className="block min-w-0 w-full text-left text-xs text-muted-foreground transition-colors hover:text-foreground hover:underline"
+      title={locationText}
+    >
+      <TruncatedPath
+        path={locationText}
+        className="text-xs"
+        title={undefined}
+      />
+    </button>
+  );
+}

package/src/mcp/css-color.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { findColorTokenForHex, normalizeHex, parseCssColor } from "./css-color";
+import type { CssTokenDefinition } from "../types/report";
+
+function colorDef(name: string, value: string): CssTokenDefinition {
+  return {
+    name,
+    value,
+    category: "color",
+    scope: "theme",
+    path: "theme.css",
+    line: 1,
+  };
+}
+
+describe("css-color", () => {
+  it("normalizes shorthand hex", () => {
+    expect(normalizeHex("#abc")).toBe("#aabbcc");
+    expect(normalizeHex("#DC2626")).toBe("#dc2626");
+  });
+
+  it("parses rgb to hex", () => {
+    expect(parseCssColor("rgb(220, 38, 38)")).toBe("#dc2626");
+    expect(parseCssColor("rgba(220, 38, 38, 0.5)")).toBe("#dc2626");
+  });
+
+  it("finds token by normalized hex when value is rgb", () => {
+    const defs = [colorDef("--color-danger", "rgb(220, 38, 38)")];
+    const token = findColorTokenForHex(defs, "#dc2626");
+    expect(token?.name).toBe("--color-danger");
+  });
+
+  it("finds token when value is hex and finding uses shorthand", () => {
+    const defs = [colorDef("--color-danger", "#dc2626")];
+    const token = findColorTokenForHex(defs, "#dc2626");
+    expect(token?.name).toBe("--color-danger");
+  });
+
+  it("resolves var() chains before matching", () => {
+    const defs = [
+      colorDef("--primary", "#93c5fd"),
+      colorDef("--color-primary", "var(--primary)"),
+    ];
+    const token = findColorTokenForHex(defs, "#93c5fd");
+    expect(token?.name).toBe("--color-primary");
+  });
+
+  it("returns undefined when no token matches", () => {
+    const defs = [colorDef("--color-danger", "rgb(220, 38, 38)")];
+    expect(findColorTokenForHex(defs, "#ff0066")).toBeUndefined();
+  });
+});

package/src/mcp/css-color.ts

@@ -0,0 +1,73 @@
+import type { CssTokenDefinition } from "../types/report";
+
+/** Expand `#abc` → `#aabbcc` (lowercase). */
+export function normalizeHex(raw: string): string | null {
+  const s = raw.trim().replace(/^#/, "");
+  if (s.length === 3 && /^[0-9a-fA-F]{3}$/.test(s)) {
+    return `#${s[0]}${s[0]}${s[1]}${s[1]}${s[2]}${s[2]}`.toLowerCase();
+  }
+  if (s.length === 6 && /^[0-9a-fA-F]{6}$/.test(s)) {
+    return `#${s}`.toLowerCase();
+  }
+  return null;
+}
+
+/** Parse hex or `rgb()`/`rgba()` into normalized `#rrggbb`. */
+export function parseCssColor(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("#")) {
+    return normalizeHex(trimmed);
+  }
+  const rgb = trimmed.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i);
+  if (rgb) {
+    const [, r, g, b] = rgb;
+    const toHex = (n: string) => Number(n).toString(16).padStart(2, "0");
+    return `#${toHex(r!)}${toHex(g!)}${toHex(b!)}`;
+  }
+  return null;
+}
+
+const VAR_REF_RE = /var\(\s*(--[a-zA-Z0-9][a-zA-Z0-9_-]*)/;
+const MAX_VAR_DEPTH = 8;
+
+function resolveTokenValue(
+  value: string,
+  varMap: Map<string, string>,
+  depth = 0,
+): string | null {
+  if (depth > MAX_VAR_DEPTH) return null;
+  const trimmed = value.trim();
+  const varMatch = trimmed.match(VAR_REF_RE);
+  if (varMatch?.[1]) {
+    const next = varMap.get(varMatch[1]);
+    if (!next) return null;
+    return resolveTokenValue(next, varMap, depth + 1);
+  }
+  return trimmed;
+}
+
+/** Find a color token whose resolved value equals the given hex (after normalization). */
+export function findColorTokenForHex(
+  definitions: CssTokenDefinition[] | undefined,
+  hex: string,
+): CssTokenDefinition | undefined {
+  const target = parseCssColor(hex);
+  if (!target || !definitions?.length) return undefined;
+
+  const varMap = new Map(definitions.map((d) => [d.name, d.value]));
+
+  const matches = definitions.filter((def) => {
+    if (def.category !== "color") return false;
+    const resolved = resolveTokenValue(def.value, varMap);
+    if (!resolved) return false;
+    return parseCssColor(resolved) === target;
+  });
+
+  if (matches.length === 0) return undefined;
+
+  return matches.sort((a, b) => {
+    const aPref = a.name.startsWith("--color-") ? 0 : 1;
+    const bPref = b.name.startsWith("--color-") ? 0 : 1;
+    return aPref - bPref;
+  })[0];
+}

package/src/mcp/rule-catalog.json

@@ -45,15 +45,15 @@
     "rule_id": "token-hardcoded-color",
     "pillar": "token",
     "default_severity": "warning",
-    "description": "Hardcoded hex/rgb color instead of design tokens.",
+    "description": "Hardcoded hex/rgb color with no matching value in scanned CSS design tokens (className, style, or literals).",
     "fix_hint": "Replace with a CSS variable or Tailwind theme utility from css_tokens."
   },
   {
     "rule_id": "token-tailwind-arbitrary",
     "pillar": "token",
     "default_severity": "warning",
-    "description": "Tailwind arbitrary value (e.g. bg-[#fff]) bypasses the token system.",
-    "fix_hint": "Use a named theme utility or CSS custom property."
+    "description": "Tailwind arbitrary color or redundant size that duplicates the default scale or @theme spacing tokens.",
+    "fix_hint": "Use a named theme utility (e.g. w-20, p-layout-md) instead of an arbitrary bracket value."
   },
   {
     "rule_id": "token-unused-css-var",
@@ -115,8 +115,8 @@
     "rule_id": "code-inline-style",
     "pillar": "code",
     "default_severity": "warning",
-    "description": "Inline JSX style={{}} bypasses token/Tailwind conventions.",
-    "fix_hint": "Use className with theme utilities."
+    "description": "Inline JSX style uses hardcoded colors not in scanned CSS design tokens.",
+    "fix_hint": "Use className with theme utilities or CSS variables instead of inline color values."
   },
   {
     "rule_id": "code-empty-catch",

package/src/mcp/verify-loop.test.ts

@@ -46,4 +46,28 @@ describe("verify-loop", () => {
     const fix = suggestFix(report, { rule_id: "token-hardcoded-color" });
     expect(fix?.fix_hint).toBeTruthy();
   });
+
+  it("matches rgb token values when suggesting hardcoded color fix", () => {
+    const report = loadDemoReport();
+    const fix = suggestFix(report, {
+      rule_id: "token-hardcoded-color",
+      message: "Hardcoded color `#dc2626` — no matching design token",
+    });
+    // Demo theme defines --color-danger as hex; rgb form should also resolve.
+    const rgbReport = {
+      ...report,
+      css_tokens: {
+        ...report.css_tokens!,
+        definitions: report.css_tokens!.definitions.map((d) =>
+          d.name === "--color-danger" ? { ...d, value: "rgb(220, 38, 38)" } : d,
+        ),
+      },
+    };
+    const rgbFix = suggestFix(rgbReport, {
+      rule_id: "token-hardcoded-color",
+      message: "Hardcoded color `#dc2626` — no matching design token",
+    });
+    expect(rgbFix?.token).toBe("--color-danger");
+    expect(fix?.fix_hint).toBeTruthy();
+  });
 });

package/src/mcp/verify-loop.ts

@@ -1,4 +1,5 @@
 import { catalogSummary, componentSpec, findingsForPaths } from "./agent-query";
+import { findColorTokenForHex } from "./css-color";
 import { ruleById } from "./rule-catalog";
 import type { LintFinding, WorkspaceReport } from "../types/report";
 
@@ -13,7 +14,7 @@ export type FixSuggestion = {
 
 export function suggestFix(
   report: WorkspaceReport,
-  opts: { rule_id: string; path?: string; component?: string },
+  opts: { rule_id: string; path?: string; component?: string; message?: string },
 ): FixSuggestion | null {
   const entry = ruleById(opts.rule_id);
   const fix_hint = entry?.fix_hint ?? "Review the finding and align with design system conventions.";
@@ -42,19 +43,39 @@ export function suggestFix(
   }
 
   if (opts.rule_id === "token-hardcoded-color") {
-    const colorToken = report.css_tokens?.definitions.find(
-      (d) => d.category === "color",
-    );
+    const hexMatch = opts.message?.match(/`(#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}))`/);
+    const hex = hexMatch?.[1]?.toLowerCase();
+    const colorToken =
+      hex != null
+        ? findColorTokenForHex(report.css_tokens?.definitions, hex)
+        : report.css_tokens?.definitions.find((d) => d.category === "color");
     return {
       rule_id: opts.rule_id,
       fix_hint,
       suggestion: colorToken
-        ? `Use theme token \`${colorToken.name}\` or Tailwind utility bound to it instead of a hardcoded color.`
-        : "Replace hardcoded color with a CSS variable or Tailwind theme utility.",
+        ? `Use theme token \`${colorToken.name}\` or Tailwind utility bound to it instead of hardcoded \`${hex ?? "color"}\`.`
+        : "Replace hardcoded color with a CSS variable or Tailwind theme utility from css_tokens.",
       token: colorToken?.name,
     };
   }
 
+  if (opts.rule_id === "token-tailwind-arbitrary") {
+    const utilityMatch = opts.message?.match(/Use `([^`]+)` instead of arbitrary/);
+    if (utilityMatch?.[1]) {
+      return {
+        rule_id: opts.rule_id,
+        fix_hint,
+        suggestion: `Replace the arbitrary value with \`${utilityMatch[1]}\` from the Tailwind or @theme spacing scale.`,
+      };
+    }
+    return {
+      rule_id: opts.rule_id,
+      fix_hint,
+      suggestion:
+        "Replace the arbitrary bracket value with a named theme utility or CSS custom property.",
+    };
+  }
+
   if (opts.rule_id === "a11y-img-alt" && opts.path) {
     const decorative =
       /avatar|icon|logo|decorative|spacer/i.test(opts.path) ||
@@ -141,6 +162,7 @@ export function findingsWithSuggestions(
       rule_id: f.rule_id,
       path: f.path,
       component: componentMatch?.[1],
+      message: f.message,
     });
     return suggestion ? { ...f, suggestion } : f;
   });