dslinter 0.0.31 → 0.0.33

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.0.33
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.32...v0.0.33)
+
+### 🏡 Chore
+
+- **release:** V0.0.32 ([bb07996](https://github.com/jrmybtlr/DSLinter/commit/bb07996))
+
+### ❤️ Contributors
+
+- Jeremy Butler <jeremy.butler@laravel.com>
+
+## v0.0.32
+
+[compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.31...v0.0.32)
+
 ## v0.0.31
 
 [compare changes](https://github.com/jrmybtlr/DSLinter/compare/v0.0.30...v0.0.31)

package/bin/lib/port-check.mjs

@@ -0,0 +1,57 @@
+import net from "node:net";
+import { spawnSync } from "node:child_process";
+
+/**
+ * @param {number} port
+ * @param {string} [host]
+ */
+export function isPortInUse(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", (err) => {
+      resolve(err && "code" in err && err.code === "EADDRINUSE");
+    });
+    server.once("listening", () => {
+      server.close(() => resolve(false));
+    });
+    server.listen(port, host);
+  });
+}
+
+/**
+ * @param {number} port
+ */
+export function describePortOccupant(port) {
+  if (process.platform === "win32") {
+    const r = spawnSync("netstat", ["-ano"], { encoding: "utf8" });
+    const line = (r.stdout ?? "")
+      .split("\n")
+      .find((l) => l.includes(`:${port}`) && l.includes("LISTENING"));
+    return line?.trim() ?? null;
+  }
+  const r = spawnSync("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], {
+    encoding: "utf8",
+  });
+  const lines = (r.stdout ?? "").trim().split("\n").filter(Boolean);
+  if (lines.length < 2) return null;
+  return lines.slice(1).join("\n");
+}
+
+/**
+ * @param {number} port
+ */
+export async function warnIfPortBusy(port) {
+  if (!(await isPortInUse(port))) return false;
+  const detail = describePortOccupant(port);
+  process.stderr.write(
+    [
+      "",
+      `[dslinter] Port ${port} is already in use — scanner cannot bind.`,
+      detail ? `  ${detail.replace(/\n/g, "\n  ")}` : "",
+      `  Stop the old process, then restart. Example: lsof -nP -iTCP:${port} -sTCP:LISTEN`,
+      "  If you already have `npm run dev` running, open the Vite URL it printed (e.g. http://localhost:5173/).",
+      "",
+    ].join("\n"),
+  );
+  return true;
+}

package/bin/lib/project-root.mjs

@@ -1,10 +1,77 @@
+import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
 
