dslinter 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.1.3
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.2...v0.1.3)
+
+## v0.1.2
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.1...v0.1.2)
+
 ## v0.1.1
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.1.0...v0.1.1)

package/README.md

@@ -48,6 +48,7 @@ The crates.io crate **`dslint`** is a **different project**. Use **`cargo instal
 Typical usage:
 
 ```bash
+npx dslinter init                         # scaffold src/playground/buildRegistry.ts
 npx dslinter                              # dev (watch + dashboard)
 npx dslinter --report /path/to/repo --json
 npx dslinter --report --output public/dslint-report.json
@@ -71,11 +72,53 @@ Set `DSLINT_SERVE_PORT` to override the default scanner port (`7878`). Your Vite
    @import "dslinter/theme.css";
    ```
 
+## Live component previews (consumer Vite apps)
+
+If the dashboard shows **“Scan snapshot — no live preview”** for a component that appears in the catalog, the scanner found the file but Vite did not load it. Wire previews in three steps:
+
+1. **Scaffold** (optional): `npx dslinter init` → `src/playground/buildRegistry.ts`; for Inertia/Laravel (`resources/js/…`) use `npx dslinter init --laravel`
+2. **Glob** must cover nested paths, e.g. `import.meta.glob("../components/**/*.{tsx,jsx}", { eager: true })`
+3. **App**: pass `playgroundEntries` and `playgroundJoinSkips` from the registry into `DashboardLayout`
+
+```tsx
+import { useMemo } from "react";
+import { DashboardLayout, useWorkspaceReport } from "dslinter";
+import {
+  buildPlaygroundEntries,
+  getPlaygroundJoinSkips,
+} from "./playground/buildRegistry";
+
+const dslinterReport = useWorkspaceReport({
+  reportUrl: "/dslint-report.json",
+  watchUrl: "/events",
+});
+
+const playgroundEntries = useMemo(
+  () => buildPlaygroundEntries(dslinterReport.report),
+  [dslinterReport.report],
+);
+const playgroundJoinSkips = useMemo(
+  () => getPlaygroundJoinSkips(dslinterReport.report),
+  [dslinterReport.report],
+);
+
+<DashboardLayout
+  playgroundEntries={playgroundEntries}
+  playgroundJoinSkips={playgroundJoinSkips}
+  dslinterReport={dslinterReport}
+/>;
+```
+
+In dev, skipped joins are also logged to the console. The inspect pane shows the expected Vite glob key when a preview fails.
+
+Run the scanner from the **project root** (`npx dslinter .`) so `playgrounds[].rel_path` matches your repo layout.
+
 ## Wiring the layout
 
 `DashboardLayout` needs:
 
 - **`playgroundEntries`** — from the report’s `playgrounds` list joined to your React modules (see repo `demo/src/playground/buildRegistry.ts`).
+- **`playgroundJoinSkips`** (optional) — from `buildPlaygroundEntriesFromReportWithSkips` for richer inspect-pane hints.
 - **`tokenCatalog`** — token wall data (see `demo/src/tokenCatalog.ts`).
 - **`dslinterReport`** — from `useWorkspaceReport({ reportUrl: "/dslint-report.json", ... })`.
 

package/bin/dslinter.mjs

@@ -6,10 +6,16 @@ import { parseDslinterArgs } from "./lib/parse-args.mjs";
 import { runScannerInternal } from "./lib/run-scanner.mjs";
 import { runBuildMode } from "./modes/build.mjs";
 import { runDevMode } from "./modes/dev.mjs";
+import { runInitMode } from "./modes/init.mjs";
 import { runReportMode } from "./modes/report.mjs";
 
 const rawArgs = process.argv.slice(2);
 
+if (rawArgs[0] === "init") {
+  runInitMode({ argv: rawArgs.slice(1) });
+  process.exit(0);
+}
+
 if (process.env.DSLINTER_INTERNAL === "1") {
   runScannerInternal(rawArgs);
 }

package/bin/modes/init.mjs

@@ -0,0 +1,101 @@
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+
+/**
+ * @param {string} targetDir
+ * @returns {"laravel" | "default"}
+ */
+function detectInitLayout(targetDir) {
+  if (existsSync(join(targetDir, "resources", "js"))) return "laravel";
+  return "default";
+}
+
+/**
+ * @param {{ targetDir?: string; layout?: "laravel" | "default"; argv?: string[] }} opts
+ */
+export function runInitMode(opts = {}) {
+  const argv = opts.argv ?? [];
+  const forceLaravel = argv.includes("--laravel") || argv.includes("--resources-js");
+  const targetDir = resolve(
+    opts.targetDir ?? argv.find((a) => !a.startsWith("-")) ?? process.cwd(),
+  );
+  const layout =
+    opts.layout ?? (forceLaravel ? "laravel" : detectInitLayout(targetDir));
+
+  const registryDir =
+    layout === "laravel"
+      ? join(targetDir, "resources", "js", "playground")
+      : join(targetDir, "src", "playground");
+  const registryPath = join(registryDir, "buildRegistry.ts");
+  const templateName =
+    layout === "laravel" ? "buildRegistry.laravel.ts" : "buildRegistry.ts";
+  const templatePath = join(
+    packageRoot,
+    "templates",
+    "playground",
+    templateName,
+  );
+
+  if (existsSync(registryPath)) {
+    process.stderr.write(
+      `dslinter init: ${registryPath} already exists — remove it first to re-scaffold.\n`,
+    );
+    process.exit(1);
+  }
+
+  mkdirSync(registryDir, { recursive: true });
+  copyFileSync(templatePath, registryPath);
+
+  const snippetPath = join(registryDir, "vite.dslinter.snippet.ts");
+  const snippetTemplate = join(
+    packageRoot,
+    "templates",
+    "vite.dslinter.snippet.ts",
+  );
+  if (!existsSync(snippetPath) && existsSync(snippetTemplate)) {
+    copyFileSync(snippetTemplate, snippetPath);
+  }
+
+  const appHintPath = join(registryDir, "README.txt");
+  writeFileSync(
+    appHintPath,
+    [
+      "Wire live component previews in your App:",
+      "",
+      "  import { useMemo } from 'react';",
+      "  import { DashboardLayout, useWorkspaceReport } from 'dslinter';",
+      layout === "laravel"
+        ? "  import { buildPlaygroundEntries } from '@/playground/buildRegistry';"
+        : "  import { buildPlaygroundEntries } from './playground/buildRegistry';",
+      "",
+      "  const dslinterReport = useWorkspaceReport({ reportUrl: '/dslint-report.json', watchUrl: '/events' });",
+      "  const playgroundEntries = useMemo(() => buildPlaygroundEntries(dslinterReport.report), [dslinterReport.report]);",
+      "",
+      "  <DashboardLayout playgroundEntries={playgroundEntries} dslinterReport={dslinterReport} ... />",
+      "",
+      "Run the scanner from the repo root: npx dslinter .",
+      "",
+    ].join("\n"),
+  );
+
+  process.stdout.write(
+    [
+      "dslinter init: wrote playground registry",
+      `  ${registryPath}`,
+      "",
+      `Layout: ${layout}`,
+      "",
+      "Next:",
+      `  1. Import buildPlaygroundEntries in your App (see ${registryDir}/README.txt)`,
+      "  2. Merge vite.dslinter.snippet.ts into vite.config.ts (proxy + react dedupe)",
+      layout === "laravel"
+        ? "     (Inertia: glob uses resources/js/** — not @dslint-scan unless you add the alias snippet)"
+        : "",
+      "  3. Run npx dslinter . from the project root",
+      "",
+    ].join("\n"),
+  );
+}