@taodigital/app-brain 0.0.0-stage → 1.2.0

package/dist/traceability.d.ts

@@ -0,0 +1,213 @@
+export declare function isRealReqId(v: unknown): v is string;
+/** Primary traceTo followed by additional links, de-duplicated, placeholders removed. */
+export declare function linkedReqIds(tc: {
+    traceTo?: string | null;
+    traceToExtra?: unknown;
+}): string[];
+export declare function caseTracesTo(tc: {
+    traceTo?: string | null;
+    traceToExtra?: unknown;
+}, reqId: string): boolean;
+/**
+ * Deterministic AC → test-case match: a case addresses an AC when it shares ≥ 40% of the AC's
+ * content tokens (and ≥ 2 tokens, or ≥ 1 when the AC itself has ≤ 2 tokens).
+ */
+export declare function matchAcceptanceCriterion(ac: string, cases: Array<{
+    id: string;
+    ref?: string | null;
+    title?: string;
+    steps?: unknown;
+    expectedResult?: string | null;
+    preconditions?: string | null;
+}>): {
+    covered: boolean;
+    confidence: number;
+    caseRefs: string[];
+};
+export interface TraceScriptInfo {
+    language: string;
+    /** null when the script body is not available (e.g. stored in object storage). */
+    annotated: boolean | null;
+    aiScore: number | null;
+    aligned: boolean | null;
+    stepCoveragePct: number | null;
+    verifiedAt: string | null;
+}
+export interface TraceCaseInput {
+    id: string;
+    ref: string | null;
+    title: string;
+    kind: string;
+    status: string;
+    suiteId: string;
+    steps: unknown;
+    expectedResult: string | null;
+    preconditions: string | null;
+    traceTo: string | null;
+    traceToExtra: unknown;
+    scenarioId: string | null;
+    suspect: boolean;
+    suspectReason: string | null;
+    scripts: TraceScriptInfo[];
+}
+export interface TraceRequirementInput {
+    id: string;
+    reqId: string;
+    title: string;
+    priority: string;
+    status: string;
+    source: string;
+    acceptanceCriteria: unknown;
+    externalMeta: any;
+    updatedAt?: Date | string | null;
+}
+export interface TraceScenarioInput {
+    id: string;
+    requirementId: string;
+    title: string;
+    status: string;
+}
+export interface TraceabilityMatrix {
+    generatedAt: string;
+    summary: {
+        requirements: number;
+        requirementsCovered: number;
+        requirementsPartial: number;
+        requirementsUntested: number;
+        requirementsWithScripts: number;
+        acTotal: number;
+        acCovered: number;
+        acCoveragePct: number | null;
+        testCases: number;
+        testCasesLinked: number;
+        orphanTestCases: number;
+        brokenLinks: number;
+        suspectTestCases: number;
+        scripts: number;
+        scriptsMissingAnnotation: number;
+        scriptsAligned: number;
+    };
+    requirements: Array<{
+        reqId: string;
+        title: string;
+        priority: string;
+        status: string;
+        source: string;
+        jira: {
+            url?: string;
+            status?: string;
+            epic?: string;
+            labels: string[];
+            links: string[];
+        } | null;
+        coverageState: 'covered' | 'partial' | 'untested';
+        acCoveragePct: number | null;
+        hasSuspect: boolean;
+        acceptanceCriteria: Array<{
+            index: number;
+            text: string;
+            covered: boolean;
+            confidence: number;
+            testCases: string[];
+        }>;
+        scenarios: Array<{
+            id: string;
+            title: string;
+            status: string;
+        }>;
+        testCases: Array<{
+            id: string;
+            ref: string | null;
+            title: string;
+            kind: string;
+            status: string;
+            linkType: 'primary' | 'additional';
+            scenarioId: string | null;
+            suspect: boolean;
+            suspectReason: string | null;
+            scripts: TraceScriptInfo[];
+        }>;
+    }>;
+    orphans: Array<{
+        id: string;
+        ref: string | null;
+        title: string;
+        traceTo: string | null;
+        reason: 'no-link' | 'placeholder';
+    }>;
+    brokenLinks: Array<{
+        id: string;
+        ref: string | null;
+        title: string;
+        reqId: string;
+    }>;
+}
+export declare const EXPORT_GATE_MIN = 60;
+export declare function buildTraceabilityMatrix(input: {
+    requirements: TraceRequirementInput[];
+    testCases: TraceCaseInput[];
+    scenarios: TraceScenarioInput[];
+}): TraceabilityMatrix;
+export interface AlignmentRowInput {
+    testCaseId: string;
+    ref: string | null;
+    title: string;
+    traceTo: string | null;
+    language: string;
+    score: number;
+    aligned: boolean;
+    issues: unknown;
+    stepCoveragePct: number | null;
+    stepCoverage: any;
+    verifiedAt: Date | string | null;
+}
+export interface AlignmentReport {
+    generatedAt: string;
+    methodology: {
+        aiScore: string;
+        stepCoverage: string;
+        alignedThreshold: number;
+        exportGate: number;
+    };
+    summary: {
+        scripts: number;
+        avgAiScore: number | null;
+        avgStepCoveragePct: number | null;
+        alignedCount: number;
+        passRatePct: number | null;
+        belowExportGate: number;
+        distribution: Record<'0-39' | '40-59' | '60-74' | '75-89' | '90-100', number>;
+    };
+    rows: Array<{
+        testCaseId: string;
+        ref: string | null;
+        title: string;
+        traceTo: string | null;
+        language: string;
+        aiScore: number;
+        aligned: boolean;
+        stepCoveragePct: number | null;
+        totalSteps: number | null;
+        coveredSteps: number | null;
+        assertionCoveragePct: number | null;
+        uncoveredSteps: Array<{
+            index: number;
+            step: string;
+        }>;
+        perStep: Array<{
+            index: number;
+            step: string;
+            covered: boolean;
+            confidence: number;
+            matchedLine?: number;
+            matchedStatement?: string;
+        }>;
+        issues: string[];
+        verifiedAt: string | null;
+    }>;
+}
+export declare function buildAlignmentReport(rows: AlignmentRowInput[]): AlignmentReport;
+export declare function traceabilityToCsv(m: TraceabilityMatrix): string;
+export declare function alignmentReportToCsv(rep: AlignmentReport): string;
+export declare function loadTraceabilityMatrix(tenantId: string, projectId: string): Promise<TraceabilityMatrix>;
+export declare function loadAlignmentReport(tenantId: string, projectId: string): Promise<AlignmentReport>;

