dslinter 0.0.6

package/src/dashboard/useWorkspaceReport.ts

@@ -0,0 +1,136 @@
+import { useEffect, useRef, useState } from "react";
+import type { WorkspaceReport } from "../types/report";
+
+async function loadReport(url: string): Promise<WorkspaceReport> {
+  const res = await fetch(url, { cache: "no-store" });
+  if (!res.ok) {
+    throw new Error(`${res.status} ${res.statusText}`);
+  }
+  return res.json() as Promise<WorkspaceReport>;
+}
+
+export type DslinterReportState = {
+  report: WorkspaceReport | null;
+  error: string | null;
+  loading: boolean;
+};
+
+export type UseWorkspaceReportOptions = {
+  /** URL of the JSON report file. */
+  reportUrl?: string;
+  /**
+   * URL of the SSE endpoint (e.g. `http://localhost:7878/events`) emitted by
+   * `dslint --serve`.  When provided the hook subscribes and re-fetches the
+   * report on every `data: updated` event.
+   */
+  watchUrl?: string;
+  /**
+   * Polling interval in milliseconds (0 = off).  Used as a fallback when
+   * `watchUrl` is not provided.  On each tick the hook issues a `HEAD` request
+   * and re-fetches the full JSON only when `Last-Modified` / `ETag` changed.
+   */
+  refreshIntervalMs?: number;
+};
+
+export function useWorkspaceReport(
+  reportUrlOrOptions: string | UseWorkspaceReportOptions = "/dslint-report.json",
+): DslinterReportState {
+  // Accept either the legacy string overload or the options object.
+  const {
+    reportUrl = "/dslint-report.json",
+    watchUrl,
+    refreshIntervalMs = 0,
+  }: UseWorkspaceReportOptions = typeof reportUrlOrOptions === "string"
+    ? { reportUrl: reportUrlOrOptions }
+    : reportUrlOrOptions;
+
+  const [report, setReport] = useState<WorkspaceReport | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  // Ref tracking the last known ETag / Last-Modified for poll-based change detection.
+  const etagRef = useRef<string | null>(null);
+
+  // Core fetch function.
+  const fetchReport = (url: string, cancelled: { value: boolean }) => {
+    setError(null);
+    setLoading(true);
+    loadReport(url)
+      .then((r) => {
+        if (!cancelled.value) setReport(r);
+      })
+      .catch((e: unknown) => {
+        if (!cancelled.value) setError(e instanceof Error ? e.message : "Failed to load report");
+      })
+      .finally(() => {
+        if (!cancelled.value) setLoading(false);
+      });
+  };
+
+  // Initial load.
+  useEffect(() => {
+    const cancelled = { value: false };
+    fetchReport(reportUrl, cancelled);
+    return () => {
+      cancelled.value = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [reportUrl]);
+
+  // SSE subscription (takes priority over polling).
+  useEffect(() => {
+    if (!watchUrl) return;
+    const source = new EventSource(watchUrl);
+    const cancelled = { value: false };
+
+    source.onmessage = (e) => {
+      if (cancelled.value) return;
+      if (e.data === "updated") {
+        fetchReport(reportUrl, cancelled);
+      }
+    };
+
+    source.onerror = () => {
+      // SSE errors are transient; the browser will reconnect automatically.
+    };
+
+    return () => {
+      cancelled.value = true;
+      source.close();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [watchUrl, reportUrl]);
+
+  // Polling fallback (only when watchUrl is absent and refreshIntervalMs > 0).
+  useEffect(() => {
+    if (watchUrl || refreshIntervalMs <= 0) return;
+
+    const cancelled = { value: false };
+
+    const id = setInterval(async () => {
+      if (cancelled.value) return;
+      try {
+        // Use HEAD to check for changes before fetching the full JSON.
+        const head = await fetch(reportUrl, { method: "HEAD", cache: "no-store" });
+        const etag = head.headers.get("ETag") ?? head.headers.get("Last-Modified") ?? null;
+        if (etag && etag === etagRef.current) {
+          // Not changed — skip.
+          return;
+        }
+        etagRef.current = etag;
+        fetchReport(reportUrl, cancelled);
+      } catch {
+        // Network error during poll — ignore silently; the user will see the
+        // previous state.
+      }
+    }, refreshIntervalMs);
+
+    return () => {
+      cancelled.value = true;
+      clearInterval(id);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [watchUrl, refreshIntervalMs, reportUrl]);
+
+  return { report, error, loading };
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+/**
+ * DSLinter dashboard — React UI for playgrounds, tokens, and governance.
+ * Host apps should import styles once: `@import "dslinter/theme.css";` (after Tailwind + `@source` for this package).
+ */
+export type { PlaygroundEntry, PlaygroundMeta } from "./types/playground";
+export type {
+  PlaygroundArgs,
+  PlaygroundControl,
+  PlaygroundBooleanControl,
+  PlaygroundStringControl,
+  PlaygroundNumberControl,
+  PlaygroundSelectControl,
+} from "./types/controls";
+export { defaultArgsFromControls } from "./types/controls";
+export { definePlayground } from "./playground/definePlayground";
+export type { DefinedPlayground } from "./playground/definePlayground";
+export type { PlaygroundPreviewProps, PlaygroundPreviewComponent } from "./types/preview";
+export type {
+  WorkspaceReport,
+  GovernanceScores,
+  LintFinding,
+  UsageSummary,
+  UsageLocation,
+  ComponentDefinition,
+  FileScan,
+  PlaygroundSpec,
+  DeclaredPropKind,
+} from "./types/report";
+export type {
+  TokenCatalog,
+  TokenCatalogColor,
+  TokenCatalogSpacing,
+  TokenCatalogRadius,
+  TokenCatalogTypography,
+  TokenCatalogFontFamily,
+  TokenCatalogFontSize,
+  TokenCatalogFontWeight,
+} from "./types/tokenCatalog";
+export {
+  defaultTailwindFontFamilies,
+  defaultTailwindFontSizes,
+  defaultTailwindFontWeights,
+} from "./types/defaultTailwindTypography";
+
+export {
+  DashboardLayout,
+  DashboardThemeProvider,
+  useDashboardTheme,
+} from "./shell/DashboardLayout";
+export type {
+  DashboardLayoutProps,
+  DashboardResolvedTheme,
+  DashboardThemePreference,
+} from "./shell/DashboardLayout";
+export { useWorkspaceReport } from "./dashboard/useWorkspaceReport";
+export type { DslinterReportState } from "./dashboard/useWorkspaceReport";
+export { a11ySummaryForModule, resolveModuleSourcePath } from "./report/a11yForModule";
+export type { A11yModuleSummary } from "./report/a11yForModule";
+export { tokenStyleFindingsForModule } from "./report/tokenStyleFindingsForModule";
+export { codeScoreSummaryForModule } from "./report/codeScoreForModule";
+export type { CodeScoreModuleSummary } from "./report/codeScoreForModule";
+export { TokenWall } from "./dashboard/TokenWall";
+export { DashboardBody } from "./dashboard/DashboardBody";
+
+export type { HashRoute } from "./shell/hashRoute";
+export { parseHashRoute, formatHashRoute } from "./shell/hashRoute";
+export { useHashRoute } from "./shell/useHashRoute";

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/playground/definePlayground.tsx

@@ -0,0 +1,99 @@
+import type { ComponentType, ReactNode } from "react";
+import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+import type { PlaygroundMeta } from "../types/playground";
+import type { PlaygroundPreviewComponent, PlaygroundPreviewProps } from "../types/preview";
+
+export type DefinedPlayground = {
+  playgroundMeta: PlaygroundMeta;
+  playgroundControls: PlaygroundControl[];
+  PlaygroundPreview: PlaygroundPreviewComponent;
+};
+
+type PlaygroundDefinitionBase = {
+  /**
+   * Stable sidebar / URL id. Defaults to the component’s `displayName` or function `name`
+   * (dev builds). Required for `render`-only definitions or when the name is unreliable.
+   */
+  id?: string;
+  title?: string;
+  /** Sidebar / report group (e.g. from dslint `playground_groups`). */
+  group?: string;
+  /** @deprecated Use `group` — kept for older call sites. */
+  section?: string;
+  controls?: PlaygroundControl[];
+};
+
+type DefineWithComponent<P> = PlaygroundDefinitionBase & {
+  /** Map control values to props for the preview component. */
+  props: (values: PlaygroundArgs) => P;
+};
+
+type DefineWithRender = PlaygroundDefinitionBase & {
+  /** Use when the preview is not a straight prop pass (composition, static demos, wrappers). */
+  render: (values: PlaygroundArgs) => ReactNode;
+};
+
+function getComponentLabel(Component: unknown): string | undefined {
+  if (typeof Component !== "function") return undefined;
+  const fn = Component as { displayName?: string; name?: string };
+  return fn.displayName ?? fn.name;
+}
+
+function inferId(nameFallback: string | undefined): string {
+  if (nameFallback && nameFallback.length > 0) return nameFallback;
+  throw new Error(
+    "definePlayground: set `id` in options when the component has no usable `name` / `displayName`, or when using a `render`-only definition.",
+  );
+}
+
+function resolveMeta(
+  base: PlaygroundDefinitionBase,
+  nameFallback: string | undefined,
+): PlaygroundMeta {
+  const id = base.id ?? inferId(nameFallback);
+  const title = base.title ?? id;
+  const group = base.group ?? base.section;
+  return {
+    id,
+    title,
+    ...(group !== undefined && group !== "" ? { group } : {}),
+  };
+}
+
+/**
+ * Optional escape hatch: declare dashboard playground exports manually. Prefer driving
+ * playgrounds from `dslint-report.json` (`playgrounds`) so component files stay free of
+ * dashboard package imports.
+ */
+export function definePlayground<P extends Record<string, unknown>>(
+  component: ComponentType<P>,
+  options: DefineWithComponent<P>,
+): DefinedPlayground;
+
+export function definePlayground(options: DefineWithRender): DefinedPlayground;
+
+export function definePlayground<P extends Record<string, unknown>>(
+  componentOrOptions: ComponentType<P> | DefineWithRender,
+  options?: DefineWithComponent<P>,
+): DefinedPlayground {
+  if (options !== undefined) {
+    const Component = componentOrOptions as ComponentType<P>;
+    const opts = options;
+    const meta = resolveMeta(opts, getComponentLabel(Component));
+    const controls = opts.controls ?? [];
+    function PlaygroundPreview({ values }: PlaygroundPreviewProps) {
+      return <Component {...opts.props(values)} />;
+    }
+    PlaygroundPreview.displayName = `${meta.id}PlaygroundPreview`;
+    return { playgroundMeta: meta, playgroundControls: controls, PlaygroundPreview };
+  }
+
+  const opts = componentOrOptions as DefineWithRender;
+  const meta = resolveMeta(opts, undefined);
+  const controls = opts.controls ?? [];
+  function PlaygroundPreview({ values }: PlaygroundPreviewProps) {
+    return <>{opts.render(values)}</>;
+  }
+  PlaygroundPreview.displayName = `${meta.id}PlaygroundPreview`;
+  return { playgroundMeta: meta, playgroundControls: controls, PlaygroundPreview };
+}

package/src/playground/enumerateControlCombinations.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import {
+  enumerateControlCombinations,
+  PLAYGROUND_VARIANT_MATRIX_CAP,
+} from "./enumerateControlCombinations";
+import type { PlaygroundControl } from "../types/controls";
+
+describe("enumerateControlCombinations", () => {
+  it("returns empty when there are no boolean or select axes", () => {
+    const controls: PlaygroundControl[] = [
+      { key: "label", label: "label", type: "string", default: "Hi" },
+      { key: "count", label: "count", type: "number", default: 1 },
+    ];
+    const base = { label: "X", count: 42 };
+    const r = enumerateControlCombinations(controls, base);
+    expect(r.combinations).toEqual([]);
+    expect(r.totalCount).toBe(0);
+    expect(r.capped).toBe(false);
+    expect(r.finiteAxisKeys).toEqual([]);
+  });
+
+  it("expands booleans and merges string props from base", () => {
+    const controls: PlaygroundControl[] = [
+      { key: "open", label: "open", type: "boolean", default: false },
+      { key: "title", label: "title", type: "string", default: "T" },
+    ];
+    const base = { open: false, title: "Hello" };
+    const r = enumerateControlCombinations(controls, base);
+    expect(r.totalCount).toBe(2);
+    expect(r.capped).toBe(false);
+    expect(r.finiteAxisKeys).toEqual(["open"]);
+    expect(r.combinations).toEqual([
+      { open: false, title: "Hello" },
+      { open: true, title: "Hello" },
+    ]);
+  });
+
+  it("computes Cartesian product for boolean and select", () => {
+    const controls: PlaygroundControl[] = [
+      {
+        key: "variant",
+        label: "variant",
+        type: "select",
+        default: "a",
+        options: [
+          { value: "a", label: "a" },
+          { value: "b", label: "b" },
+        ],
+      },
+      { key: "disabled", label: "disabled", type: "boolean", default: false },
+    ];
+    const base = { variant: "a", disabled: false, extra: "keep" };
+    const r = enumerateControlCombinations(controls, base);
+    expect(r.totalCount).toBe(4);
+    expect(r.combinations).toHaveLength(4);
+    expect(r.finiteAxisKeys).toEqual(["variant", "disabled"]);
+    const keys = r.combinations.map((c) => `${c.variant}:${c.disabled}`);
+    expect(keys.sort()).toEqual(["a:false", "a:true", "b:false", "b:true"]);
+    for (const c of r.combinations) {
+      expect(c.extra).toBe("keep");
+    }
+  });
+
+  it("skips select with zero options", () => {
+    const controls: PlaygroundControl[] = [
+      {
+        key: "empty",
+        label: "empty",
+        type: "select",
+        default: "x",
+        options: [],
+      },
+      { key: "on", label: "on", type: "boolean", default: false },
+    ];
+    const r = enumerateControlCombinations(controls, { on: false });
+    expect(r.totalCount).toBe(2);
+    expect(r.finiteAxisKeys).toEqual(["on"]);
+  });
+
+  it("caps combinations and reports totalCount", () => {
+    const options = Array.from({ length: 20 }, (_, i) => ({
+      value: `v${i}`,
+      label: `v${i}`,
+    }));
+    const controls: PlaygroundControl[] = [
+      { key: "a", label: "a", type: "boolean", default: false },
+      { key: "b", label: "b", type: "boolean", default: false },
+      { key: "c", label: "c", type: "boolean", default: false },
+      { key: "d", label: "d", type: "boolean", default: false },
+      { key: "e", label: "e", type: "boolean", default: false },
+      {
+        key: "s",
+        label: "s",
+        type: "select",
+        default: "v0",
+        options,
+      },
+    ];
+    const base: Record<string, string | number | boolean> = {
+      a: false,
+      b: false,
+      c: false,
+      d: false,
+      e: false,
+      s: "v0",
+    };
+    const r = enumerateControlCombinations(controls, base);
+    expect(r.totalCount).toBe(2 ** 5 * 20);
+    expect(r.capped).toBe(true);
+    expect(r.combinations.length).toBe(PLAYGROUND_VARIANT_MATRIX_CAP);
+  });
+});

package/src/playground/enumerateControlCombinations.ts

@@ -0,0 +1,74 @@
+import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+
+/** Max previews in the variant matrix; larger Cartesian products show a cap notice. */
+export const PLAYGROUND_VARIANT_MATRIX_CAP = 200;
+
+export type EnumerateControlCombinationsResult = {
+  /** Cartesian product of boolean + select axes, merged over `baseValues`, truncated to cap. */
+  combinations: PlaygroundArgs[];
+  /** Full product size before capping (0 when there are no finite axes). */
+  totalCount: number;
+  /** True when `totalCount` exceeds the cap. */
+  capped: boolean;
+  /** Keys that were expanded in the product (stable control order). */
+  finiteAxisKeys: string[];
+};
+
+type FiniteAxis = {
+  key: string;
+  values: Array<string | number | boolean>;
+};
+
+function finiteAxesFromControls(controls: PlaygroundControl[]): FiniteAxis[] {
+  const axes: FiniteAxis[] = [];
+  for (const c of controls) {
+    if (c.type === "boolean") {
+      axes.push({ key: c.key, values: [false, true] });
+    } else if (c.type === "select" && c.options.length > 0) {
+      axes.push({
+        key: c.key,
+        values: c.options.map((o) => o.value),
+      });
+    }
+  }
+  return axes;
+}
+
+/**
+ * Builds every combination of boolean and select controls, overlaid on `baseValues`
+ * (string/number props stay as in the interactive panel).
+ */
+export function enumerateControlCombinations(
+  controls: PlaygroundControl[],
+  baseValues: PlaygroundArgs,
+): EnumerateControlCombinationsResult {
+  const axes = finiteAxesFromControls(controls);
+  if (axes.length === 0) {
+    return { combinations: [], totalCount: 0, capped: false, finiteAxisKeys: [] };
+  }
+
+  let totalCount = 1;
+  for (const a of axes) {
+    totalCount *= a.values.length;
+  }
+
+  const finiteAxisKeys = axes.map((a) => a.key);
+  const combinations: PlaygroundArgs[] = [];
+  const capped = totalCount > PLAYGROUND_VARIANT_MATRIX_CAP;
+
+  const walk = (i: number, acc: PlaygroundArgs) => {
+    if (combinations.length >= PLAYGROUND_VARIANT_MATRIX_CAP) return;
+    if (i >= axes.length) {
+      combinations.push({ ...acc });
+      return;
+    }
+    const axis = axes[i]!;
+    for (const v of axis.values) {
+      walk(i + 1, { ...acc, [axis.key]: v });
+    }
+  };
+
+  walk(0, { ...baseValues });
+
+  return { combinations, totalCount, capped, finiteAxisKeys };
+}

package/src/report/a11yForModule.ts

@@ -0,0 +1,35 @@
+import type { LintFinding, WorkspaceReport } from "../types/report";
+import { pathsMatch, resolveModuleSourcePath } from "./modulePathMatch";
+
+export type A11yModuleSummary = {
+  /** 0–100 heuristic from DSLinter `a11y-*` findings on this source file. */
+  score: number;
+  /** Count of `a11y-*` findings on this file. */
+  issueCount: number;
+  findings: LintFinding[];
+};
+
+export { resolveModuleSourcePath } from "./modulePathMatch";
+
+export function a11ySummaryForModule(
+  report: WorkspaceReport | null | undefined,
+  modulePath: string,
+): A11yModuleSummary {
+  if (!report) {
+    return { score: 100, issueCount: 0, findings: [] };
+  }
+
+  const target = resolveModuleSourcePath(report.root, modulePath);
+  const all = report.findings.filter((f) => f.rule_id.startsWith("a11y-"));
+  const findings = all.filter((f) => pathsMatch(f.path, target));
+
+  let penalty = 0;
+  for (const f of findings) {
+    if (f.severity === "error") penalty += 25;
+    else if (f.severity === "warning") penalty += 10;
+    else penalty += 3;
+  }
+  const score = Math.max(0, Math.min(100, Math.round(100 - penalty)));
+
+  return { score, issueCount: findings.length, findings };
+}

package/src/report/codeScoreForModule.ts

@@ -0,0 +1,41 @@
+import type { LintFinding, WorkspaceReport } from "../types/report";
+import { pathsMatch, resolveModuleSourcePath } from "./modulePathMatch";
+
+function isCodeScoreRule(ruleId: string): boolean {
+  return ruleId.startsWith("smell-");
+}
+
+function lineSortKey(line: number | null): number {
+  return line == null ? Number.POSITIVE_INFINITY : line;
+}
+
+export type CodeScoreModuleSummary = {
+  score: number;
+  issueCount: number;
+  findings: LintFinding[];
+};
+
+export function codeScoreSummaryForModule(
+  report: WorkspaceReport | null | undefined,
+  modulePath: string,
+): CodeScoreModuleSummary {
+  if (!report) {
+    return { score: 100, issueCount: 0, findings: [] };
+  }
+
+  const target = resolveModuleSourcePath(report.root, modulePath);
+  const rows = report.findings.filter(
+    (f) => isCodeScoreRule(f.rule_id) && pathsMatch(f.path, target),
+  );
+  const findings = [...rows].sort((a, b) => lineSortKey(a.line) - lineSortKey(b.line));
+
+  let penalty = 0;
+  for (const f of findings) {
+    if (f.severity === "error") penalty += 25;
+    else if (f.severity === "warning") penalty += 10;
+    else penalty += 3;
+  }
+  const score = Math.max(0, Math.min(100, Math.round(100 - penalty)));
+
+  return { score, issueCount: findings.length, findings };
+}

package/src/report/modulePathMatch.ts

@@ -0,0 +1,27 @@
+function norm(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
+/** Resolve `../components/...` (from demo `src/playground`) to path under `report.root`. */
+export function resolveModuleSourcePath(reportRoot: string, modulePath: string): string {
+  const rel = norm(modulePath.replace(/^\.\.\//, ""));
+  const withSrc = rel.startsWith("components/") ? `src/${rel}` : rel;
+  const root = norm(reportRoot).replace(/\/$/, "");
+  return `${root}/${withSrc}`;
+}
+
+/** Match finding path to source file even when `report.root` differs from machine that generated JSON. */
+function tailSrcComponents(p: string): string | null {
+  const m = norm(p).match(/(src\/components\/.+)$/);
+  return m ? m[1] : null;
+}
+
+export function pathsMatch(reportPath: string, candidate: string): boolean {
+  const a = norm(reportPath);
+  const b = norm(candidate);
+  if (a === b) return true;
+  const ta = tailSrcComponents(a);
+  const tb = tailSrcComponents(b);
+  if (ta && tb) return ta === tb;
+  return false;
+}

package/src/report/tokenStyleFindingsForModule.ts

@@ -0,0 +1,24 @@
+import type { LintFinding, WorkspaceReport } from "../types/report";
+import { pathsMatch, resolveModuleSourcePath } from "./modulePathMatch";
+
+function isTokenStyleRule(ruleId: string): boolean {
+  return ruleId.startsWith("token-");
+}
+
+function lineSortKey(line: number | null): number {
+  return line == null ? Number.POSITIVE_INFINITY : line;
+}
+
+/** Hardcoded / arbitrary token color findings for a playground module path. */
+export function tokenStyleFindingsForModule(
+  report: WorkspaceReport | null | undefined,
+  modulePath: string,
+): LintFinding[] {
+  if (!report) return [];
+
+  const target = resolveModuleSourcePath(report.root, modulePath);
+  const rows = report.findings.filter(
+    (f) => isTokenStyleRule(f.rule_id) && pathsMatch(f.path, target),
+  );
+  return [...rows].sort((a, b) => lineSortKey(a.line) - lineSortKey(b.line));
+}