dslinter 0.1.13 → 0.2.2

package/src/dashboard/editorLink.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildEditorFileUri,
+  resolveModuleAbsolutePath,
+} from "./editorLink";
+
+describe("resolveModuleAbsolutePath", () => {
+  it("resolves embed scan keys under report root", () => {
+    expect(
+      resolveModuleAbsolutePath(
+        "/Users/dev/demo-inertia",
+        "@dslinter-scan/resources/js/components/app-logo-icon.tsx",
+      ),
+    ).toBe(
+      "/Users/dev/demo-inertia/resources/js/components/app-logo-icon.tsx",
+    );
+  });
+
+  it("resolves consumer glob keys via src/components convention", () => {
+    expect(
+      resolveModuleAbsolutePath(
+        "/repo",
+        "../components/ui/button.tsx",
+      ),
+    ).toBe("/repo/src/components/ui/button.tsx");
+  });
+});
+
+describe("buildEditorFileUri", () => {
+  it("builds a vscode URI for unix paths", () => {
+    expect(
+      buildEditorFileUri(
+        "/Users/dev/demo-inertia/resources/js/components/app-logo-icon.tsx",
+      ),
+    ).toBe(
+      "vscode://file/Users/dev/demo-inertia/resources/js/components/app-logo-icon.tsx",
+    );
+  });
+
+  it("supports cursor scheme", () => {
+    expect(
+      buildEditorFileUri("/repo/src/Button.tsx", 2, 1, "cursor"),
+    ).toBe("cursor://file/repo/src/Button.tsx:2:1");
+  });
+
+  it("includes line and column when provided", () => {
+    expect(
+      buildEditorFileUri("/repo/src/Button.tsx", 14),
+    ).toBe("vscode://file/repo/src/Button.tsx:14:1");
+  });
+
+  it("builds a vscode URI for windows paths", () => {
+    expect(
+      buildEditorFileUri("C:/project/src/Button.tsx", 3),
+    ).toBe("vscode://file/c:/project/src/Button.tsx:3:1");
+  });
+});

package/src/dashboard/editorLink.ts