package/dist/traceability.js

@@ -0,0 +1,339 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORT_GATE_MIN = void 0;
+exports.isRealReqId = isRealReqId;
+exports.linkedReqIds = linkedReqIds;
+exports.caseTracesTo = caseTracesTo;
+exports.matchAcceptanceCriterion = matchAcceptanceCriterion;
+exports.buildTraceabilityMatrix = buildTraceabilityMatrix;
+exports.buildAlignmentReport = buildAlignmentReport;
+exports.traceabilityToCsv = traceabilityToCsv;
+exports.alignmentReportToCsv = alignmentReportToCsv;
+exports.loadTraceabilityMatrix = loadTraceabilityMatrix;
+exports.loadAlignmentReport = loadAlignmentReport;
+/**
+ * Traceability matrix + alignment report.
+ *
+ * Chain:  Jira story / requirement  →  acceptance criteria  →  test cases (primary + additional links)
+ *         →  scripts (annotation present?)  →  alignment (AI score + deterministic step coverage).
+ *
+ * Builders are pure (testable); loaders fetch tenant-scoped rows and call them.
+ */
+const database_1 = require("@taodigital/database");
+// ─── Link helpers ────────────────────────────────────────────────────────────
+const UNLINKED = new Set(['', 'REQ-UNKNOWN', 'UNKNOWN', 'N/A']);
+function isRealReqId(v) {
+    return typeof v === 'string' && !UNLINKED.has(v.trim().toUpperCase());
+}
+/** Primary traceTo followed by additional links, de-duplicated, placeholders removed. */
+function linkedReqIds(tc) {
+    const extra = Array.isArray(tc.traceToExtra) ? tc.traceToExtra : [];
+    const all = [tc.traceTo, ...extra].filter(isRealReqId).map((s) => s.trim());
+    return [...new Set(all)];
+}
+function caseTracesTo(tc, reqId) {
+    return linkedReqIds(tc).includes(reqId);
+}
+// ─── Acceptance-criterion matching ───────────────────────────────────────────
+const AC_STOP = new Set([
+    'the', 'a', 'an', 'to', 'of', 'on', 'in', 'into', 'and', 'or', 'with', 'for', 'from', 'then', 'that', 'is', 'are', 'be',
+    'should', 'will', 'shall', 'can', 'it', 'its', 'this', 'these', 'those', 'at', 'by', 'as', 'user', 'given', 'when', 'but',
+    'so', 'now', 'has', 'have', 'had', 'does', 'not', 'all', 'any', 'able', 'must', 'page', 'screen', 'system', 'application',
+]);
+function acTokenize(text) {
+    const out = new Set();
+    for (const raw of text.toLowerCase().replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^a-z0-9]+/)) {
+        let w = raw;
+        if (w.length < 3 || AC_STOP.has(w))
+            continue;
+        if (w.length > 5 && w.endsWith('ing'))
+            w = w.slice(0, -3);
+        else if (w.length > 4 && w.endsWith('ed'))
+            w = w.slice(0, -2);
+        else if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss'))
+            w = w.slice(0, -1);
+        if (!AC_STOP.has(w))
+            out.add(w);
+    }
+    return out;
+}
+function stepText(s) {
+    if (typeof s === 'string')
+        return s;
+    if (s && typeof s === 'object') {
+        const o = s;
+        return [o.action, o.data, o.expected, o.text].filter((v) => v != null && typeof v !== 'object').join(' ');
+    }
+    return '';
+}
+function caseCorpus(tc) {
+    const steps = Array.isArray(tc.steps) ? tc.steps.map(stepText) : [];
+    return [tc.title, tc.preconditions, tc.expectedResult, ...steps].filter(Boolean).join(' ');
+}
+/**
+ * Deterministic AC → test-case match: a case addresses an AC when it shares ≥ 40% of the AC's
+ * content tokens (and ≥ 2 tokens, or ≥ 1 when the AC itself has ≤ 2 tokens).
+ */
+function matchAcceptanceCriterion(ac, cases) {
+    const tokens = acTokenize(ac);
+    if (tokens.size === 0)
+        return { covered: false, confidence: 0, caseRefs: [] };
+    const needed = tokens.size <= 2 ? 1 : 2;
+    const hits = [];
+    for (const tc of cases) {
+        const corpus = acTokenize(caseCorpus(tc));
+        let n = 0;
+        for (const t of tokens)
+            if (corpus.has(t))
+                n++;
+        const ratio = n / tokens.size;
+        if (n >= needed && ratio >= 0.4)
+            hits.push({ ref: tc.ref ?? tc.id, ratio });
+    }
+    hits.sort((a, b) => b.ratio - a.ratio);
+    return {
+        covered: hits.length > 0,
+        confidence: hits.length ? Math.round(hits[0].ratio * 100) / 100 : 0,
+        caseRefs: hits.map((h) => h.ref),
+    };
+}
+const ALIGN_THRESHOLD = 75;
+exports.EXPORT_GATE_MIN = 60;
+function acList(raw) {
+    return Array.isArray(raw) ? raw.map((v) => String(v)).filter((s) => s.trim()) : [];
+}
+function jiraInfo(meta, source) {
+    if (!meta || typeof meta !== 'object')
+        return source === 'JIRA_IMPORT' ? { labels: [], links: [] } : null;
+    return {
+        url: meta.url ?? undefined,
+        status: meta.status ?? undefined,
+        epic: meta.epic?.key ? `${meta.epic.key}${meta.epic.summary ? ` — ${meta.epic.summary}` : ''}` : (typeof meta.epic === 'string' ? meta.epic : undefined),
+        labels: Array.isArray(meta.labels) ? meta.labels.map(String) : [],
+        links: Array.isArray(meta.links) ? meta.links.map((l) => `${l.type ?? 'relates'}: ${l.key ?? l}`) : [],
+    };
+}
+// ─── Matrix builder ──────────────────────────────────────────────────────────
+function buildTraceabilityMatrix(input) {
+    const active = input.testCases.filter((t) => t.status !== 'RETIRED');
+    const reqIds = new Set(input.requirements.map((r) => r.reqId));
+    const reqDbIdToReqId = new Map(input.requirements.map((r) => [r.id, r.reqId]));
+    const rows = input.requirements.map((r) => {
+        const linked = active.filter((t) => caseTracesTo(t, r.reqId));
+        const acs = acList(r.acceptanceCriteria).map((text, i) => {
+            const m = matchAcceptanceCriterion(text, linked);
+            return { index: i + 1, text, covered: m.covered, confidence: m.confidence, testCases: m.caseRefs };
+        });
+        const acCovered = acs.filter((a) => a.covered).length;
+        const acCoveragePct = acs.length ? Math.round((acCovered / acs.length) * 1000) / 10 : null;
+        const coverageState = linked.length === 0 ? 'untested' : acs.length === 0 || acCovered === acs.length ? 'covered' : 'partial';
+        return {
+            reqId: r.reqId,
+            title: r.title,
+            priority: r.priority,
+            status: r.status,
+            source: r.source,
+            jira: jiraInfo(r.externalMeta, r.source),
+            coverageState,
+            acCoveragePct,
+            hasSuspect: linked.some((t) => t.suspect),
+            acceptanceCriteria: acs,
+            scenarios: input.scenarios
+                .filter((s) => reqDbIdToReqId.get(s.requirementId) === r.reqId)
+                .map((s) => ({ id: s.id, title: s.title, status: s.status })),
+            testCases: linked.map((t) => ({
+                id: t.id, ref: t.ref, title: t.title, kind: t.kind, status: t.status,
+                linkType: (t.traceTo === r.reqId ? 'primary' : 'additional'),
+                scenarioId: t.scenarioId, suspect: t.suspect, suspectReason: t.suspectReason, scripts: t.scripts,
+            })),
+        };
+    });
+    const orphans = [];
+    const brokenLinks = [];
+    for (const t of active) {
+        const ids = linkedReqIds(t);
+        if (ids.length === 0) {
+            orphans.push({ id: t.id, ref: t.ref, title: t.title, traceTo: t.traceTo, reason: t.traceTo ? 'placeholder' : 'no-link' });
+            continue;
+        }
+        for (const id of ids)
+            if (!reqIds.has(id))
+                brokenLinks.push({ id: t.id, ref: t.ref, title: t.title, reqId: id });
+    }
+    const allAc = rows.flatMap((r) => r.acceptanceCriteria);
+    const acCovered = allAc.filter((a) => a.covered).length;
+    const scriptsAll = active.flatMap((t) => t.scripts);
+    const linkedCases = active.filter((t) => linkedReqIds(t).some((id) => reqIds.has(id)));
+    return {
+        generatedAt: new Date().toISOString(),
+        summary: {
+            requirements: rows.length,
+            requirementsCovered: rows.filter((r) => r.coverageState === 'covered').length,
+            requirementsPartial: rows.filter((r) => r.coverageState === 'partial').length,
+            requirementsUntested: rows.filter((r) => r.coverageState === 'untested').length,
+            requirementsWithScripts: rows.filter((r) => r.testCases.some((t) => t.scripts.length > 0)).length,
+            acTotal: allAc.length,
+            acCovered,
+            acCoveragePct: allAc.length ? Math.round((acCovered / allAc.length) * 1000) / 10 : null,
+            testCases: active.length,
+            testCasesLinked: linkedCases.length,
+            orphanTestCases: orphans.length,
+            brokenLinks: brokenLinks.length,
+            suspectTestCases: active.filter((t) => t.suspect).length,
+            scripts: scriptsAll.length,
+            scriptsMissingAnnotation: scriptsAll.filter((s) => s.annotated === false).length,
+            scriptsAligned: scriptsAll.filter((s) => (s.aiScore ?? -1) >= ALIGN_THRESHOLD).length,
+        },
+        requirements: rows,
+        orphans,
+        brokenLinks,
+    };
+}
+function avg(nums) {
+    return nums.length ? Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 10) / 10 : null;
+}
+function buildAlignmentReport(rows) {
+    const outRows = rows.map((r) => {
+        const sc = r.stepCoverage && typeof r.stepCoverage === 'object' ? r.stepCoverage : null;
+        const perStep = Array.isArray(sc?.perStep) ? sc.perStep : [];
+        return {
+            testCaseId: r.testCaseId, ref: r.ref, title: r.title, traceTo: r.traceTo, language: r.language,
+            aiScore: r.score, aligned: r.score >= ALIGN_THRESHOLD, stepCoveragePct: r.stepCoveragePct,
+            totalSteps: sc?.totalSteps ?? null, coveredSteps: sc?.coveredSteps ?? null,
+            assertionCoveragePct: sc?.assertionCoverage?.pct ?? null,
+            uncoveredSteps: perStep.filter((p) => !p.covered).map((p) => ({ index: p.index, step: p.step })),
+            perStep,
+            issues: Array.isArray(r.issues) ? r.issues.map(String) : [],
+            verifiedAt: r.verifiedAt ? new Date(r.verifiedAt).toISOString() : null,
+        };
+    }).sort((a, b) => a.aiScore - b.aiScore);
+    const dist = { '0-39': 0, '40-59': 0, '60-74': 0, '75-89': 0, '90-100': 0 };
+    for (const r of outRows) {
+        const s = r.aiScore;
+        dist[s < 40 ? '0-39' : s < 60 ? '40-59' : s < 75 ? '60-74' : s < 90 ? '75-89' : '90-100']++;
+    }
+    const aligned = outRows.filter((r) => r.aligned).length;
+    return {
+        generatedAt: new Date().toISOString(),
+        methodology: {
+            aiScore: 'LLM auditor rubric per script: step coverage 40, assertion correctness 30, locator quality 20, no violations 10, minus penalties for anti-patterns. 0–100.',
+            stepCoverage: 'Deterministic: test-case steps with a matching script statement ÷ total steps (token-overlap-v1). Same input always gives the same result.',
+            alignedThreshold: ALIGN_THRESHOLD,
+            exportGate: exports.EXPORT_GATE_MIN,
+        },
+        summary: {
+            scripts: outRows.length,
+            avgAiScore: avg(outRows.map((r) => r.aiScore)),
+            avgStepCoveragePct: avg(outRows.map((r) => r.stepCoveragePct).filter((v) => typeof v === 'number')),
+            alignedCount: aligned,
+            passRatePct: outRows.length ? Math.round((aligned / outRows.length) * 1000) / 10 : null,
+            belowExportGate: outRows.filter((r) => r.aiScore < exports.EXPORT_GATE_MIN).length,
+            distribution: dist,
+        },
+        rows: outRows,
+    };
+}
+// ─── CSV ─────────────────────────────────────────────────────────────────────
+function csvCell(v) {
+    const s = v == null ? '' : String(v);
+    return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+function traceabilityToCsv(m) {
+    const header = ['Requirement', 'Requirement Title', 'Priority', 'Source', 'Jira Status', 'Coverage', 'AC #', 'Acceptance Criterion', 'AC Covered', 'AC Test Cases',
+        'Test Case', 'Test Case Title', 'Link', 'TC Status', 'Suspect', 'Script Language', 'Script Annotated', 'AI Score', 'Step Coverage %'];
+    const lines = [header.join(',')];
+    for (const r of m.requirements) {
+        const base = [r.reqId, r.title, r.priority, r.source, r.jira?.status ?? '', r.coverageState];
+        const acs = r.acceptanceCriteria.length ? r.acceptanceCriteria : [null];
+        const tcs = r.testCases.length ? r.testCases : [null];
+        const n = Math.max(acs.length, tcs.length);
+        for (let i = 0; i < n; i++) {
+            const ac = acs[i] ?? null;
+            const tc = tcs[i] ?? null;
+            const sc = tc?.scripts[0];
+            lines.push([
+                ...base,
+                ac?.index ?? '', ac?.text ?? '', ac ? (ac.covered ? 'yes' : 'NO') : '', ac?.testCases.join('; ') ?? '',
+                tc?.ref ?? tc?.id ?? '', tc?.title ?? '', tc?.linkType ?? '', tc?.status ?? '', tc ? (tc.suspect ? 'YES' : 'no') : '',
+                sc?.language ?? '', sc ? (sc.annotated === null ? 'n/a' : sc.annotated ? 'yes' : 'NO') : '', sc?.aiScore ?? '', sc?.stepCoveragePct ?? '',
+            ].map(csvCell).join(','));
+        }
+    }
+    for (const o of m.orphans)
+        lines.push(['(orphan)', '', '', '', '', 'unlinked', '', '', '', '', o.ref ?? o.id, o.title, o.reason, '', '', '', '', '', ''].map(csvCell).join(','));
+    return lines.join('\n');
+}
+function alignmentReportToCsv(rep) {
+    const header = ['Test Case', 'Title', 'Requirement', 'Language', 'AI Score', 'Aligned (>=75)', 'Step Coverage %', 'Steps Covered', 'Total Steps', 'Assertion Coverage %', 'Uncovered Steps', 'Issues', 'Verified At'];
+    const lines = [header.join(',')];
+    for (const r of rep.rows) {
+        lines.push([
+            r.ref ?? r.testCaseId, r.title, r.traceTo ?? '', r.language, r.aiScore, r.aligned ? 'yes' : 'no', r.stepCoveragePct ?? '',
+            r.coveredSteps ?? '', r.totalSteps ?? '', r.assertionCoveragePct ?? '',
+            r.uncoveredSteps.map((u) => `#${u.index} ${u.step}`).join(' | '), r.issues.join(' | '), r.verifiedAt ?? '',
+        ].map(csvCell).join(','));
+    }
+    return lines.join('\n');
+}
+// ─── Loaders ─────────────────────────────────────────────────────────────────
+async function loadTraceabilityMatrix(tenantId, projectId) {
+    const data = await (0, database_1.withTenant)(tenantId, async (tx) => {
+        const [requirements, testCases, scenarios, scripts, alignments] = await Promise.all([
+            tx.requirement.findMany({ where: { tenantId, projectId }, orderBy: { reqId: 'asc' } }),
+            tx.testCase.findMany({
+                where: { tenantId, projectId },
+                select: { id: true, ref: true, title: true, kind: true, status: true, suiteId: true, steps: true, expectedResult: true, preconditions: true, traceTo: true, traceToExtra: true, scenarioId: true, suspect: true, suspectReason: true },
+            }),
+            tx.scenario.findMany({ where: { tenantId, projectId }, select: { id: true, requirementId: true, title: true, status: true } }),
+            tx.testScript.findMany({ where: { tenantId, projectId }, select: { testCaseId: true, language: true, code: true, codeKey: true } }),
+            tx.alignmentResult.findMany({ where: { tenantId, projectId }, select: { testCaseId: true, language: true, score: true, aligned: true, stepCoveragePct: true, verifiedAt: true } }),
+        ]);
+        return { requirements, testCases, scenarios, scripts, alignments };
+    });
+    const alignKey = (id, lang) => `${id}::${lang}`;
+    const alignMap = new Map(data.alignments.map((a) => [alignKey(a.testCaseId, a.language), a]));
+    const scriptsByCase = new Map();
+    for (const s of data.scripts) {
+        if (!scriptsByCase.has(s.testCaseId))
+            scriptsByCase.set(s.testCaseId, []);
+        scriptsByCase.get(s.testCaseId).push(s);
+    }
+    const testCases = data.testCases.map((t) => {
+        const ids = linkedReqIds(t);
+        const scripts = (scriptsByCase.get(t.id) ?? []).map((s) => {
+            const a = alignMap.get(alignKey(t.id, s.language));
+            const hasBody = typeof s.code === 'string' && s.code.length > 0;
+            return {
+                language: s.language,
+                annotated: hasBody ? ids.some((id) => s.code.toLowerCase().includes(id.toLowerCase())) : (s.codeKey ? null : false),
+                aiScore: a?.score ?? null,
+                aligned: a ? a.score >= ALIGN_THRESHOLD : null,
+                stepCoveragePct: a?.stepCoveragePct ?? null,
+                verifiedAt: a?.verifiedAt ? new Date(a.verifiedAt).toISOString() : null,
+            };
+        });
+        return { ...t, traceToExtra: t.traceToExtra ?? [], scripts };
+    });
+    return buildTraceabilityMatrix({ requirements: data.requirements, testCases, scenarios: data.scenarios });
+}
+async function loadAlignmentReport(tenantId, projectId) {
+    const rows = await (0, database_1.withTenant)(tenantId, async (tx) => {
+        const alignments = await tx.alignmentResult.findMany({ where: { tenantId, projectId } });
+        const ids = [...new Set(alignments.map((a) => a.testCaseId))];
+        const cases = ids.length
+            ? await tx.testCase.findMany({ where: { tenantId, id: { in: ids } }, select: { id: true, ref: true, title: true, traceTo: true } })
+            : [];
+        const byId = new Map(cases.map((c) => [c.id, c]));
+        return alignments
+            .filter((a) => byId.has(a.testCaseId))
+            .map((a) => {
+            const c = byId.get(a.testCaseId);
+            return {
+                testCaseId: a.testCaseId, ref: c.ref, title: c.title, traceTo: c.traceTo, language: a.language,
+                score: a.score, aligned: a.aligned, issues: a.issues, stepCoveragePct: a.stepCoveragePct ?? null,
+                stepCoverage: a.stepCoverage ?? null, verifiedAt: a.verifiedAt,
+            };
+        });
+    });
+    return buildAlignmentReport(rows);
+}

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "@taodigital/app-brain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsx --test src/**/*.test.ts"
+  },
+  "dependencies": {
+    "@taodigital/core": "*",
+    "@taodigital/database": "*",
+    "@taodigital/reranker": "*",
+    "@aws-sdk/client-s3": "^3.1075.0",
+    "@aws-sdk/s3-request-presigner": "^3.1075.0",
+    "nodemailer": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^8.0.1"
+  }
+}

