@selfcure/generator 0.1.0

package/README.md

@@ -0,0 +1,19 @@
+# @selfcure/generator
+
+> Legacy BYOK test generator for **selfcure** — turns component analysis into Playwright test code via an LLM.
+
+Part of selfcure's **fallback pipeline** for teams not using the Playwright Test Agents. Sends component analysis to a provider-agnostic `LanguageModel` (via the Vercel AI SDK) and receives a Playwright `.spec.ts`. **BYOK** — bring your own key; no credentials ship with the package.
+
+Supported providers: Anthropic, OpenAI, Google Gemini, Groq, DeepSeek, and local Ollama.
+
+Internal library powering `selfcure run`. The headline, preventive flow is `selfcure lint` — see [`@selfcure/cli`](https://www.npmjs.com/package/@selfcure/cli).
+
+## Install
+
+```bash
+npm install @selfcure/generator
+```
+
+## Docs
+
+Full documentation: https://github.com/ricardofrancocustodio/selfcure#readme

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { AnalysisResult } from '@selfcure/analyzer';
+import { LanguageModel } from 'ai';
+import { ProjectMap } from '@selfcure/crawler';
+
+type ProviderId = 'anthropic' | 'openai' | 'google' | 'groq' | 'deepseek' | 'ollama';
+interface ProviderMeta {
+    id: ProviderId;
+    label: string;
+    /** Env var that holds the API key (null = no key required, e.g. Ollama) */
+    envVar: string | null;
+    defaultGenerationModel: string;
+    defaultHealingModel: string;
+    /** Default base URL — only present for providers behind a configurable endpoint */
+    defaultBaseURL?: string;
+    /** Short hint shown in the wizard */
+    hint: string;
+    apiKeyPlaceholder: string;
+}
+declare const PROVIDERS: Record<ProviderId, ProviderMeta>;
+interface AIConfig {
+    provider: ProviderId;
+    generationModel?: string;
+    healingModel?: string;
+    /** Override the env var name (default: PROVIDERS[provider].envVar) */
+    apiKeyEnv?: string;
+    /** Override the base URL (used by Ollama / DeepSeek / self-hosted endpoints) */
+    baseURL?: string;
+}
+type ModelKind = 'generation' | 'healing';
+/**
+ * Build a Vercel AI SDK LanguageModel for the given config + role.
+ * Throws if the provider requires an API key and the env var is missing.
+ */
+declare function getModel(ai: AIConfig, kind: ModelKind): LanguageModel;
+
+interface RuntimeDiscoveryResult {
+    routes: Array<{
+        route: string;
+        status: string;
+        interactiveElements: Array<{
+            score: number;
+        }>;
+    }>;
+}
+interface DiscoveryLlmInput {
+    framework: string;
+    packageManager: string;
+    packageScripts: string[];
+    routeCandidates: string[];
+    /** Present only when runtime discovery already ran */
+    runtimeFindings?: {
+        route: string;
+        status: string;
+        flaggedCount: number;
+    }[];
+}
+interface HiddenStateHint {
+    route: string;
+    /** Plain-language description of the UI trigger, e.g. "button 'Add to cart'" */
+    triggerHint: string;
+}
+interface DiscoveryLlmOutput {
+    routesToVisit: string[];
+    hiddenStatesToExplore: HiddenStateHint[];
+    /** LLM's own confidence in its suggestions, 0–1 */
+    confidence: number;
+    notes: string[];
+}
+/** Build the compact structured input for the discovery LLM call. */
+declare function buildDiscoveryInput(map: ProjectMap, rtResult?: RuntimeDiscoveryResult): DiscoveryLlmInput;
+/**
+ * Return true when the deterministic evidence is uncertain enough that an LLM
+ * call is worthwhile.  Skip LLM when:
+ * - All static route candidates have confidence >= 0.9 AND
+ * - Runtime shows no unreachable routes (or runtime wasn't run)
+ */
+declare function shouldUseLlm(map: ProjectMap, rtResult?: RuntimeDiscoveryResult): boolean;
+declare function buildDiscoveryPrompt(input: DiscoveryLlmInput): string;
+declare function validateDiscoveryOutput(raw: unknown, allowedRoutes: string[]): DiscoveryLlmOutput;
+/**
+ * Ask the configured LLM provider to suggest which routes to visit and which
+ * hidden states to explore.  Only called when `shouldUseLlm()` returns true.
+ *
+ * Throws if the provider API key is missing or the response cannot be parsed.
+ */
+declare function runLlmDiscovery(input: DiscoveryLlmInput, aiConfig: AIConfig): Promise<DiscoveryLlmOutput>;
+
+interface GeneratorOptions {
+    /** Resolved `ai` block from selfcure.config.mjs — provider + model overrides */
+    ai: AIConfig;
+    /** Output directory where generated test files will be written */
+    testsDir: string;
+    /** Cap per LLM request to avoid runaway costs */
+    maxInputTokens?: number;
+}
+interface GeneratedTest {
+    /** Absolute path of the generated .spec.ts file */
+    filePath: string;
+    sourceComponent: string;
+    testCode: string;
+    generatedAt: Date;
+}
+/**
+ * For each analysed component, call the configured LLM and receive a
+ * Playwright test file. The provider (Anthropic/OpenAI/Google/Groq/DeepSeek/
+ * Ollama) and model are resolved from `options.ai`.
+ *
+ * The required API key is read from the env var declared by the provider
+ * (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY, …).
+ */
+declare function generate(analyses: AnalysisResult[], options: GeneratorOptions): Promise<GeneratedTest[]>;
+
+export { type AIConfig, type DiscoveryLlmInput, type DiscoveryLlmOutput, type GeneratedTest, type GeneratorOptions, type HiddenStateHint, type ModelKind, PROVIDERS, type ProviderId, type ProviderMeta, buildDiscoveryInput, buildDiscoveryPrompt, generate as default, generate, getModel, runLlmDiscovery, shouldUseLlm, validateDiscoveryOutput };

package/dist/index.js

@@ -0,0 +1,281 @@
+// src/index.ts
+import { generateText as generateText2 } from "ai";
+
+// src/ai.ts
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createGroq } from "@ai-sdk/groq";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+var PROVIDERS = {
+  anthropic: {
+    id: "anthropic",
+    label: "Anthropic",
+    envVar: "ANTHROPIC_API_KEY",
+    defaultGenerationModel: "claude-opus-4-7",
+    defaultHealingModel: "claude-haiku-4-5",
+    hint: "Top-tier reasoning, $$$",
+    apiKeyPlaceholder: "sk-ant-\u2026"
+  },
+  openai: {
+    id: "openai",
+    label: "OpenAI",
+    envVar: "OPENAI_API_KEY",
+    defaultGenerationModel: "gpt-4.1",
+    defaultHealingModel: "gpt-4o-mini",
+    hint: "Most widely available",
+    apiKeyPlaceholder: "sk-\u2026"
+  },
+  google: {
+    id: "google",
+    label: "Google Gemini",
+    envVar: "GOOGLE_GENERATIVE_AI_API_KEY",
+    defaultGenerationModel: "gemini-2.0-flash-exp",
+    defaultHealingModel: "gemini-2.0-flash-exp",
+    hint: "Generous free tier",
+    apiKeyPlaceholder: "AIza\u2026"
+  },
+  groq: {
+    id: "groq",
+    label: "Groq",
+    envVar: "GROQ_API_KEY",
+    defaultGenerationModel: "llama-3.3-70b-versatile",
+    defaultHealingModel: "llama-3.1-8b-instant",
+    hint: "Free tier, fastest inference",
+    apiKeyPlaceholder: "gsk_\u2026"
+  },
+  deepseek: {
+    id: "deepseek",
+    label: "DeepSeek",
+    envVar: "DEEPSEEK_API_KEY",
+    defaultGenerationModel: "deepseek-chat",
+    defaultHealingModel: "deepseek-chat",
+    defaultBaseURL: "https://api.deepseek.com/v1",
+    hint: "Ultra-cheap, OpenAI-compatible",
+    apiKeyPlaceholder: "sk-\u2026"
+  },
+  ollama: {
+    id: "ollama",
+    label: "Ollama (local)",
+    envVar: null,
+    defaultGenerationModel: "qwen2.5-coder:14b",
+    defaultHealingModel: "qwen2.5-coder:7b",
+    defaultBaseURL: "http://localhost:11434/v1",
+    hint: "No key, runs locally",
+    apiKeyPlaceholder: ""
+  }
+};
+function pickModelName(ai, kind) {
+  const meta = PROVIDERS[ai.provider];
+  if (kind === "generation") return ai.generationModel ?? meta.defaultGenerationModel;
+  return ai.healingModel ?? meta.defaultHealingModel;
+}
+function readApiKey(ai) {
+  const envName = ai.apiKeyEnv ?? PROVIDERS[ai.provider].envVar;
+  if (!envName) return void 0;
+  return process.env[envName];
+}
+function getModel(ai, kind) {
+  const meta = PROVIDERS[ai.provider];
+  const modelName = pickModelName(ai, kind);
+  const apiKey = readApiKey(ai);
+  if (meta.envVar && !apiKey) {
+    throw new Error(
+      `Missing ${meta.envVar} for provider "${ai.provider}". Set it in your .env or shell environment.`
+    );
+  }
+  switch (ai.provider) {
+    case "anthropic": {
+      const client = createAnthropic({ apiKey });
+      return client(modelName);
+    }
+    case "openai": {
+      const client = createOpenAI({ apiKey });
+      return client(modelName);
+    }
+    case "google": {
+      const client = createGoogleGenerativeAI({ apiKey });
+      return client(modelName);
+    }
+    case "groq": {
+      const client = createGroq({ apiKey });
+      return client(modelName);
+    }
+    case "deepseek": {
+      const client = createOpenAICompatible({
+        name: "deepseek",
+        baseURL: ai.baseURL ?? meta.defaultBaseURL,
+        apiKey
+      });
+      return client(modelName);
+    }
+    case "ollama": {
+      const client = createOpenAICompatible({
+        name: "ollama",
+        baseURL: ai.baseURL ?? meta.defaultBaseURL
+      });
+      return client(modelName);
+    }
+  }
+}
+
+// src/discovery.ts
+import { generateText } from "ai";
+function buildDiscoveryInput(map, rtResult) {
+  const scripts = [
+    map.devCommand,
+    map.buildCommand,
+    map.testCommand
+  ].filter((s) => Boolean(s));
+  const input = {
+    framework: map.framework,
+    packageManager: map.packageManager,
+    packageScripts: scripts,
+    routeCandidates: map.routeCandidates.map((r) => r.path)
+  };
+  if (rtResult) {
+    input.runtimeFindings = rtResult.routes.map((r) => ({
+      route: r.route,
+      status: r.status,
+      flaggedCount: r.interactiveElements.filter((e) => e.score < 80).length
+    }));
+  }
+  return input;
+}
+function shouldUseLlm(map, rtResult) {
+  const avgConf = map.routeCandidates.length > 0 ? map.routeCandidates.reduce((s, r) => s + r.confidence, 0) / map.routeCandidates.length : 0;
+  if (avgConf < 0.85) return true;
+  if (rtResult) {
+    const hasUnreachable = rtResult.routes.some((r) => r.status !== "reachable");
+    if (hasUnreachable) return true;
+  }
+  return false;
+}
+function buildDiscoveryPrompt(input) {
+  return [
+    `You are analyzing a ${input.framework} frontend application to improve testability coverage.`,
+    "",
+    "Given the project information below, identify:",
+    "1. Which route candidates are the most important to test (prioritise by user-journey value)",
+    "2. Any hidden states (modals, drawers, wizard steps, dialogs) likely triggered from those routes",
+    "",
+    "Project information:",
+    JSON.stringify(input, null, 2),
+    "",
+    "Respond with ONLY valid JSON \u2014 no prose, no markdown fences:",
+    "{",
+    '  "routesToVisit": ["/", "/login"],',
+    '  "hiddenStatesToExplore": [',
+    `    { "route": "/checkout", "triggerHint": "button with accessible name 'Add payment method'" }`,
+    "  ],",
+    '  "confidence": 0.82,',
+    '  "notes": []',
+    "}",
+    "",
+    "Rules:",
+    "- routesToVisit must be a subset of routeCandidates",
+    "- confidence must be a number between 0 and 1",
+    "- hiddenStatesToExplore may be an empty array",
+    "- notes may be an empty array",
+    "- Do NOT include any explanation outside the JSON object"
+  ].join("\n");
+}
+function validateDiscoveryOutput(raw, allowedRoutes) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Discovery LLM output is not an object");
+  }
+  const r = raw;
+  if (!Array.isArray(r["routesToVisit"])) {
+    throw new Error("routesToVisit must be an array");
+  }
+  if (typeof r["confidence"] !== "number" || r["confidence"] < 0 || r["confidence"] > 1) {
+    throw new Error("confidence must be a number between 0 and 1");
+  }
+  const allowed = new Set(allowedRoutes);
+  const routesToVisit = r["routesToVisit"].filter((x) => typeof x === "string" && allowed.has(x));
+  const hiddenStatesToExplore = Array.isArray(r["hiddenStatesToExplore"]) ? r["hiddenStatesToExplore"].filter(
+    (x) => typeof x === "object" && x !== null && typeof x["route"] === "string" && typeof x["triggerHint"] === "string"
+  ) : [];
+  const notes = Array.isArray(r["notes"]) ? r["notes"].filter((x) => typeof x === "string") : [];
+  return {
+    routesToVisit,
+    hiddenStatesToExplore,
+    confidence: r["confidence"],
+    notes
+  };
+}
+async function runLlmDiscovery(input, aiConfig) {
+  const model = getModel(aiConfig, "generation");
+  const prompt = buildDiscoveryPrompt(input);
+  const { text } = await generateText({ model, prompt, maxOutputTokens: 1e3 });
+  const match = text.match(/\{[\s\S]*\}/);
+  if (!match) {
+    throw new Error(`LLM response contained no JSON object.
+
+Raw response:
+${text}`);
+  }
+  const parsed = JSON.parse(match[0]);
+  return validateDiscoveryOutput(parsed, input.routeCandidates);
+}
+
+// src/index.ts
+function buildPrompt(analysis) {
+  const { component, interactiveElements, score } = analysis;
+  const ambiguous = interactiveElements.filter((e) => e.ambiguous);
+  const ambiguitySection = ambiguous.length ? `
+
+## Ambiguous locators
+The following elements have no unique locator in this component \u2014 multiple nodes share the best available selector. For each, narrow the locator (e.g. \`page.getByRole('button', { name: ... })\`, \`.filter({ hasText })\`, \`.nth(i)\`, or scope under a parent) so each test targets exactly one node:
+${ambiguous.map((e) => `- ${e.type} [${e.selector}]${e.label ? ` \u2014 label: "${e.label}"` : ""} (${e.ambiguityReason ?? "matches multiple elements"})`).join("\n")}` : "";
+  return `You are an expert Playwright test engineer.
+
+Generate a complete, runnable Playwright TypeScript test file for the component described below.
+
+## Component
+- Name: ${component.componentName}
+- Framework: ${component.framework}
+- File: ${component.filePath}
+- Testability score: ${score}/100
+
+## Interactive elements
+${interactiveElements.map((e) => `- ${e.type} [${e.selector}]${e.ambiguous ? " \u26A0 ambiguous" : ""} \u2014 actions: ${e.actions.join(", ")}`).join("\n")}${ambiguitySection}
+
+## Rules
+- Use \`@playwright/test\` imports only.
+- Each test must be independent (no shared state).
+- Use accessible-name selectors (getByRole, getByLabel) over CSS selectors where possible.
+- For elements flagged as ambiguous, never use the bare selector \u2014 always combine with a name, text, or scoping locator so the query resolves to exactly one node.
+- Include at least one positive and one negative test case per interactive element.
+- Output ONLY the TypeScript code, no markdown fences.`;
+}
+async function generate(analyses, options) {
+  const model = getModel(options.ai, "generation");
+  const results = [];
+  for (const analysis of analyses) {
+    const { text } = await generateText2({
+      model,
+      prompt: buildPrompt(analysis),
+      maxOutputTokens: options.maxInputTokens ?? 4096
+    });
+    results.push({
+      filePath: `${options.testsDir}/${analysis.component.componentName}.spec.ts`,
+      sourceComponent: analysis.component.filePath,
+      testCode: text,
+      generatedAt: /* @__PURE__ */ new Date()
+    });
+  }
+  return results;
+}
+var index_default = generate;
+export {
+  PROVIDERS,
+  buildDiscoveryInput,
+  buildDiscoveryPrompt,
+  index_default as default,
+  generate,
+  getModel,
+  runLlmDiscovery,
+  shouldUseLlm,
+  validateDiscoveryOutput
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@selfcure/generator",
+  "version": "0.1.0",
+  "description": "Sends component analysis to an LLM (Anthropic/OpenAI/Google/Groq/DeepSeek/Ollama) and receives Playwright test code",
+  "type": "module",
+  "license": "MIT",
+  "author": "ricardofrancocustodio",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricardofrancocustodio/selfcure.git",
+    "directory": "packages/generator"
+  },
+  "homepage": "https://github.com/ricardofrancocustodio/selfcure#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@selfcure/analyzer": "^0.1.0",
+    "ai": "^6.0.191",
+    "@ai-sdk/anthropic": "^3.0.79",
+    "@ai-sdk/openai": "^3.0.65",
+    "@ai-sdk/google": "^3.0.79",
+    "@ai-sdk/groq": "^3.0.39",
+    "@ai-sdk/openai-compatible": "^2.0.48"
+  }
+}