@taodigital/agents 0.0.0-stage → 1.2.1

package/dist/crawl-diff-agent.js

@@ -0,0 +1,412 @@
+"use strict";
+/**
+ * ZeTa-AI Crawl Diff Agent
+ *
+ * Compares DOM elements and navigation flows across two crawl runs to detect
+ * structural UI changes. Drives the approval gate state machine that gates
+ * script generation until all diffs are reviewed.
+ *
+ * Public entry points:
+ *   computeCrawlDiffs           — diff elements + flows between two crawl jobs
+ *   createCrawlContextEnhancement — create ContextEnhancement record for a crawl job
+ *   approveCrawlDiff            — mark a diff approved, flag affected test cases suspect
+ *   recomputeApprovalGateSummary — recompute contextPhase based on pending diffs
+ *   computeCoverageGaps         — find UI elements not covered by any test case
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCrawlDiffs = computeCrawlDiffs;
+exports.createCrawlContextEnhancement = createCrawlContextEnhancement;
+exports.approveCrawlDiff = approveCrawlDiff;
+exports.recomputeApprovalGateSummary = recomputeApprovalGateSummary;
+exports.computeCoverageGaps = computeCoverageGaps;
+const database_1 = require("@taodigital/database");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const PHASE_ORDER = [
+    'PENDING_CONTEXT',
+    'CONTEXT_PARTIAL',
+    'CONTEXT_ENRICHED',
+    'DIFF_PENDING_APPROVAL',
+    'ALL_DIFFS_APPROVED',
+    'READY_FOR_SCRIPT_GEN',
+];
+const CONTEXT_THRESHOLDS = {
+    WEB: 80,
+    API: 40,
+    NATIVE: 60,
+    HYBRID: 70,
+};
+// Non-interactive roles to skip in coverage gap analysis
+const NON_INTERACTIVE_ROLES = new Set(['link', 'heading', 'image', 'text']);
+// ─── 1. computeCrawlDiffs ─────────────────────────────────────────────────────
+async function computeCrawlDiffs(tenantId, projectId, fromJobId, toJobId) {
+    // Load screens for each job run, keyed by url (fallback to name)
+    const [fromScreens, toScreens] = await Promise.all([
+        database_1.prismaAdmin.screen.findMany({
+            where: { tenantId, projectId, lastCrawlJobId: fromJobId },
+        }),
+        database_1.prismaAdmin.screen.findMany({
+            where: { tenantId, projectId, lastCrawlJobId: toJobId },
+        }),
+    ]);
+    const fromScreenMap = new Map(fromScreens.map((s) => [s.url ?? s.name, s]));
+    const toScreenMap = new Map(toScreens.map((s) => [s.url ?? s.name, s]));
+    // Find screens present in both runs
+    const commonKeys = [...fromScreenMap.keys()].filter((k) => toScreenMap.has(k));
+    const diffsToCreate = [];
+    // ── Element diffs for common screens ──────────────────────────────────────
+    for (const key of commonKeys) {
+        const fromScreen = fromScreenMap.get(key);
+        const toScreen = toScreenMap.get(key);
+        const [fromElements, toElements] = await Promise.all([
+            database_1.prismaAdmin.element.findMany({ where: { tenantId, screenId: fromScreen.id } }),
+            database_1.prismaAdmin.element.findMany({ where: { tenantId, screenId: toScreen.id } }),
+        ]);
+        // Key elements by role+meaning for comparison
+        const makeElementKey = (e) => `${e.role ?? ''}::${e.meaning ?? e.text ?? ''}`;
+        const fromElemMap = new Map(fromElements.map((e) => [makeElementKey(e), e]));
+        const toElemMap = new Map(toElements.map((e) => [makeElementKey(e), e]));
+        // Removed elements (in from, not in to)
+        for (const [eKey, elem] of fromElemMap) {
+            if (!toElemMap.has(eKey)) {
+                const affectedTestCaseIds = await findAffectedTestCases(tenantId, projectId, [elem.id]);
+                const severity = computeSeverity(affectedTestCaseIds.length);
+                diffsToCreate.push({
+                    tenantId,
+                    projectId,
+                    fromJobId,
+                    toJobId,
+                    diffType: 'ELEMENT_REMOVED',
+                    severity,
+                    status: severity === 'NONE' ? 'APPROVED' : 'PENDING',
+                    fromScreenId: fromScreen.id,
+                    toScreenId: toScreen.id,
+                    elementRole: elem.role,
+                    elementMeaning: elem.meaning,
+                    affectedTestCaseIds,
+                });
+            }
+        }
+        // Added elements (in to, not in from)
+        for (const [eKey, elem] of toElemMap) {
+            if (!fromElemMap.has(eKey)) {
+                const affectedTestCaseIds = await findAffectedTestCases(tenantId, projectId, [elem.id]);
+                const severity = computeSeverity(affectedTestCaseIds.length);
+                diffsToCreate.push({
+                    tenantId,
+                    projectId,
+                    fromJobId,
+                    toJobId,
+                    diffType: 'ELEMENT_ADDED',
+                    severity,
+                    status: severity === 'NONE' ? 'APPROVED' : 'PENDING',
+                    fromScreenId: fromScreen.id,
+                    toScreenId: toScreen.id,
+                    elementRole: elem.role,
+                    elementMeaning: elem.meaning,
+                    affectedTestCaseIds,
+                });
+            }
+        }
+    }
+    // ── Flow diffs (DiscoveredLink) ────────────────────────────────────────────
+    const [fromLinks, toLinks] = await Promise.all([
+        database_1.prismaAdmin.discoveredLink.findMany({ where: { tenantId, projectId, jobId: fromJobId } }),
+        database_1.prismaAdmin.discoveredLink.findMany({ where: { tenantId, projectId, jobId: toJobId } }),
+    ]);
+    const fromLinkSet = new Set(fromLinks.map((l) => l.href));
+    const toLinkSet = new Set(toLinks.map((l) => l.href));
+    // Links added in toJob (not in fromJob)
+    for (const link of toLinks) {
+        if (!fromLinkSet.has(link.href)) {
+            diffsToCreate.push({
+                tenantId,
+                projectId,
+                fromJobId,
+                toJobId,
+                diffType: 'FLOW_ADDED',
+                severity: 'MINOR',
+                status: 'PENDING',
+                fromScreenId: null,
+                toScreenId: link.toScreenId,
+                fromHref: null,
+                toHref: link.href,
+                affectedTestCaseIds: [],
+            });
+        }
+    }
+    // Links removed (in fromJob, not in toJob)
+    for (const link of fromLinks) {
+        if (!toLinkSet.has(link.href)) {
+            diffsToCreate.push({
+                tenantId,
+                projectId,
+                fromJobId,
+                toJobId,
+                diffType: 'FLOW_REMOVED',
+                severity: 'SIGNIFICANT',
+                status: 'PENDING',
+                fromScreenId: link.toScreenId,
+                toScreenId: null,
+                fromHref: link.href,
+                toHref: null,
+                affectedTestCaseIds: [],
+            });
+        }
+    }
+    // ── Batch-create all diffs ─────────────────────────────────────────────────
+    if (diffsToCreate.length > 0) {
+        await database_1.prismaAdmin.crawlDiff.createMany({
+            data: diffsToCreate.map((d) => ({
+                ...d,
+                affectedTestCaseIds: JSON.stringify(d.affectedTestCaseIds),
+                createdAt: new Date(),
+            })),
+            skipDuplicates: true,
+        });
+    }
+    const criticalCount = diffsToCreate.filter((d) => d.severity === 'CRITICAL').length;
+    const significantCount = diffsToCreate.filter((d) => d.severity === 'SIGNIFICANT').length;
+    // ── Create context enhancement record ────────────────────────────────────
+    await createCrawlContextEnhancement(tenantId, projectId, toJobId, diffsToCreate.map((d) => ({ severity: d.severity })));
+    return {
+        diffCount: diffsToCreate.length,
+        criticalCount,
+        significantCount,
+    };
+}
+// ─── 2. createCrawlContextEnhancement ────────────────────────────────────────
+async function createCrawlContextEnhancement(tenantId, projectId, toJobId, diffs) {
+    const hasPendingDiffs = diffs.filter((d) => d.severity !== 'NONE').length > 0;
+    const status = hasPendingDiffs ? 'DIFF_READY' : 'APPROVED';
+    return database_1.prismaAdmin.contextEnhancement.create({
+        data: {
+            tenantId,
+            projectId,
+            sourceType: 'CRAWL',
+            crawlJobId: toJobId,
+            status,
+            proposedChanges: [],
+            createdAt: new Date(),
+        },
+    });
+}
+// ─── 3. approveCrawlDiff ──────────────────────────────────────────────────────
+async function approveCrawlDiff(tenantId, projectId, diffId, reviewedBy) {
+    const diff = await database_1.prismaAdmin.crawlDiff.findFirstOrThrow({
+        where: { id: diffId, tenantId },
+    });
+    await database_1.prismaAdmin.$transaction([
+        database_1.prismaAdmin.crawlDiff.update({
+            where: { id: diffId },
+            data: {
+                status: 'APPROVED',
+                reviewedBy,
+                reviewedAt: new Date(),
+            },
+        }),
+    ]);
+    // Flag affected test cases as suspect
+    const affectedTestCaseIds = (() => {
+        try {
+            const raw = diff.affectedTestCaseIds;
+            if (Array.isArray(raw))
+                return raw;
+            if (typeof raw === 'string')
+                return JSON.parse(raw);
+            return [];
+        }
+        catch {
+            return [];
+        }
+    })();
+    if (affectedTestCaseIds.length > 0) {
+        await database_1.prismaAdmin.testCase.updateMany({
+            where: { id: { in: affectedTestCaseIds }, tenantId },
+            data: { suspect: true },
+        });
+    }
+    await recomputeApprovalGateSummary(tenantId, projectId);
+}
+// ─── 4. recomputeApprovalGateSummary ─────────────────────────────────────────
+async function recomputeApprovalGateSummary(tenantId, projectId) {
+    const [screenshotPending, figmaPending, crawlPending, apiSpecPending] = await Promise.all([
+        database_1.prismaAdmin.contextEnhancement.count({
+            where: { tenantId, projectId, sourceType: 'SCREENSHOT', status: { in: ['DIFF_READY', 'PENDING'] } },
+        }),
+        database_1.prismaAdmin.contextEnhancement.count({
+            where: { tenantId, projectId, sourceType: 'FIGMA', status: { in: ['DIFF_READY', 'PENDING'] } },
+        }),
+        database_1.prismaAdmin.crawlDiff.count({
+            where: { tenantId, projectId, status: 'PENDING' },
+        }),
+        database_1.prismaAdmin.contextEnhancement.count({
+            where: { tenantId, projectId, sourceType: 'API_SPEC', status: { in: ['DIFF_READY', 'PENDING'] } },
+        }),
+    ]);
+    const project = await database_1.prismaAdmin.project.findFirstOrThrow({
+        where: { id: projectId, tenantId },
+        select: {
+            projectKind: true,
+            contextScore: true,
+            contextPhase: true,
+            contextSourceRequirements: true,
+        },
+    });
+    const req = project.contextSourceRequirements ?? {};
+    const summary = {
+        screenshotsDone: screenshotPending === 0,
+        figmaDone: figmaPending === 0,
+        crawlDone: crawlPending === 0,
+        apiSpecDone: apiSpecPending === 0,
+        pendingCounts: {
+            screenshot: screenshotPending,
+            figma: figmaPending,
+            crawl: crawlPending,
+            apiSpec: apiSpecPending,
+        },
+    };
+    const allRequiredDone = Object.entries(req).every(([src, level]) => {
+        if (level !== 'REQUIRED')
+            return true;
+        const key = src === 'apiSpec' ? 'apiSpecDone' : src + 'Done';
+        return summary[key] === true;
+    });
+    const projectKind = project.projectKind ?? 'WEB';
+    const contextScore = project.contextScore ?? 0;
+    const currentPhase = project.contextPhase ?? 'PENDING_CONTEXT';
+    const threshold = CONTEXT_THRESHOLDS[projectKind] ?? 80;
+    const totalPending = screenshotPending + figmaPending + crawlPending + apiSpecPending;
+    const currentIdx = PHASE_ORDER.indexOf(currentPhase);
+    let newPhase = currentPhase;
+    if (currentPhase === 'CONTEXT_ENRICHED' &&
+        totalPending > 0) {
+        newPhase = 'DIFF_PENDING_APPROVAL';
+    }
+    else if (currentIdx <= PHASE_ORDER.indexOf('ALL_DIFFS_APPROVED') &&
+        allRequiredDone &&
+        totalPending === 0) {
+        newPhase = 'ALL_DIFFS_APPROVED';
+    }
+    if (newPhase === 'ALL_DIFFS_APPROVED' && contextScore >= threshold) {
+        newPhase = 'READY_FOR_SCRIPT_GEN';
+    }
+    // Never regress to an earlier phase
+    const newIdx = PHASE_ORDER.indexOf(newPhase);
+    const finalPhase = newIdx > currentIdx ? newPhase : currentPhase;
+    await database_1.prismaAdmin.project.update({
+        where: { id: projectId },
+        data: {
+            approvalGateSummary: summary,
+            contextPhase: finalPhase,
+        },
+    });
+    return { ...summary, allRequiredDone, contextPhase: finalPhase };
+}
+// ─── 5. computeCoverageGaps ───────────────────────────────────────────────────
+async function computeCoverageGaps(tenantId, projectId) {
+    const [elements, testCases] = await Promise.all([
+        database_1.prismaAdmin.element.findMany({
+            where: { tenantId, projectId },
+            take: 500,
+        }),
+        database_1.prismaAdmin.testCase.findMany({
+            where: { tenantId, projectId },
+            select: { id: true, groundedOn: true, steps: true },
+        }),
+    ]);
+    // Build set of element IDs referenced by any test case
+    const coveredElementIds = new Set();
+    for (const tc of testCases) {
+        const groundedOn = (() => {
+            try {
+                const raw = tc.groundedOn;
+                if (Array.isArray(raw))
+                    return raw;
+                if (typeof raw === 'string')
+                    return JSON.parse(raw);
+                return [];
+            }
+            catch {
+                return [];
+            }
+        })();
+        for (const id of groundedOn)
+            coveredElementIds.add(id);
+    }
+    // Find interactive elements not covered by any test case
+    const uncoveredElements = elements.filter((e) => !coveredElementIds.has(e.id) &&
+        e.role != null &&
+        !NON_INTERACTIVE_ROLES.has(e.role.toLowerCase()));
+    // Upsert BugSignal for each uncovered element
+    for (const element of uncoveredElements) {
+        await database_1.prismaAdmin.bugSignal.upsert({
+            where: {
+                tenantId_elementId_signalType: {
+                    tenantId,
+                    elementId: element.id,
+                    signalType: 'ELEMENT_NOT_IN_TESTS',
+                },
+            },
+            update: {
+                updatedAt: new Date(),
+            },
+            create: {
+                tenantId,
+                projectId,
+                elementId: element.id,
+                signalType: 'ELEMENT_NOT_IN_TESTS',
+                severity: 'LOW',
+                title: `UI element not covered: ${element.role ?? 'unknown'}/${element.meaning ?? element.text ?? element.id}`,
+                status: 'OPEN',
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            },
+        });
+    }
+    return { gapsFound: uncoveredElements.length };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Find test case IDs whose groundedOn array contains any of the given element IDs.
+ */
+async function findAffectedTestCases(tenantId, projectId, elementIds) {
+    if (elementIds.length === 0)
+        return [];
+    const testCases = await database_1.prismaAdmin.testCase.findMany({
+        where: { tenantId, projectId },
+        select: { id: true, groundedOn: true },
+    });
+    const affected = [];
+    for (const tc of testCases) {
+        const groundedOn = (() => {
+            try {
+                const raw = tc.groundedOn;
+                if (Array.isArray(raw))
+                    return raw;
+                if (typeof raw === 'string')
+                    return JSON.parse(raw);
+                return [];
+            }
+            catch {
+                return [];
+            }
+        })();
+        if (elementIds.some((id) => groundedOn.includes(id))) {
+            affected.push(tc.id);
+        }
+    }
+    return affected;
+}
+/**
+ * Compute diff severity based on how many test cases are affected.
+ *   > 5  → CRITICAL
+ *   1-5  → SIGNIFICANT
+ *   0    → MINOR (auto-approve as NONE would hide it; keep MINOR for awareness)
+ */
+function computeSeverity(affectedCount) {
+    if (affectedCount > 5)
+        return 'CRITICAL';
+    if (affectedCount >= 1)
+        return 'SIGNIFICANT';
+    return 'NONE';
+}

