dslinter 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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)
+
 ## v0.1.0
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.35...v0.1.0)

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/lib/dev-banner.mjs

@@ -196,7 +196,10 @@ export function formatDevBanner(opts) {
     plainWidths.push(14 + 2 + `${apiBase}/events`.length);
   }
   if (opts.pollMs) plainWidths.push(14 + 2 + `polling every ${opts.pollMs} ms`.length);
-  plainWidths.push(visibleLength("  Open the Dashboard URL in your browser. Ctrl+C to stop."));
+  const footerPlain = opts.bundledUrl
+    ? "  Open the Bundled UI URL in your browser. Ctrl+C to stop."
+    : "  Open the Dashboard URL in your browser. Ctrl+C to stop.";
+  plainWidths.push(visibleLength(footerPlain));
 
   const contentWidth = Math.min(maxBox - 4, Math.max(...plainWidths, 40));
   const totalWidth = contentWidth + 4;
@@ -213,7 +216,7 @@ export function formatDevBanner(opts) {
     ...row(color.label("Report file"), reportPlain, contentWidth, color.value),
   );
   styledRows.push("");
-  if (opts.dashboardUrl) {
+  if (opts.dashboardUrl && !opts.bundledUrl) {
     styledRows.push(
       ...row(color.label("Dashboard"), opts.dashboardUrl, contentWidth, color.url),
     );
@@ -251,7 +254,7 @@ export function formatDevBanner(opts) {
     );
   }
   styledRows.push("");
-  styledRows.push(color.dim("  Open the Dashboard URL in your browser. Ctrl+C to stop."));
+  styledRows.push(color.dim(footerPlain));
 
   return boxLines(styledRows, totalWidth).join("\n");
 }

package/bin/lib/dev-banner.test.mjs

@@ -22,7 +22,7 @@ describe("shortenPath", () => {
 });
 
 describe("formatDevBanner", () => {
-  it("includes logo, scan path, report, dashboard, and API URLs", () => {
+  it("includes logo, scan path, report, bundled UI, and API URLs", () => {
     const text = formatDevBanner({
       scanPath: "/tmp/components",
       reportPath: "/tmp/components/public/dslint-report.json",
@@ -36,11 +36,27 @@ describe("formatDevBanner", () => {
     expect(text).toContain(LOGO[1]);
     expect(text).toContain("Scan path");
     expect(text).toContain("Report file");
-    expect(text).toContain("Dashboard");
-    expect(text).toContain("http://localhost:5173/");
+    expect(text).toContain("Bundled UI");
+    expect(text).not.toContain("http://localhost:5173/");
+    expect(text).not.toMatch(/\bDashboard\b/);
     expect(text).toContain("7878");
     expect(text).toContain("dslint-report.json");
     expect(text).toContain("polling every 150 ms");
+    expect(text).toContain("Open the Bundled UI URL");
+  });
+
+  it("shows dashboard URL when bundled UI is not served", () => {
+    const text = formatDevBanner({
+      scanPath: "/tmp/components",
+      reportPath: "/tmp/components/public/dslint-report.json",
+      apiPort: 7878,
+      apiAvailable: true,
+      dashboardUrl: "http://localhost:5173/",
+      pollMs: 150,
+    });
+    expect(text).toContain("Dashboard");
+    expect(text).toContain("http://localhost:5173/");
+    expect(text).toContain("Open the Dashboard URL");
   });
 
   it("marks API unavailable when port is busy", () => {

package/bin/modes/dev.mjs

@@ -152,11 +152,17 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
       {
         cwd: embedRoot,
         stdio: "inherit",
-        env: { ...process.env, DSLINT_SERVE_PORT: String(port) },
+        env: {
+          ...process.env,
+          DSLINT_SERVE_PORT: String(port),
+          DSLINT_SCAN_ROOT: scanAbs,
+        },
       },
     );
     children.push(vite);
-    printDevBanner({ ...bannerBase, dashboardUrl });
+    printDevBanner(
+      attachBundledStatic ? bannerBase : { ...bannerBase, dashboardUrl },
+    );
 
     vite.on("exit", (code, signal) => {
       cleanup("SIGTERM");
@@ -183,11 +189,17 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
       {
         cwd: consumerViteRoot,
         stdio: "inherit",
-        env: { ...process.env, DSLINT_SERVE_PORT: String(port) },
+        env: {
+          ...process.env,
+          DSLINT_SERVE_PORT: String(port),
+          DSLINT_SCAN_ROOT: scanAbs,
+        },
       },
     );
     children.push(vite);
-    printDevBanner({ ...bannerBase, dashboardUrl });
+    printDevBanner(
+      attachBundledStatic ? bannerBase : { ...bannerBase, dashboardUrl },
+    );
 
     vite.on("exit", (code, signal) => {
       cleanup("SIGTERM");
@@ -198,9 +210,9 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
   }
 
   if (bundledDist) {
-    const dashboardUrl = bundledUrl ?? `http://127.0.0.1:${port}/`;
-    printDevBanner({ ...bannerBase, dashboardUrl });
-    maybeOpenBrowser(dashboardUrl);
+    const openUrl = bundledUrl ?? `http://127.0.0.1:${port}/`;
+    printDevBanner(bannerBase);
+    maybeOpenBrowser(openUrl);
     scanner.on("exit", (code) => process.exit(code ?? 0));
     return;
   }

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"),
+  );
+}