dslinter 0.1.5 → 0.2.0

package/src/playground/playgroundJoin.test.ts

@@ -1,9 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { WorkspaceReport } from "../types/report";
-import {
-  defaultConsumerGlobKeyFromRelPath,
-  diagnosePlaygroundJoinSkips,
-} from "./playgroundJoin";
+import { defaultConsumerGlobKeyFromRelPath, diagnosePlaygroundJoinSkips } from "./playgroundJoin";
 import { buildPlaygroundEntriesFromReportWithSkips } from "./buildPlaygroundEntriesFromReport";
 
 describe("defaultConsumerGlobKeyFromRelPath", () => {
@@ -20,11 +17,9 @@ describe("defaultConsumerGlobKeyFromRelPath", () => {
   });
 
   it("maps Laravel resources/js paths", () => {
-    expect(
-      defaultConsumerGlobKeyFromRelPath(
-        "resources/js/Components/Icons/Activity.tsx",
-      ),
-    ).toBe("../Components/Icons/Activity.tsx");
+    expect(defaultConsumerGlobKeyFromRelPath("resources/js/Components/Icons/Activity.tsx")).toBe(
+      "../Components/Icons/Activity.tsx",
+    );
   });
 });
 
@@ -34,12 +29,11 @@ describe("diagnosePlaygroundJoinSkips", () => {
     files: [],
     findings: [],
     scores: {
-      system_health: 0,
-      token_adoption: 0,
-      component_adoption: 0,
+      design_system_health: 0,
       ux_consistency: 0,
+      accessibility: 0,
+      maintainability: 0,
     },
-    ownership: [],
     duplicate_components: [],
     usage_by_component: [],
     playgrounds: [
@@ -53,9 +47,13 @@ describe("diagnosePlaygroundJoinSkips", () => {
   };
 
   it("flags module_not_found when glob key is missing", () => {
-    const skipped = diagnosePlaygroundJoinSkips(report, {}, {
-      globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath,
-    });
+    const skipped = diagnosePlaygroundJoinSkips(
+      report,
+      {},
+      {
+        globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath,
+      },
+    );
     expect(skipped).toHaveLength(1);
     expect(skipped[0]?.reason).toBe("module_not_found");
     expect(skipped[0]?.globKey).toBe("../components/ui/button.tsx");
@@ -70,13 +68,75 @@ describe("diagnosePlaygroundJoinSkips", () => {
         },
       },
     };
+    const { entries, skipped } = buildPlaygroundEntriesFromReportWithSkips(report, modules, {
+      globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath,
+      logJoinSkips: false,
+    });
+    expect(skipped).toHaveLength(0);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.id).toBe("Button");
+  });
+
+  it("joins default-exported components by export_name", () => {
+    const defaultExportReport: WorkspaceReport = {
+      ...report,
+      playgrounds: [
+        {
+          id: "AppLogoIcon",
+          export_name: "AppLogoIcon",
+          rel_path: "resources/js/components/app-logo-icon.tsx",
+          declared_props: [],
+        },
+      ],
+    };
+    const key = defaultConsumerGlobKeyFromRelPath(
+      "resources/js/components/app-logo-icon.tsx",
+    );
+    const modules = {
+      [key]: {
+        default: function AppLogoIcon() {
+          return null;
+        },
+      },
+    };
     const { entries, skipped } = buildPlaygroundEntriesFromReportWithSkips(
-      report,
+      defaultExportReport,
       modules,
-      { globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath, logJoinSkips: false },
+      {
+        globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath,
+        logJoinSkips: false,
+      },
     );
     expect(skipped).toHaveLength(0);
     expect(entries).toHaveLength(1);
-    expect(entries[0]?.id).toBe("Button");
+    expect(entries[0]?.id).toBe("AppLogoIcon");
+  });
+
+  it("joins bare rel_path via unique suffix when subdirectory scan shortened the path", () => {
+    const subdirReport: WorkspaceReport = {
+      ...report,
+      playgrounds: [
+        {
+          id: "Button",
+          export_name: "Button",
+          rel_path: "Button.tsx",
+          declared_props: [],
+        },
+      ],
+    };
+    const modules = {
+      "../Components/Button.tsx": {
+        Button: function Button() {
+          return null;
+        },
+      },
+    };
+    const { entries, skipped } = buildPlaygroundEntriesFromReportWithSkips(subdirReport, modules, {
+      globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath,
+      logJoinSkips: false,
+    });
+    expect(skipped).toHaveLength(0);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.modulePath).toBe("../Components/Button.tsx");
   });
 });