+/** @returns {string} `packages/dashboard` root (embed SPA + library). */
+export function getDashboardPackageRoot() {
+  return packageRoot;
+}
+
+/**
+ * @param {string} dir
+ * @param {number} [latest]
+ */
+function maxMtimeInDir(dir, latest = 0) {
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, ent.name);
+    if (ent.isDirectory()) {
+      latest = maxMtimeInDir(p, latest);
+    } else if (ent.isFile()) {
+      latest = Math.max(latest, statSync(p).mtimeMs);
+    }
+  }
+  return latest;
+}
+
+/**
+ * Rebuild `dashboard-dist/` when embed sources are newer than the bundle (or dist is missing).
+ * @param {string} root
+ */
+export function ensureDashboardBuilt(root = packageRoot) {
+  const distIndex = join(root, "dashboard-dist", "index.html");
+  const force =
+    process.env.DSLINTER_REBUILD_DASHBOARD === "1" ||
+    process.env.DSLINTER_REBUILD_DASHBOARD?.toLowerCase() === "true";
+
+  let needsBuild = force || !existsSync(distIndex);
+  if (!needsBuild) {
+    const distMtime = statSync(distIndex).mtimeMs;
+    for (const sub of ["src", "embed"]) {
+      const dir = join(root, sub);
+      if (existsSync(dir) && maxMtimeInDir(dir) > distMtime) {
+        needsBuild = true;
+        break;
+      }
+    }
+    const configPath = join(root, "vite.config.ts");
+    if (existsSync(configPath) && statSync(configPath).mtimeMs > distMtime) {
+      needsBuild = true;
+    }
+  }
+
+  if (!needsBuild) return dashboardDirIfReady(join(root, "dashboard-dist"));
+
+  process.stderr.write("[dslinter] Building dashboard bundle (dashboard-dist)…\n");
+  const result = spawnSync("npm", ["run", "build:dashboard"], {
+    cwd: root,
+    stdio: "inherit",
+    env: process.env,
+  });
+  if (result.status !== 0) {
+    throw new Error("dslinter: dashboard build failed");
+  }
+  return dashboardDirIfReady(join(root, "dashboard-dist"));
+}
+
+/** @returns {boolean} */
+export function hasEmbedDashboard() {
+  return existsSync(join(packageRoot, "index.html"));
+}
+
 const VITE_CONFIG_NAMES = ["vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"];
 
 /**
@@ -79,7 +146,11 @@ export function resolveBundledDashboardDir() {
     return dashboardDirIfReady(dir);
   }
 
-  return dashboardDirIfReady(join(packageRoot, "dashboard-dist"));
+  try {
+    return ensureDashboardBuilt(packageRoot);
+  } catch {
+    return dashboardDirIfReady(join(packageRoot, "dashboard-dist"));
+  }
 }
 
 /**

package/bin/modes/dev.mjs

@@ -1,11 +1,15 @@
 import { spawn, spawnSync } from "node:child_process";
+import { join } from "node:path";
 import {
   defaultReportPath,
   defaultServePort,
   findViteRoot,
+  getDashboardPackageRoot,
+  hasEmbedDashboard,
   resolveBundledDashboardDir,
   resolveViteBin,
 } from "../lib/project-root.mjs";
+import { warnIfPortBusy } from "../lib/port-check.mjs";
 import { spawnScanner } from "../lib/run-scanner.mjs";
 import { waitForPort } from "../lib/wait-for-port.mjs";
 
@@ -20,8 +24,16 @@ import { waitForPort } from "../lib/wait-for-port.mjs";
 export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort }) {
   const port = servePort ?? defaultServePort();
   const reportPath = defaultReportPath(scanPath, outputPath);
-  const viteRoot = findViteRoot(process.cwd());
-  const bundledDist = resolveBundledDashboardDir();
+  const consumerViteRoot = findViteRoot(process.cwd());
+  const embedRoot = getDashboardPackageRoot();
+  const embedViteBin = hasEmbedDashboard() ? resolveViteBin(embedRoot) : null;
+  /** Live embed UI from source (proxies report/SSE to the scanner port). */
+  const useEmbedViteDev =
+    embedViteBin != null &&
+    consumerViteRoot == null &&
+    process.env.DSLINTER_NO_EMBED_VITE?.trim() !== "1";
+
+  const bundledDist = useEmbedViteDev ? null : resolveBundledDashboardDir();
 
   const args = [...scannerArgs];
   const hasServe = args.some((a) => a === "--serve" || a.startsWith("--serve="));
@@ -31,10 +43,21 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
   if (!args.some((a) => a === "--output" || a.startsWith("--output="))) {
     args.push("--output", reportPath);
   }
