dslinter 0.1.13 → 0.2.0

package/bin/lib/enrich-playgrounds-from-ts.mjs

@@ -0,0 +1,201 @@
+/**
+ * Post-scan enrichment: fill playground prop kinds/options from TypeScript.
+ */
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  createCheckerProgram,
+  inferDeclaredPropsFromTsx,
+  inferPlaygroundPropMetadata,
+} from "./infer-prop-types-from-ts.mjs";
+
+/**
+ * @param {Record<string, unknown>} report
+ * @param {string} projectRoot
+ * @returns {boolean} true when any playground row changed
+ */
+export function enrichWorkspaceReport(report, projectRoot) {
+  const playgrounds = report.playgrounds;
+  if (!Array.isArray(playgrounds) || playgrounds.length === 0) return false;
+
+  const checkerBundle = createCheckerProgram(projectRoot);
+  if (!checkerBundle) return false;
+
+  const { program, checker } = checkerBundle;
+  let changed = false;
+
+  for (const spec of playgrounds) {
+    if (!spec || typeof spec !== "object") continue;
+
+    let declaredProps = Array.isArray(spec.declared_props) ? [...spec.declared_props] : [];
+    const relPath = typeof spec.rel_path === "string" ? spec.rel_path : "";
+    const exportName = typeof spec.export_name === "string" ? spec.export_name : spec.id;
+
+    if (typeof exportName !== "string" || !relPath) continue;
+
+    const inferred = inferDeclaredPropsFromTsx(projectRoot, relPath, exportName);
+    if (inferred.length && (!declaredProps.length || inferred.length > declaredProps.length)) {
+      declaredProps = inferred;
+      spec.declared_props = declaredProps;
+      changed = true;
+    }
+
+    const before = JSON.stringify({
+      kinds: spec.declared_prop_kinds ?? {},
+      options: spec.declared_prop_options ?? {},
+      defaults: spec.declared_prop_defaults ?? {},
+    });
+
+    const meta = inferPlaygroundPropMetadata(
+      checker,
+      program,
+      projectRoot,
+      relPath,
+      exportName,
+      declaredProps,
+      {
+        declared_prop_kinds: spec.declared_prop_kinds,
+        declared_prop_options: spec.declared_prop_options,
+        declared_prop_defaults: spec.declared_prop_defaults,
+      },
+    );
+
+    if (Object.keys(meta.declared_prop_kinds).length) {
+      spec.declared_prop_kinds = meta.declared_prop_kinds;
+    }
+    if (Object.keys(meta.declared_prop_options).length) {
+      spec.declared_prop_options = meta.declared_prop_options;
+    }
+    if (Object.keys(meta.declared_prop_defaults).length) {
+      spec.declared_prop_defaults = meta.declared_prop_defaults;
+    }
+
+    const after = JSON.stringify({
+      kinds: spec.declared_prop_kinds ?? {},
+      options: spec.declared_prop_options ?? {},
+      defaults: spec.declared_prop_defaults ?? {},
+    });
+    if (before !== after) changed = true;
+  }
+
+  return changed;
+}
+
+/**
+ * @param {string} reportPath
+ * @param {string} projectRoot
+ * @returns {boolean}
+ */
+export function enrichReportFile(reportPath, projectRoot) {
+  let report;
+  try {
+    report = JSON.parse(readFileSync(reportPath, "utf8"));
+  } catch {
+    return false;
+  }
+
+  const changed = enrichWorkspaceReport(report, projectRoot);
+  if (!changed) return false;
+
+  const json = `${JSON.stringify(report, null, 2)}\n`;
+  const dir = dirname(reportPath);
+  const tmp = join(dir, `.dslinter-enrich-${process.pid}.tmp`);
+  writeFileSync(tmp, json);
+  renameSync(tmp, reportPath);
+  return true;
+}
+
+/**
+ * @param {string} reportPath
+ * @param {string} projectRoot
+ */
+export function enrichReportFileBestEffort(reportPath, projectRoot) {
+  try {
+    enrichReportFile(reportPath, projectRoot);
+  } catch (err) {
+    if (process.env.DSLINTER_QUIET !== "1") {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`dslinter: TS playground enrich skipped (${msg})\n`);
+    }
+  }
+}
+
+/** @typedef {{ projectRoot: string; reportPath: string; logPrefix?: string }} EnrichOptions */
+
+/**
+ * CLI-facing enrichment used by report, build, dev, and watch modes.
+ *
+ * @param {EnrichOptions} opts
+ * @returns {Promise<boolean>} true when enrichment ran and wrote the report
+ */
+export async function enrichPlaygroundsFromTs({
+  projectRoot,
+  reportPath,
+  logPrefix = "dslinter",
+}) {
+  if (!createCheckerProgram(projectRoot)) {
+    if (process.env.DSLINTER_DEBUG?.trim() === "1") {
+      process.stderr.write(
+        `${logPrefix}: skip playground TS enrichment (no tsconfig.json)\n`,
+      );
+    }
+    return false;
+  }
+
+  try {
+    return enrichReportFile(reportPath, projectRoot);
+  } catch (err) {
+    if (process.env.DSLINTER_DEBUG?.trim() === "1") {
+      process.stderr.write(
+        `${logPrefix}: skip playground TS enrichment (${err instanceof Error ? err.message : err})\n`,
+      );
+    }
+    return false;
+  }
+}
+
+/**
+ * Poll the report file and re-run TS enrichment after the scanner writes JSON.
+ *
+ * @param {EnrichOptions & { pollMs?: number }} opts
+ * @returns {() => void} stop function
+ */
+export function watchEnrichPlaygroundsFromTs({
+  projectRoot,
+  reportPath,
+  logPrefix = "dslinter",
+  pollMs = 300,
+}) {
+  let lastMtimeMs = 0;
+  let running = false;
+  let stopped = false;
+
+  const tick = async () => {
+    if (stopped || running) return;
+    running = true;
+    try {
+      const { statSync } = await import("node:fs");
+      let mtimeMs;
+      try {
+        mtimeMs = statSync(reportPath).mtimeMs;
+      } catch {
+        return;
+      }
+      if (mtimeMs <= lastMtimeMs) return;
+      lastMtimeMs = mtimeMs;
+      await enrichPlaygroundsFromTs({ projectRoot, reportPath, logPrefix });
+    } finally {
+      running = false;
+    }
+  };
+
+  const interval = setInterval(() => {
+    void tick();
+  }, pollMs);
+  void tick();
+
+  return () => {
+    stopped = true;
+    clearInterval(interval);
+  };
+}

