dslinter 0.1.13 → 0.2.0

package/src/playground/expandPlaygroundControls.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { expandPlaygroundControls, exampleProps, propsFromControls } from "./expandPlaygroundControls";
+
+describe("expandPlaygroundControls", () => {
+  it("expands string shorthand to string controls", () => {
+    const controls = expandPlaygroundControls({ title: "Hello" });
+    expect(controls).toEqual([
+      { key: "title", label: "Title", type: "string", default: "Hello" },
+    ]);
+  });
+
+  it("expands prop key list with prop-name defaults", () => {
+    const controls = expandPlaygroundControls(["title", "description"]);
+    expect(controls).toEqual([
+      {
+        key: "title",
+        label: "Title",
+        type: "string",
+        default: "title",
+        defaultSource: "example",
+        placeholder: "title",
+      },
+      {
+        key: "description",
+        label: "Description",
+        type: "string",
+        default: "description",
+        defaultSource: "example",
+        placeholder: "description",
+      },
+    ]);
+    expect(propsFromControls(controls, {})).toEqual({
+      title: "title",
+      description: "description",
+    });
+  });
+
+  it("exampleProps builds prop-name defaults", () => {
+    expect(exampleProps("title", "description")).toEqual({
+      title: "title",
+      description: "description",
+    });
+  });
+
+  it("propsFromControls uses control defaults", () => {
+    const controls = expandPlaygroundControls({ count: 2, enabled: true });
+    expect(propsFromControls(controls, {})).toEqual({ count: 2, enabled: true });
+    expect(propsFromControls(controls, { count: 5 })).toEqual({ count: 5, enabled: true });
+  });
+});

package/src/playground/expandPlaygroundControls.ts

@@ -0,0 +1,97 @@
+import { defaultArgsFromControls } from "../types/controls";
+import type { PlaygroundArgs, PlaygroundControl } from "../types/controls";
+
+export type CompactPlaygroundControl =
+  | string
+  | number
+  | boolean
+  | Partial<PlaygroundControl> & { key?: string };
+
+/** Shorthand: list prop keys; defaults and placeholders use the key name. */
+export type PlaygroundControlKeys = readonly string[];
+
+export type PlaygroundControlsInput =
+  | PlaygroundControl[]
+  | Record<string, CompactPlaygroundControl>
+  | PlaygroundControlKeys;
+
+function isPropKeyList(input: readonly unknown[]): input is readonly string[] {
+  return input.length > 0 && input.every((item) => typeof item === "string");
+}
+
+function titleCase(key: string): string {
+  return key
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+function isFullControl(value: CompactPlaygroundControl): value is PlaygroundControl {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "type" in value &&
+    typeof (value as PlaygroundControl).type === "string"
+  );
+}
+
+function expandOne(key: string, value: CompactPlaygroundControl): PlaygroundControl {
+  if (isFullControl(value)) {
+    const label = value.label ?? titleCase(key);
+    return { ...value, key, label } as PlaygroundControl;
+  }
+  if (typeof value === "boolean") {
+    return { key, label: titleCase(key), type: "boolean", default: value };
+  }
+  if (typeof value === "number") {
+    return { key, label: titleCase(key), type: "number", default: value };
+  }
+  return { key, label: titleCase(key), type: "string", default: String(value) };
+}
+
+function expandPropNameControl(key: string): PlaygroundControl {
+  return {
+    key,
+    label: titleCase(key),
+    type: "string",
+    default: key,
+    defaultSource: "example",
+    placeholder: key,
+  };
+}
+
+/** Shorthand defaults where each value equals the prop key (panel placeholder text). */
+export function exampleProps(...keys: string[]): Record<string, string> {
+  return Object.fromEntries(keys.map((key) => [key, key]));
+}
+
+/** Expand shorthand `controls` into full `PlaygroundControl` objects. */
+export function expandPlaygroundControls(
+  input: PlaygroundControlsInput | undefined,
+): PlaygroundControl[] {
+  if (!input) return [];
+  if (Array.isArray(input)) {
+    if (isPropKeyList(input)) {
+      return input.map((key) => expandPropNameControl(key));
+    }
+    return input;
+  }
+  return Object.entries(input).map(([key, value]) => expandOne(key, value));
+}
+
+/** Map panel values to a props object using control defaults (no manual `??` fallbacks). */
+export function propsFromControls<T extends PlaygroundArgs>(
+  controls: PlaygroundControl[],
+  values: PlaygroundArgs,
+  defaults?: Partial<T>,
+): T {
+  const out = { ...defaultArgsFromControls(controls), ...defaults } as Record<
+    string,
+    string | number | boolean
+  >;
+  for (const c of controls) {
+    const v = values[c.key];
+    if (v !== undefined) out[c.key] = v;
+  }
+  return out as T;
+}

