dslinter 0.1.5 → 0.2.0

package/bin/lib/infer-prop-types-from-ts.test.mjs

@@ -0,0 +1,174 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
+const reactTypesRoot = join(packageRoot, "node_modules/@types");
+import {
+  classifyPropType,
+  createCheckerProgram,
+  extractFiniteStringUnion,
+  findComponentParamType,
+  inferPlaygroundPropMetadata,
+} from "./infer-prop-types-from-ts.mjs";
+
+/**
+ * @param {string} root
+ * @param {Record<string, string>} files
+ */
+function writeProject(root, files) {
+  mkdirSync(root, { recursive: true });
+  writeFileSync(
+    join(root, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          strict: true,
+          jsx: "react-jsx",
+          module: "ESNext",
+          moduleResolution: "bundler",
+          noEmit: true,
+          skipLibCheck: true,
+          typeRoots: [reactTypesRoot],
+        },
+        include: ["**/*.tsx"],
+      },
+      null,
+      2,
+    ),
+  );
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(root, rel);
+    mkdirSync(join(abs, ".."), { recursive: true });
+    writeFileSync(abs, content);
+  }
+}
+
+describe("infer-prop-types-from-ts", () => {
+  it("extracts finite string union literals", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ts-"));
+    try {
+      writeProject(root, {
+        "Union.tsx": `
+export function Union({ mode }: { mode: "text" | "email" | "password" }) {
+  return <input type={mode} />;
+}
+`,
+      });
+      const bundle = createCheckerProgram(root);
+      expect(bundle).not.toBeNull();
+      const sf = bundle.program.getSourceFile(join(root, "Union.tsx"));
+      expect(sf).toBeDefined();
+      const paramType = findComponentParamType(bundle.checker, sf, "Union");
+      expect(paramType).toBeDefined();
+      const sym = bundle.checker.getPropertyOfType(paramType, "mode");
+      expect(sym).toBeDefined();
+      const propType = bundle.checker.getTypeOfSymbol(sym);
+      expect(extractFiniteStringUnion(bundle.checker, propType)).toEqual([
+        "email",
+        "password",
+        "text",
+      ]);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects unions that include plain string", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ts-"));
+    try {
+      writeProject(root, {
+        "Wide.tsx": `
+export function Wide({ label }: { label: string | "foo" }) {
+  return <span>{label}</span>;
+}
+`,
+      });
+      const bundle = createCheckerProgram(root);
+      const sf = bundle.program.getSourceFile(join(root, "Wide.tsx"));
+      const paramType = findComponentParamType(bundle.checker, sf, "Wide");
+      const sym = bundle.checker.getPropertyOfType(paramType, "label");
+      const propType = bundle.checker.getTypeOfSymbol(sym);
+      expect(extractFiniteStringUnion(bundle.checker, propType)).toBeNull();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("finds param type for function + export { Name }", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ts-"));
+    try {
+      writeProject(root, {
+        "Input.tsx": `
+function Input({ type }: { type?: "text" | "password" }) {
+  return <input type={type} />;
+}
+export { Input };
+`,
+      });
+      const bundle = createCheckerProgram(root);
+      const sf = bundle.program.getSourceFile(join(root, "Input.tsx"));
+      expect(findComponentParamType(bundle.checker, sf, "Input")).toBeDefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("infers type select options for ComponentProps input wrapper", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ts-"));
+    try {
+      writeProject(root, {
+        "input.tsx": `
+import * as React from "react";
+
+function Input({ className, type, placeholder, ...props }: React.ComponentProps<"input">) {
+  return <input type={type} placeholder={placeholder} className={className} {...props} />;
+}
+
+export { Input };
+`,
+      });
+      const bundle = createCheckerProgram(root);
+      const meta = inferPlaygroundPropMetadata(
+        bundle.checker,
+        bundle.program,
+        root,
+        "input.tsx",
+        "Input",
+        ["className", "type", "placeholder"],
+      );
+      expect(meta.declared_prop_kinds.type).toBe("string");
+      expect(meta.declared_prop_options.type).toBeDefined();
+      expect(meta.declared_prop_options.type.length).toBeGreaterThanOrEqual(2);
+      expect(meta.declared_prop_options.type).toContain("text");
+      expect(meta.declared_prop_options.type).toContain("password");
+      expect(meta.declared_prop_defaults.type).toBe("text");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  it("classifies boolean props", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-ts-"));
+    try {
+      writeProject(root, {
+        "Toggle.tsx": `
+export function Toggle({ disabled }: { disabled?: boolean }) {
+  return <button disabled={disabled} />;
+}
+`,
+      });
+      const bundle = createCheckerProgram(root);
+      const sf = bundle.program.getSourceFile(join(root, "Toggle.tsx"));
+      const paramType = findComponentParamType(bundle.checker, sf, "Toggle");
+      const sym = bundle.checker.getPropertyOfType(paramType, "disabled");
+      expect(classifyPropType(bundle.checker, bundle.checker.getTypeOfSymbol(sym))).toBe(
+        "boolean",
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/bin/lib/parse-args.mjs

@@ -2,7 +2,10 @@
  * Parse dslinter CLI argv into mode + scanner args (no subprocess).
  */
 
+import { resolveScanAndProjectRoots } from "./resolve-project.mjs";
+
 const MODE_FLAGS = new Set(["--report", "--watch", "--build"]);
+const YES_FLAGS = new Set(["--yes", "-y"]);
 
 /** @param {string | undefined} raw */
 function parseServePort(raw) {
@@ -17,16 +20,21 @@ function parseServePort(raw) {
  *   mode: "dev" | "report" | "watch" | "build" | "scanner";
  *   scannerArgs: string[];
  *   scanPath: string;
+ *   projectRoot: string;
  *   outputPath: string | null;
  *   servePort: number | null;
+ *   yes: boolean;
+ *   explicitScanPath: string | null;
  * }}
  */
 export function parseDslinterArgs(argv) {
   const modes = [];
   const scannerArgs = [];
+  let yes = false;
 
   for (const arg of argv) {
     if (MODE_FLAGS.has(arg)) modes.push(arg.slice(2));
+    else if (YES_FLAGS.has(arg)) yes = true;
     else scannerArgs.push(arg);
   }
 
@@ -67,13 +75,17 @@ export function parseDslinterArgs(argv) {
     mode = "dev";
   }
 
-  const scanPath = positional ?? ".";
+  const explicitScanPath = positional ?? null;
+  const { scanPath, projectRoot } = resolveScanAndProjectRoots(explicitScanPath);
 
   return {
     mode,
     scannerArgs,
     scanPath,
+    projectRoot,
     outputPath,
     servePort,
+    yes,
+    explicitScanPath,
   };
 }

package/bin/lib/parse-args.test.mjs

@@ -24,9 +24,15 @@ describe("parseDslinterArgs", () => {
     const p = parseDslinterArgs(["--report", "demo", "-p", "--json"]);
     expect(p.mode).toBe("report");
     expect(p.scannerArgs).toEqual(["demo", "-p", "--json"]);
-    expect(p.scanPath).toBe("demo");
+    expect(p.scanPath).toContain("demo");
   });
 
+  it("parses --yes flag", () => {
+    const p = parseDslinterArgs(["--yes"]);
+    expect(p.yes).toBe(true);
+  });
+
+
   it("uses scanner mode for --serve only", () => {
     expect(parseDslinterArgs([".", "--serve", "7878"]).mode).toBe("scanner");
   });

package/bin/lib/paths.mjs

@@ -0,0 +1,8 @@
+export const REPORT_FILE_NAME = "dslinter-report.json";
+export const REPORT_URL_PATH = "/dslinter-report.json";
+
+export const CONFIG_FILE_NAMES = [".dslinter.json", "dslinter.json"];
+
+export const DEFAULT_CONFIG_FILE_NAME = ".dslinter.json";
+
+export const IGNORE_FILE_NAME = ".dslinterignore";

package/bin/lib/project-root.mjs

@@ -1,8 +1,11 @@
 import { spawnSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { dirname, isAbsolute, join, normalize, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveServePort } from "./constants.mjs";
+import { readEnv } from "./env.mjs";
+import { REPORT_FILE_NAME } from "./paths.mjs";
 
 const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -27,12 +30,26 @@ function maxMtimeInDir(dir, latest = 0) {
   return latest;
 }
 
+/**
+ * @param {string} [root]
+ * @returns {boolean} true when embed SPA sources exist (monorepo / git checkout).
+ */
+export function hasEmbedDashboard(root = packageRoot) {
+  return existsSync(join(root, "index.html"));
+}
+
 /**
  * Rebuild `dashboard-dist/` when embed sources are newer than the bundle (or dist is missing).
+ * Published npm installs omit embed sources; use prebuilt `dashboard-dist/` only.
  * @param {string} root
  */
 export function ensureDashboardBuilt(root = packageRoot) {
-  const distIndex = join(root, "dashboard-dist", "index.html");
+  const distDir = join(root, "dashboard-dist");
+  if (!hasEmbedDashboard(root)) {
+    return dashboardDirIfReady(distDir);
+  }
+
+  const distIndex = join(distDir, "index.html");
   const force =
     process.env.DSLINTER_REBUILD_DASHBOARD === "1" ||
     process.env.DSLINTER_REBUILD_DASHBOARD?.toLowerCase() === "true";
@@ -40,12 +57,9 @@ export function ensureDashboardBuilt(root = packageRoot) {
   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 embedDir = join(root, "embed");
+    if (existsSync(embedDir) && maxMtimeInDir(embedDir) > distMtime) {
+      needsBuild = true;
     }
     const configPath = join(root, "vite.config.ts");
     if (existsSync(configPath) && statSync(configPath).mtimeMs > distMtime) {
@@ -53,7 +67,7 @@ export function ensureDashboardBuilt(root = packageRoot) {
     }
   }
 
-  if (!needsBuild) return dashboardDirIfReady(join(root, "dashboard-dist"));
+  if (!needsBuild) return dashboardDirIfReady(distDir);
 
   process.stderr.write("[dslinter] Building dashboard bundle (dashboard-dist)…\n");
   const result = spawnSync("npm", ["run", "build:dashboard"], {
@@ -64,12 +78,7 @@ export function ensureDashboardBuilt(root = packageRoot) {
   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"));
+  return dashboardDirIfReady(distDir);
 }
 
 const VITE_CONFIG_NAMES = ["vite.config.ts", "vite.config.js", "vite.config.mjs", "vite.config.cjs"];
@@ -97,19 +106,78 @@ export function findViteRoot(startDir) {
  */
 export function defaultReportPath(scanPath, outputFlag) {
   if (outputFlag) return resolve(outputFlag);
-  return resolve(scanPath, "public", "dslint-report.json");
+  const scanAbs = resolve(scanPath);
+  const viteRoot = findViteRoot(scanAbs);
+  if (viteRoot && resolve(viteRoot) !== scanAbs) {
+    return resolve(viteRoot, "public", REPORT_FILE_NAME);
+  }
+  return resolve(scanAbs, "public", REPORT_FILE_NAME);
+}
+
+/**
+ * Log when scan was promoted from a subdirectory to the project root.
+ * @param {{ promoted: boolean; originalPath?: string; scanPath: string }} info
+ * @deprecated Subdirectory scans are no longer promoted; use {@link logScanScopeHint}.
+ */
+export function logScanRootPromotion(info) {
+  if (!info.promoted || !info.originalPath) return;
+  process.stderr.write(
+    `dslinter: using project root ${info.scanPath} (was ${info.originalPath}).\n`,
+  );
+}
+
+/**
+ * Log when scanning a subdirectory while config/report use the project root.
+ * @param {{
+ *   scanPath: string;
+ *   projectRoot: string;
+ *   explicitScanPath: string | null;
+ * }} info
+ */
+export function logScanScopeHint(info) {
+  const scanAbs = resolve(info.scanPath);
+  const projectAbs = resolve(info.projectRoot);
+  if (scanAbs === projectAbs) return;
+
+  const implicit =
+    info.explicitScanPath == null ||
+    info.explicitScanPath === "" ||
+    info.explicitScanPath === ".";
+  if (!implicit) return;
+
+  const rel =
+    relative(projectAbs, scanAbs).replace(/\\/g, "/") || scanAbs;
+  process.stderr.write(
+    `dslinter: scanning ${rel} (project root: ${projectAbs}). Run from repo root for a full-repo scan.\n`,
+  );
+}
+
+/**
+ * @deprecated Use {@link logScanRootPromotion} after {@link promoteScanToProjectRoot}.
+ * @param {string} scanPath absolute or relative scan path
+ * @param {{ outputPath?: string | null }} [opts]
+ */
+export function warnIfSubdirectoryScan(scanPath, opts = {}) {
+  const scanAbs = resolve(scanPath);
+  const viteRoot = findViteRoot(scanAbs);
+  if (!viteRoot) return;
+  const viteAbs = resolve(viteRoot);
+  if (scanAbs === viteAbs) return;
+
+  process.stderr.write(
+    "dslinter: using project root for scan (subdirectory paths shorten playground rel_path).\n",
+  );
+  if (!opts.outputPath) {
+    const reportAt = defaultReportPath(viteAbs, null);
+    process.stderr.write(`dslinter: report → ${reportAt}\n`);
+  }
 }
 
 /**
  * @returns {number}
  */
 export function defaultServePort() {
-  const fromEnv = process.env.DSLINT_SERVE_PORT?.trim();
-  if (fromEnv) {
-    const n = Number.parseInt(fromEnv, 10);
-    if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
-  }
-  return 7878;
+  return resolveServePort();
 }
 
 /**
@@ -131,7 +199,7 @@ function dashboardDirIfReady(dir) {
  *
  * Resolution order:
  * 1. Skip when `DSLINTER_NO_BUNDLED_DASHBOARD=1`
- * 2. `DSLINT_DASHBOARD_STATIC` — absolute or cwd-relative (temp/gitignored dirs ok)
+ * 2. `DSLINTER_DASHBOARD_STATIC` — absolute or cwd-relative (temp/gitignored dirs ok)
  * 3. `dashboard-dist/` next to the installed `dslinter` package
  *
  * @returns {string | null}
@@ -140,7 +208,7 @@ export function resolveBundledDashboardDir() {
   const optOut = process.env.DSLINTER_NO_BUNDLED_DASHBOARD?.trim();
   if (optOut === "1" || optOut?.toLowerCase() === "true") return null;
 
-  const fromEnv = process.env.DSLINT_DASHBOARD_STATIC?.trim();
+  const fromEnv = readEnv("DASHBOARD_STATIC");
   if (fromEnv) {
     const dir = isAbsolute(fromEnv) ? normalize(fromEnv) : resolve(process.cwd(), fromEnv);
     return dashboardDirIfReady(dir);

package/bin/lib/project-root.test.mjs

@@ -0,0 +1,52 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  defaultReportPath,
+  ensureDashboardBuilt,
+  hasEmbedDashboard,
+} from "./project-root.mjs";
+
+describe("ensureDashboardBuilt (published install layout)", () => {
+  it("returns prebuilt dashboard-dist without spawning build when embed sources are absent", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-published-"));
+    mkdirSync(join(root, "dashboard-dist"), { recursive: true });
+    writeFileSync(join(root, "dashboard-dist", "index.html"), "<!doctype html>");
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(join(root, "src", "index.ts"), "export {};\n");
+
+    expect(hasEmbedDashboard(root)).toBe(false);
+
+    const dist = ensureDashboardBuilt(root);
+    expect(dist).toBeTruthy();
+    expect(dist).toContain("dashboard-dist");
+  });
+});
+
+describe("defaultReportPath", () => {
+  it("writes to project public/ when scan path is a subdirectory of vite root", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-laravel-"));
+    const components = join(root, "resources", "js", "Components");
+    mkdirSync(components, { recursive: true });
+    writeFileSync(join(root, "vite.config.js"), "export default {};\n");
+
+    const reportPath = defaultReportPath(components, null);
+    expect(reportPath).toBe(join(root, "public", "dslinter-report.json"));
+  });
+
+  it("uses scan path public/ when scan path is the vite root", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-vite-root-"));
+    mkdirSync(join(root, "src"), { recursive: true });
+    writeFileSync(join(root, "vite.config.ts"), "export default {};\n");
+
+    const reportPath = defaultReportPath(root, null);
+    expect(reportPath).toBe(join(root, "public", "dslinter-report.json"));
+  });
+
+  it("honors explicit --output", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-out-"));
+    const custom = join(root, "custom-report.json");
+    expect(defaultReportPath(root, custom)).toBe(custom);
+  });
+});

package/bin/lib/prompt.mjs

@@ -0,0 +1,31 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { envIs } from "./env.mjs";
+
+/**
+ * @returns {boolean}
+ */
+export function isInteractiveTTY() {
+  const ci = process.env.CI === "true" || process.env.CI === "1";
+  if (ci) return false;
+  if (envIs("NO_PROMPT")) return false;
+  return Boolean(input.isTTY && output.isTTY);
+}
+
+/**
+ * @param {string} question
+ * @param {{ defaultYes?: boolean }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function confirmYesNo(question, opts = {}) {
+  const defaultYes = opts.defaultYes !== false;
+  const hint = defaultYes ? "[Y/n]" : "[y/N]";
+  const rl = createInterface({ input, output });
+  try {
+    const answer = (await rl.question(`${question} ${hint} `)).trim().toLowerCase();
+    if (!answer) return defaultYes;
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}

package/bin/lib/resolve-project.mjs

@@ -0,0 +1,78 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { findViteRoot } from "./project-root.mjs";
+
+/**
+ * Walk up from `cwd` and return the best project root for scanning.
+ * 1. Nearest ancestor with vite.config.*
+ * 2. Else nearest ancestor with resources/js/ (Laravel)
+ * 3. Else cwd
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function resolveProjectRoot(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  let laravelCandidate = null;
+
+  for (;;) {
+    const viteRoot = findViteRoot(dir);
+    if (viteRoot) return resolve(viteRoot);
+
+    if (!laravelCandidate && existsSync(join(dir, "resources", "js"))) {
+      laravelCandidate = dir;
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return laravelCandidate ?? resolve(cwd);
+}
+
+/**
+ * Resolve the scan path (file-walk boundary): explicit positional relative to cwd;
+ * otherwise cwd. `"."` is literal cwd, not project root.
+ * @param {string | null | undefined} explicitPath user positional or null for default
+ * @param {string} [cwd]
+ * @returns {string} absolute path
+ */
+export function resolveScanPath(explicitPath, cwd = process.cwd()) {
+  if (explicitPath != null && explicitPath !== "") {
+    return resolve(cwd, explicitPath);
+  }
+  return resolve(cwd);
+}
+
+/**
+ * Scan root (walk boundary) and project root (config, CSS, report parent).
+ * @param {string | null | undefined} explicitPath
+ * @param {string} [cwd]
+ * @returns {{ scanPath: string; projectRoot: string }}
+ */
+export function resolveScanAndProjectRoots(explicitPath, cwd = process.cwd()) {
+  const scanPath = resolveScanPath(explicitPath, cwd);
+  const projectRoot = resolveProjectRoot(cwd);
+  return { scanPath, projectRoot };
+}
+
+/**
+ * Replace or insert the scanner positional path in argv.
+ * @param {string[]} scannerArgs
+ * @param {string} scanPath absolute scan path
+ * @returns {string[]}
+ */
+export function withScannerScanPath(scannerArgs, scanPath) {
+  const out = [];
+  let replaced = false;
+  for (const arg of scannerArgs) {
+    if (!replaced && !arg.startsWith("-")) {
+      out.push(scanPath);
+      replaced = true;
+      continue;
+    }
+    out.push(arg);
+  }
+  if (!replaced) out.unshift(scanPath);
+  return out;
+}

package/bin/lib/resolve-project.test.mjs

@@ -0,0 +1,74 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  resolveProjectRoot,
+  resolveScanAndProjectRoots,
+  resolveScanPath,
+} from "./resolve-project.mjs";
+
+describe("resolveProjectRoot", () => {
+  it("prefers vite root over laravel layout when both exist", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-resolve-vite-"));
+    mkdirSync(join(root, "resources", "js"), { recursive: true });
+    writeFileSync(join(root, "vite.config.js"), "export default {};\n");
+    expect(resolveProjectRoot(root)).toBe(root);
+  });
+
+  it("uses resources/js ancestor when no vite config", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-resolve-laravel-"));
+    mkdirSync(join(root, "resources", "js", "Components"), { recursive: true });
+    const sub = join(root, "resources", "js", "Components");
+    expect(resolveProjectRoot(sub)).toBe(root);
+  });
+});
+
+describe("resolveScanPath", () => {
+  it("defaults to cwd when no explicit path", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scan-default-"));
+    const sub = join(root, "src", "components");
+    mkdirSync(sub, { recursive: true });
+    expect(resolveScanPath(null, sub)).toBe(sub);
+  });
+
+  it("treats '.' as literal cwd", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scan-dot-"));
+    const sub = join(root, "resources", "js", "components");
+    mkdirSync(sub, { recursive: true });
+    writeFileSync(join(root, "vite.config.js"), "export default {};\n");
+    expect(resolveScanPath(".", sub)).toBe(sub);
+    expect(resolveScanPath(".", sub)).not.toBe(root);
+  });
+
+  it("honors explicit positional path", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scan-explicit-"));
+    const demo = join(root, "demo");
+    mkdirSync(demo, { recursive: true });
+    expect(resolveScanPath("demo", root)).toBe(demo);
+  });
+});
+
+describe("resolveScanAndProjectRoots", () => {
+  it("keeps scan at cwd and project at vite root from subdirectory", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scan-project-"));
+    const components = join(root, "resources", "js", "components");
+    mkdirSync(components, { recursive: true });
+    writeFileSync(join(root, "vite.config.js"), "export default {};\n");
+
+    const result = resolveScanAndProjectRoots(null, components);
+    expect(result.scanPath).toBe(components);
+    expect(result.projectRoot).toBe(root);
+  });
+
+  it("uses cwd for '.' while project root is vite root", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-scan-dot-project-"));
+    const components = join(root, "resources", "js", "components");
+    mkdirSync(components, { recursive: true });
+    writeFileSync(join(root, "vite.config.js"), "export default {};\n");
+
+    const result = resolveScanAndProjectRoots(".", components);
+    expect(result.scanPath).toBe(components);
+    expect(result.projectRoot).toBe(root);
+  });
+});