@@ -0,0 +1,71 @@
+import { resolveModuleSourcePath } from "../report/modulePathMatch";
+import { normalizePath } from "./paths";
+
+const EMBED_PREFIX = "@dslinter-scan/";
+
+/** Resolve a playground `modulePath` to an absolute file path under `reportRoot`. */
+export function resolveModuleAbsolutePath(
+  reportRoot: string,
+  modulePath: string,
+): string {
+  const normalized = normalizePath(modulePath);
+  if (normalized.startsWith(EMBED_PREFIX)) {
+    const root = normalizePath(reportRoot);
+    return `${root}/${normalized.slice(EMBED_PREFIX.length)}`;
+  }
+  return resolveModuleSourcePath(reportRoot, modulePath);
+}
+
+const OPEN_FILE_PATH = "/dslinter/open-file";
+
+/** Open a local file via the dev server, falling back to editor URI handlers. */
+export async function openSourceFile(
+  absolutePath: string,
+  line?: number,
+  column = 1,
+): Promise<void> {
+  if (typeof window === "undefined") return;
+
+  const params = new URLSearchParams({ path: absolutePath });
+  if (line != null) params.set("line", String(line));
+  params.set("column", String(column));
+
+  try {
+    const res = await fetch(`${OPEN_FILE_PATH}?${params}`, { method: "POST" });
+    if (res.ok) return;
+  } catch {
+    // Static build or server unavailable — fall back to protocol links below.
+  }
+
+  window.location.assign(
+    buildEditorFileUri(absolutePath, line, column, "cursor"),
+  );
+}
+
+/** Open a local file in VS Code / Cursor via the editor URI handler. */
+export function buildEditorFileUri(
+  absolutePath: string,
+  line?: number,
+  column = 1,
+  scheme: "vscode" | "cursor" = "vscode",
+): string {
+  const path = normalizePath(absolutePath);
+  const suffix = line != null ? `:${line}:${column}` : "";
+
+  if (/^[a-zA-Z]:/.test(path)) {
+    const drive = path.slice(0, 2).toLowerCase();
+    const rest = path
+      .slice(2)
+      .replace(/^\//, "")
+      .split("/")
+      .map(encodeURIComponent)
+      .join("/");
+    return `${scheme}://file/${drive}/${rest}${suffix}`;
+  }
+
+  const encoded = path
+    .split("/")
+    .map((segment, index) => (index === 0 && segment === "" ? "" : encodeURIComponent(segment)))
+    .join("/");
+  return `${scheme}://file${encoded}${suffix}`;
+}

package/src/dashboard/paths.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { truncatePathMiddle } from "./paths";
+
+const SAMPLE =
+  "resources/js/components/manage-two-factor.tsx";
+
+describe("truncatePathMiddle", () => {
+  it("returns the path unchanged when it fits", () => {
+    expect(truncatePathMiddle(SAMPLE, 100)).toBe(SAMPLE);
+    expect(truncatePathMiddle(SAMPLE, SAMPLE.length)).toBe(SAMPLE);
+  });
+
+  it("drops middle directories while keeping filename", () => {
+    expect(truncatePathMiddle(SAMPLE, 41)).toBe(
+      "resources/js/.../manage-two-factor.tsx",
+    );
+  });
+
+  it("progressively collapses more leading segments", () => {
+    expect(truncatePathMiddle(SAMPLE, 37)).toBe(
+      "resources/.../manage-two-factor.tsx",
+    );
+    expect(truncatePathMiddle(SAMPLE, 27)).toBe(
+      ".../manage-two-factor.tsx",
+    );
+  });
+
+  it("normalizes backslashes", () => {
+    expect(
+      truncatePathMiddle(
+        "resources\\js\\components\\manage-two-factor.tsx",
+        100,
+      ),
+    ).toBe(SAMPLE);
+  });
+
+  it("returns a single long filename when there are no directories", () => {
+    const filename = "manage-two-factor-with-a-very-long-name.tsx";
+    expect(truncatePathMiddle(filename, 10)).toBe(filename);
+  });
+
+  it("prefers filename over prefix when budget is too small for ellipsis", () => {
+    expect(truncatePathMiddle(SAMPLE, 5)).toBe("manage-two-factor.tsx");
+  });
+
+  it("handles empty path", () => {
+    expect(truncatePathMiddle("", 10)).toBe("");
+  });
+});

package/src/dashboard/paths.ts

@@ -1,10 +1,58 @@
+const ELLIPSIS = "/.../";
+
+export function normalizePath(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/$/, "");
+}
+
 export function shortPath(root: string, fullPath: string): string {
-  const norm = (p: string) => p.replace(/\\/g, "/").replace(/\/$/, "");
-  const r = norm(root);
-  const f = norm(fullPath);
+  const r = normalizePath(root);
+  const f = normalizePath(fullPath);
   if (f.startsWith(r + "/")) {
     return f.slice(r.length + 1);
   }
   const parts = f.split("/");
   return parts.slice(-3).join("/");
 }
+
+/**
+ * Truncate a file path from the middle, preserving the filename and path
+ * separators. Leading path segments are kept when space allows.
+ */
+export function truncatePathMiddle(path: string, maxLength: number): string {
+  const normalized = normalizePath(path);
+  if (normalized.length <= maxLength) return normalized;
+  if (maxLength <= 0) return normalized;
+
+  const segments = normalized.split("/");
+  const filename = segments.pop() ?? "";
+  if (segments.length === 0) return filename;
+
+  for (let keep = segments.length; keep >= 0; keep--) {
+    const prefix = segments.slice(0, keep).join("/");
+    const result =
+      keep === 0 ? `.../${filename}` : `${prefix}${ELLIPSIS}${filename}`;
+    if (result.length <= maxLength) return result;
+  }
+
+  return filename;
+}
+
+/** How many monospace characters fit in an element's client width. */
+export function monospaceCharCountThatFits(element: HTMLElement): number {
+  const width = element.clientWidth;
+  if (width <= 0) return 1;
+
+  const style = getComputedStyle(element);
+  const probe = document.createElement("span");
+  probe.textContent = "m";
+  probe.style.position = "absolute";
+  probe.style.visibility = "hidden";
+  probe.style.whiteSpace = "pre";
+  probe.style.font = style.font;
+  document.body.appendChild(probe);
+  const charWidth = probe.getBoundingClientRect().width;
+  probe.remove();
+
+  if (charWidth <= 0) return 1;
+  return Math.max(1, Math.floor(width / charWidth));
+}

