dslinter 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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` → writes `src/playground/buildRegistry.ts`
+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({ targetDir: rawArgs[1] });
+  process.exit(0);
+}
+
 if (process.env.DSLINTER_INTERNAL === "1") {
   runScannerInternal(rawArgs);
 }

package/bin/modes/init.mjs

@@ -0,0 +1,73 @@
+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 {{ targetDir?: string }} opts
+ */
+export function runInitMode(opts = {}) {
+  const targetDir = resolve(opts.targetDir ?? process.cwd());
+  const registryDir = join(targetDir, "src", "playground");
+  const registryPath = join(registryDir, "buildRegistry.ts");
+  const templatePath = join(
+    packageRoot,
+    "templates",
+    "playground",
+    "buildRegistry.ts",
+  );
+
+  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';",
+      "  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}`,
+      "",
+      "Next:",
+      "  1. Import buildPlaygroundEntries in your App (see src/playground/README.txt)",
+      "  2. Merge vite.dslinter.snippet.ts into vite.config.ts (proxy + react dedupe)",
+      "  3. Run npx dslinter . from the project root",
+      "",
+    ].join("\n"),
+  );
+}