package/src/archetype-classification.test.ts

@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { classifyScreenArchetype, matchInterestingJourneyPairs } from './archetype-classification.js';
+
+test('classifyScreenArchetype: a screen with a password-role element is LOGIN', () => {
+  const result = classifyScreenArchetype(
+    { id: 's1', name: 'Account Access', url: '/account/access' },
+    [{ role: 'password', expectedData: null }, { role: 'text', expectedData: null }],
+  );
+  assert.equal(result.archetype, 'LOGIN');
+});
+
+test('classifyScreenArchetype: a screen with no password element but a login-like URL is LOGIN', () => {
+  const result = classifyScreenArchetype(
+    { id: 's1', name: 'Sign In', url: '/signin' },
+    [],
+  );
+  assert.equal(result.archetype, 'LOGIN');
+});
+
+test('classifyScreenArchetype: signup URL requires BOTH email and password fields, not just the URL', () => {
+  const withBoth = classifyScreenArchetype(
+    { id: 's1', name: 'Register', url: '/register' },
+    [{ role: 'email', expectedData: null }, { role: 'password', expectedData: null }],
+  );
+  assert.equal(withBoth.archetype, 'SIGNUP');
+
+  // Register URL but only an email field (no password) — falls through past
+  // the SIGNUP rule (needs both) and the LOGIN rule (needs a password), but
+  // an email input is itself a data-entry field, so this correctly lands on
+  // FORM rather than the less useful GENERIC.
+  const emailOnly = classifyScreenArchetype(
+    { id: 's2', name: 'Register', url: '/register' },
+    [{ role: 'email', expectedData: null }],
+  );
+  assert.equal(emailOnly.archetype, 'FORM');
+});
+
+test('classifyScreenArchetype: checkout/cart URL wins even over other signals', () => {
+  const result = classifyScreenArchetype(
+    { id: 's1', name: 'Your Cart', url: '/cart' },
+    [{ role: 'text', expectedData: null }],
+  );
+  assert.equal(result.archetype, 'CHECKOUT');
+});
+
+test('classifyScreenArchetype: a search-role element with a neutral URL is SEARCH', () => {
+  const result = classifyScreenArchetype(
+    { id: 's1', name: 'Find Products', url: '/products' },
+    [{ role: 'search', expectedData: null }],
+  );
+  assert.equal(result.archetype, 'SEARCH');
+});
+
+test('classifyScreenArchetype: plain data-entry fields with no other signal is FORM', () => {
+  const result = classifyScreenArchetype(
+    { id: 's1', name: 'Profile', url: '/profile' },
+    [{ role: 'text', expectedData: null }, { role: 'date', expectedData: null }],
+  );
+  assert.equal(result.archetype, 'FORM');
+});
+
+test('classifyScreenArchetype: a screen with no distinguishing signals is GENERIC', () => {
+  const result = classifyScreenArchetype(
+    { id: 's1', name: 'About Us', url: '/about' },
+    [{ role: 'a', expectedData: null }],
+  );
+  assert.equal(result.archetype, 'GENERIC');
+});
+
+test('matchInterestingJourneyPairs: pairs a LOGIN screen with every CHECKOUT screen', () => {
+  const screens = [
+    { id: 'login1', name: 'Login', archetype: 'LOGIN' as const },
+    { id: 'checkout1', name: 'Checkout', archetype: 'CHECKOUT' as const },
+    { id: 'about1', name: 'About', archetype: 'GENERIC' as const },
+  ];
+  const pairs = matchInterestingJourneyPairs(screens);
+  const loginToCheckout = pairs.find((p) => p.startScreenId === 'login1' && p.endScreenId === 'checkout1');
+  assert.ok(loginToCheckout, 'expected a Login -> Checkout candidate');
+  assert.equal(loginToCheckout!.label, 'Login → Checkout');
+  // GENERIC screens never appear as either side of a suggestion.
+  assert.ok(!pairs.some((p) => p.startScreenId === 'about1' || p.endScreenId === 'about1'));
+});
+
+test('matchInterestingJourneyPairs: returns no candidates when nothing matches any rule', () => {
+  const screens = [
+    { id: 's1', name: 'About', archetype: 'GENERIC' as const },
+    { id: 's2', name: 'Contact', archetype: 'GENERIC' as const },
+  ];
+  assert.deepEqual(matchInterestingJourneyPairs(screens), []);
+});