package/src/playground/playgroundJoin.ts

@@ -1,5 +1,10 @@
 import type { PlaygroundSpec, WorkspaceReport } from "../types/report";
-import type { BuildPlaygroundModules, BuildPlaygroundOptions } from "./buildPlaygroundEntriesFromReport";
+import type {
+  BuildPlaygroundModules,
+  BuildPlaygroundOptions,
+} from "./buildPlaygroundEntriesFromReport";
+import { defaultEmbedGlobKeyFromRelPath } from "./embedGlobKey";
+import { getModuleExport } from "./playgroundModuleExport";
 
 export type PlaygroundJoinSkipReason = "module_not_found" | "export_not_found";
 
@@ -12,6 +17,10 @@ export type PlaygroundJoinSkip = {
 
 const DEFAULT_CONSUMER_STRIP_PREFIXES = ["src/", "resources/js/"] as const;
 
+export function viteDevMode(): boolean {
+  return Boolean((import.meta as ImportMeta & { env?: { DEV?: boolean } }).env?.DEV);
+}
+
 /**
  * Build `globKeyFromRelPath` for a registry file one level below a source root
  * (e.g. `src/playground/` or `resources/js/playground/`).
@@ -50,17 +59,36 @@ export function defaultConsumerGlobKeyFromRelPath(relPath: string): string {
   return createConsumerGlobKeyFromRelPath()(relPath);
 }
 
-export function defaultEmbedGlobKeyFromRelPath(relPath: string): string {
+export { defaultEmbedGlobKeyFromRelPath } from "./embedGlobKey";
+
+/**
+ * When `rel_path` is a bare filename (subdirectory scan), find a unique module key
+ * whose path ends with `/${relPath}` (consumer glob or embed keys).
+ */
+export function findUniqueModuleKeyBySuffix(
+  relPath: string,
+  modules: BuildPlaygroundModules,
+): string | undefined {
   const trimmed = relPath.replace(/^\/+/, "");
-  return `@dslint-scan/${trimmed}`;
+  if (trimmed.includes("/")) return undefined;
+
+  const suffix = `/${trimmed}`;
+  const candidates = Object.keys(modules).filter((key) => key.endsWith(suffix));
+  const unique = [...new Set(candidates)];
+  return unique.length === 1 ? unique[0] : undefined;
 }
 
-function getExport(
-  mod: Record<string, unknown>,
-  exportName: string,
-): unknown {
-  const x = mod[exportName];
-  return typeof x === "function" ? x : undefined;
+/**
+ * Resolve a module map key for a report `rel_path` (exact glob key, then suffix fallback).
+ */
+export function resolveModuleKeyForRelPath(
+  relPath: string,
+  modules: BuildPlaygroundModules,
+  globKeyFromRelPath: (relPath: string) => string,
+): string | undefined {
+  const primary = globKeyFromRelPath(relPath);
+  if (modules[primary]) return primary;
+  return findUniqueModuleKeyBySuffix(relPath, modules);
 }
 
 /**
@@ -74,13 +102,13 @@ export function diagnosePlaygroundJoinSkips(
   const specs = report?.playgrounds;
   if (!specs?.length) return [];
 
-  const globKeyFromRelPath =
-    options.globKeyFromRelPath ?? defaultEmbedGlobKeyFromRelPath;
+  const globKeyFromRelPath = options.globKeyFromRelPath ?? defaultEmbedGlobKeyFromRelPath;
 
   const skipped: PlaygroundJoinSkip[] = [];
   for (const spec of specs) {
     const globKey = globKeyFromRelPath(spec.rel_path);
-    const mod = modules[globKey];
+    const resolvedKey = resolveModuleKeyForRelPath(spec.rel_path, modules, globKeyFromRelPath);
+    const mod = resolvedKey ? modules[resolvedKey] : undefined;
     if (!mod) {
       skipped.push({
         export_name: spec.export_name,
@@ -90,11 +118,11 @@ export function diagnosePlaygroundJoinSkips(
       });
       continue;
     }
-    if (!getExport(mod, spec.export_name)) {
+    if (!getModuleExport(mod, spec.export_name)) {
       skipped.push({
         export_name: spec.export_name,
         rel_path: spec.rel_path,
-        globKey,
+        globKey: resolvedKey ?? globKey,
         reason: "export_not_found",
       });
     }
@@ -103,19 +131,18 @@ export function diagnosePlaygroundJoinSkips(
 }
 
 /**
- * Dev-only: log skipped playground joins (module glob / export name mismatches).
+ * Log skipped playground joins (module glob / export name mismatches).
+ * Opt-in via `logJoinSkips: true` on {@link buildPlaygroundEntriesFromReportWithSkips}.
  */
 export function logPlaygroundJoinSkips(
   skipped: PlaygroundJoinSkip[],
   options?: { label?: string },
 ): void {
   if (!skipped.length) return;
-  if (typeof import.meta !== "undefined" && !import.meta.env?.DEV) return;
+  if (!viteDevMode()) return;
 
   const label = options?.label ?? "[dslinter] playground preview";
-  console.warn(
-    `${label}: ${skipped.length} component(s) have a scan row but no live preview.`,
-  );
+  console.warn(`${label}: ${skipped.length} component(s) have a scan row but no live preview.`);
   for (const s of skipped.slice(0, 12)) {
     const hint =
       s.reason === "module_not_found"
@@ -132,9 +159,7 @@ export function findPlaygroundSpec(
   report: WorkspaceReport | null | undefined,
   componentId: string,
 ): PlaygroundSpec | undefined {
-  return report?.playgrounds?.find(
-    (p) => p.export_name === componentId || p.id === componentId,
-  );
+  return report?.playgrounds?.find((p) => p.export_name === componentId || p.id === componentId);
 }
 
 export function findPlaygroundJoinSkip(

package/src/playground/playgroundModuleExport.test.ts

@@ -0,0 +1,42 @@
+import { forwardRef } from "react";
+import { describe, expect, it } from "vitest";
+import { getModuleExport, isPlaygroundComponent } from "./playgroundModuleExport";
+
+describe("playgroundModuleExport", () => {
+  it("accepts forwardRef components", () => {
+    const Forward = forwardRef(() => null);
+    expect(typeof Forward).toBe("object");
+    expect(isPlaygroundComponent(Forward)).toBe(true);
+  });
+
+  it("getModuleExport returns forwardRef export", () => {
+    const Forward = forwardRef(() => null);
+    Forward.displayName = "DropdownMenu";
+    const mod = { DropdownMenu: Forward };
+    expect(getModuleExport(mod, "DropdownMenu")).toBe(Forward);
+  });
+
+  it("getModuleExport falls back to default export when named export is missing", () => {
+    function AppLogoIcon() {
+      return null;
+    }
+    const mod = { default: AppLogoIcon };
+    expect(getModuleExport(mod, "AppLogoIcon")).toBe(AppLogoIcon);
+  });
+
+  it("getModuleExport prefers named export over default", () => {
+    function Named() {
+      return null;
+    }
+    function DefaultOnly() {
+      return null;
+    }
+    const mod = { Button: Named, default: DefaultOnly };
+    expect(getModuleExport(mod, "Button")).toBe(Named);
+  });
+
+  it("rejects non-components", () => {
+    expect(isPlaygroundComponent(null)).toBe(false);
+    expect(isPlaygroundComponent({ foo: 1 })).toBe(false);
+  });
+});

package/src/playground/playgroundModuleExport.ts

@@ -0,0 +1,22 @@
+import type { ComponentType } from "react";
+
+/** True for function components and exotic types (forwardRef, memo). */
+export function isPlaygroundComponent(value: unknown): value is ComponentType<
+  Record<string, unknown>
+> {
+  if (typeof value === "function") return true;
+  if (typeof value !== "object" || value === null) return false;
+  const o = value as Record<string, unknown>;
+  return typeof o.render === "function" || typeof o.$$typeof === "symbol";
+}
+
+export function getModuleExport(
+  mod: Record<string, unknown>,
+  exportName: string,
+): ComponentType<Record<string, unknown>> | undefined {
+  const named = mod[exportName];
+  if (isPlaygroundComponent(named)) return named;
+  const fallback = mod.default;
+  if (isPlaygroundComponent(fallback)) return fallback;
+  return undefined;
+}

package/src/playground/playgroundSpecsKey.ts

@@ -0,0 +1,8 @@
+import type { WorkspaceReport } from "../types/report";
+
+/** Stable memo key — ignores report object identity when playground specs are unchanged. */
+export function playgroundSpecsKey(
+  report: WorkspaceReport | null | undefined,
+): string {
+  return JSON.stringify(report?.playgrounds ?? []);
+}

package/src/playground/propCoerce.ts

@@ -0,0 +1,91 @@
+import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+import type { DeclaredPropKind, PlaygroundSpec } from "../types/report";
+import {
+  childrenPropForPreview,
+  isLikelyBooleanProp,
+  isPassthroughStringProp,
+  SKIP_PLAYGROUND_PROPS,
+} from "./controls";
+
+export function coerceDeclaredPropKind(v: unknown): DeclaredPropKind | undefined {
+  if (v === "boolean" || v === "string" || v === "number" || v === "unknown")
+    return v;
+  return undefined;
+}
+
+export function normalizedPropKinds(
+  raw: PlaygroundSpec["declared_prop_kinds"],
+): Partial<Record<string, DeclaredPropKind>> | undefined {
+  if (!raw || typeof raw !== "object") return undefined;
+  const out: Partial<Record<string, DeclaredPropKind>> = {};
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    const ck = coerceDeclaredPropKind(v);
+    if (ck && ck !== "unknown") out[k] = ck;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+function propKeysForPreview(
+  controls: PlaygroundControl[],
+  declaredProps: string[],
+): string[] {
+  if (controls.length > 0) return controls.map((c) => c.key);
+  return declaredProps.filter((k) => k !== "key" && k !== "ref");
+}
+
+export function valuesToComponentProps(
+  controls: PlaygroundControl[],
+  declaredProps: string[],
+  values: PlaygroundArgs,
+  propKinds?: Partial<Record<string, DeclaredPropKind>>,
+  exportName?: string,
+): Record<string, unknown> {
+  const o: Record<string, unknown> = {};
+  for (const key of propKeysForPreview(controls, declaredProps)) {
+    if (SKIP_PLAYGROUND_PROPS.has(key)) continue;
+    if (isPassthroughStringProp(key)) {
+      const raw = values[key];
+      if (raw === undefined || raw === null || String(raw).length === 0) continue;
+      o[key] = String(raw);
+      continue;
+    }
+    if (key === "children") {
+      const coerced = childrenPropForPreview(exportName, values.children);
+      if (coerced !== undefined) o[key] = coerced;
+      continue;
+    }
+    const kind = propKinds?.[key];
+    if (kind === "boolean") {
+      o[key] = Boolean(values[key]);
+      continue;
+    }
+    if (kind === "number") {
+      const raw = values[key];
+      const n = typeof raw === "number" ? raw : Number(raw);
+      o[key] = Number.isFinite(n) ? n : 0;
+      continue;
+    }
+    if (kind === "string") {
+      o[key] = values[key];
+      continue;
+    }
+    if (isLikelyBooleanProp(key)) {
+      o[key] = Boolean(values[key]);
+      continue;
+    }
+    o[key] = values[key];
+  }
+  return o;
+}
+
+export function mergeStaticDefaults(
+  fromValues: Record<string, unknown>,
+  staticDefaults: Record<string, unknown>,
+): Record<string, unknown> {
+  const o = { ...fromValues };
+  for (const [k, v] of Object.entries(staticDefaults)) {
+    const cur = o[k];
+    if (cur === undefined || (cur === "" && k !== "children")) o[k] = v;
+  }
+  return o;
+}

package/src/playground/scanVariantA11y.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatVariantLabel,
+  mergePlaygroundA11yFindings,
+  playgroundA11yScore,
+} from "./scanVariantA11y";
+
+describe("formatVariantLabel", () => {
+  it("joins axis keys and values", () => {
+    expect(
+      formatVariantLabel(
+        { variant: "destructive", size: "default", asChild: false },
+        ["variant", "size"],
+      ),
+    ).toBe("variant=destructive size=default");
+  });
+});
+
+describe("playgroundA11yScore", () => {
+  it("combines static and variant findings", () => {
+    const staticFindings = [
+      {
+        rule_id: "a11y-button-name",
+        message: "missing name",
+        path: "Button.tsx",
+        line: 1,
+        severity: "warning" as const,
+      },
+    ];
+    const variantFindings = [
+      {
+        rule_id: "a11y-playground-color-contrast",
+        message: "contrast too low",
+        path: "",
+        line: null,
+        severity: "error" as const,
+        variant_label: "variant=destructive size=default",
+      },
+    ];
+
+    expect(
+      mergePlaygroundA11yFindings(staticFindings, variantFindings),
+    ).toHaveLength(2);
+    expect(playgroundA11yScore(staticFindings, variantFindings)).toBe(65);
+  });
+});

package/src/playground/scanVariantA11y.ts

@@ -0,0 +1,107 @@
+import type { PlaygroundArgs } from "../types/controls";
+import type { LintFinding, Severity } from "../types/report";
+import { a11yScoreFromFindings } from "../report/a11yScoring";
+
+export type PlaygroundA11yFinding = LintFinding;
+
+export type VariantPreviewTarget = {
+  element: Element;
+  combo: PlaygroundArgs;
+  axisKeys: string[];
+};
+
+const SCAN_CONCURRENCY = 4;
+
+function formatAxisValue(value: string | number | boolean | undefined): string {
+  if (value === undefined) return "?";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
+export function formatVariantLabel(
+  combo: PlaygroundArgs,
+  axisKeys: string[],
+): string {
+  return axisKeys
+    .map((key) => `${key}=${formatAxisValue(combo[key])}`)
+    .join(" ");
+}
+
+function axeImpactToSeverity(
+  impact: string | null | undefined,
+): Severity {
+  if (impact === "critical" || impact === "serious") return "error";
+  if (impact === "moderate") return "warning";
+  return "info";
+}
+
+async function loadAxe() {
+  const mod = await import("axe-core");
+  return mod.default;
+}
+
+export async function scanElementA11y(
+  element: Element,
+  variantLabel: string,
+): Promise<PlaygroundA11yFinding[]> {
+  const axe = await loadAxe();
+  const results = await axe.run(element, {
+    runOnly: {
+      type: "rule",
+      values: ["color-contrast"],
+    },
+  });
+
+  const findings: PlaygroundA11yFinding[] = [];
+  for (const violation of results.violations) {
+    const severity = axeImpactToSeverity(violation.impact);
+    const summary = violation.help || violation.description;
+    for (const node of violation.nodes) {
+      findings.push({
+        rule_id: `a11y-playground-${violation.id}`,
+        message: node.failureSummary
+          ? `${summary} (${node.failureSummary})`
+          : summary,
+        path: "",
+        line: null,
+        severity,
+        variant_label: variantLabel,
+      });
+    }
+  }
+  return findings;
+}
+
+export async function scanVariantPreviews(
+  targets: VariantPreviewTarget[],
+): Promise<PlaygroundA11yFinding[]> {
+  const findings: PlaygroundA11yFinding[] = [];
+
+  for (let i = 0; i < targets.length; i += SCAN_CONCURRENCY) {
+    const chunk = targets.slice(i, i + SCAN_CONCURRENCY);
+    const chunkFindings = await Promise.all(
+      chunk.map(({ element, combo, axisKeys }) =>
+        scanElementA11y(element, formatVariantLabel(combo, axisKeys)),
+      ),
+    );
+    findings.push(...chunkFindings.flat());
+  }
+
+  return findings;
+}
+
+export function mergePlaygroundA11yFindings(
+  staticFindings: LintFinding[],
+  variantFindings: PlaygroundA11yFinding[],
+): PlaygroundA11yFinding[] {
+  return [...staticFindings, ...variantFindings];
+}
+
+export function playgroundA11yScore(
+  staticFindings: LintFinding[],
+  variantFindings: PlaygroundA11yFinding[],
+): number {
+  return a11yScoreFromFindings(
+    mergePlaygroundA11yFindings(staticFindings, variantFindings),
+  );
+}

package/src/playground/snippet.ts

@@ -0,0 +1,83 @@
+import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+
+function jsxTextOrStringifyExpression(text: string): string {
+  if (!/[<>{}&]/.test(text)) return text;
+  return `{JSON.stringify(${JSON.stringify(text)})}`;
+}
+
+function valueMatchesPlaygroundDefault(
+  control: PlaygroundControl,
+  value: string | number | boolean | undefined,
+): boolean {
+  switch (control.type) {
+    case "boolean":
+      return Boolean(value) === control.default;
+    case "number": {
+      const n = typeof value === "number" ? value : Number(value);
+      return Number.isFinite(n) && n === control.default;
+    }
+    case "string":
+    case "select":
+      return String(value ?? "") === String(control.default);
+    default:
+      return false;
+  }
+}
+
+export function genericUsageSnippet(
+  exportName: string,
+  values: PlaygroundArgs,
+  controls: PlaygroundControl[],
+): string {
+  const controlByKey = new Map(controls.map((c) => [c.key, c] as const));
+
+  const emitPropKey = (key: string): boolean => {
+    const c = controlByKey.get(key);
+    if (!c) return true;
+    return !valueMatchesPlaygroundDefault(c, values[key]);
+  };
+
+  const hasChildrenKey = Object.prototype.hasOwnProperty.call(
+    values,
+    "children",
+  );
+  const childVal = hasChildrenKey ? values.children : undefined;
+
+  const propKeys = Object.keys(values)
+    .filter((k) => k !== "children")
+    .filter(emitPropKey)
+    .sort((a, b) => a.localeCompare(b));
+  const propsStr = propKeys
+    .map((k) => `${k}={${JSON.stringify(values[k])}}`)
+    .join(" ");
+
+  const openWithProps =
+    propKeys.length === 0 ? `<${exportName}` : `<${exportName} ${propsStr}`;
+
+  if (!hasChildrenKey) {
+    return propKeys.length === 0 ? `<${exportName} />` : `${openWithProps} />`;
+  }
+
+  if (typeof childVal === "boolean") {
+    const allKeys = Object.keys(values)
+      .filter(emitPropKey)
+      .sort((a, b) => a.localeCompare(b));
+    const allProps = allKeys
+      .map((k) => `${k}={${JSON.stringify(values[k])}}`)
+      .join(" ");
+    return allKeys.length === 0
+      ? `<${exportName} />`
+      : `<${exportName} ${allProps} />`;
+  }
+
+  const asText =
+    typeof childVal === "number" ? String(childVal) : String(childVal ?? "");
+  if (asText.length === 0) {
+    return propKeys.length === 0 ? `<${exportName} />` : `${openWithProps} />`;
+  }
+
+  const body = jsxTextOrStringifyExpression(asText);
+  return propKeys.length === 0
+    ? `<${exportName}>${body}</${exportName}>`
+    : `${openWithProps}>${body}</${exportName}>`;
+}