dslinter 0.1.1 → 0.1.3

package/src/playground/playgroundJoin.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import type { WorkspaceReport } from "../types/report";
+import {
+  defaultConsumerGlobKeyFromRelPath,
+  diagnosePlaygroundJoinSkips,
+} from "./playgroundJoin";
+import { buildPlaygroundEntriesFromReportWithSkips } from "./buildPlaygroundEntriesFromReport";
+
+describe("defaultConsumerGlobKeyFromRelPath", () => {
+  it("maps nested ui paths for src/playground registry", () => {
+    expect(defaultConsumerGlobKeyFromRelPath("src/components/ui/button.tsx")).toBe(
+      "../components/ui/button.tsx",
+    );
+  });
+
+  it("maps flat component paths", () => {
+    expect(defaultConsumerGlobKeyFromRelPath("src/components/Button.tsx")).toBe(
+      "../components/Button.tsx",
+    );
+  });
+
+  it("maps Laravel resources/js paths", () => {
+    expect(
+      defaultConsumerGlobKeyFromRelPath(
+        "resources/js/Components/Icons/Activity.tsx",
+      ),
+    ).toBe("../Components/Icons/Activity.tsx");
+  });
+});
+
+describe("diagnosePlaygroundJoinSkips", () => {
+  const report: WorkspaceReport = {
+    root: "/repo",
+    files: [],
+    findings: [],
+    scores: {
+      system_health: 0,
+      token_adoption: 0,
+      component_adoption: 0,
+      ux_consistency: 0,
+    },
+    ownership: [],
+    duplicate_components: [],
+    usage_by_component: [],
+    playgrounds: [
+      {
+        id: "Button",
+        export_name: "Button",
+        rel_path: "src/components/ui/button.tsx",
+        declared_props: [],
+      },
+    ],
+  };
+
+  it("flags module_not_found when glob key is missing", () => {
+    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");
+  });
+
+  it("joins when module and export exist", () => {
+    const key = defaultConsumerGlobKeyFromRelPath("src/components/ui/button.tsx");
+    const modules = {
+      [key]: {
+        Button: function Button() {
+          return null;
+        },
+      },
+    };
+    const { entries, skipped } = buildPlaygroundEntriesFromReportWithSkips(
+      report,
+      modules,
+      { globKeyFromRelPath: defaultConsumerGlobKeyFromRelPath, logJoinSkips: false },
+    );
+    expect(skipped).toHaveLength(0);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.id).toBe("Button");
+  });
+});

package/src/playground/playgroundJoin.ts