package/src/dashboard/updateDslintConfig.ts

@@ -0,0 +1,22 @@
+const CONFIG_HIDE_PATH = "/dslinter-config/hide-component";
+
+export type HideCatalogComponentResult = {
+  ok: boolean;
+  hidden_components: string[];
+};
+
+/** Append a component name to `hidden_components` in `.dslinter.json` (dev server only). */
+export async function hideCatalogComponent(
+  componentName: string,
+): Promise<HideCatalogComponentResult> {
+  const res = await fetch(CONFIG_HIDE_PATH, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: componentName }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(text || `Failed to hide component (${res.status})`);
+  }
+  return (await res.json()) as HideCatalogComponentResult;
+}

package/src/dashboard/useWorkspaceReport.ts

@@ -33,11 +33,11 @@ export type UseWorkspaceReportOptions = {
 };
 
 export function useWorkspaceReport(
-  reportUrlOrOptions: string | UseWorkspaceReportOptions = "/dslint-report.json",
+  reportUrlOrOptions: string | UseWorkspaceReportOptions = "/dslinter-report.json",
 ): DslinterReportState {
   // Accept either the legacy string overload or the options object.
   const {
-    reportUrl = "/dslint-report.json",
+    reportUrl = "/dslinter-report.json",
     watchUrl,
     refreshIntervalMs = 0,
   }: UseWorkspaceReportOptions = typeof reportUrlOrOptions === "string"
@@ -50,11 +50,15 @@ export function useWorkspaceReport(
 
   // Ref tracking the last known ETag / Last-Modified for poll-based change detection.
   const etagRef = useRef<string | null>(null);
+  // Cancellation refs — one per effect, reset at the top of each effect.
+  const initialCancelledRef = useRef(false);
+  const sseCancelledRef = useRef(false);
+  const pollCancelledRef = useRef(false);
 
   // Core fetch function.
   const fetchReport = (
     url: string,
-    cancelled: { value: boolean },
+    cancelledRef: { current: boolean },
     options?: { showLoading?: boolean },
   ) => {
     const showLoading = options?.showLoading !== false;
@@ -64,22 +68,22 @@ export function useWorkspaceReport(
     }
     loadReport(url)
       .then((r) => {
-        if (!cancelled.value) setReport(r);
+        if (!cancelledRef.current) setReport(r);
       })
       .catch((e: unknown) => {
-        if (!cancelled.value) setError(e instanceof Error ? e.message : "Failed to load report");
+        if (!cancelledRef.current) setError(e instanceof Error ? e.message : "Failed to load report");
       })
       .finally(() => {
-        if (!cancelled.value && showLoading) setLoading(false);
+        if (!cancelledRef.current && showLoading) setLoading(false);
       });
   };
 
   // Initial load.
   useEffect(() => {
-    const cancelled = { value: false };
-    fetchReport(reportUrl, cancelled, { showLoading: true });
+    initialCancelledRef.current = false;
+    fetchReport(reportUrl, initialCancelledRef, { showLoading: true });
     return () => {
-      cancelled.value = true;
+      initialCancelledRef.current = true;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [reportUrl]);
@@ -88,12 +92,12 @@ export function useWorkspaceReport(
   useEffect(() => {
     if (!watchUrl) return;
     const source = new EventSource(watchUrl);
-    const cancelled = { value: false };
+    sseCancelledRef.current = false;
 
     source.onmessage = (e) => {
-      if (cancelled.value) return;
+      if (sseCancelledRef.current) return;
       if (e.data === "updated") {
-        fetchReport(reportUrl, cancelled, { showLoading: false });
+        fetchReport(reportUrl, sseCancelledRef, { showLoading: false });
       }
     };
 
@@ -102,7 +106,7 @@ export function useWorkspaceReport(
     };
 
     return () => {
-      cancelled.value = true;
+      sseCancelledRef.current = true;
       source.close();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -112,10 +116,10 @@ export function useWorkspaceReport(
   useEffect(() => {
     if (watchUrl || refreshIntervalMs <= 0) return;
 
-    const cancelled = { value: false };
+    pollCancelledRef.current = false;
 
     const id = setInterval(async () => {
-      if (cancelled.value) return;
+      if (pollCancelledRef.current) return;
       try {
         // Use HEAD to check for changes before fetching the full JSON.
         const head = await fetch(reportUrl, { method: "HEAD", cache: "no-store" });
@@ -125,7 +129,7 @@ export function useWorkspaceReport(
           return;
         }
         etagRef.current = etag;
-        fetchReport(reportUrl, cancelled, { showLoading: false });
+        fetchReport(reportUrl, pollCancelledRef, { showLoading: false });
       } catch {
         // Network error during poll — ignore silently; the user will see the
         // previous state.
@@ -133,7 +137,7 @@ export function useWorkspaceReport(
     }, refreshIntervalMs);
 
     return () => {
-      cancelled.value = true;
+      pollCancelledRef.current = true;
       clearInterval(id);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/src/index.ts

@@ -10,9 +10,33 @@ export type {
   PlaygroundStringControl,
   PlaygroundNumberControl,
   PlaygroundSelectControl,
+  PlaygroundValuesUpdater,
 } from "./types/controls";
 export { defaultArgsFromControls } from "./types/controls";
 export { definePlayground } from "./playground/definePlayground";
+export type { DefinePlaygroundKitOptions } from "./playground/definePlayground";
+/** @deprecated Use `definePlayground({ kit, controls })` instead. */
+export { definePlaygroundFromKit } from "./playground/definePlaygroundFromKit";
+export {
+  expandPlaygroundControls,
+  exampleProps,
+  propsFromControls,
+  type CompactPlaygroundControl,
+  type PlaygroundControlKeys,
+  type PlaygroundControlsInput,
+} from "./playground/expandPlaygroundControls";
+export {
+  hideCatalogComponent,
+  type HideCatalogComponentResult,
+} from "./dashboard/updateDslintConfig";
+export {
+  isCatalogComponentHidden,
+  reportWithExtraHidden,
+  pathMatchesPrefix,
+  type ReportConfig,
+} from "./dashboard/catalogVisibility";
+export { collectDefinedPlaygrounds } from "./playground/collectDefinedPlaygrounds";
+export { mergePlaygroundEntries } from "./playground/mergePlaygroundEntries";
 export {
   buildPlaygroundEntriesFromReport,
   buildPlaygroundEntriesFromReportWithSkips,
@@ -40,6 +64,7 @@ export {
   createPlaygroundRegistryEntriesOnly,
 } from "./playground/createPlaygroundRegistry";
 export { usePlaygroundFromReport } from "./playground/usePlaygroundFromReport";
+export { playgroundSpecsKey } from "./playground/playgroundSpecsKey";
 export type { CreatePlaygroundRegistryOptions } from "./playground/createPlaygroundRegistry";
 export type { DefinedPlayground } from "./playground/definePlayground";
 export type { PlaygroundPreviewProps, PlaygroundPreviewComponent } from "./types/preview";
@@ -52,6 +77,7 @@ export type {
   ComponentDefinition,
   FileScan,
   PlaygroundSpec,
+  ReportConfig,
   DeclaredPropKind,
   CssTokenSummary,
   CssTokenDefinition,

package/src/mcp/agent-context.ts

@@ -0,0 +1,148 @@
+import { catalogSummary, governanceSummary, tokenSummary } from "./agent-query";
+import { ruleCatalog } from "./rule-catalog";
+import type { WorkspaceReport } from "../types/report";
+
+export type AgentContextOptions = {
+  max_components?: number;
+  max_findings?: number;
+  format?: "markdown" | "json";
+};
+
+function topUsageHint(
+  propValueFreqs: Record<string, Record<string, number>> | undefined,
+): string {
+  if (!propValueFreqs) return "";
+  const parts: string[] = [];
+  for (const [prop, values] of Object.entries(propValueFreqs)) {
+    const sorted = Object.entries(values).sort((a, b) => b[1] - a[1]);
+    const top = sorted[0];
+    if (top) parts.push(`${prop}=${top[0]}`);
+  }
+  return parts.slice(0, 3).join(", ");
+}
+
+export function buildAgentContext(
+  report: WorkspaceReport,
+  opts: AgentContextOptions = {},
+): string | Record<string, unknown> {
+  const maxComponents = opts.max_components ?? 30;
+  const maxFindings = opts.max_findings ?? 10;
+  const format = opts.format ?? "markdown";
+
+  const gov = governanceSummary(report);
+  const catalog = catalogSummary(report, { limit: maxComponents });
+  const tokens = tokenSummary(report);
+  const snap = report.config_snapshot ?? {};
+
+  const deprecated = catalog.filter((c) => c.deprecated).map((c) => c.name);
+  const duplicates = catalog.filter((c) => c.duplicate).map((c) => c.name);
+
+  const topFindings = [...(report.findings ?? [])]
+    .sort((a, b) => {
+      const order = { error: 0, warning: 1, info: 2 };
+      return order[a.severity] - order[b.severity];
+    })
+    .slice(0, maxFindings)
+    .map((f) => ({
+      rule_id: f.rule_id,
+      severity: f.severity,
+      path: f.path,
+      line: f.line,
+      message: f.message,
+    }));
+
+  const payload = {
+    schema_version: report.schema_version ?? 1,
+    generated_at: report.generated_at ?? null,
+    scores: gov.scores,
+    finding_counts: gov.finding_counts,
+    top_components: catalog.map((c) => ({
+      name: c.name,
+      references: c.reference_count,
+      import_path: c.import_path,
+      usage_hint: topUsageHint(
+        report.usage_by_component.find((u) => u.component === c.name)
+          ?.prop_value_frequencies,
+      ),
+    })),
+    deprecated_components: deprecated,
+    duplicate_components: duplicates,
+    top_findings: topFindings,
+    token_summary: {
+      defined: tokens.tokens.length,
+      unused: tokens.unused_count,
+    },
+    policy: {
+      include_dirs: snap.include_dirs ?? [],
+      known_tokens: snap.known_tokens ?? [],
+    },
+    dos: [
+      "Use components from the catalog before creating new ones.",
+      "Match prop values to repo usage patterns (see top_components.usage_hint).",
+      "Use theme tokens and Tailwind utilities from known_tokens / css_tokens.",
+    ],
+    donts: [
+      ...(deprecated.length
+        ? [`Do not use deprecated components: ${deprecated.join(", ")}.`]
+        : []),
+      "Do not hardcode hex colors or Tailwind arbitrary values.",
+      "Do not duplicate existing component names.",
+      ...(snap.include_dirs?.length
+        ? [`Prefer components under: ${snap.include_dirs.join(", ")}.`]
+        : []),
+    ],
+  };
+
+  if (format === "json") {
+    return payload;
+  }
+
+  const lines: string[] = [
+    "# DSLinter agent context",
+    "",
+    `Generated: ${payload.generated_at ?? "unknown"}`,
+    "",
+    "## Governance scores",
+    `- Design system health: ${gov.scores.design_system_health}/100`,
+    `- UX consistency: ${gov.scores.ux_consistency}/100`,
+    `- Accessibility: ${gov.scores.accessibility}/100`,
+    `- Maintainability: ${gov.scores.maintainability}/100`,
+    "",
+    "## Top components (by usage)",
+  ];
+
+  for (const c of payload.top_components) {
+    const hint = c.usage_hint ? ` — ${c.usage_hint}` : "";
+    const path = c.import_path ? ` (${c.import_path})` : "";
+    lines.push(`- **${c.name}** (${c.references} refs)${path}${hint}`);
+  }
+
+  if (deprecated.length) {
+    lines.push("", "## Deprecated (do not use)", deprecated.map((d) => `- ${d}`).join("\n"));
+  }
+  if (duplicates.length) {
+    lines.push("", "## Duplicates (consolidate)", duplicates.map((d) => `- ${d}`).join("\n"));
+  }
+
+  if (topFindings.length) {
+    lines.push("", "## Top findings");
+    for (const f of topFindings) {
+      lines.push(
+        `- [${f.severity}] ${f.rule_id} @ ${f.path}${f.line != null ? `:${f.line}` : ""}: ${f.message}`,
+      );
+    }
+  }
+
+  lines.push(
+    "",
+    "## Do",
+    ...payload.dos.map((d) => `- ${d}`),
+    "",
+    "## Don't",
+    ...payload.donts.map((d) => `- ${d}`),
+  );
+
+  lines.push("", "## Rule catalog", `${ruleCatalog().length} rules documented.`);
+
+  return lines.join("\n");
+}

package/src/mcp/agent-query.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { buildAgentContext } from "./agent-context";
+import {
+  catalogSummary,
+  componentSpec,
+  findingsQuery,
+  governanceSummary,
+  tokenSummary,
+} from "./agent-query";
+import { normalizeReportPaths } from "./normalize-paths";
+import type { WorkspaceReport } from "../types/report";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const demoReportPath = join(__dirname, "../../../../demo/public/dslinter-report.json");
+
+function loadDemoReport(): WorkspaceReport {
+  const raw = readFileSync(demoReportPath, "utf8");
+  return normalizeReportPaths(JSON.parse(raw) as WorkspaceReport);
+}
+
+describe("normalizeReportPaths", () => {
+  it("strips root prefix from paths", () => {
+    const report = loadDemoReport();
+    for (const f of report.files) {
+      expect(f.path.startsWith("/")).toBe(false);
+    }
+  });
+});
+
+describe("agent-query", () => {
+  it("returns catalog sorted by usage", () => {
+    const report = loadDemoReport();
+    const catalog = catalogSummary(report, { limit: 10 });
+    expect(catalog.length).toBeGreaterThan(0);
+    for (let i = 1; i < catalog.length; i++) {
+      expect(catalog[i - 1]!.reference_count).toBeGreaterThanOrEqual(
+        catalog[i]!.reference_count,
+      );
+    }
+  });
+
+  it("returns Button spec with example jsx", () => {
+    const report = loadDemoReport();
+    const spec = componentSpec(report, "Button");
+    expect(spec).not.toBeNull();
+    expect(spec!.example_jsx).toMatch(/Button/);
+  });
+
+  it("filters findings by rule prefix", () => {
+    const report = loadDemoReport();
+    const rows = findingsQuery(report, { rule_prefix: "a11y-", limit: 5 });
+    expect(rows.every((f) => f.rule_id.startsWith("a11y-"))).toBe(true);
+  });
+
+  it("summarizes governance", () => {
+    const report = loadDemoReport();
+    const gov = governanceSummary(report);
+    expect(gov.scores.design_system_health).toBeGreaterThan(0);
+    expect(gov.total_findings).toBeGreaterThan(0);
+  });
+
+  it("lists css tokens", () => {
+    const report = loadDemoReport();
+    const tokens = tokenSummary(report);
+    expect(tokens.tokens.length).toBeGreaterThan(0);
+  });
+});
+
+describe("agent-context", () => {
+  it("builds markdown context", () => {
+    const report = loadDemoReport();
+    const md = buildAgentContext(report, { format: "markdown" });
+    expect(String(md)).toContain("Governance scores");
+    expect(String(md)).toContain("Top components");
+  });
+
+  it("builds json context", () => {
+    const report = loadDemoReport();
+    const json = buildAgentContext(report, { format: "json" }) as Record<
+      string,
+      unknown
+    >;
+    expect(json.scores).toBeDefined();
+    expect(Array.isArray(json.top_components)).toBe(true);
+  });
+});