@qulib/core 0.8.2 → 0.10.0

package/dist/reporters/heatmap.js

@@ -0,0 +1,146 @@
+/**
+ * Per-page coverage heatmap for Markdown reports.
+ *
+ * buildPageHeatmap() is a pure function — no I/O, no side-effects.
+ * It derives a rows × dimensions matrix from GapAnalysis.gaps and sorts
+ * rows worst-first (most critical coverage problems bubble to the top).
+ *
+ * Dimensions map to the GapSchema.category enum values so the heatmap
+ * always stays in sync with what the scanner can produce.
+ */
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** The ordered set of gap categories that appear as heatmap columns. */
+export const HEATMAP_DIMENSIONS = [
+    'untested-route',
+    'a11y',
+    'console-error',
+    'broken-link',
+    'coverage',
+    'untested-api-endpoint',
+    'auth-surface',
+];
+/** Display labels for each dimension column header. */
+export const DIMENSION_LABELS = {
+    'untested-route': 'Untested',
+    'a11y': 'A11y',
+    'console-error': 'Console',
+    'broken-link': 'Links',
+    'coverage': 'Coverage',
+    'untested-api-endpoint': 'API',
+    'auth-surface': 'Auth',
+};
+/** Severity order — higher index = worse. */
+const SEVERITY_ORDER = {
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+/** Intensity glyph scale, indexed by SEVERITY_ORDER value (1..4). */
+const SEVERITY_GLYPHS = {
+    0: '·', // no gap on this page for this dimension
+    1: '🟡', // low
+    2: '🟠', // medium
+    3: '🔴', // high
+    4: '🚨', // critical
+};
+// ---------------------------------------------------------------------------
+// Pure builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a per-page coverage heatmap from a flat list of gaps.
+ *
+ * @param gaps  The gaps array from GapAnalysis.
+ * @returns     A PageHeatmap with rows sorted worst-first.
+ */
+export function buildPageHeatmap(gaps) {
+    const pageMap = new Map();
+    for (const gap of gaps) {
+        // Only include dimensions the heatmap tracks; skip unknowns gracefully.
+        const dim = gap.category;
+        if (!HEATMAP_DIMENSIONS.includes(dim))
+            continue;
+        if (!pageMap.has(gap.path)) {
+            pageMap.set(gap.path, new Map());
+        }
+        const dimMap = pageMap.get(gap.path);
+        if (!dimMap.has(dim)) {
+            dimMap.set(dim, []);
+        }
+        dimMap.get(dim).push(gap);
+    }
+    const rows = [];
+    for (const [path, dimMap] of pageMap) {
+        const cells = {};
+        let worstScore = 0;
+        for (const dim of HEATMAP_DIMENSIONS) {
+            const dimGaps = dimMap.get(dim) ?? [];
+            if (dimGaps.length === 0) {
+                cells[dim] = { worstSeverity: null, glyph: SEVERITY_GLYPHS[0], count: 0 };
+            }
+            else {
+                let worst = 'low';
+                for (const g of dimGaps) {
+                    if (SEVERITY_ORDER[g.severity] > SEVERITY_ORDER[worst]) {
+                        worst = g.severity;
+                    }
+                }
+                const score = SEVERITY_ORDER[worst];
+                worstScore += score;
+                cells[dim] = { worstSeverity: worst, glyph: SEVERITY_GLYPHS[score], count: dimGaps.length };
+            }
+        }
+        rows.push({ path, cells, worstScore });
+    }
+    // Sort worst-first (highest worstScore first), then alphabetically by path for stability.
+    rows.sort((a, b) => {
+        if (b.worstScore !== a.worstScore)
+            return b.worstScore - a.worstScore;
+        return a.path.localeCompare(b.path);
+    });
+    return {
+        rows,
+        dimensions: HEATMAP_DIMENSIONS,
+        totalGaps: gaps.length,
+    };
+}
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+/**
+ * Render a PageHeatmap as a Markdown section string.
+ * Returns an empty string when there are no rows (nothing scanned).
+ */
+export function renderHeatmapSection(heatmap) {
+    if (heatmap.rows.length === 0) {
+        return '';
+    }
+    const dimLabels = heatmap.dimensions.map((d) => DIMENSION_LABELS[d]);
+    // Build table header
+    const header = `| Page | ${dimLabels.join(' | ')} |`;
+    const separator = `|------|${heatmap.dimensions.map(() => ':---:').join('|')}|`;
+    const tableRows = heatmap.rows
+        .map((row) => {
+        const cells = heatmap.dimensions.map((d) => row.cells[d].glyph).join(' | ');
+        return `| \`${row.path}\` | ${cells} |`;
+    })
+        .join('\n');
+    const legend = [
+        '**Legend:**',
+        `🚨 critical`,
+        `🔴 high`,
+        `🟠 medium`,
+        `🟡 low`,
+        `· none`,
+    ].join(' · ');
+    return `## Per-page coverage heatmap
+
+${header}
+${separator}
+${tableRows}
+
+${legend}
+`;
+}

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

@@ -1 +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,CAkEjG"}
+{"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;AAGrE,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqEjG"}

package/dist/reporters/markdown-reporter.js

@@ -1,5 +1,6 @@
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { buildPageHeatmap, renderHeatmapSection } from './heatmap.js';
 export async function writeMarkdownReport(analysis, outputDir) {
     await mkdir(outputDir, { recursive: true });
     const rc = analysis.releaseConfidence;
@@ -16,6 +17,8 @@ export async function writeMarkdownReport(analysis, outputDir) {
     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 heatmap = buildPageHeatmap(analysis.gaps);
+    const heatmapSection = renderHeatmapSection(heatmap);
     const ci = analysis.costIntelligence;
     const costSection = ci
         ? `## Cost Intelligence
@@ -41,7 +44,7 @@ export async function writeMarkdownReport(analysis, outputDir) {
 - Scan budget exhausted (unfinished queue): ${analysis.coverageBudgetExceeded ? 'yes' : 'no'}
 ${analysis.coverageWarning ? `- Warning: **${analysis.coverageWarning}**` : '- Warning: none'}
 
-${costSection}
+${heatmapSection}${costSection}
 ## Coverage gaps (${analysis.gaps.length})
 
 | Path | Category | Severity | Reason |

package/dist/scaffold-tests.d.ts

@@ -1,13 +1,27 @@
+import { type SpecValidationReport } from './adapters/validate-specs.js';
 import type { NeutralScenario, GeneratedTest } from './schemas/gap-analysis.schema.js';
 import type { AdapterType } from './schemas/config.schema.js';
 import type { AnalyzeProgressSink } from './harness/progress-log.js';
 import type { TelemetrySink } from './telemetry/telemetry.interface.js';
+import type { RecipeId, RecipeConfig } from './schemas/recipe.schema.js';
 export interface ScaffoldOptions {
     framework?: Extract<AdapterType, 'cypress-e2e' | 'playwright'>;
     maxPagesToScan?: number;
     scenarios?: NeutralScenario[];
     progressLog?: AnalyzeProgressSink;
     telemetry?: TelemetrySink;
+    /**
+     * Optional list of recipe ids to expand into additional scenarios.
+     * Recipe scenarios are APPENDED to any scenarios derived from analysis or
+     * supplied via `scenarios` — they never replace existing content.
+     * Example: ['auth', 'a11y'] appends login-flow + a11y scenarios.
+     */
+    recipes?: RecipeId[];
+    /**
+     * Per-recipe configuration overrides (selectors, routes, impact thresholds).
+     * Only consulted when `recipes` is non-empty.
+     */
+    recipeConfig?: RecipeConfig;
 }
 export interface ProjectConfig {
     configFile: {
@@ -29,6 +43,13 @@ export interface ScaffoldResult {
     generatedTests: GeneratedTest[];
     scenarios: NeutralScenario[];
     projectConfig: ProjectConfig;
+    /**
+     * Dry-run validation of every generated spec: each spec is transpiled through
+     * the TypeScript compiler and any parse/compile error is surfaced here. This
+     * is the witness that the scaffold did not emit broken code — `ok: false`
+     * means at least one generated spec will not parse. Always populated.
+     */
+    specValidation: SpecValidationReport;
 }
 export declare function scaffoldTests(url: string, options?: ScaffoldOptions): Promise<ScaffoldResult>;
 //# sourceMappingURL=scaffold-tests.d.ts.map

package/dist/scaffold-tests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold-tests.d.ts","sourceRoot":"","sources":["../src/scaffold-tests.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,WAAW,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC1F,YAAY,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;IAC9D,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC;CAC9B;AA8ED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAyCzB"}
+{"version":3,"file":"scaffold-tests.d.ts","sourceRoot":"","sources":["../src/scaffold-tests.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEjG,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAEzE,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,WAAW,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC1F,YAAY,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,OAAO,CAAC,WAAW,EAAE,aAAa,GAAG,YAAY,CAAC,CAAC;IAC9D,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B;;;;;OAKG;IACH,cAAc,EAAE,oBAAoB,CAAC;CACtC;AA8ED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAmDzB"}

package/dist/scaffold-tests.js

@@ -1,5 +1,7 @@
 import { analyzeApp } from './analyze.js';
 import { createAdapter } from './adapters/adapter-factory.js';
+import { validateGeneratedTests } from './adapters/validate-specs.js';
+import { expandRecipes } from './recipes/index.js';
 function buildCypressProjectConfig(url) {
     return {
         configFile: {
@@ -104,10 +106,18 @@ export async function scaffoldTests(url, options = {}) {
         });
         scenarios = result.gapAnalysis.scenarios;
     }
+    // Expand any requested recipes and append their scenarios (additive — never replace).
+    const recipeScenarios = expandRecipes(options.recipes, options.recipeConfig ?? {});
+    const allScenarios = recipeScenarios.length > 0
+        ? [...scenarios, ...recipeScenarios]
+        : scenarios;
     const adapter = createAdapter(framework);
-    const generatedTests = adapter.renderAll(scenarios);
+    const generatedTests = adapter.renderAll(allScenarios);
     const projectConfig = framework === 'cypress-e2e'
         ? buildCypressProjectConfig(url)
         : buildPlaywrightProjectConfig(url);
-    return { url, framework, generatedTests, scenarios, projectConfig };
+    // Dry-run every generated spec through the TS compiler so a parse/compile
+    // failure is caught here, not when a developer first runs the suite.
+    const specValidation = validateGeneratedTests(generatedTests);
+    return { url, framework, generatedTests, scenarios: allScenarios, projectConfig, specValidation };
 }