@qulib/core 0.1.0

package/dist/index.js

@@ -0,0 +1 @@
+export { analyzeApp } from './analyze.js';

package/dist/llm/context-builder.d.ts

@@ -0,0 +1,3 @@
+import type { Gap } from '../schemas/gap-analysis.schema.js';
+export declare function buildGapPrompt(gaps: Gap[], limit: number): string;
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/llm/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../src/llm/context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,mCAAmC,CAAC;AAE7D,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAkCjE"}

package/dist/llm/context-builder.js

@@ -0,0 +1,33 @@
+export function buildGapPrompt(gaps, limit) {
+    const topGaps = [...gaps]
+        .sort((a, b) => {
+        const order = { high: 0, medium: 1, low: 2 };
+        return order[a.severity] - order[b.severity];
+    })
+        .slice(0, limit);
+    const gapList = topGaps
+        .map((g, i) => `${i + 1}. [${g.severity}] ${g.category} at ${g.path}: ${g.reason}`)
+        .join('\n');
+    return `You are a QA engineer. Given these quality gaps found in a web application, generate test scenarios.
+
+Gaps to address:
+${gapList}
+
+Return ONLY a JSON array. No markdown. No explanation. No code fences.
+
+Each item must match this exact shape:
+{
+  "id": "string (unique)",
+  "title": "string",
+  "description": "string",
+  "targetPath": "string (the route path)",
+  "steps": [
+    { "action": "navigate|click|type|assert-visible|assert-hidden|assert-text|assert-disabled|assert-count|wait|api-call", "target": "string (optional)", "value": "string (optional)", "description": "string" }
+  ],
+  "tags": ["string"],
+  "recommendations": [
+    { "adapter": "playwright|cypress-e2e|cypress-component|api|accessibility", "reason": "string", "confidence": "high|medium|low" }
+  ],
+  "sourceGapIds": ["string"]
+}`;
+}

package/dist/llm/provider.d.ts

@@ -0,0 +1,4 @@
+import { type Gap, type NeutralScenario } from '../schemas/gap-analysis.schema.js';
+export declare function callLLM(prompt: string, tokenBudget: number): Promise<string>;
+export declare function generateScenariosFromTemplate(gaps: Gap[]): NeutralScenario[];
+//# sourceMappingURL=provider.d.ts.map

package/dist/llm/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/llm/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,GAAG,EAAE,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAE1G,wBAAsB,OAAO,CAC3B,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CA0BjB;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,eAAe,EAAE,CA4B5E"}

package/dist/llm/provider.js

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+import { NeutralScenarioSchema } from '../schemas/gap-analysis.schema.js';
+export async function callLLM(prompt, tokenBudget) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        throw new Error('ANTHROPIC_API_KEY is not set');
+    const response = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify({
+            model: 'claude-sonnet-4-20250514',
+            max_tokens: tokenBudget,
+            messages: [{ role: 'user', content: prompt }],
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`LLM call failed: ${response.status} ${text}`);
+    }
+    const data = await response.json();
+    const text = data.content.find((b) => b.type === 'text')?.text ?? '';
+    return text;
+}
+export function generateScenariosFromTemplate(gaps) {
+    return gaps.map((gap) => {
+        const steps = [];
+        steps.push({ action: 'navigate', target: gap.path, description: `Navigate to ${gap.path}` });
+        if (gap.category === 'untested-route') {
+            steps.push({ action: 'assert-visible', description: 'Assert page loaded successfully' });
+        }
+        else if (gap.category === 'console-error') {
+            steps.push({ action: 'assert-hidden', description: 'Assert no console errors are present' });
+        }
+        else if (gap.category === 'a11y') {
+            steps.push({ action: 'assert-visible', description: 'Run accessibility scan on page' });
+        }
+        else if (gap.category === 'broken-link') {
+            steps.push({ action: 'assert-visible', description: 'Assert all links resolve correctly' });
+        }
+        const adapter = gap.category === 'a11y' ? 'accessibility' : 'playwright';
+        return NeutralScenarioSchema.parse({
+            id: randomUUID(),
+            title: `[${gap.severity.toUpperCase()}] ${gap.category} — ${gap.path}`,
+            description: gap.reason,
+            targetPath: gap.path,
+            steps,
+            tags: [gap.category, gap.severity],
+            recommendations: [{ adapter, reason: 'Generated from template', confidence: 'low' }],
+            sourceGapIds: [gap.id],
+        });
+    });
+}

package/dist/phases/act.d.ts