@@ -0,0 +1,145 @@
+import type { PlaygroundSpec, WorkspaceReport } from "../types/report";
+import type { BuildPlaygroundModules, BuildPlaygroundOptions } from "./buildPlaygroundEntriesFromReport";
+
+export type PlaygroundJoinSkipReason = "module_not_found" | "export_not_found";
+
+export type PlaygroundJoinSkip = {
+  export_name: string;
+  rel_path: string;
+  globKey: string;
+  reason: PlaygroundJoinSkipReason;
+};
+
+const DEFAULT_CONSUMER_STRIP_PREFIXES = ["src/", "resources/js/"] as const;
+
+/**
+ * Build `globKeyFromRelPath` for a registry file one level below a source root
+ * (e.g. `src/playground/` or `resources/js/playground/`).
+ */
+export function createConsumerGlobKeyFromRelPath(
+  options: {
+    /** Path prefixes removed from report `rel_path` before prepending `relativePrefix`. */
+    stripPrefixes?: readonly string[];
+    /** Prepended to the stripped path (default `../`). */
+    relativePrefix?: string;
+  } = {},
+): (relPath: string) => string {
+  const stripPrefixes = options.stripPrefixes ?? DEFAULT_CONSUMER_STRIP_PREFIXES;
+  const relativePrefix = options.relativePrefix ?? "../";
+  return (relPath: string) => {
+    let trimmed = relPath.replace(/^\/+/, "");
+    for (const prefix of stripPrefixes) {
+      if (trimmed.startsWith(prefix)) {
+        trimmed = trimmed.slice(prefix.length);
+        break;
+      }
+    }
+    return `${relativePrefix}${trimmed}`;
+  };
+}
+
+/**
+ * Maps report `rel_path` to a Vite `import.meta.glob` key when the registry lives in
+ * `src/playground/` or `resources/js/playground/` next to your components.
+ *
+ * Examples:
+ * - `src/components/ui/button.tsx` → `../components/ui/button.tsx`
+ * - `resources/js/Components/Icons/Activity.tsx` → `../Components/Icons/Activity.tsx`
+ */
+export function defaultConsumerGlobKeyFromRelPath(relPath: string): string {
+  return createConsumerGlobKeyFromRelPath()(relPath);
+}
+
+export function defaultEmbedGlobKeyFromRelPath(relPath: string): string {
+  const trimmed = relPath.replace(/^\/+/, "");
+  return `@dslint-scan/${trimmed}`;
+}
+
+function getExport(
+  mod: Record<string, unknown>,
+  exportName: string,
+): unknown {
+  const x = mod[exportName];
+  return typeof x === "function" ? x : undefined;
+}
+
+/**
+ * For each playground spec, explain why it would not join to `modules`.
+ */
+export function diagnosePlaygroundJoinSkips(
+  report: WorkspaceReport | null | undefined,
+  modules: BuildPlaygroundModules,
+  options: Pick<BuildPlaygroundOptions, "globKeyFromRelPath"> = {},
+): PlaygroundJoinSkip[] {
+  const specs = report?.playgrounds;
+  if (!specs?.length) return [];
+
+  const globKeyFromRelPath =
+    options.globKeyFromRelPath ?? defaultEmbedGlobKeyFromRelPath;
+
+  const skipped: PlaygroundJoinSkip[] = [];
+  for (const spec of specs) {
+    const globKey = globKeyFromRelPath(spec.rel_path);
+    const mod = modules[globKey];
+    if (!mod) {
+      skipped.push({
+        export_name: spec.export_name,
+        rel_path: spec.rel_path,
+        globKey,
+        reason: "module_not_found",
+      });
+      continue;
+    }
+    if (!getExport(mod, spec.export_name)) {
+      skipped.push({
+        export_name: spec.export_name,
+        rel_path: spec.rel_path,
+        globKey,
+        reason: "export_not_found",
+      });
+    }
+  }
+  return skipped;
+}
+
+/**
+ * Dev-only: log skipped playground joins (module glob / export name mismatches).
+ */
+export function logPlaygroundJoinSkips(
+  skipped: PlaygroundJoinSkip[],
+  options?: { label?: string },
+): void {
+  if (!skipped.length) return;
+  if (typeof import.meta !== "undefined" && !import.meta.env?.DEV) return;
+
+  const label = options?.label ?? "[dslinter] playground 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"
+        ? `add import.meta.glob key "${s.globKey}" (from rel_path "${s.rel_path}")`
+        : `export function ${s.export_name} from "${s.rel_path}"`;
+    console.warn(`  - ${s.export_name}: ${hint}`);
+  }
+  if (skipped.length > 12) {
+    console.warn(`  … and ${skipped.length - 12} more`);
+  }
+}
+
+export function findPlaygroundSpec(
+  report: WorkspaceReport | null | undefined,
+  componentId: string,
+): PlaygroundSpec | undefined {
+  return report?.playgrounds?.find(
+    (p) => p.export_name === componentId || p.id === componentId,
+  );
+}
+
+export function findPlaygroundJoinSkip(
+  skipped: PlaygroundJoinSkip[] | undefined,
+  componentId: string,
+): PlaygroundJoinSkip | undefined {
+  return skipped?.find((s) => s.export_name === componentId);
+}

package/src/shell/DashboardLayout.tsx

@@ -20,6 +20,10 @@ import { TokensPane } from "../components/TokensPane";
 import { DashboardCommandPalette } from "../components/DashboardCommandPalette";
 import { componentCatalogNamesFromReport } from "../dashboard/aggregate";
 import { resolvePlaygroundEntry } from "../playground/buildPlaygroundEntriesFromReport";
+import {
+  findPlaygroundJoinSkip,
+  type PlaygroundJoinSkip,
+} from "../playground/playgroundJoin";
 import { useHashRoute } from "./useHashRoute";
 
 const STORAGE_KEY = "dslinter-dashboard-theme";
