dslinter 0.1.13 → 0.2.0

package/bin/lib/run-scanner.mjs

@@ -3,14 +3,38 @@ import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readEnv, envIs } from "./env.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "../..");
 const binScript = join(__dirname, "../dslinter.mjs");
+const enrichScript = join(__dirname, "enrich-report-cli.mjs");
 const require = createRequire(import.meta.url);
 
 const SCANNER_VERSION_MARKER = "design system linting";
 
+/** Env vars for the Rust watch post-write TS enrich hook. */
+export function scannerEnrichEnv(projectRoot) {
+  if (process.env.DSLINTER_SKIP_TS_ENRICH === "1") {
+    return {};
+  }
+  /** @type {Record<string, string>} */
+  const env = {
+    DSLINTER_ENRICH_SCRIPT: enrichScript,
+    DSLINTER_NODE: process.execPath,
+  };
+  if (projectRoot) {
+    env.DSLINTER_PROJECT_ROOT = projectRoot;
+  }
+  return env;
+}
+
+function applyEnrichEnv(projectRoot) {
+  for (const [key, value] of Object.entries(scannerEnrichEnv(projectRoot))) {
+    process.env[key] = value;
+  }
+}
+
 function isOurScanner(binary) {
   const help = spawnSync(binary, ["--help"], { encoding: "utf8" });
   const out = `${help.stdout ?? ""}${help.stderr ?? ""}`;
@@ -21,17 +45,24 @@ function isOurScanner(binary) {
  * @returns {Promise<import("node:child_process").ChildProcess>}
  */
 export async function spawnScanner(scannerArgs, options = {}) {
-  const fromEnv = process.env.DSLINT_BIN?.trim();
+  const projectRoot = options.projectRoot ?? process.env.DSLINTER_PROJECT_ROOT;
+  const enrichEnv = scannerEnrichEnv(projectRoot);
+  const fromEnv = readEnv("BIN");
   if (fromEnv) {
     if (!existsSync(fromEnv)) {
-      throw new Error(`dslinter: DSLINT_BIN not found: ${fromEnv}`);
+      throw new Error(`dslinter: DSLINTER_BIN not found: ${fromEnv}`);
     }
     if (!isOurScanner(fromEnv)) {
-      throw new Error("dslinter: DSLINT_BIN does not look like the DSLint scanner");
+      throw new Error("dslinter: DSLINTER_BIN does not look like the DSLinter scanner");
     }
     return spawn(fromEnv, scannerArgs, {
       stdio: "inherit",
       ...options,
+      env: {
+        ...process.env,
+        ...enrichEnv,
+        ...options.env,
+      },
     });
   }
 
@@ -41,6 +72,7 @@ export async function spawnScanner(scannerArgs, options = {}) {
     env: {
       ...process.env,
       DSLINTER_INTERNAL: "1",
+      ...enrichEnv,
       ...options.env,
     },
   });
@@ -53,7 +85,8 @@ export async function spawnScanner(scannerArgs, options = {}) {
  * @returns {number}
  */
 export function runScannerSync(scannerArgs, opts = {}) {
-  const fromEnv = process.env.DSLINT_BIN?.trim();
+  applyEnrichEnv(opts.projectRoot);
+  const fromEnv = readEnv("BIN");
   if (fromEnv) {
     const child = spawnSync(fromEnv, scannerArgs, {
       stdio: opts.captureStdout ? ["ignore", "pipe", "inherit"] : "inherit",
@@ -105,13 +138,14 @@ export function runScannerSync(scannerArgs, opts = {}) {
  * @param {string[]} args
  */
 export function runScannerInternal(args) {
-  const fromEnv = process.env.DSLINT_BIN?.trim();
+  applyEnrichEnv(process.env.DSLINTER_PROJECT_ROOT);
+  const fromEnv = readEnv("BIN");
   if (fromEnv) {
     const child = spawnSync(fromEnv, args, { stdio: "inherit" });
     process.exit(child.status === null ? 1 : child.status);
   }
 
-  if (process.env.DSLINT_ALLOW_PATH === "1") {
+  if (envIs("ALLOW_PATH")) {
     const onPath = spawnSync("dslinter", ["--help"], { encoding: "utf8" });
     const out = `${onPath.stdout ?? ""}${onPath.stderr ?? ""}`;
     if (onPath.status === 0 && out.includes(SCANNER_VERSION_MARKER)) {

package/bin/lib/scaffold-config.mjs

@@ -1,14 +1,25 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import {
+  CONFIG_FILE_NAMES,
+  DEFAULT_CONFIG_FILE_NAME,
+} from "./paths.mjs";
 
-const CONFIG_NAMES = [".dslint.json", "dslint.json"];
+/**
+ * @param {string} targetDir
+ * @returns {"laravel" | "default"}
+ */
+export function detectInitLayout(targetDir) {
+  if (existsSync(join(targetDir, "resources", "js"))) return "laravel";
+  return "default";
+}
 
 /**
  * @param {string} targetDir
  * @returns {string | null}
  */
 export function findDslintConfigPath(targetDir) {
-  for (const name of CONFIG_NAMES) {
+  for (const name of CONFIG_FILE_NAMES) {
     const candidate = join(targetDir, name);
     if (existsSync(candidate)) return candidate;
   }
@@ -24,27 +35,72 @@ function existingPaths(targetDir, candidates) {
   return candidates.filter((rel) => existsSync(join(targetDir, rel)));
 }
 
+/**
+ * Prefer lowercase `resources/js/components` for playground_groups when both casings exist.
+ * @param {string} targetDir
+ * @param {"laravel" | "default"} layout
+ * @param {string[]} includeDirs
+ * @returns {string | undefined}
+ */
+function pickPlaygroundGroupPrefix(targetDir, layout, includeDirs) {
+  if (layout === "laravel") {
+    const lower = "resources/js/components";
+    const upper = "resources/js/Components";
+    if (existsSync(join(targetDir, lower))) return lower;
+    if (existsSync(join(targetDir, upper))) return upper;
+  }
+  return includeDirs[0];
+}
+
 /**
  * @param {string} targetDir
  * @param {"laravel" | "default"} layout
  */
+/**
+ * Pick the narrowest existing directory from ordered candidates (first match wins).
+ * @param {string} targetDir
+ * @param {string[]} candidates ordered narrow → broad
+ * @returns {string[]}
+ */
+function narrowestIncludeDir(targetDir, candidates) {
+  for (const rel of candidates) {
+    if (existsSync(join(targetDir, rel))) return [rel];
+  }
+  return [];
+}
+
+/**
+ * @param {string} targetDir
+ * @param {"laravel" | "default"} layout
+ * @returns {string | undefined}
+ */
+export function detectDefaultIncludeDir(targetDir, layout) {
+  const candidates =
+    layout === "laravel"
+      ? ["resources/js/components", "resources/js/Components", "resources/js"]
+      : ["src/components", "src/ui", "src"];
+  return narrowestIncludeDir(targetDir, candidates)[0];
+}
+
 function buildStarterConfig(targetDir, layout) {
   const includeCandidates =
     layout === "laravel"
-      ? ["resources/js/Components", "resources/js/components", "resources/js"]
+      ? ["resources/js/components", "resources/js/Components", "resources/js"]
       : ["src/components", "src/ui", "src"];
   const cssCandidates =
     layout === "laravel"
       ? ["resources/css/app.css", "src/index.css"]
       : ["src/index.css", "src/styles.css", "src/app.css", "app/globals.css"];
 
-  const includeDirs = existingPaths(targetDir, includeCandidates);
+  const includeDirs = narrowestIncludeDir(targetDir, includeCandidates);
   const cssEntrypoints = existingPaths(targetDir, cssCandidates);
-  const groupPrefix = includeDirs[0];
+  const groupPrefix = pickPlaygroundGroupPrefix(targetDir, layout, includeDirs);
 
   return {
     include_dirs: includeDirs,
     ignore_globs: [],
+    hidden_components: [],
+    hidden_paths: [],
     css_entrypoints: cssEntrypoints,
     ...(groupPrefix
       ? {
@@ -57,19 +113,51 @@ function buildStarterConfig(targetDir, layout) {
 }
 
 /**
- * @param {{ targetDir: string; layout: "laravel" | "default" }} opts
+ * @param {string} targetDir
+ * @returns {{ exists: boolean; path: string | null }}
+ */
+export function assessDslintConfig(targetDir) {
+  const existing = findDslintConfigPath(resolve(targetDir));
+  return { exists: Boolean(existing), path: existing };
+}
+
+/**
+ * @param {{
+ *   targetDir: string;
+ *   layout: "laravel" | "default";
+ *   includeDir?: string;
+ * }} opts
  * @returns {{ created: boolean; path: string; existed: boolean }}
  */
-export function ensureDslintConfig(opts) {
+export function writeDslintConfig(opts) {
   const targetDir = resolve(opts.targetDir);
   const existing = findDslintConfigPath(targetDir);
   if (existing) {
     return { created: false, path: existing, existed: true };
   }
 
-  const configPath = join(targetDir, ".dslint.json");
+  const configPath = join(targetDir, DEFAULT_CONFIG_FILE_NAME);
   mkdirSync(targetDir, { recursive: true });
   const payload = buildStarterConfig(targetDir, opts.layout);
+  if (opts.includeDir) {
+    payload.include_dirs = [opts.includeDir];
+    const groupPrefix = pickPlaygroundGroupPrefix(
+      targetDir,
+      opts.layout,
+      payload.include_dirs,
+    );
+    if (groupPrefix) {
+      payload.playground_groups = { components: [groupPrefix] };
+    }
+  }
   writeFileSync(configPath, `${JSON.stringify(payload, null, 2)}\n`);
   return { created: true, path: configPath, existed: false };
 }
+
+/**
+ * @param {{ targetDir: string; layout: "laravel" | "default" }} opts
+ * @returns {{ created: boolean; path: string; existed: boolean }}
+ */
+export function ensureDslintConfig(opts) {
+  return writeDslintConfig(opts);
+}

package/bin/lib/scaffold-config.test.mjs

@@ -15,14 +15,24 @@ describe("ensureDslintConfig", () => {
 
     const raw = readFileSync(result.path, "utf8");
     const parsed = JSON.parse(raw);
-    expect(parsed.include_dirs).toContain("src/components");
+    expect(parsed.include_dirs).toEqual(["src/components"]);
     expect(parsed.css_entrypoints).toContain("src/index.css");
     expect(parsed.ignore_globs).toEqual([]);
   });
 
+  it("prefers narrowest laravel components dir", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scaffold-laravel-"));
+    mkdirSync(join(root, "resources", "js", "components"), { recursive: true });
+    mkdirSync(join(root, "resources", "js", "layouts"), { recursive: true });
+
+    const result = ensureDslintConfig({ targetDir: root, layout: "laravel" });
+    const parsed = JSON.parse(readFileSync(result.path, "utf8"));
+    expect(parsed.include_dirs).toEqual(["resources/js/components"]);
+  });
+
   it("does not overwrite an existing config", () => {
     const root = mkdtempSync(join(tmpdir(), "dslinter-scaffold-existing-"));
-    const existing = join(root, ".dslint.json");
+    const existing = join(root, ".dslinter.json");
     writeFileSync(existing, "{\n  \"ignore_globs\": [\"custom/**\"]\n}\n");
 
     const result = ensureDslintConfig({ targetDir: root, layout: "default" });

package/bin/lib/scan-host.mjs

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { detectInitLayout } from "./scaffold-config.mjs";
+import { envIs } from "./env.mjs";
+
+const HOST_APP_CANDIDATES = [
+  "src/App.tsx",
+  "src/App.jsx",
+  "src/app.tsx",
+  "resources/js/app.tsx",
+];
+
+/**
+ * True when the scan root already embeds DashboardLayout (e.g. demo app).
+ * @param {string} scanRoot
+ */
+export function scanProjectHostsDashboard(scanRoot) {
+  const root = resolve(scanRoot);
+  for (const rel of HOST_APP_CANDIDATES) {
+    const p = join(root, rel);
+    if (!existsSync(p)) continue;
+    try {
+      const text = readFileSync(p, "utf8");
+      if (/DashboardLayout/.test(text) && /dslinter/.test(text)) {
+        return true;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return false;
+}
+
+/**
+ * Prefer consumer Vite dev (host app) vs embed dashboard SPA.
+ * @param {string} scanRoot
+ */
+export function shouldUseConsumerViteDev(scanRoot) {
+  if (envIs("USE_CONSUMER_VITE")) return true;
+  if (envIs("NO_CONSUMER_VITE")) return false;
+  if (scanProjectHostsDashboard(scanRoot)) return true;
+  if (detectInitLayout(scanRoot) === "laravel") return false;
+  return false;
+}

package/bin/lib/scan-host.test.mjs

@@ -0,0 +1,41 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  scanProjectHostsDashboard,
+  shouldUseConsumerViteDev,
+} from "./scan-host.mjs";
+
+describe("scanProjectHostsDashboard", () => {
+  it("detects DashboardLayout in src/App.tsx", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-host-"));
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(
+      join(root, "src", "App.tsx"),
+      `import { DashboardLayout } from "dslinter";\nexport default function App() { return <DashboardLayout />; }\n`,
+    );
+    expect(scanProjectHostsDashboard(root)).toBe(true);
+  });
+
+  it("returns false for laravel app entry", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-laravel-app-"));
+    mkdirSync(join(root, "resources", "js"), { recursive: true });
+    writeFileSync(
+      join(root, "resources", "js", "app.tsx"),
+      `import { createInertiaApp } from "@inertiajs/react";\n`,
+    );
+    expect(scanProjectHostsDashboard(root)).toBe(false);
+  });
+});
+
+describe("shouldUseConsumerViteDev", () => {
+  it("prefers embed for laravel layout", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-laravel-vite-"));
+    mkdirSync(join(root, "resources", "js"), { recursive: true });
+    const prev = process.env.DSLINTER_USE_CONSUMER_VITE;
+    delete process.env.DSLINTER_USE_CONSUMER_VITE;
+    expect(shouldUseConsumerViteDev(root)).toBe(false);
+    process.env.DSLINTER_USE_CONSUMER_VITE = prev;
+  });
+});

package/bin/lib/setup-readiness.mjs

@@ -0,0 +1,153 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  detectDefaultIncludeDir,
+  detectInitLayout,
+  findDslintConfigPath,
+  writeDslintConfig,
+} from "./scaffold-config.mjs";
+import { resolveProjectRoot } from "./resolve-project.mjs";
+import { readEnv } from "./env.mjs";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { confirmYesNo, isInteractiveTTY } from "./prompt.mjs";
+import { defaultReportPath } from "./project-root.mjs";
+
+/**
+ * @typedef {"missing_config" | "missing_public"} SetupIssueKind
+ */
+
+/**
+ * @typedef {{ kind: SetupIssueKind; label: string }} SetupIssue
+ */
+
+/**
+ * @param {string} targetDir project / vite root
+ * @param {string} reportPath absolute report file path
+ * @returns {SetupIssue[]}
+ */
+export function assessSetupReadiness(targetDir, reportPath) {
+  const root = resolve(targetDir);
+  const issues = [];
+
+  if (!findDslintConfigPath(root)) {
+    issues.push({ kind: "missing_config", label: ".dslinter.json" });
+  }
+
+  const publicDir = dirname(resolve(reportPath));
+  if (!existsSync(publicDir)) {
+    issues.push({ kind: "missing_public", label: "public/" });
+  }
+
+  return issues;
+}
+
+/**
+ * @param {string} reportPath
+ */
+export function ensurePublicDir(reportPath) {
+  const publicDir = dirname(resolve(reportPath));
+  if (!existsSync(publicDir)) {
+    mkdirSync(publicDir, { recursive: true });
+  }
+}
+
+/**
+ * @param {{
+ *   targetDir: string;
+ *   reportPath: string;
+ *   yes?: boolean;
+ *   interactive?: boolean;
+ * }} opts
+ * @returns {Promise<{ applied: string[]; skipped: boolean }>}
+ */
+export async function ensureMinimalSetup(opts) {
+  const targetDir = resolve(opts.targetDir);
+  const reportPath = resolve(opts.reportPath);
+  const noScaffold = readEnv("NO_SCAFFOLD") === "1";
+
+  const issues = assessSetupReadiness(targetDir, reportPath);
+  if (!issues.length || noScaffold) {
+    if (issues.length && noScaffold) {
+      process.stderr.write(
+        `dslinter: setup incomplete (${issues.map((i) => i.label).join(", ")}). Set DSLINTER_NO_SCAFFOLD=0 or run with --yes to create.\n`,
+      );
+    }
+    return { applied: [], skipped: noScaffold && issues.length > 0 };
+  }
+
+  const ci = process.env.CI === "true" || process.env.CI === "1";
+  const autoYes = opts.yes === true || ci;
+  const interactive = opts.interactive ?? isInteractiveTTY();
+
+  let shouldApply = autoYes;
+  if (!shouldApply && interactive) {
+    process.stderr.write("dslinter: setup incomplete for live previews.\n");
+    for (const issue of issues) {
+      process.stderr.write(`  Missing: ${issue.label}\n`);
+    }
+    shouldApply = await confirmYesNo("Create these files now?");
+  } else if (!shouldApply && !interactive) {
+    process.stderr.write(
+      `dslinter: setup incomplete (${issues.map((i) => i.label).join(", ")}). Run with --yes or use an interactive terminal.\n`,
+    );
+    return { applied: [], skipped: true };
+  }
+
+  if (!shouldApply) {
+    process.stderr.write(
+      "dslinter: continuing without scaffold — previews and governance may be limited.\n",
+    );
+    return { applied: [], skipped: true };
+  }
+
+  /** @type {string[]} */
+  const applied = [];
+
+  if (issues.some((i) => i.kind === "missing_config")) {
+    const layout = detectInitLayout(targetDir);
+    let includeDir = detectDefaultIncludeDir(targetDir, layout);
+    if (interactive && includeDir) {
+      const rl = createInterface({ input, output });
+      try {
+        const answer = (
+          await rl.question(`Components directory [${includeDir}]: `)
+        ).trim();
+        if (answer) includeDir = answer;
+      } finally {
+        rl.close();
+      }
+    }
+    const result = writeDslintConfig({
+      targetDir,
+      layout,
+      ...(includeDir ? { includeDir } : {}),
+    });
+    applied.push(result.path);
+    process.stderr.write(`dslinter: created ${result.path}\n`);
+  }
+
+  if (issues.some((i) => i.kind === "missing_public")) {
+    ensurePublicDir(reportPath);
+    applied.push(dirname(reportPath));
+    process.stderr.write(`dslinter: created ${dirname(reportPath)}/\n`);
+  }
+
+  return { applied, skipped: false };
+}
+
+/**
+ * Convenience: assess using default report path for a scan root.
+ * @param {string} scanPath
+ * @param {{ yes?: boolean }} [opts]
+ */
+export async function ensureMinimalSetupForScan(scanPath, opts = {}) {
+  const scanAbs = resolve(scanPath);
+  const reportPath = defaultReportPath(scanAbs, null);
+  const targetDir = resolveProjectRoot(scanAbs);
+  return ensureMinimalSetup({
+    targetDir,
+    reportPath,
+    yes: opts.yes,
+  });
+}

package/bin/lib/setup-readiness.test.mjs

@@ -0,0 +1,32 @@
+import { existsSync, mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { assessSetupReadiness, ensurePublicDir } from "./setup-readiness.mjs";
+
+describe("assessSetupReadiness", () => {
+  it("reports missing config and public", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ready-"));
+    const reportPath = join(root, "public", "dslinter-report.json");
+    const issues = assessSetupReadiness(root, reportPath);
+    expect(issues.map((i) => i.kind)).toContain("missing_config");
+    expect(issues.map((i) => i.kind)).toContain("missing_public");
+  });
+
+  it("passes when config and public exist", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ready-ok-"));
+    mkdirSync(join(root, "public"), { recursive: true });
+    const reportPath = join(root, "public", "dslinter-report.json");
+    writeFileSync(join(root, ".dslinter.json"), "{}\n");
+    expect(assessSetupReadiness(root, reportPath)).toHaveLength(0);
+  });
+});
+
+describe("ensurePublicDir", () => {
+  it("creates public directory", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-public-"));
+    const reportPath = join(root, "public", "dslinter-report.json");
+    ensurePublicDir(reportPath);
+    expect(existsSync(join(root, "public"))).toBe(true);
+  });
+});

package/bin/modes/build.mjs

@@ -1,25 +1,51 @@
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
-import { defaultReportPath, findViteRoot, resolveViteBin } from "../lib/project-root.mjs";
+import {
+  defaultReportPath,
+  findViteRoot,
+  resolveViteBin,
+} from "../lib/project-root.mjs";
+import { enrichPlaygroundsFromTs } from "../lib/enrich-playgrounds-from-ts.mjs";
+import { ensureMinimalSetup } from "../lib/setup-readiness.mjs";
 import { runScannerSync } from "../lib/run-scanner.mjs";
 
 /**
  * @param {{
  *   scanPath: string;
+ *   projectRoot: string;
  *   outputPath: string | null;
  *   scannerArgs: string[];
+ *   yes?: boolean;
  * }}
  */
-export function runBuildMode({ scanPath, outputPath, scannerArgs }) {
-  const reportPath = defaultReportPath(scanPath, outputPath);
+export async function runBuildMode({
+  scanPath,
+  projectRoot,
+  outputPath,
+  scannerArgs,
+  yes = false,
+}) {
+  const scanAbs = resolve(scanPath);
+  const projectAbs = resolve(projectRoot);
+  const reportPath = defaultReportPath(scanAbs, outputPath);
+  await ensureMinimalSetup({
+    targetDir: projectAbs,
+    reportPath,
+    yes,
+  });
   const args = ["--report", ...scannerArgs];
   if (!args.some((a) => a === "--output" || a.startsWith("--output="))) {
     args.push("--output", reportPath);
   }
 
-  const code = runScannerSync(args);
+  const code = runScannerSync(args, { projectRoot: projectAbs });
   if (code !== 0) process.exit(code);
 
+  await enrichPlaygroundsFromTs({
+    projectRoot: projectAbs,
+    reportPath,
+  });
+
   const viteRoot = findViteRoot(process.cwd());
   if (!viteRoot) {
     process.stderr.write(
@@ -33,13 +59,12 @@ export function runBuildMode({ scanPath, outputPath, scannerArgs }) {
     process.stderr.write(`dslinter: vite not installed in ${viteRoot}. Run npm install.\n`);
     process.exit(1);
   }
-  const scanAbs = resolve(scanPath);
   const child = spawnSync(process.execPath, [viteBin, "build"], {
     cwd: viteRoot,
     stdio: "inherit",
     env: {
       ...process.env,
-      DSLINT_SCAN_ROOT: scanAbs,
+      DSLINTER_SCAN_ROOT: scanAbs,
     },
   });
   process.exit(child.status === null ? 1 : child.status);