@@ -0,0 +1,5 @@
+import type { HarnessConfig } from '../schemas/config.schema.js';
+import type { GapAnalysis } from '../schemas/gap-analysis.schema.js';
+import type { RunArtifactsOptions } from '../harness/run-options.js';
+export declare function act(analysis: GapAnalysis, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<void>;
+//# sourceMappingURL=act.d.ts.map

package/dist/phases/act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/phases/act.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAIrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,wBAAsB,GAAG,CACvB,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/phases/act.js

@@ -0,0 +1,41 @@
+import { join } from 'node:path';
+import { writeJsonReport } from '../reporters/json-reporter.js';
+import { writeMarkdownReport } from '../reporters/markdown-reporter.js';
+import { logDecision } from '../harness/decision-logger.js';
+export async function act(analysis, config, artifacts = { writeArtifacts: true }) {
+    const outputDir = join(process.cwd(), 'output');
+    const logOpts = { persist: artifacts.writeArtifacts, memory: artifacts.decisionMemory };
+    const log = artifacts.writeArtifacts ? console.log : console.error;
+    if (artifacts.writeArtifacts) {
+        await writeJsonReport(analysis, outputDir);
+        await writeMarkdownReport(analysis, outputDir);
+    }
+    await logDecision({
+        timestamp: new Date().toISOString(),
+        phase: 'act',
+        decision: 'reports-written',
+        reason: artifacts.writeArtifacts
+            ? `Wrote JSON and Markdown reports to ${outputDir}`
+            : 'Skipped writing reports (ephemeral run)',
+        metadata: {
+            gapCount: analysis.gaps.length,
+            scenarioCount: analysis.scenarios.length,
+            releaseConfidence: analysis.releaseConfidence,
+            requireHumanReview: config.requireHumanReview,
+        },
+    }, logOpts);
+    log('\n[qulib] Analysis complete');
+    log(`  Gaps found:          ${analysis.gaps.length}`);
+    log(`  Scenarios generated: ${analysis.scenarios.length}`);
+    log(`  Release confidence:  ${analysis.releaseConfidence}/100`);
+    if (config.requireHumanReview) {
+        log('\n[qulib] Human review required before applying any generated output.');
+        if (artifacts.writeArtifacts) {
+            log('  Reports:   output/report.json and output/report.md');
+            log('  Decisions: .scan-state/decision-log.json');
+        }
+        else {
+            log('  Ephemeral run: inspect JSON printed to stdout (no files written).');
+        }
+    }
+}

package/dist/phases/observe.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessConfig } from '../schemas/config.schema.js';
+import { type RouteInventory } from '../schemas/route-inventory.schema.js';
+import { type RepoAnalysis } from '../schemas/repo-analysis.schema.js';
+import type { RunArtifactsOptions } from '../harness/run-options.js';
+export interface ObserveResult {
+    routes: RouteInventory;
+    repo: RepoAnalysis | null;
+}
+export declare function observe(baseUrl: string, repoPath: string | undefined, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<ObserveResult>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/phases/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/phases/observe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,sCAAsC,CAAC;AACjG,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAK3F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;CAC3B;AAED,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,aAAa,CAAC,CAoDxB"}

package/dist/phases/observe.js

@@ -0,0 +1,48 @@
+import { RouteInventorySchema } from '../schemas/route-inventory.schema.js';
+import { RepoAnalysisSchema } from '../schemas/repo-analysis.schema.js';
+import { createExplorer } from '../tools/explorer-factory.js';
+import { scanRepo } from '../tools/repo-scanner.js';
+import { StateManager } from '../harness/state-manager.js';
+import { logDecision } from '../harness/decision-logger.js';
+export async function observe(baseUrl, repoPath, config, artifacts = { writeArtifacts: true }) {
+    const explorer = createExplorer(config.explorer);
+    const stateManager = new StateManager();
+    const logOpts = { persist: artifacts.writeArtifacts, memory: artifacts.decisionMemory };
+    const rawRoutes = await explorer.explore(baseUrl, config);
+    const routes = RouteInventorySchema.parse(rawRoutes);
+    if (artifacts.writeArtifacts) {
+        await stateManager.writeState('discovered-routes.json', routes, RouteInventorySchema);
+    }
+    await logDecision({
+        timestamp: new Date().toISOString(),
+        phase: 'observe',
+        decision: 'exploration-complete',
+        reason: `Discovered ${routes.routes.length} routes; budgetExceeded=${routes.budgetExceeded}`,
+        metadata: {
+            baseUrl,
+            scannedRoutes: routes.routes.length,
+            budgetExceeded: routes.budgetExceeded,
+            pagesSkipped: routes.pagesSkipped,
+        },
+    }, logOpts);
+    let repo = null;
+    if (repoPath) {
+        const rawRepo = await scanRepo(repoPath);
+        repo = RepoAnalysisSchema.parse(rawRepo);
+        if (artifacts.writeArtifacts) {
+            await stateManager.writeState('repo-inventory.json', repo, RepoAnalysisSchema);
+        }
+        await logDecision({
+            timestamp: new Date().toISOString(),
+            phase: 'observe',
+            decision: 'repo-scan-complete',
+            reason: `Scanned repo inventory: ${repo.routes.length} routes, ${repo.testFiles.length} test files`,
+            metadata: {
+                repoPath,
+                routeCount: repo.routes.length,
+                testFileCount: repo.testFiles.length,
+            },
+        }, logOpts);
+    }
+    return { routes, repo };
+}

package/dist/phases/think.d.ts

@@ -0,0 +1,6 @@
+import type { HarnessConfig } from '../schemas/config.schema.js';
+import { type GapAnalysis } from '../schemas/gap-analysis.schema.js';
+import type { ObserveResult } from './observe.js';
+import type { RunArtifactsOptions } from '../harness/run-options.js';
+export declare function think(observed: ObserveResult, config: HarnessConfig, artifacts?: RunArtifactsOptions): Promise<GapAnalysis>;
+//# sourceMappingURL=think.d.ts.map

package/dist/phases/think.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"think.d.ts","sourceRoot":"","sources":["../../src/phases/think.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAA4C,KAAK,WAAW,EAAwB,MAAM,mCAAmC,CAAC;AACrI,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAMlD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,wBAAsB,KAAK,CACzB,QAAQ,EAAE,aAAa,EACvB,MAAM,EAAE,aAAa,EACrB,SAAS,GAAE,mBAA8C,GACxD,OAAO,CAAC,WAAW,CAAC,CA6FtB"}

package/dist/phases/think.js

@@ -0,0 +1,85 @@
+import { GapAnalysisSchema, NeutralScenarioSchema } from '../schemas/gap-analysis.schema.js';
+import { analyzeGaps } from '../tools/gap-engine.js';
+import { StateManager } from '../harness/state-manager.js';
+import { logDecision } from '../harness/decision-logger.js';
+import { callLLM, generateScenariosFromTemplate } from '../llm/provider.js';
+import { buildGapPrompt } from '../llm/context-builder.js';
+export async function think(observed, config, artifacts = { writeArtifacts: true }) {
+    const mode = observed.repo ? 'url-repo' : 'url-only';
+    const stateManager = new StateManager();
+    const logOpts = { persist: artifacts.writeArtifacts, memory: artifacts.decisionMemory };
+    const partialAnalysis = GapAnalysisSchema.parse({
+        ...analyzeGaps(observed.routes, observed.repo, mode, config),
+        scenarios: [],
+        generatedTests: [],
+    });
+    if (artifacts.writeArtifacts) {
+        await stateManager.writeState('gap-analysis.json', partialAnalysis, GapAnalysisSchema);
+    }
+    await logDecision({
+        timestamp: new Date().toISOString(),
+        phase: 'think',
+        decision: 'gap-analysis-complete',
+        reason: `Computed ${partialAnalysis.gaps.length} gaps with release confidence ${partialAnalysis.releaseConfidence}`,
+        metadata: {
+            mode,
+            gapCount: partialAnalysis.gaps.length,
+            releaseConfidence: partialAnalysis.releaseConfidence,
+        },
+    }, logOpts);
+    let scenarioSource = 'template';
+    let generatedScenarios = [];
+    if (!process.env.ANTHROPIC_API_KEY) {
+        await logDecision({
+            timestamp: new Date().toISOString(),
+            phase: 'think',
+            decision: 'llm-scenarios-skipped',
+            reason: 'Skipped LLM scenario generation because ANTHROPIC_API_KEY is not set',
+        }, logOpts);
+        generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+    }
+    else {
+        try {
+            const prompt = buildGapPrompt(partialAnalysis.gaps, config.testGenerationLimit);
+            const response = await callLLM(prompt, config.llmTokenBudget);
+            const parsed = JSON.parse(response);
+            const candidates = Array.isArray(parsed) ? parsed : [];
+            for (const item of candidates) {
+                const validated = NeutralScenarioSchema.safeParse(item);
+                if (validated.success) {
+                    generatedScenarios.push(validated.data);
+                }
+            }
+            if (generatedScenarios.length === 0) {
+                generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+                scenarioSource = 'template';
+            }
+            else {
+                scenarioSource = 'llm';
+            }
+        }
+        catch {
+            generatedScenarios = generateScenariosFromTemplate(partialAnalysis.gaps);
+            scenarioSource = 'template';
+        }
+    }
+    await logDecision({
+        timestamp: new Date().toISOString(),
+        phase: 'think',
+        decision: 'scenario-generation-complete',
+        reason: `Generated ${generatedScenarios.length} scenarios via ${scenarioSource}`,
+        metadata: {
+            source: scenarioSource,
+            scenarioCount: generatedScenarios.length,
+        },
+    }, logOpts);
+    const completeAnalysis = GapAnalysisSchema.parse({
+        ...partialAnalysis,
+        scenarios: generatedScenarios,
+        generatedTests: [],
+    });
+    if (artifacts.writeArtifacts) {
+        await stateManager.writeState('gap-analysis.json', completeAnalysis, GapAnalysisSchema);
+    }
+    return completeAnalysis;
+}

package/dist/reporters/json-reporter.d.ts

@@ -0,0 +1,3 @@
+import type { GapAnalysis } from '../schemas/gap-analysis.schema.js';
+export declare function writeJsonReport(analysis: GapAnalysis, outputDir: string): Promise<void>;
+//# sourceMappingURL=json-reporter.d.ts.map

package/dist/reporters/json-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-reporter.d.ts","sourceRoot":"","sources":["../../src/reporters/json-reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE,wBAAsB,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK7F"}

package/dist/reporters/json-reporter.js

@@ -0,0 +1,8 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function writeJsonReport(analysis, outputDir) {
+    await mkdir(outputDir, { recursive: true });
+    const filePath = join(outputDir, 'report.json');
+    await writeFile(filePath, JSON.stringify(analysis, null, 2), 'utf-8');
+    console.log(`[qulib] JSON report written to ${filePath}`);
+}

package/dist/reporters/markdown-reporter.d.ts

@@ -0,0 +1,3 @@
+import type { GapAnalysis } from '../schemas/gap-analysis.schema.js';
+export declare function writeMarkdownReport(analysis: GapAnalysis, outputDir: string): Promise<void>;
+//# sourceMappingURL=markdown-reporter.d.ts.map

package/dist/reporters/markdown-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-reporter.d.ts","sourceRoot":"","sources":["../../src/reporters/markdown-reporter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CjG"}

package/dist/reporters/markdown-reporter.js

@@ -0,0 +1,42 @@
+import { writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function writeMarkdownReport(analysis, outputDir) {
+    await mkdir(outputDir, { recursive: true });
+    const recommendation = analysis.releaseConfidence >= 80 ? 'READY' :
+        analysis.releaseConfidence >= 50 ? 'CONDITIONAL' : 'NOT READY';
+    const gapRows = analysis.gaps
+        .map((g) => `| ${g.path} | ${g.category} | ${g.severity} | ${g.reason} |`)
+        .join('\n');
+    const scenarioBlocks = analysis.scenarios
+        .map((s) => `### ${s.title}\n${s.description}\n\nSteps:\n${s.steps.map((step) => `- ${step.description}`).join('\n')}\n\nRecommended adapters: ${s.recommendations.map((r) => r.adapter).join(', ')}`)
+        .join('\n\n---\n\n');
+    const md = `# Qulib Quality Gap Report
+
+**Generated:** ${analysis.analyzedAt}
+**Mode:** ${analysis.mode}
+**Release confidence:** ${analysis.releaseConfidence}/100 — ${recommendation}
+
+## Coverage
+
+- Pages scanned: ${analysis.coveragePagesScanned}
+- Scan budget exhausted (unfinished queue): ${analysis.coverageBudgetExceeded ? 'yes' : 'no'}
+${analysis.coverageWarning ? `- Warning: **${analysis.coverageWarning}**` : '- Warning: none'}
+
+## Coverage gaps (${analysis.gaps.length})
+
+| Path | Category | Severity | Reason |
+|------|----------|----------|--------|
+${gapRows}
+
+## Generated scenarios (${analysis.scenarios.length})
+
+${scenarioBlocks || '_No scenarios generated._'}
+
+## Decision log
+
+See \`.scan-state/decision-log.json\` for the full audit trail.
+`;
+    const filePath = join(outputDir, 'report.md');
+    await writeFile(filePath, md, 'utf-8');
+    console.log(`[qulib] Markdown report written to ${filePath}`);
+}