package/dist/data-agent.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ZeTa-AI Test Data Generation Agent
+ *
+ * Field-schema grounded: loads typed AppField catalog before generating.
+ * If all grounded elements are non-data-bearing (buttons/links/toggles)
+ * → returns interaction variations, NOT fabricated field:value datasets.
+ *
+ * Four generation modes:
+ *   FORM   — ≥1 data-bearing field → typed, constraint-aware parameterized datasets
+ *   STATE  — all non-data-bearing → precondition-state datasets
+ *   VOLUME — PERFORMANCE / LOAD kinds → data-setup specs (row counts, concurrency, seed)
+ *   SKIP   — kinds not suited to any parameterized data (EXPLORATORY, MUTATION, AB_TEST, etc.)
+ */
+import type { LLMConfig } from './llm.js';
+export declare function scheduleSkillFileRefresh(tenantId: string, projectId: string, delayMs?: number): void;
+export declare function generateTestData(opts: {
+    tenantId: string;
+    projectId: string;
+    testCaseId: string;
+    jobId?: string;
+    targetCount?: number;
+}): Promise<{
+    dataSets: never[];
+    saved: never[];
+    skipped: boolean;
+    reason: string;
+    mode?: undefined;
+    source?: undefined;
+} | {
+    dataSets: {
+        label: string;
+        category: string;
+        values: Record<string, string>;
+        expectedOutcome: string;
+    }[];
+    saved: {
+        tenantId: string;
+        id: string;
+        projectId: string;
+        source: string;
+        kind: string;
+        testCaseId: string;
+        payload: import("@prisma/client/runtime/library").JsonValue;
+        supersededAt: Date | null;
+    }[];
+    mode: string;
+    source: string;
+    skipped?: undefined;
+    reason?: undefined;
+}>;
+/**
+ * Generates test data for up to 5 test cases in a single LLM call.
+ *
+ * Caller is responsible for chunking: pass batches of up to 5 cases.
+ * Returns a Map keyed by the original case id, value is the dataSets array
+ * using the same per-dataset shape as generateTestData().
+ *
+ * Cases that the LLM omits from its response are absent from the returned Map
+ * (caller should fall back to generateTestData() for those).
+ */
+export declare function generateTestDataBatch(cases: Array<{
+    id: string;
+    title: string;
+    steps: string[];
+    expectedResult: string;
+    preconditions?: string;
+    testDataInline?: object;
+}>, options?: {
+    llmCfg?: LLMConfig;
+    skillFile?: string;
+    tenantId?: string;
+    projectId?: string;
+}): Promise<Map<string, unknown>>;
+/**
+ * Shape used by parseCsvToDatasets / mergeExternalDatasets.
+ * Matches the inline dataset shape used throughout this module.
+ */
+type CsvDataSet = {
+    label: string;
+    category: string;
+    values: Record<string, string>;
+    expectedOutcome: string;
+};
+/**
+ * Parse a CSV string (with header row) into VALID/INVALID/EDGE test datasets.
+ * Column names map to dataset field names.
+ * Rows are assigned categories based on a 'category' column (if present) or
+ * positionally: first 40% VALID, next 40% INVALID, last 20% EDGE.
+ *
+ * @param csvContent - Raw CSV string content
+ * @param fieldMap - Optional alias map: { csvColumnName: normalizedFieldName }
+ * @returns Array of dataset objects ready for use in test data generation
+ */
+export declare function parseCsvToDatasets(csvContent: string, fieldMap?: Record<string, string>): CsvDataSet[];
+/**
+ * Merge externally-provided datasets (from CSV upload) with LLM-generated datasets.
+ * External datasets take priority for matching categories.
+ * Deduplicates by category label.
+ */
+export declare function mergeExternalDatasets(generated: CsvDataSet[], external: CsvDataSet[]): CsvDataSet[];
+export {};