package/src/playground/inferKitJsx.test.ts

@@ -0,0 +1,77 @@
+import { createElement } from "react";
+import { describe, expect, it } from "vitest";
+import {
+  inferKitJsxSlots,
+  inferKitRootPropBindings,
+  slotDefaultFromComponent,
+  slotLabelFromComponent,
+} from "./inferKitJsx";
+
+function Alert(props: { variant?: string; children?: unknown }) {
+  return createElement("div", props);
+}
+function AlertTitle(props: { children?: unknown }) {
+  return createElement("div", props);
+}
+function AlertDescription(props: { children?: unknown }) {
+  return createElement("div", props);
+}
+
+describe("inferKitJsx", () => {
+  it("reads createElement children bindings (including vite transforms)", () => {
+    const viteTransformed =
+      "({ title, description }) => (0,createElement)(Alert, { variant: 'default' }, (0,createElement)(AlertTitle, null, title), (0,createElement)(AlertDescription, null, description))";
+    const fromVite = Object.assign(() => null, { toString: () => viteTransformed });
+    expect(inferKitJsxSlots(fromVite)).toEqual([
+      { component: "AlertTitle", param: "title" },
+      { component: "AlertDescription", param: "description" },
+    ]);
+  });
+
+  it("reads root prop bindings from createElement", () => {
+    const fromVite = Object.assign(() => null, {
+      toString: () => "({ variant }) => (0,createElement)(Alert, { variant }, (0,createElement)(AlertTitle, null, 'Hi'))",
+    });
+    expect(inferKitRootPropBindings(fromVite)).toEqual([
+      { component: "Alert", prop: "variant", param: "variant" },
+    ]);
+  });
+
+  it("reads root prop bindings from vite SSR import wrappers", () => {
+    const fromVite = Object.assign(() => null, {
+      toString: () =>
+        "({ title, description, variant }) => (0,__vite_ssr_import_0__.createElement)(\n      Alert,\n      { variant },\n      (0,__vite_ssr_import_0__.createElement)(AlertTitle, null, title),\n      (0,__vite_ssr_import_0__.createElement)(AlertDescription, null, description)\n    )",
+    });
+    expect(inferKitRootPropBindings(fromVite)).toEqual([
+      { component: "Alert", prop: "variant", param: "variant" },
+    ]);
+  });
+
+  it("reads root prop bindings from source JSX", () => {
+    const kit = Object.assign(() => null, {
+      toString: () =>
+        '({ title, description, variant }) => (<Alert className="max-w-md" variant={variant}><AlertTitle>{title}</AlertTitle></Alert>)',
+    });
+    expect(inferKitRootPropBindings(kit)).toEqual([
+      { component: "Alert", prop: "variant", param: "variant" },
+    ]);
+  });
+
+  it("reads source JSX slots", () => {
+    const kit = Object.assign(() => null, {
+      toString: () =>
+        "({ title, description }) => (<Alert><AlertTitle>{title}</AlertTitle><AlertDescription>{description}</AlertDescription></Alert>)",
+    });
+    expect(inferKitJsxSlots(kit)).toEqual([
+      { component: "AlertTitle", param: "title" },
+      { component: "AlertDescription", param: "description" },
+    ]);
+  });
+
+  it("derives slot labels and defaults from component names", () => {
+    expect(slotLabelFromComponent("AlertTitle")).toBe("Title");
+    expect(slotLabelFromComponent("AlertDescription")).toBe("Description");
+    expect(slotDefaultFromComponent("AlertTitle")).toBe("Heads up");
+    expect(slotDefaultFromComponent("DialogTrigger")).toBe("Open");
+  });
+});

package/src/playground/inferKitJsx.ts

