dslinter 0.2.3 → 0.3.0

package/src/dashboard/paths.test.ts

@@ -1,9 +1,26 @@
 import { describe, expect, it } from "vitest";
-import { truncatePathMiddle } from "./paths";
+import { resolveReportAbsolutePath, truncatePathMiddle } from "./paths";
 
 const SAMPLE =
   "resources/js/components/manage-two-factor.tsx";
 
+describe("resolveReportAbsolutePath", () => {
+  it("returns absolute paths unchanged when under root", () => {
+    expect(
+      resolveReportAbsolutePath(
+        "/repo",
+        "/repo/src/components/Button.tsx",
+      ),
+    ).toBe("/repo/src/components/Button.tsx");
+  });
+
+  it("joins root-relative paths", () => {
+    expect(
+      resolveReportAbsolutePath("/repo", "src/pages/Home.tsx"),
+    ).toBe("/repo/src/pages/Home.tsx");
+  });
+});
+
 describe("truncatePathMiddle", () => {
   it("returns the path unchanged when it fits", () => {
     expect(truncatePathMiddle(SAMPLE, 100)).toBe(SAMPLE);

package/src/dashboard/paths.ts

@@ -14,6 +14,14 @@ export function shortPath(root: string, fullPath: string): string {
   return parts.slice(-3).join("/");
 }
 
+/** Resolve a report path (absolute or root-relative) to an absolute path. */
+export function resolveReportAbsolutePath(root: string, path: string): string {
+  const r = normalizePath(root);
+  const p = normalizePath(path);
+  if (p.startsWith(r + "/") || p === r) return p;
+  return `${r}/${p}`;
+}
+
 /**
  * Truncate a file path from the middle, preserving the filename and path
  * separators. Leading path segments are kept when space allows.

package/src/mcp/agent-query.ts

@@ -7,7 +7,7 @@ import {
 import { findingsForComponent } from "../report/findingsForComponent";
 import { controlsForSpec } from "../playground/controls";
 import { genericUsageSnippet } from "../playground/snippet";
-import { pillarForRule, ruleById, ruleCatalog } from "./rule-catalog";
+import { pillarForRule, ruleCatalog } from "./rule-catalog";
 import { findingMatchesPath } from "./normalize-paths";
 import type {
   ConfigSnapshot,

package/src/playground/buildPlaygroundEntriesFromReport.test.ts

@@ -86,7 +86,7 @@ describe("playground preview props", () => {
   it("maps playground control values even when declared_props omits them", () => {
     const controlOverrides: Record<string, PlaygroundControl[]> = {
       Demo: [
-        { key: "children", label: "children", type: "string", default: "" },
+        { key: "children", label: "children", type: "node", default: "" },
         {
           key: "variant",
           label: "variant",
@@ -168,8 +168,8 @@ describe("playground preview props", () => {
     expect(asChild?.type).toBe("boolean");
 
     const children = entry!.controls.find((c) => c.key === "children");
-    expect(children?.type).toBe("string");
-    if (children?.type === "string") {
+    expect(children?.type).toBe("node");
+    if (children?.type === "node") {
       expect(children.default).toBe("Example");
     }
 

package/src/playground/controls.ts

@@ -19,18 +19,19 @@ export function stringDefaultForProp(key: string): string {
 }
 
 export type PlaygroundStringControl = Extract<PlaygroundControl, { type: "string" }>;
+export type PlaygroundNodeControl = Extract<PlaygroundControl, { type: "node" }>;
 
 /** Parts like BreadcrumbSeparator default to an icon when children is omitted. */
 export function usesIconChildrenFallback(exportName: string): boolean {
   return exportName.endsWith("Separator");
 }
 
-export function childrenControl(exportName?: string): PlaygroundStringControl {
+export function childrenControl(exportName?: string): PlaygroundNodeControl {
   if (exportName && usesIconChildrenFallback(exportName)) {
     return {
       key: "children",
       label: "children",
-      type: "string",
+      type: "node",
       default: "",
       placeholder: "Custom separator (chevron when empty)",
     };
@@ -38,12 +39,22 @@ export function childrenControl(exportName?: string): PlaygroundStringControl {
   return {
     key: "children",
     label: "children",
-    type: "string",
+    type: "node",
     default: CHILDREN_SLOT_DEFAULT,
     placeholder: "Slot content",
   };
 }
 
+export function nodeControlForProp(key: string): PlaygroundNodeControl {
+  return {
+    key,
+    label: key,
+    type: "node",
+    default: defaultStringForProp(key),
+    placeholder: "Slot content",
+  };
+}
+
 export function childrenPropForPreview(
   exportName: string | undefined,
   raw: unknown,
@@ -133,6 +144,8 @@ export function controlsFromDeclaredProps(
       out.push({ key, label: key, type: "boolean", default: false });
     } else if (kind === "number") {
       out.push({ key, label: key, type: "number", default: 0 });
+    } else if (kind === "node") {
+      out.push(nodeControlForProp(key));
     } else if (kind === "string") {
       out.push({
         key,

package/src/playground/enrichKitControls.ts

@@ -29,7 +29,7 @@ function enrichOneControl(control: PlaygroundControl, slot: KitJsxSlot | undefin
   const exampleDefault = slotDefaultFromComponent(slot.component);
   const hint = `${slot.component} children`;
 
-  if (control.type === "string") {
+  if (control.type === "string" || control.type === "node") {
     const useExample =
       exampleDefault !== undefined &&
       (control.default === control.key || control.default === control.key.toLowerCase());
@@ -102,12 +102,12 @@ function propMetadataForCatalog(
 
   const def = definitionForExport(report, spec.export_name);
   const propOptions = {
-    ...(def?.declared_prop_options ?? {}),
-    ...(spec.declared_prop_options ?? {}),
+    ...def?.declared_prop_options,
+    ...spec.declared_prop_options,
   };
   const propDefaults = {
-    ...(def?.declared_prop_defaults ?? {}),
-    ...(spec.declared_prop_defaults ?? {}),
+    ...def?.declared_prop_defaults,
+    ...spec.declared_prop_defaults,
   };
   const propKinds = { ...spec.declared_prop_kinds };
 

package/src/playground/inferKitJsx.test.ts

@@ -1,4 +1,3 @@
-import { createElement } from "react";
 import { describe, expect, it } from "vitest";
 import {
   inferKitJsxSlots,
@@ -7,16 +6,6 @@ import {
   slotLabelFromComponent,
 } from "./inferKitJsx";
 
-function Alert(props: { variant?: string; children?: unknown }) {
-  return createElement("div", props);
-}
-function AlertTitle(props: { children?: unknown }) {
-  return createElement("div", props);
-}
-function AlertDescription(props: { children?: unknown }) {
-  return createElement("div", props);
-}
-
 describe("inferKitJsx", () => {
   it("reads createElement children bindings (including vite transforms)", () => {
     const viteTransformed =

package/src/playground/inferPropTypesFromTs.d.mts

@@ -1,7 +1,7 @@
 import type { Program, TypeChecker, SourceFile, Type } from "typescript";
 import type { PlaygroundSpec } from "../types/report.js";
 
-export type PropKind = "boolean" | "string" | "number";
+export type PropKind = "boolean" | "string" | "number" | "node";
 
 export type CheckerProgram = {
   program: Program;

package/src/playground/inferPropTypesFromTs.mjs

@@ -122,12 +122,22 @@ export function findComponentParamType(checker, sf, exportName) {
   return found;
 }
 
+/** @param {ts.TypeChecker} checker @param {ts.Type} type */
+function isReactNodeType(checker, type) {
+  const alias = type.aliasSymbol?.escapedName ?? type.aliasSymbol?.name;
+  if (alias === "ReactNode" || alias === "ReactElement") return true;
+  const text = checker.typeToString(type);
+  if (text === "ReactNode" || text === "ReactElement") return true;
+  return false;
+}
+
 /**
  * @param {ts.TypeChecker} checker
  * @param {ts.Type} type
  * @returns {PropKind | null}
  */
 export function classifyPropType(checker, type) {
+  if (isReactNodeType(checker, type)) return "node";
   const nn = checker.getNonNullableType(type);
   if (nn.isUnion()) {
     const parts = nn.types.map((u) =>
@@ -146,10 +156,16 @@ export function classifyPropType(checker, type) {
   return null;
 }
 
-/** @param {ts.TypeChecker} checker @param {ts.Type} type */
-function followTypeAlias(checker, type) {
+/** @param {ts.TypeChecker} checker @param {ts.Type} type @param {Set<number>} [seen] */
+function followTypeAlias(checker, type, seen = new Set()) {
   if (type.aliasSymbol) {
-    return followTypeAlias(checker, checker.getDeclaredTypeOfSymbol(type.aliasSymbol));
+    if (seen.has(type.id)) return type;
+    seen.add(type.id);
+    return followTypeAlias(
+      checker,
+      checker.getDeclaredTypeOfSymbol(type.aliasSymbol),
+      seen,
+    );
   }
   return type;
 }

package/src/playground/inferPropTypesFromTs.test.ts

@@ -217,6 +217,38 @@ describe("enrichPlaygroundSpecFromTs", () => {
     expect(enriched.declared_prop_defaults?.type).toBe("text");
     expect(enriched.declared_prop_kinds?.type).toBe("string");
   });
+
+  it("classifies ReactNode props as node", () => {
+    const root = tempProject({
+      "src/section.tsx": `
+        import type { ReactNode } from "react";
+        export function Section({
+          children,
+          actions,
+        }: {
+          children: ReactNode;
+          actions?: ReactNode;
+        }) {
+          return null;
+        }
+      `,
+    });
+    const bundle = createCheckerProgram(root)!;
+    const spec: PlaygroundSpec = {
+      id: "Section",
+      export_name: "Section",
+      rel_path: "src/section.tsx",
+      declared_props: ["children", "actions"],
+    };
+    const enriched = enrichPlaygroundSpecFromTs(
+      spec,
+      bundle.checker,
+      bundle.program,
+      root,
+    );
+    expect(enriched.declared_prop_kinds?.children).toBe("node");
+    expect(enriched.declared_prop_kinds?.actions).toBe("node");
+  });
 });
 
 describe("createCheckerProgram", () => {

package/src/playground/inferPropTypesFromTs.ts

@@ -1,5 +1,5 @@
 export type { DeclaredPropKind, PlaygroundSpec } from "../types/report";
-export type PropKind = "boolean" | "string" | "number";
+export type PropKind = "boolean" | "string" | "number" | "node";
 
 export type CheckerProgram = {
   program: import("typescript").Program;

package/src/playground/playgroundJoin.ts

@@ -168,3 +168,37 @@ export function findPlaygroundJoinSkip(
 ): PlaygroundJoinSkip | undefined {
   return skipped?.find((s) => s.export_name === componentId);
 }
+
+/** User-facing hint when a playground spec cannot join to the Vite module graph. */
+export function playgroundJoinDetailMessage(
+  skip: PlaygroundJoinSkip | undefined,
+  spec: PlaygroundSpec | undefined,
+): string | null {
+  if (skip?.reason === "module_not_found") {
+    const { globKey, rel_path } = skip;
+    const subdirHint = !rel_path.includes("/")
+      ? " This usually means the scanner was run from a subdirectory. Re-run from the project root: npx dslinter ."
+      : "";
+    if (globKey.startsWith("@dslinter-scan/")) {
+      return [
+        `Expected module key "${globKey}" but the dslinter Vite plugin did not load it.`,
+        `Use <DashboardLayout autoPlayground /> and run via npx dslinter (zero vite.config changes), or add plugins: [dslinter()] from dslinter/vite to vite.config.ts.`,
+        `Run the scanner from the project root so rel_path "${rel_path}" matches files under DSLINTER_SCAN_ROOT.`,
+      ].join(" ");
+    }
+    return [
+      `Vite glob is missing key "${globKey}" for report path "${rel_path}".`,
+      `Prefer <DashboardLayout autoPlayground /> with plugins: [dslinter()] from dslinter/vite, or run npx dslinter init for a custom buildRegistry.ts glob.`,
+      subdirHint,
+    ]
+      .filter(Boolean)
+      .join("");
+  }
+  if (skip?.reason === "export_not_found") {
+    return `Module loaded but named export "${skip.export_name}" was not found. Use export function ${skip.export_name}(…) in ${skip.rel_path}.`;
+  }
+  if (spec) {
+    return `Report path: ${spec.rel_path} (export ${spec.export_name}). Use autoPlayground with dslinter/vite, or ensure buildRegistry.ts glob covers this file.`;
+  }
+  return null;
+}

package/src/playground/propCoerce.ts

@@ -8,7 +8,7 @@ import {
 } from "./controls";
 
 export function coerceDeclaredPropKind(v: unknown): DeclaredPropKind | undefined {
-  if (v === "boolean" || v === "string" || v === "number" || v === "unknown")
+  if (v === "boolean" || v === "string" || v === "number" || v === "node" || v === "unknown")
     return v;
   return undefined;
 }
@@ -65,7 +65,7 @@ export function valuesToComponentProps(
       o[key] = Number.isFinite(n) ? n : 0;
       continue;
     }
-    if (kind === "string") {
+    if (kind === "string" || kind === "node") {
       o[key] = values[key];
       continue;
     }

package/src/playground/snippet.ts

@@ -17,6 +17,7 @@ function valueMatchesPlaygroundDefault(
       return Number.isFinite(n) && n === control.default;
     }
     case "string":
+    case "node":
     case "select":
       return String(value ?? "") === String(control.default);
     default:

package/src/shell/DashboardLayout.tsx

@@ -14,6 +14,7 @@ import type { TokenCatalog } from "../types/tokenCatalog";
 import type { DslinterReportState } from "../dashboard/useWorkspaceReport";
 import { ComponentInspectPane } from "../components/ComponentInspectPane";
 import { ComponentPlaygroundPane } from "../components/ComponentPlaygroundPane";
+import { CatalogPane } from "../components/CatalogPane";
 import { GovernancePane } from "../components/GovernancePane";
 import { Sidebar } from "../components/Sidebar";
 import { TokensPane } from "../components/TokensPane";
@@ -21,6 +22,7 @@ import { DashboardCommandPalette } from "../components/DashboardCommandPalette";
 import {
   componentCatalogNamesFromReport,
   componentCatalogTreeFromReport,
+  resolveFamilyNavigationTarget,
 } from "../dashboard/aggregate";
 import { reportWithExtraHidden } from "../dashboard/catalogVisibility";
 import { resolvePlaygroundEntry } from "../playground/buildPlaygroundEntriesFromReport";
@@ -186,14 +188,17 @@ export function DashboardLayoutInner({
         return [{ name: item.name, label: item.name }];
       }
       return [
-        { name: item.parent, label: item.parent },
+        {
+          name: resolveFamilyNavigationTarget(item, catalogNames),
+          label: item.parent,
+        },
         ...item.children.map((child) => ({
           name: child,
           label: `${item.parent} / ${child}`,
         })),
       ];
     });
-  }, [catalogReport]);
+  }, [catalogReport, catalogNames]);
 
   const handleHideFromCatalog = useCallback(
     (componentName: string) => {
@@ -230,9 +235,22 @@ export function DashboardLayoutInner({
         onOpenComponent={(name) =>
           navigate({ view: "component", componentId: name })
         }
+        onOpenCatalog={() => navigate({ view: "catalog" })}
       />
     );
-  } else {
+  } else if (route.view === "catalog") {
+    main = (
+      <CatalogPane
+        landing={overview}
+        dslinterReportHint={dslinterReportHint}
+        dslinterReport={dslinterReport}
+        onOpenComponent={(name) =>
+          navigate({ view: "component", componentId: name })
+        }
+        onBackToGovernance={() => navigate({ view: "governance" })}
+      />
+    );
+  } else if (route.view === "component") {
     const componentId = route.componentId;
     const entry = resolvePlaygroundEntry(playgroundEntries, componentId);
     const inCatalog = catalogNames.includes(componentId);
@@ -264,7 +282,6 @@ export function DashboardLayoutInner({
             playgroundJoinSkips,
             componentId,
           )}
-          onBackToGovernance={() => navigate({ view: "governance" })}
           onOpenComponent={(name) =>
             navigate({ view: "component", componentId: name })
           }

package/src/shell/hashRoute.test.ts

@@ -18,6 +18,11 @@ describe("parseHashRoute", () => {
   it("parses tokens", () => {
     expect(parseHashRoute("/tokens")).toEqual({ view: "tokens" });
   });
+
+  it("parses catalog", () => {
+    expect(parseHashRoute("/catalog")).toEqual({ view: "catalog" });
+    expect(parseHashRoute("/governance/catalog")).toEqual({ view: "catalog" });
+  });
 });
 
 describe("formatHashRoute", () => {
@@ -30,4 +35,8 @@ describe("formatHashRoute", () => {
   it("formats governance", () => {
     expect(formatHashRoute({ view: "governance" })).toBe("/governance");
   });
+
+  it("formats catalog", () => {
+    expect(formatHashRoute({ view: "catalog" })).toBe("/catalog");
+  });
 });

package/src/shell/hashRoute.ts

@@ -1,6 +1,7 @@
 export type HashRoute =
   | { view: "tokens" }
   | { view: "governance" }
+  | { view: "catalog" }
   | { view: "component"; componentId: string };
 
 function trimTrailingSlashes(path: string): string {
@@ -27,6 +28,9 @@ export function parseHashRoute(pathname: string): HashRoute {
   if (path === "/tokens") {
     return { view: "tokens" };
   }
+  if (path === "/catalog" || path === "/governance/catalog") {
+    return { view: "catalog" };
+  }
   if (path.startsWith("/component/")) {
     const componentId = decodeURIComponent(path.slice("/component/".length));
     if (componentId.length > 0) {
@@ -42,6 +46,8 @@ export function formatHashRoute(route: HashRoute): string {
       return "/tokens";
     case "governance":
       return "/governance";
+    case "catalog":
+      return "/catalog";
     case "component":
       return `/component/${encodeURIComponent(route.componentId)}`;
     default:

package/src/types/controls.ts

@@ -26,6 +26,16 @@ export type PlaygroundStringControl = {
   placeholder?: string;
 };
 
+export type PlaygroundNodeControl = {
+  key: string;
+  label: string;
+  type: "node";
+  default: string;
+  defaultSource?: PlaygroundDefaultSource;
+  placeholder?: string;
+  hint?: string;
+};
+
 export type PlaygroundNumberControl = {
   key: string;
   label: string;
@@ -49,6 +59,7 @@ export type PlaygroundSelectControl = {
 export type PlaygroundControl =
   | PlaygroundBooleanControl
   | PlaygroundStringControl
+  | PlaygroundNodeControl
   | PlaygroundNumberControl
   | PlaygroundSelectControl;
 
@@ -61,6 +72,7 @@ export function defaultArgsFromControls(controls: PlaygroundControl[] | undefine
         out[c.key] = c.default;
         break;
       case "string":
+      case "node":
       case "select":
         out[c.key] = c.default;
         break;

package/src/types/report.ts

@@ -90,7 +90,7 @@ export interface UsageSummary {
  * Simplified prop kind from TypeScript (e.g. demo `merge-playgrounds.mjs`).
  * Dashboard falls back to name heuristics when a key is missing or kind is `unknown`.
  */
-export type DeclaredPropKind = "boolean" | "string" | "number" | "unknown";
+export type DeclaredPropKind = "boolean" | "string" | "number" | "node" | "unknown";
 
 /** Emitted by dslint for dashboard playgrounds (no per-component TS registration). */
 export interface PlaygroundSpec {

package/vite/embedTailwindSources.ts

@@ -4,14 +4,16 @@ import { projectRootForConfig, readIncludeDirs } from "./collectScanModules";
 
 const FALLBACK_INCLUDE_DIRS = ["resources/js", "src", "app"];
 
-const DASHBOARD_SRC_MARKER = `${join("packages", "dashboard", "src")}`;
-
 function normalizePosixPath(path: string): string {
   return path.replace(/\\/g, "/").replace(/\/$/, "");
 }
 
-function isDashboardPackageSrc(absPath: string): boolean {
-  return normalizePosixPath(absPath).endsWith(DASHBOARD_SRC_MARKER);
+function isDashboardPackageSrc(absPath: string, packageRoot: string): boolean {
+  const dashboardSrc = normalizePosixPath(join(resolve(packageRoot), "src"));
+  const normalized = normalizePosixPath(absPath);
+  return (
+    normalized === dashboardSrc || normalized.startsWith(`${dashboardSrc}/`)
+  );
 }
 
 function resolveConsumerSourceAbsDirs(
@@ -34,7 +36,7 @@ function resolveConsumerSourceAbsDirs(
     if (!norm) continue;
     const abs = resolve(projectRoot, norm);
     if (!existsSync(abs)) continue;
-    if (isDashboardPackageSrc(abs)) continue;
+    if (isDashboardPackageSrc(abs, packageRoot)) continue;
     unique.add(abs);
   }
 
@@ -42,7 +44,7 @@ function resolveConsumerSourceAbsDirs(
     for (const dir of FALLBACK_INCLUDE_DIRS) {
       const abs = resolve(scanAbs, dir);
       if (!existsSync(abs)) continue;
-      if (isDashboardPackageSrc(abs)) continue;
+      if (isDashboardPackageSrc(abs, packageRoot)) continue;
       unique.add(abs);
     }
   }