@@ -121,6 +125,8 @@ export function useDashboardTheme(): DashboardThemeContextValue {
 
 export type DashboardLayoutProps = {
   playgroundEntries: PlaygroundEntry[];
+  /** Join failures from `buildPlaygroundEntriesFromReportWithSkips` — powers inspect-pane hints. */
+  playgroundJoinSkips?: PlaygroundJoinSkip[];
   tokenCatalog?: TokenCatalog;
   /** Custom intro shown above the governance inventory on `#!/governance`; defaults to package copy. */
   overview?: ReactNode;
@@ -136,6 +142,7 @@ export type DashboardLayoutProps = {
 
 function DashboardLayoutInner({
   playgroundEntries,
+  playgroundJoinSkips,
   tokenCatalog,
   overview,
   reportUrl,
@@ -202,6 +209,10 @@ function DashboardLayoutInner({
           workspaceReport={dslinterReport.report}
           reportReady={reportReady}
           hasPlaygroundSpec={hasPlaygroundSpec}
+          playgroundJoinSkip={findPlaygroundJoinSkip(
+            playgroundJoinSkips,
+            componentId,
+          )}
           onBackToGovernance={() => navigate({ view: "governance" })}
         />
       );

package/templates/playground/buildRegistry.laravel.ts

@@ -0,0 +1,26 @@
+import type { PlaygroundEntry, WorkspaceReport } from "dslinter";
+import { createPlaygroundRegistry } from "dslinter";
+
+/**
+ * Registry lives in `resources/js/playground/`.
+ * Glob is relative to this file — covers Inertia/React components under `resources/js/`.
+ */
+const modules = import.meta.glob("../**/*.{tsx,jsx}", {
+  eager: true,
+}) as Record<string, Record<string, unknown>>;
+
+const buildWithSkips = createPlaygroundRegistry(modules, {
+  stripPrefixes: ["resources/js/", "src/"],
+});
+
+export function buildPlaygroundEntries(
+  report: WorkspaceReport | null | undefined,
+): PlaygroundEntry[] {
+  return buildWithSkips(report).entries;
+}
+
+export function getPlaygroundJoinSkips(
+  report: WorkspaceReport | null | undefined,
+) {
+  return buildWithSkips(report).skipped;
+}

package/templates/playground/buildRegistry.ts

@@ -0,0 +1,26 @@
+import type { PlaygroundEntry, WorkspaceReport } from "dslinter";
+import { createPlaygroundRegistry } from "dslinter";
+
+/**
+ * Eager Vite glob — must cover every path in `dslint-report.json` → `playgrounds[].rel_path`.
+ * Nested paths (e.g. `src/components/ui/button.tsx`) require `**`, not a single `*`.
+ */
+const modules = import.meta.glob("../components/**/*.{tsx,jsx}", {
+  eager: true,
+}) as Record<string, Record<string, unknown>>;
+
+const buildWithSkips = createPlaygroundRegistry(modules);
+
+/** Live previews for the dashboard (`DashboardLayout` → `playgroundEntries`). */
+export function buildPlaygroundEntries(
+  report: WorkspaceReport | null | undefined,
+): PlaygroundEntry[] {
+  return buildWithSkips(report).entries;
+}
+
+/** Skipped joins (module glob / export mismatch) — useful for debugging previews. */
+export function getPlaygroundJoinSkips(
+  report: WorkspaceReport | null | undefined,
+) {
+  return buildWithSkips(report).skipped;
+}

package/templates/vite.dslint-scan-alias.snippet.ts

@@ -0,0 +1,21 @@
+/**
+ * Add to `vite.config.ts` when using the `@dslint-scan` embed-style glob in your App:
+ *
+ *   import path from "node:path";
+ *   const scanRoot = path.resolve(process.env.DSLINT_SCAN_ROOT ?? ".");
+ *
+ *   resolve: {
+ *     alias: {
+ *       "@dslint-scan": scanRoot,
+ *     },
+ *   },
+ *   server: {
+ *     fs: { allow: [scanRoot] },
+ *   },
+ *
+ * App:
+ *   const modules = import.meta.glob("@dslint-scan/**/*.{tsx,jsx}", { eager: true });
+ *   buildPlaygroundEntriesFromReport(report, modules);
+ *
+ * Prefer `npx dslinter init --laravel` (relative glob) when you have your own Vite app.
+ */

package/templates/vite.dslinter.snippet.ts

@@ -0,0 +1,28 @@
+/**
+ * Add to your existing `vite.config.ts` when using `npx dslinter` dev mode.
+ * Adjust paths if your app layout differs from `src/` + `public/dslint-report.json`.
+ */
+import path from "node:path";
+
+const DSLINT_SERVE_PORT = Number(process.env.DSLINT_SERVE_PORT ?? "7878");
+
+// Inside defineConfig(({ mode }) => ({ ... })):
+export const dslinterViteSnippet = {
+  resolve: {
+    dedupe: ["react", "react-dom"],
+  },
+  server: {
+    proxy:
+      // mode === "serve" when started via `npx dslinter` (not plain `vite`)
+      {
+        "/dslint-report.json": {
+          target: `http://127.0.0.1:${DSLINT_SERVE_PORT}`,
+          changeOrigin: true,
+        },
+        "/events": {
+          target: `http://127.0.0.1:${DSLINT_SERVE_PORT}`,
+          changeOrigin: true,
+        },
+      },
+  },
+};