@@ -0,0 +1,165 @@
+export type KitJsxSlot = {
+  param: string;
+  component: string;
+};
+
+export type KitRootPropBinding = {
+  param: string;
+  component: string;
+  prop: string;
+};
+
+function kitSource(fn: Function): string {
+  return fn.toString();
+}
+
+/** Vite/esbuild wraps JSX as `(0, import.createElement)(Type, props)` (often split across lines). */
+function normalizeKitSource(src: string): string {
+  return src
+    .replace(/\(\s*0\s*,\s*(?:[\w$.]+\.)?(jsx(?:DEV)?|createElement)\)\s*\(/g, "$1(")
+    .replace(/(?:[\w$.]+\.)?(jsx(?:DEV)?|createElement)\(/g, "$1(");
+}
+
+/** `AlertTitle` → `Title`; `DialogDescription` → `Description`. */
+export function slotLabelFromComponent(component: string): string {
+  const match = component.match(/^[A-Z][a-z]+(?=[A-Z])/);
+  const suffix = match ? component.slice(match[0].length) : component;
+  return suffix
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (c) => c.toUpperCase())
+    .trim();
+}
+
+/** Example copy for common compound slot names. */
+export function slotDefaultFromComponent(component: string): string | undefined {
+  if (component.endsWith("Title")) return "Heads up";
+  if (component.endsWith("Description")) return "This is a short description.";
+  if (component.endsWith("Trigger") || component.includes("Trigger")) return "Open";
+  if (component.endsWith("Content")) return "Content";
+  if (component.endsWith("Label")) return "Label";
+  return undefined;
+}
+
+const RUNTIME_CHILDREN_SLOT_RE =
+  /(?:jsx(?:DEV)?|createElement)\(\s*([A-Za-z_$][\w$]*)\s*,\s*[^,]*,\s*([A-Za-z_$][\w$]*)\s*(?:\)|,)/g;
+const RUNTIME_CHILDREN_PROP_RE =
+  /(?:jsx(?:DEV)?|createElement)\(\s*([A-Za-z_$][\w$]*)\s*,\s*\{[^}]*\bchildren:\s*([A-Za-z_$][\w$]*)/g;
+const RUNTIME_ROOT_PROPS_RE =
+  /(?:jsx(?:DEV)?|createElement)\(\s*([A-Za-z_$][\w$]*)\s*,\s*\{([\s\S]*?)\}\s*(?:,|\))/g;
+
+function collectJsxRuntimeSlots(src: string, out: KitJsxSlot[]): void {
+  const normalized = normalizeKitSource(src);
+  for (const match of normalized.matchAll(RUNTIME_CHILDREN_SLOT_RE)) {
+    out.push({ component: match[1]!, param: match[2]! });
+  }
+  for (const match of normalized.matchAll(RUNTIME_CHILDREN_PROP_RE)) {
+    out.push({ component: match[1]!, param: match[2]! });
+  }
+}
+
+function collectSourceJsxSlots(src: string, out: KitJsxSlot[]): void {
+  const re = /<([A-Z][A-Za-z0-9]*)(?:\s[^>]*)?>\s*\{\s*([A-Za-z_$][\w$]*)\s*\}\s*<\/\1>/g;
+  for (const match of src.matchAll(re)) {
+    out.push({ component: match[1]!, param: match[2]! });
+  }
+}
+
+/** Map kit params to compound subcomponents (`AlertTitle`, etc.) from JSX. */
+export function inferKitJsxSlots(fn: Function): KitJsxSlot[] {
+  const src = kitSource(fn);
+  const out: KitJsxSlot[] = [];
+  collectSourceJsxSlots(src, out);
+  collectJsxRuntimeSlots(src, out);
+
+  const seen = new Set<string>();
+  return out.filter((slot) => {
+    const id = `${slot.component}:${slot.param}`;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+}
+
+function parseJsxPropsObject(raw: string | undefined): Array<{ prop: string; param: string }> {
+  if (!raw) return [];
+  const body = raw.trim();
+  const out: Array<{ prop: string; param: string }> = [];
+
+  if (/^[A-Za-z_$][\w$]*$/.test(body)) {
+    return [{ prop: body, param: body }];
+  }
+
+  const re = /\b([A-Za-z_$][\w$]*)\s*:\s*([A-Za-z_$][\w$]*)\b/g;
+  for (const match of raw.matchAll(re)) {
+    const prop = match[1]!;
+    const param = match[2]!;
+    if (prop === "children" || prop === "className" || prop === "style" || prop === "asChild") {
+      continue;
+    }
+    out.push({ prop, param });
+  }
+
+  // ES shorthand `{ variant }` → `variant: variant`
+  const shorthandRe = /(?:^|[,{]\s*)([A-Za-z_$][\w$]*)\s*(?=[,}])/g;
+  for (const match of raw.matchAll(shorthandRe)) {
+    const prop = match[1]!;
+    if (
+      prop === "children" ||
+      prop === "className" ||
+      prop === "style" ||
+      prop === "asChild" ||
+      out.some((binding) => binding.prop === prop)
+    ) {
+      continue;
+    }
+    out.push({ prop, param: prop });
+  }
+
+  return out;
+}
+
+function collectRootPropBindings(src: string, out: KitRootPropBinding[]): void {
+  const normalized = normalizeKitSource(src);
+  for (const match of normalized.matchAll(RUNTIME_ROOT_PROPS_RE)) {
+    for (const binding of parseJsxPropsObject(match[2])) {
+      out.push({ component: match[1]!, prop: binding.prop, param: binding.param });
+    }
+  }
+
+  const sourceRoot = /<([A-Z][A-Za-z0-9]*)([^>]*)>/g;
+  for (const match of src.matchAll(sourceRoot)) {
+    const attrs = match[2] ?? "";
+    const attrRe = /\b([A-Za-z_$][\w$]*)\s*=\s*\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+    for (const attr of attrs.matchAll(attrRe)) {
+      const prop = attr[1]!;
+      if (prop === "className" || prop === "style" || prop === "asChild") continue;
+      out.push({ component: match[1]!, prop, param: attr[2]! });
+    }
+  }
+}
+
+/** Root component prop bindings such as `<Alert variant={variant}>`. */
+export function inferKitRootPropBindings(fn: Function): KitRootPropBinding[] {
+  const src = kitSource(fn);
+  const out: KitRootPropBinding[] = [];
+  collectRootPropBindings(src, out);
+
+  const seen = new Set<string>();
+  return out.filter((binding) => {
+    const id = `${binding.component}.${binding.prop}:${binding.param}`;
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+}
+
+export function primaryRootComponent(fn: Function): string | undefined {
+  const bindings = inferKitRootPropBindings(fn);
+  if (bindings.length > 0) return bindings[0]!.component;
+  const slots = inferKitJsxSlots(fn);
+  for (const slot of slots) {
+    const prefix = slot.component.match(/^[A-Z][a-z]+(?=[A-Z])/)?.[0];
+    if (prefix && slot.component.startsWith(prefix)) return prefix;
+  }
+  return undefined;
+}

package/src/playground/inferKitParams.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { controlsFromKitParams, inferKitParams } from "./inferKitParams";
+
+describe("inferKitParams", () => {
+  it("reads simple destructured keys", () => {
+    const kit = ({ title, description }: { title: string; description: string }) =>
+      `${title}-${description}`;
+    expect(inferKitParams(kit)).toEqual([{ key: "title" }, { key: "description" }]);
+  });
+
+  it("reads inline defaults from destructuring", () => {
+    const kit = ({ placeholder = "Pick a stack" }: { placeholder?: string }) => placeholder;
+    expect(inferKitParams(kit)).toEqual([
+      { key: "placeholder", defaultValue: "Pick a stack" },
+    ]);
+  });
+
+  it("reads boolean defaults", () => {
+    const kit = ({ showEmail = false }: { showEmail?: boolean }) => showEmail;
+    expect(inferKitParams(kit)).toEqual([{ key: "showEmail", defaultValue: false }]);
+  });
+
+  it("returns empty for parameterless kits", () => {
+    const kit = () => "static";
+    expect(inferKitParams(kit)).toEqual([]);
+  });
+
+  it("returns empty for non-destructured params", () => {
+    const kit = (props: { title: string }) => props.title;
+    expect(inferKitParams(kit)).toEqual([]);
+  });
+
+  it("builds control defaults from inferred params", () => {
+    expect(
+      controlsFromKitParams([
+        { key: "title" },
+        { key: "placeholder", defaultValue: "Pick one" },
+      ]),
+    ).toEqual({ title: "title", placeholder: "Pick one" });
+  });
+});

package/src/playground/inferKitParams.ts

@@ -0,0 +1,113 @@
+import type { CompactPlaygroundControl } from "./expandPlaygroundControls";
+
+export type InferredKitParam = {
+  key: string;
+  defaultValue?: CompactPlaygroundControl;
+};
+
+function splitTopLevelCommas(input: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let quote: "'" | '"' | "`" | null = null;
+  let start = 0;
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i]!;
+    if (quote) {
+      if (ch === quote && input[i - 1] !== "\\") quote = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") depth += 1;
+    else if (ch === "}" || ch === "]" || ch === ")") depth -= 1;
+    else if (ch === "," && depth === 0) {
+      parts.push(input.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(input.slice(start));
+  return parts;
+}
+
+function parseLiteral(raw: string): CompactPlaygroundControl | undefined {
+  const value = raw.trim();
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  const quoted =
+    (value.startsWith("'") && value.endsWith("'")) ||
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("`") && value.endsWith("`"));
+  if (quoted && value.length >= 2) return value.slice(1, -1);
+  return undefined;
+}
+
+function parseDestructuredSegment(segment: string): InferredKitParam | null {
+  const trimmed = segment.trim();
+  if (!trimmed || trimmed.startsWith("...")) return null;
+
+  const assignIdx = findTopLevelChar(trimmed, "=");
+  if (assignIdx !== -1) {
+    const left = trimmed.slice(0, assignIdx).trim();
+    const defaultRaw = trimmed.slice(assignIdx + 1).trim();
+    const key = left.includes(":") ? left.split(":")[0]!.trim() : left;
+    if (!/^[A-Za-z_$][\w$]*$/.test(key)) return null;
+    const defaultValue = parseLiteral(defaultRaw);
+    return defaultValue !== undefined ? { key, defaultValue } : { key };
+  }
+
+  const colonIdx = findTopLevelChar(trimmed, ":");
+  if (colonIdx !== -1) {
+    const key = trimmed.slice(0, colonIdx).trim();
+    if (!/^[A-Za-z_$][\w$]*$/.test(key)) return null;
+    return { key };
+  }
+
+  if (!/^[A-Za-z_$][\w$]*$/.test(trimmed)) return null;
+  return { key: trimmed };
+}
+
+function findTopLevelChar(input: string, target: string): number {
+  let depth = 0;
+  let quote: "'" | '"' | "`" | null = null;
+  for (let i = 0; i < input.length; i += 1) {
+    const ch = input[i]!;
+    if (quote) {
+      if (ch === quote && input[i - 1] !== "\\") quote = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"' || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") depth += 1;
+    else if (ch === "}" || ch === "]" || ch === ")") depth -= 1;
+    else if (ch === target && depth === 0) return i;
+  }
+  return -1;
+}
+
+function objectDestructuringSource(fn: Function): string | undefined {
+  const src = fn.toString().trim();
+  const match = src.match(/^(?:async\s*)?(?:function\s*)?\(\s*\{([\s\S]*?)\}\s*(?::[^)=]*)?\)/);
+  return match?.[1];
+}
+
+/** Read destructured parameter keys (and inline defaults) from a kit callback. */
+export function inferKitParams(fn: Function): InferredKitParam[] {
+  const inner = objectDestructuringSource(fn);
+  if (!inner) return [];
+  return splitTopLevelCommas(inner)
+    .map(parseDestructuredSegment)
+    .filter((param): param is InferredKitParam => param !== null);
+}
+
+export function controlsFromKitParams(params: InferredKitParam[]): Record<string, CompactPlaygroundControl> {
+  const out: Record<string, CompactPlaygroundControl> = {};
+  for (const param of params) {
+    out[param.key] = param.defaultValue ?? param.key;
+  }
+  return out;
+}

package/src/playground/inferPropTypesFromTs.d.mts

@@ -0,0 +1,47 @@
+import type { Program, TypeChecker, SourceFile, Type } from "typescript";
+import type { PlaygroundSpec } from "../types/report.js";
+
+export type PropKind = "boolean" | "string" | "number";
+
+export type CheckerProgram = {
+  program: Program;
+  checker: TypeChecker;
+};
+
+export declare function createCheckerProgram(projectRoot: string): CheckerProgram | null;
+
+export declare function findComponentParamType(
+  checker: TypeChecker,
+  sf: SourceFile,
+  exportName: string,
+): Type | undefined;
+
+export declare function classifyPropType(checker: TypeChecker, type: Type): PropKind | null;
+
+export declare function extractFiniteStringUnion(
+  checker: TypeChecker,
+  type: Type,
+): string[] | null;
+
+export declare function inferDeclaredPropKindsFromTs(
+  checker: TypeChecker,
+  program: Program,
+  projectRoot: string,
+  relPath: string,
+  exportName: string,
+  declaredProps: string[],
+): Record<string, string>;
+
+export declare function enrichPlaygroundSpecFromTs(
+  spec: PlaygroundSpec,
+  checker: TypeChecker,
+  program: Program,
+  projectRoot: string,
+): PlaygroundSpec;
+
+export declare function enrichPlaygroundsFromReport(
+  report: { playgrounds?: PlaygroundSpec[] },
+  checker: TypeChecker,
+  program: Program,
+  projectRoot: string,
+): void;