-  if (bundledDist && !args.some((a) => a === "--dashboard-static" || a.startsWith("--dashboard-static="))) {
+
+  const hasDashboardStaticFlag = args.some(
+    (a) => a === "--dashboard-static" || a.startsWith("--dashboard-static="),
+  );
+  const attachBundledStatic =
+    bundledDist != null && !useEmbedViteDev && !hasDashboardStaticFlag;
+
+  if (attachBundledStatic) {
     args.push("--dashboard-static", bundledDist);
   }
 
+  if (hasServe || args.some((a) => a.startsWith("--serve="))) {
+    await warnIfPortBusy(port);
+  }
+
   const scanner = await spawnScanner(args);
   const children = [scanner];
 
@@ -61,61 +84,108 @@ export async function runDevMode({ scanPath, outputPath, scannerArgs, servePort
     process.exit(1);
   }
 
-  if (bundledDist) {
-    const url = `http://127.0.0.1:${port}/`;
-    const lines = [
-      "",
-      "[dslinter] Bundled dashboard at",
-      `  ${url}`,
-      `  Report: http://127.0.0.1:${port}/dslint-report.json`,
-    ];
-    if (viteRoot) {
-      lines.push(
-        "  Vite dev server also starting (use its URL for your app; proxy /dslint-report.json and /events to this port if needed).",
-      );
-    }
-    lines.push("");
-    process.stderr.write(lines.join("\n"));
-    if (!viteRoot) {
-      maybeOpenBrowser(url);
-      scanner.on("exit", (code) => process.exit(code ?? 0));
-      return;
-    }
-  }
+  const apiUrl = `http://127.0.0.1:${port}/dslint-report.json`;
 
-  if (!viteRoot) {
+  if (useEmbedViteDev) {
+    const uiPort = process.env.DSLINTER_DEV_UI_PORT?.trim() || "5175";
+    const vite = spawn(
+      process.execPath,
+      [embedViteBin, "--config", join(embedRoot, "vite.config.ts"), "--mode", "serve", "--port", uiPort],
+      {
+        cwd: embedRoot,
+        stdio: "inherit",
+        env: { ...process.env, DSLINT_SERVE_PORT: String(port) },
+      },
+    );
+    children.push(vite);
     process.stderr.write(
       [
         "",
-        "[dslinter] No vite.config.* and no bundled dashboard-dist — scanner only (watch + serve).",
-        "  Reinstall dslinter or run `pnpm --filter dslinter run build:dashboard` from the repo.",
-        "  Or add a Vite app with proxy for /dslint-report.json and /events.",
-        `  Scanner: http://127.0.0.1:${port}/dslint-report.json`,
+        "[dslinter] Dashboard UI (live source)",
+        `  http://127.0.0.1:${uiPort}/`,
+        "[dslinter] Scanner API",
+        `  ${apiUrl}`,
+        `  SSE: http://127.0.0.1:${port}/events`,
         "",
       ].join("\n"),
     );
-    scanner.on("exit", (code) => process.exit(code ?? 0));
+    vite.on("exit", (code, signal) => {
+      cleanup("SIGTERM");
+      if (signal) process.kill(process.pid, signal);
+      else process.exit(code ?? 0);
+    });
     return;
   }
 
-  const viteBin = resolveViteBin(viteRoot);
-  if (!viteBin) {
-    process.stderr.write(`dslinter: vite not installed in ${viteRoot}. Run npm install.\n`);
-    cleanup("SIGTERM");
-    process.exit(1);
+  if (consumerViteRoot) {
+    const viteBin = resolveViteBin(consumerViteRoot);
+    if (!viteBin) {
+      process.stderr.write(`dslinter: vite not installed in ${consumerViteRoot}. Run npm install.\n`);
+      cleanup("SIGTERM");
+      process.exit(1);
+    }
+
+    const bundledUrl = attachBundledStatic ? `http://127.0.0.1:${port}/` : null;
+    process.stderr.write(
+      [
+        "",
+        "[dslinter] Dashboard UI (recommended) — Vite dev server with live dslinter source:",
+        "  http://localhost:5173/  (or the port Vite prints below if 5173 is taken)",
+        bundledUrl
+          ? `[dslinter] Bundled dashboard (same build as publish) — only if port ${port} bound successfully:`
+          : `[dslinter] Scanner API only on :${port} (port may be busy — use Vite URL above):`,
+        bundledUrl ? `  ${bundledUrl}` : null,
+        `  ${apiUrl}`,
+        `  SSE: http://127.0.0.1:${port}/events`,
+        "",
+        "  Do not use `npx dslint` — that is a different npm package. Use `npm run dev` or `npx dslinter .` in demo/.",
+        "",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    );
+
+    const vite = spawn(process.execPath, [viteBin, "--mode", "serve"], {
+      cwd: consumerViteRoot,
+      stdio: "inherit",
+      env: { ...process.env, DSLINT_SERVE_PORT: String(port) },
+    });
+    children.push(vite);
+
+    vite.on("exit", (code, signal) => {
+      cleanup("SIGTERM");
+      if (signal) process.kill(process.pid, signal);
+      else process.exit(code ?? 0);
+    });
+    return;
   }
 
-  const vite = spawn(process.execPath, [viteBin, "--mode", "serve"], {
-    cwd: viteRoot,
-    stdio: "inherit",
-  });
-  children.push(vite);
+  if (bundledDist) {
+    const url = `http://127.0.0.1:${port}/`;
+    process.stderr.write(
+      [
+        "",
+        "[dslinter] Bundled dashboard",
+        `  ${url}`,
+        `  Report: ${apiUrl}`,
+        "",
+      ].join("\n"),
+    );
+    maybeOpenBrowser(url);
+    scanner.on("exit", (code) => process.exit(code ?? 0));
+    return;
+  }
 
-  vite.on("exit", (code, signal) => {
-    cleanup("SIGTERM");
-    if (signal) process.kill(process.pid, signal);
-    else process.exit(code ?? 0);
-  });
+  process.stderr.write(
+    [
+      "",
+      "[dslinter] Scanner only (no dashboard UI).",
+      `  Report: ${apiUrl}`,
+      "  Run `pnpm --filter dslinter run build:dashboard` or use a Vite project with dslinter.",
+      "",
+    ].join("\n"),
+  );
+  scanner.on("exit", (code) => process.exit(code ?? 0));
 }
 
 /**