package/bin/lib/enrich-playgrounds-from-ts.test.mjs

@@ -0,0 +1,74 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { enrichReportFile } from "./enrich-playgrounds-from-ts.mjs";
+
+describe("enrich-playgrounds-from-ts", () => {
+  it("writes declared_prop_options for Input.type into report file", () => {
+    const root = mkdtempSync(join(tmpdir(), "dslinter-enrich-"));
+    const reportPath = join(root, "report.json");
+    try {
+      writeFileSync(
+        reportPath,
+        JSON.stringify(
+          {
+            root,
+            playgrounds: [
+              {
+                id: "Input",
+                export_name: "Input",
+                rel_path: "input.tsx",
+                declared_props: ["type"],
+              },
+            ],
+          },
+          null,
+          2,
+        ),
+      );
+
+      writeFileSync(
+        join(root, "tsconfig.json"),
+        JSON.stringify(
+          {
+            compilerOptions: {
+              strict: true,
+              jsx: "react-jsx",
+              module: "ESNext",
+              moduleResolution: "bundler",
+              noEmit: true,
+              skipLibCheck: true,
+              typeRoots: [
+                join(process.cwd(), "node_modules/@types"),
+              ],
+            },
+            include: ["**/*.tsx"],
+          },
+          null,
+          2,
+        ),
+      );
+
+      writeFileSync(
+        join(root, "input.tsx"),
+        `
+import * as React from "react";
+function Input({ type }: React.ComponentProps<"input">) {
+  return <input type={type} />;
+}
+export { Input };
+`,
+      );
+
+      expect(enrichReportFile(reportPath, root)).toBe(true);
+      const report = JSON.parse(readFileSync(reportPath, "utf8"));
+      const input = report.playgrounds[0];
+      expect(input.declared_prop_options.type).toContain("email");
+      expect(input.declared_prop_defaults.type).toBe("text");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/bin/lib/enrich-report-cli.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CLI entry for Rust watch post-write hook and manual enrichment.
+ * Usage: node enrich-report-cli.mjs <reportPath> <projectRoot>
+ */
+import { enrichReportFileBestEffort } from "./enrich-playgrounds-from-ts.mjs";
+
+const [reportPath, projectRoot] = process.argv.slice(2);
+if (!reportPath || !projectRoot) {
+  process.stderr.write("usage: enrich-report-cli.mjs <reportPath> <projectRoot>\n");
+  process.exit(1);
+}
+
+enrichReportFileBestEffort(reportPath, projectRoot);

package/bin/lib/env.mjs

@@ -0,0 +1,20 @@
+/** @typedef {import("node:process").ProcessEnv} ProcessEnv */
+
+/**
+ * Read `DSLINTER_*` environment variables.
+ * @param {string} name Suffix after the prefix, e.g. `"SERVE_PORT"`.
+ * @param {ProcessEnv} [env]
+ * @returns {string | undefined}
+ */
+export function readEnv(name, env = process.env) {
+  return env[`DSLINTER_${name}`]?.trim() || undefined;
+}
+
+/**
+ * @param {string} name
+ * @param {string} [value]
+ * @param {ProcessEnv} [env]
+ */
+export function envIs(name, value = "1", env = process.env) {
+  return readEnv(name, env) === value;
+}

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

@@ -0,0 +1,381 @@
+/**
+ * TypeScript checker helpers for playground prop kinds and finite string unions.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import ts from "typescript";
+
+/** @typedef {"boolean" | "string" | "number"} DeclaredPropKind */
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ program: import("typescript").Program; checker: import("typescript").TypeChecker } | null}
+ */
+export function createCheckerProgram(projectRoot) {
+  const configPath = resolve(projectRoot, "tsconfig.json");
+  if (!existsSync(configPath)) return null;
+
+  const readJson = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (readJson.error) return null;
+
+  const parsed = ts.parseJsonConfigFileContent(
+    readJson.config,
+    ts.sys,
+    projectRoot,
+    undefined,
+    configPath,
+  );
+  if (parsed.errors.length) return null;
+
+  const program = ts.createProgram({
+    rootNames: parsed.fileNames,
+    options: { ...parsed.options, noCheck: false },
+  });
+
+  return { program, checker: program.getTypeChecker() };
+}
+
+/**
+ * @param {import("typescript").Node} node
+ */
+function hasExportModifier(node) {
+  return node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+
+/**
+ * @param {import("typescript").SourceFile} sf
+ * @returns {Set<string>}
+ */
+function collectNamedExportNames(sf) {
+  /** @type {Set<string>} */
+  const names = new Set();
+
+  function visit(node) {
+    if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+      for (const el of node.exportClause.elements) {
+        names.add(el.name.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return names;
+}
+
+/**
+ * @param {import("typescript").CallExpression} call
+ * @returns {import("typescript").ParameterDeclaration | undefined}
+ */
+function firstParamFromForwardRefCall(call) {
+  const callee = call.expression;
+  const isForwardRef =
+    ts.isIdentifier(callee) &&
+    (callee.text === "forwardRef" || callee.text.endsWith(".forwardRef"));
+  if (!isForwardRef) return undefined;
+
+  const arg = call.arguments[0];
+  if (!arg || (!ts.isArrowFunction(arg) && !ts.isFunctionExpression(arg))) {
+    return undefined;
+  }
+  return arg.parameters[0];
+}
+
+/**
+ * Resolve the first parameter type for a component export.
+ *
+ * @param {import("typescript").TypeChecker} checker
+ * @param {import("typescript").SourceFile} sf
+ * @param {string} exportName
+ * @returns {import("typescript").Type | undefined}
+ */
+export function findComponentParamType(checker, sf, exportName) {
+  const namedExports = collectNamedExportNames(sf);
+
+  /** @type {import("typescript").Type | undefined} */
+  let found;
+
+  function isTargetExport(hasDirectExportModifier) {
+    return hasDirectExportModifier || namedExports.has(exportName);
+  }
+
+  function visit(node) {
+    if (found !== undefined) return;
+
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name?.text === exportName &&
+      isTargetExport(hasExportModifier(node))
+    ) {
+      const p0 = node.parameters[0];
+      if (p0) found = checker.getTypeAtLocation(p0);
+      return;
+    }
+
+    if (ts.isVariableStatement(node)) {
+      if (!isTargetExport(hasExportModifier(node))) return;
+
+      for (const decl of node.declarationList.declarations) {
+        if (!ts.isIdentifier(decl.name) || decl.name.text !== exportName || !decl.initializer) {
+          continue;
+        }
+
+        const init = decl.initializer;
+        if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+          const p0 = init.parameters[0];
+          if (p0) {
+            found = checker.getTypeAtLocation(p0);
+            return;
+          }
+        }
+
+        if (ts.isCallExpression(init)) {
+          const p0 = firstParamFromForwardRefCall(init);
+          if (p0) {
+            found = checker.getTypeAtLocation(p0);
+            return;
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return found;
+}
+
+/**
+ * @param {import("typescript").TypeChecker} checker
+ * @param {import("typescript").Type} type
+ * @returns {DeclaredPropKind | null}
+ */
+export function classifyPropType(checker, type) {
+  const nn = checker.getNonNullableType(type);
+  if (nn.isUnion()) {
+    const parts = nn.types.map((u) =>
+      classifyPropType(checker, checker.getNonNullableType(u)),
+    );
+    const ok = parts.filter((p) => p !== null);
+    if (!ok.length) return null;
+    const set = new Set(ok);
+    if (set.size === 1) return [...set][0];
+    if ([...set].every((x) => x === "string")) return "string";
+    if ([...set].every((x) => x === "number")) return "number";
+    return null;
+  }
+  if (nn.flags & (ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral)) return "boolean";
+  if (nn.flags & (ts.TypeFlags.Enum | ts.TypeFlags.EnumLiteral)) return "string";
+  if (nn.flags & (ts.TypeFlags.Number | ts.TypeFlags.NumberLike)) return "number";
+  if (nn.flags & (ts.TypeFlags.String | ts.TypeFlags.StringLike)) return "string";
+  return null;
+}
+
+/**
+ * @param {import("typescript").TypeChecker} checker
+ * @param {import("typescript").Type} type
+ */
+function isPlainStringType(checker, type) {
+  const nn = checker.getNonNullableType(type);
+  return (
+    (nn.flags & ts.TypeFlags.String) !== 0 &&
+    (nn.flags & ts.TypeFlags.StringLiteral) === 0
+  );
+}
+
+/**
+ * React and other libs use `string & {}` as an open-string catch-all alongside literals.
+ *
+ * @param {import("typescript").TypeChecker} checker
+ * @param {import("typescript").Type} type
+ */
+function isOpenStringCatchAllType(checker, type) {
+  const nn = checker.getNonNullableType(type);
+  if (isPlainStringType(checker, nn)) return true;
+  if (!nn.isIntersection?.()) return false;
+  const parts = nn.types.map((t) => checker.getNonNullableType(t));
+  const hasString = parts.some((p) => (p.flags & ts.TypeFlags.String) !== 0);
+  const hasEmptyObject = parts.some((p) => checker.typeToString(p) === "{}");
+  return hasString && hasEmptyObject;
+}
+
+/**
+ * Extract a finite union of string literals suitable for a select control.
+ *
+ * @param {import("typescript").TypeChecker} checker
+ * @param {import("typescript").Type} type
+ * @param {{ max?: number; seen?: Set<number> }} [opts]
+ * @returns {string[] | null}
+ */
+export function extractFiniteStringUnion(checker, type, opts = {}) {
+  const max = opts.max ?? 32;
+  const seen = opts.seen ?? new Set();
+
+  const nn = checker.getNonNullableType(type);
+  if (seen.has(nn.id)) return null;
+  seen.add(nn.id);
+
+  if (nn.isUnion?.()) {
+    /** @type {string[]} */
+    const literals = [];
+    for (const member of nn.types) {
+      if (isOpenStringCatchAllType(checker, member)) continue;
+      const part = extractFiniteStringUnion(checker, member, { max, seen });
+      if (part === null) {
+        if (isPlainStringType(checker, member)) return null;
+        continue;
+      }
+      literals.push(...part);
+    }
+    const unique = [...new Set(literals)];
+    if (unique.length < 2) return null;
+    unique.sort();
+    return unique.slice(0, max);
+  }
+
+  if (nn.aliasSymbol) {
+    const aliasType = checker.getDeclaredTypeOfSymbol(nn.aliasSymbol);
+    if (aliasType.id !== nn.id) {
+      return extractFiniteStringUnion(checker, aliasType, { max, seen });
+    }
+  }
+
+  if (nn.isStringLiteral()) {
+    return [nn.value];
+  }
+
+  if (nn.flags & ts.TypeFlags.EnumLiteral) {
+    const value = nn.value;
+    if (typeof value === "string") return [value];
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string} relPath
+ * @returns {import("typescript").SourceFile | undefined}
+ */
+function sourceFileForRelPath(program, projectRoot, relPath) {
+  const abs = resolve(projectRoot, relPath);
+  const norm = (p) => p.replace(/\\/g, "/");
+  const want = norm(abs);
+  return program.getSourceFiles().find((f) => norm(f.fileName) === want);
+}
+
+/**
+ * @param {import("typescript").TypeChecker} checker
+ * @param {import("typescript").Program} program
+ * @param {string} projectRoot
+ * @param {string} relPath
+ * @param {string} exportName
+ * @param {string[]} declaredProps
+ * @param {{
+ *   declared_prop_options?: Record<string, string[]>;
+ *   declared_prop_defaults?: Record<string, string>;
+ *   declared_prop_kinds?: Record<string, string>;
+ * }} [existing]
+ */
+export function inferPlaygroundPropMetadata(
+  checker,
+  program,
+  projectRoot,
+  relPath,
+  exportName,
+  declaredProps,
+  existing = {},
+) {
+  const sf = sourceFileForRelPath(program, projectRoot, relPath);
+  if (!sf) {
+    return {
+      declared_prop_kinds: existing.declared_prop_kinds ?? {},
+      declared_prop_options: existing.declared_prop_options ?? {},
+      declared_prop_defaults: existing.declared_prop_defaults ?? {},
+    };
+  }
+
+  const paramType = findComponentParamType(checker, sf, exportName);
+  if (!paramType) {
+    return {
+      declared_prop_kinds: existing.declared_prop_kinds ?? {},
+      declared_prop_options: existing.declared_prop_options ?? {},
+      declared_prop_defaults: existing.declared_prop_defaults ?? {},
+    };
+  }
+
+  /** @type {Record<string, DeclaredPropKind>} */
+  const kinds = { ...existing.declared_prop_kinds };
+  /** @type {Record<string, string[]>} */
+  const options = { ...existing.declared_prop_options };
+  /** @type {Record<string, string>} */
+  const defaults = { ...existing.declared_prop_defaults };
+
+  for (const key of declaredProps) {
+    if (key === "key" || key === "ref") continue;
+
+    const sym = checker.getPropertyOfType(paramType, key);
+    if (!sym) continue;
+    const propType = checker.getTypeOfSymbol(sym);
+
+    if (!kinds[key]) {
+      const kind = classifyPropType(checker, propType);
+      if (kind !== null) kinds[key] = kind;
+    }
+
+    if (!options[key]) {
+      const literals = extractFiniteStringUnion(checker, propType);
+      if (literals && literals.length >= 2) {
+        options[key] = literals;
+        if (key === "type" && literals.includes("text") && !defaults[key]) {
+          defaults[key] = "text";
+        }
+      }
+    }
+  }
+
+  return {
+    declared_prop_kinds: kinds,
+    declared_prop_options: options,
+    declared_prop_defaults: defaults,
+  };
+}
+
+export function inferDeclaredPropsFromTsx(projectRoot, relPath, exportName) {
+  const abs = resolve(projectRoot, relPath);
+  let text;
+  try {
+    text = readFileSync(abs, "utf8");
+  } catch {
+    return [];
+  }
+
+  const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  /** @type {string[]} */
+  const names = [];
+
+  function visit(node) {
+    if (
+      ts.isFunctionDeclaration(node) &&
+      node.name?.text === exportName &&
+      (hasExportModifier(node) || collectNamedExportNames(sf).has(exportName))
+    ) {
+      const p0 = node.parameters[0];
+      if (p0 && ts.isObjectBindingPattern(p0.name)) {
+        for (const el of p0.name.elements) {
+          if (!ts.isBindingElement(el)) continue;
+          if (el.propertyName && ts.isIdentifier(el.propertyName)) {
+            names.push(el.propertyName.text);
+          } else if (ts.isIdentifier(el.name)) {
+            names.push(el.name.text);
+          }
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return [...new Set(names)].sort();
+}