taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/application/contract/contract-verifier.js

@@ -0,0 +1,645 @@
+import { CONTRACT_VERDICT_POLICY_VERSION, ContractVerdictViewSchema } from "../../domain/contract.js";
+import { resolveLocator } from "../locator/locator-resolver.js";
+import { ScreenDetector } from "../recognition/screen-detector.js";
+import { ContractError, ContractLoader } from "./contract-loader.js";
+function aggregateStatus(outcomes) {
+    if (outcomes.some((outcome) => outcome.status === "failed")) {
+        return { status: "failed" };
+    }
+    if (outcomes.some((outcome) => outcome.status === "unresolved")) {
+        return { status: "unresolved" };
+    }
+    return { status: "passed" };
+}
+function aggregateAssertionStatus(outcomes) {
+    if (outcomes.some((outcome) => outcome.status === "failed")) {
+        return { status: "failed" };
+    }
+    if (outcomes.some((outcome) => outcome.status === "unresolved")) {
+        return { status: "unresolved" };
+    }
+    return { status: "passed" };
+}
+function reasonForFailureCode(code) {
+    switch (code) {
+        case "CONTRACT_JOURNEY_DRIFT":
+            return "JOURNEY_DRIFT";
+        case "CONTRACT_JOURNEY_MISSING":
+            return "JOURNEY_MISSING";
+        case "CONTRACT_KNOWLEDGE_UNAVAILABLE":
+            return "KNOWLEDGE_UNAVAILABLE";
+        default:
+            return "CONTRACT_INVALID";
+    }
+}
+function matchesCheckpoint(definition, result, logcatEvidence) {
+    if (definition.stepIndex !== result.stepIndex) {
+        return false;
+    }
+    const expected = definition.expect.allOf.map((condition) => [
+        condition.kind,
+        "locator" in condition ? condition.locator
+            : "expect" in condition ? condition.expect : condition.expected
+    ]);
+    return expected.length === result.conditions.length
+        && result.conditions.every((condition, index) => {
+            if (condition.kind === "logcatEvent" && condition.status === "passed"
+                && (logcatEvidence?.some((entry) => (entry.lastDroppedAtMs === undefined
+                    || entry.lastDroppedAtMs >= condition.startedAtMs)) === true || condition.matchedCount !== 1
+                    || condition.matchedLineSha256 === undefined
+                    || condition.matchedAtMs === undefined
+                    || condition.evidenceRef === undefined)) {
+                return false;
+            }
+            const identity = "locator" in condition ? condition.locator
+                : "expect" in condition ? condition.expect : condition.expected;
+            return JSON.stringify([condition.kind, identity])
+                === JSON.stringify(expected[index]);
+        });
+}
+function checkpointOutcomes(definitions, required, results, logcatEvidence) {
+    return required.map((id) => {
+        const definition = definitions.find((entry) => entry.id === id);
+        const matches = results.filter((result) => result.id === id);
+        if (definition === undefined || matches.length !== 1
+            || matches[0] === undefined) {
+            return {
+                id,
+                status: "notRun",
+                message: matches.length > 1
+                    ? "Duplicate Checkpoint results are not trustworthy"
+                    : "Required Checkpoint was not evaluated"
+            };
+        }
+        if (!matchesCheckpoint(definition, matches[0], logcatEvidence)) {
+            return {
+                id,
+                status: "unresolved",
+                message: "Checkpoint conditions or evaluation point differ from the bound Journey"
+            };
+        }
+        return { id, status: matches[0].status };
+    });
+}
+export class ContractVerifier {
+    dependencies;
+    loader;
+    detector = new ScreenDetector();
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.loader = new ContractLoader({
+            readText: dependencies.readText
+        });
+    }
+    verify = async (input) => {
+        const startedAt = new Date(this.dependencies.now()).toISOString();
+        const environment = {
+            projectRoot: input.projectRoot,
+            packageName: input.config.run.packageName,
+            devices: input.devices.map((device) => device.deviceSerial)
+        };
+        const provenance = {
+            policyVersion: CONTRACT_VERDICT_POLICY_VERSION,
+            ...(input.taphoundVersion === undefined
+                ? {}
+                : { taphoundVersion: input.taphoundVersion }),
+            ...(Object.keys(input.toolVersions).length === 0
+                ? {}
+                : { toolVersions: input.toolVersions })
+        };
+        let loaded;
+        try {
+            loaded = await this.loader.load({
+                projectRoot: input.projectRoot,
+                contractPath: input.contractPath
+            });
+        }
+        catch (error) {
+            const contractError = error instanceof ContractError ? error : undefined;
+            const code = contractError?.code ?? "CONTRACT_INVALID";
+            const reason = reasonForFailureCode(code);
+            return {
+                view: this.invalidView(startedAt, {
+                    reason,
+                    message: contractError?.message
+                        ?? "Acceptance Contract could not be loaded",
+                    environment,
+                    provenance
+                }),
+                exitCode: 2
+            };
+        }
+        const contract = loaded.contract;
+        const needsKnowledge = contract.targetScreen !== undefined
+            || contract.preconditions.some((precondition) => precondition.kind === "screen"
+                || precondition.kind === "anchor") || contract.assertions.some((assertion) => assertion.type === "screen");
+        let knowledge;
+        if (needsKnowledge) {
+            if (this.dependencies.loadKnowledge === undefined) {
+                return {
+                    view: this.invalidView(startedAt, {
+                        reason: "KNOWLEDGE_UNAVAILABLE",
+                        message: "This Contract needs Project Knowledge (screen/anchor terms) but no knowledge loader is configured",
+                        environment,
+                        provenance
+                    }),
+                    exitCode: 2
+                };
+            }
+            try {
+                knowledge = await this.dependencies.loadKnowledge({
+                    projectRoot: input.projectRoot,
+                    packageName: input.config.run.packageName
+                });
+            }
+            catch (error) {
+                return {
+                    view: this.invalidView(startedAt, {
+                        reason: "KNOWLEDGE_UNAVAILABLE",
+                        message: `Project Knowledge is unavailable: ${error instanceof Error ? error.message : String(error)}`,
+                        environment,
+                        provenance
+                    }),
+                    exitCode: 2
+                };
+            }
+        }
+        if (contract.targetScreen !== undefined
+            && !knowledge?.screens.some((screen) => screen.id === contract.targetScreen)) {
+            return {
+                view: this.invalidView(startedAt, {
+                    reason: "KNOWLEDGE_UNAVAILABLE",
+                    message: `Contract targetScreen ${contract.targetScreen} is not present in Project Knowledge`,
+                    environment,
+                    provenance
+                }),
+                exitCode: 2
+            };
+        }
+        const preconditionOutcomes = [];
+        const assertionOutcomes = [];
+        const hooks = {
+            beforeSteps: async (context) => {
+                const outcomes = await this.evaluatePreconditions(context, contract, knowledge, input.config.run.packageName);
+                preconditionOutcomes.push(...outcomes);
+                const result = aggregateStatus(preconditionOutcomes);
+                const screen = contract.preconditions.find((precondition, index) => (precondition.kind === "screen"
+                    && outcomes[index]?.status === "passed"));
+                return screen?.kind === "screen"
+                    ? { ...result, screen: screen.screen }
+                    : result;
+            },
+            afterSteps: async (context) => {
+                const outcomes = await this.evaluateAssertions(context, contract, knowledge, input.config.run.packageName);
+                assertionOutcomes.push(...outcomes);
+                const result = aggregateAssertionStatus(assertionOutcomes);
+                const screen = contract.assertions.find((assertion, index) => (assertion.type === "screen"
+                    && outcomes[index]?.status === "passed"));
+                return screen?.type === "screen"
+                    ? { ...result, screen: screen.screen }
+                    : result;
+            }
+        };
+        let runResult;
+        try {
+            runResult = await this.dependencies.verify({
+                config: input.config,
+                journey: loaded.journey,
+                projectRoot: input.projectRoot,
+                devices: input.devices,
+                toolVersions: input.toolVersions,
+                ...(input.generatedReplayPolicy === undefined
+                    ? {}
+                    : { generatedReplayPolicy: input.generatedReplayPolicy }),
+                ...(input.requireFocusedInput === undefined
+                    ? {}
+                    : { requireFocusedInput: input.requireFocusedInput }),
+                ...(input.manualReplay === undefined
+                    ? {}
+                    : { manualReplay: input.manualReplay }),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                hooks
+            });
+        }
+        catch (error) {
+            return {
+                view: this.invalidView(startedAt, {
+                    reason: "CONTRACT_INVALID",
+                    message: `Runtime verification failed to start: ${error instanceof Error ? error.message : String(error)}`,
+                    environment,
+                    provenance
+                }),
+                exitCode: 4
+            };
+        }
+        const report = runResult.report;
+        const evidence = this.checkEvidence(contract, report);
+        const evidenceInsufficient = evidence.some((entry) => entry.required && !entry.satisfied);
+        const beforeOutcome = (runResult.hookOutcomes ?? []).find((outcome) => outcome.phase === "beforeSteps");
+        const afterOutcome = (runResult.hookOutcomes ?? []).find((outcome) => outcome.phase === "afterSteps");
+        const { preconditions, assertions } = this.withNotRun(contract, preconditionOutcomes, assertionOutcomes);
+        const checkpoints = checkpointOutcomes(loaded.journey.checkpoints ?? [], contract.requiredCheckpoints, report.checkpoints ?? [], report.logcatEvidence);
+        const failedCheckpoint = checkpoints.some((entry) => entry.status === "failed");
+        const unresolvedCheckpoint = checkpoints.some((entry) => (entry.status === "unresolved" || entry.status === "notRun"));
+        let verdict;
+        let reason;
+        let message;
+        let exitCode;
+        switch (runResult.status) {
+            case "error":
+                verdict = "inconclusive";
+                reason = "RUN_ERROR";
+                message = report.primaryFailure?.message ?? "Runtime verification errored";
+                exitCode = 1;
+                break;
+            case "manualRequired":
+                verdict = "inconclusive";
+                reason = "RUN_MANUAL_REQUIRED";
+                message = report.primaryFailure?.message
+                    ?? "The Journey requires manual replay";
+                exitCode = 1;
+                break;
+            case "failed":
+                if (report.primaryFailure?.code === "CHECKPOINT_FAILED" && failedCheckpoint) {
+                    verdict = "fail";
+                    reason = "CHECKPOINT_FAILED";
+                    message = report.primaryFailure.message;
+                    exitCode = runResult.exitCode === 0 ? 1 : runResult.exitCode;
+                }
+                else if (report.primaryFailure?.code === "CHECKPOINT_UNRESOLVED"
+                    && unresolvedCheckpoint) {
+                    verdict = "inconclusive";
+                    reason = "CHECKPOINT_UNRESOLVED";
+                    message = report.primaryFailure.message;
+                    exitCode = 1;
+                }
+                else {
+                    verdict = "fail";
+                    reason = "RUN_FAILED";
+                    message = report.primaryFailure?.message ?? "Journey replay failed";
+                    exitCode = runResult.exitCode === 0 ? 1 : runResult.exitCode;
+                }
+                break;
+            case "passed":
+                if (report.status !== "passed"
+                    || report.journey.sha256 !== contract.journey.sha256) {
+                    verdict = "inconclusive";
+                    reason = "RUN_ERROR";
+                    message = "Replay report status or Journey identity does not match this Contract";
+                    exitCode = 1;
+                    break;
+                }
+                if (failedCheckpoint) {
+                    verdict = "fail";
+                    reason = "CHECKPOINT_FAILED";
+                    message = "A required Checkpoint failed";
+                    exitCode = 1;
+                    break;
+                }
+                if (unresolvedCheckpoint) {
+                    verdict = "inconclusive";
+                    reason = "CHECKPOINT_UNRESOLVED";
+                    message = "Required Checkpoint evidence is missing or unresolved";
+                    exitCode = 1;
+                    break;
+                }
+                if (beforeOutcome?.status === "failed") {
+                    verdict = "fail";
+                    reason = "PRECONDITION_FAILED";
+                    message = "A Contract precondition failed before the Journey ran";
+                    exitCode = 1;
+                    break;
+                }
+                if (beforeOutcome?.status === "unresolved") {
+                    verdict = "inconclusive";
+                    reason = "PRECONDITION_UNRESOLVED";
+                    message = "A Contract precondition could not be determined";
+                    exitCode = 1;
+                    break;
+                }
+                if (afterOutcome?.status === "failed") {
+                    verdict = "fail";
+                    reason = "ASSERTION_FAILED";
+                    message = "A Contract assertion failed after the Journey";
+                    exitCode = 1;
+                    break;
+                }
+                if (afterOutcome?.status === "unresolved") {
+                    verdict = "inconclusive";
+                    reason = "ASSERTION_UNRESOLVED";
+                    message = "A Contract assertion could not be determined";
+                    exitCode = 1;
+                    break;
+                }
+                if (evidenceInsufficient) {
+                    verdict = "inconclusive";
+                    reason = "EVIDENCE_INSUFFICIENT";
+                    message = "Required runtime evidence is missing from the run";
+                    exitCode = 1;
+                    break;
+                }
+                verdict = "pass";
+                reason = "CONTRACT_OK";
+                message = "Acceptance Contract satisfied by runtime evidence";
+                exitCode = 0;
+                break;
+        }
+        const view = ContractVerdictViewSchema.parse({
+            version: 1,
+            contractId: contract.id,
+            contractSha256: loaded.contractSha256,
+            journeySha256: contract.journey.sha256,
+            verdict,
+            reason,
+            message,
+            preconditions,
+            assertions,
+            ...(contract.requiredCheckpoints.length === 0 ? {} : { checkpoints }),
+            evidence,
+            reportPath: runResult.reportPath,
+            reportStatus: runResult.status,
+            startedAt,
+            finishedAt: new Date(this.dependencies.now()).toISOString(),
+            environment,
+            provenance
+        });
+        if (this.dependencies.writeVerdict !== undefined) {
+            await this.dependencies.writeVerdict({
+                reportPath: runResult.reportPath,
+                verdict: view
+            });
+        }
+        return { view, exitCode };
+    };
+    invalidView = (startedAt, input) => ContractVerdictViewSchema.parse({
+        version: 1,
+        contractId: "unknown",
+        contractSha256: "0".repeat(64),
+        journeySha256: "0".repeat(64),
+        verdict: "invalid",
+        reason: input.reason,
+        message: input.message,
+        preconditions: [],
+        assertions: [],
+        evidence: [],
+        startedAt,
+        finishedAt: new Date(this.dependencies.now()).toISOString(),
+        environment: input.environment,
+        ...(input.provenance === undefined ? {} : { provenance: input.provenance })
+    });
+    evaluatePreconditions = async (context, contract, knowledge, packageName) => {
+        const outcomes = [];
+        for (const precondition of contract.preconditions) {
+            const assessed = await this.assessPrecondition(precondition, context, knowledge, packageName);
+            outcomes.push({
+                kind: precondition.kind,
+                status: assessed.status,
+                ...(assessed.status === "passed" ? {} : { message: assessed.message })
+            });
+        }
+        return outcomes;
+    };
+    assessPrecondition = async (precondition, context, knowledge, packageName) => {
+        switch (precondition.kind) {
+            case "installed":
+                return { status: "passed" };
+            case "activity":
+                return this.checkActivity(precondition.activity, precondition.timeoutMs, context, packageName);
+            case "anchor":
+                return this.checkAnchor(precondition.anchor, context, knowledge);
+            case "screen":
+                return this.checkScreen(precondition.screen, precondition.timeoutMs, context, knowledge, packageName);
+        }
+    };
+    evaluateAssertions = async (context, contract, knowledge, packageName) => {
+        const outcomes = [];
+        for (const assertion of contract.assertions) {
+            const assessed = await this.assessAssertion(assertion, context, knowledge, packageName);
+            outcomes.push({
+                type: assertion.type,
+                status: assessed.status,
+                ...(assessed.status === "passed" ? {} : { message: assessed.message })
+            });
+        }
+        return outcomes;
+    };
+    assessAssertion = async (assertion, context, knowledge, packageName) => {
+        switch (assertion.type) {
+            case "activity":
+                return this.checkActivity(assertion.activity, assertion.timeoutMs, context, packageName);
+            case "element":
+                return this.checkElement(assertion, context);
+            case "screen":
+                return this.checkScreen(assertion.screen, assertion.timeoutMs, context, knowledge, packageName);
+        }
+    };
+    checkActivity = async (expected, timeoutMs, context, packageName) => {
+        let actual;
+        try {
+            actual = await context.adb.currentActivity({
+                packageName,
+                deviceSerial: context.deviceSerial,
+                timeoutMs
+            });
+        }
+        catch (error) {
+            return {
+                status: "unresolved",
+                message: `Activity lookup failed: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+        if (actual === expected) {
+            return { status: "passed" };
+        }
+        return {
+            status: "failed",
+            message: `Expected activity ${expected}, found ${actual}`
+        };
+    };
+    checkAnchor = (anchorId, context, knowledge) => {
+        if (knowledge === undefined) {
+            return {
+                status: "unresolved",
+                message: "Project Knowledge is unavailable"
+            };
+        }
+        const anchor = knowledge.anchors.find((candidate) => candidate.id === anchorId);
+        if (anchor === undefined) {
+            return {
+                status: "unresolved",
+                message: `Anchor ${anchorId} is not defined in Project Knowledge`
+            };
+        }
+        if (anchor.identity.kind !== "element") {
+            return {
+                status: "unresolved",
+                message: `Anchor ${anchorId} does not carry an element identity; only element anchors support direct resolution`
+            };
+        }
+        const resolution = resolveLocator(context.snapshot.roots, anchor.identity.locator, {
+            requireEnabled: true,
+            viewport: context.snapshot.viewport
+        });
+        if (resolution.status === "found") {
+            return { status: "passed" };
+        }
+        if (resolution.code === "LOCATOR_AMBIGUOUS") {
+            return {
+                status: "unresolved",
+                message: `Anchor ${anchorId} is ambiguous in the current layout`
+            };
+        }
+        return {
+            status: "failed",
+            message: `Anchor ${anchorId} was not found: ${resolution.message}`
+        };
+    };
+    checkScreen = async (screenId, timeoutMs, context, knowledge, packageName) => {
+        if (knowledge === undefined) {
+            return {
+                status: "unresolved",
+                message: "Project Knowledge is unavailable"
+            };
+        }
+        const snapshot = await this.buildRuntimeSnapshot(context, packageName, timeoutMs);
+        if (snapshot === undefined) {
+            return {
+                status: "unresolved",
+                message: "Could not read the current Activity for screen detection"
+            };
+        }
+        const detection = this.detector.detect({
+            snapshot,
+            anchors: knowledge.anchors,
+            screens: knowledge.screens
+        });
+        if (detection.status === "matched") {
+            if (detection.screenId === screenId) {
+                return { status: "passed" };
+            }
+            return {
+                status: "failed",
+                message: `Expected screen ${screenId}, observed ${detection.screenId}`
+            };
+        }
+        const message = detection.status === "ambiguous"
+            ? `Screen detection is ambiguous: ${detection.screenIds.join(", ")}`
+            : "Screen detection could not identify a screen";
+        return { status: "unresolved", message };
+    };
+    buildRuntimeSnapshot = async (context, packageName, timeoutMs) => {
+        let activity;
+        try {
+            activity = await context.adb.currentActivity({
+                packageName,
+                deviceSerial: context.deviceSerial,
+                timeoutMs
+            });
+        }
+        catch {
+            return undefined;
+        }
+        return {
+            activity,
+            layout: [...context.snapshot.roots]
+        };
+    };
+    checkElement = async (assertion, context) => {
+        if (assertion.packageName !== undefined) {
+            try {
+                const foreground = await context.adb.foregroundComponent({
+                    packageName: assertion.packageName,
+                    deviceSerial: context.deviceSerial,
+                    timeoutMs: assertion.timeoutMs
+                });
+                if (foreground.packageName !== assertion.packageName) {
+                    return {
+                        status: "failed",
+                        message: `Expected foreground package ${assertion.packageName}, found ${foreground.packageName}`
+                    };
+                }
+            }
+            catch (error) {
+                return {
+                    status: "unresolved",
+                    message: `Foreground package lookup failed: ${error instanceof Error ? error.message : String(error)}`
+                };
+            }
+        }
+        const resolution = resolveLocator(context.snapshot.roots, assertion.locator, {
+            requireEnabled: false,
+            viewport: context.snapshot.viewport
+        });
+        if (resolution.status === "failed" && resolution.code === "LOCATOR_AMBIGUOUS") {
+            return {
+                status: "failed",
+                message: `Element Locator is ambiguous: ${resolution.message}`
+            };
+        }
+        const present = resolution.status === "found";
+        if (assertion.visibility === "visible") {
+            return present
+                ? { status: "passed" }
+                : {
+                    status: "failed",
+                    message: `Expected element to be visible: ${resolution.message}`
+                };
+        }
+        return present
+            ? {
+                status: "failed",
+                message: "Expected element to be absent but it was found"
+            }
+            : { status: "passed" };
+    };
+    checkEvidence = (contract, report) => {
+        const screenshotFinal = report.artifacts.screenshots.length > 0;
+        const screenshotAnyStep = screenshotFinal || report.steps.some((step) => step.locator?.annotatedScreenshotPath !== undefined);
+        const uiHierarchyFinal = (report.artifacts.uiHierarchies?.length ?? 0) > 0;
+        const logcatFinal = report.artifacts.logcats.length > 0;
+        const logcatAnyStep = report.steps.some((step) => step.logcatPath !== undefined);
+        const satisfiedFor = (requirement) => {
+            switch (requirement.kind) {
+                case "screenshot":
+                    return requirement.scope === "anyStep"
+                        ? screenshotAnyStep
+                        : screenshotFinal;
+                case "uiHierarchy":
+                    return uiHierarchyFinal;
+                case "logcat":
+                    return (report.logcatEvidence?.length ?? 0) === 0
+                        && (requirement.scope === "anyStep" ? logcatAnyStep : logcatFinal);
+            }
+        };
+        return contract.evidenceRequirements.map((requirement) => {
+            const satisfied = satisfiedFor(requirement);
+            return {
+                kind: requirement.kind,
+                required: requirement.required,
+                satisfied,
+                ...(satisfied
+                    ? {}
+                    : {
+                        detail: requirement.kind === "logcat"
+                            && (report.logcatEvidence?.length ?? 0) > 0
+                            ? "Logcat evidence is incomplete (buffer overflow)"
+                            : `Run ${report.runId} has no ${requirement.kind} evidence for scope ${requirement.scope}`
+                    })
+            };
+        });
+    };
+    withNotRun = (contract, preconditionOutcomes, assertionOutcomes) => {
+        const byKind = new Map(preconditionOutcomes.map((outcome) => [outcome.kind, outcome]));
+        const preconditions = contract.preconditions.map((precondition) => (byKind.get(precondition.kind) ?? {
+            kind: precondition.kind,
+            status: "notRun",
+            message: "Precondition was not evaluated before the run completed"
+        }));
+        const assertions = contract.assertions.map((assertion, index) => (assertionOutcomes[index] ?? {
+            type: assertion.type,
+            status: "notRun",
+            message: "Assertion was not evaluated because the run did not pass"
+        }));
+        return { preconditions, assertions };
+    };
+}

package/dist/application/devices/resolve-device-assignments.d.ts

@@ -0,0 +1,21 @@
+import type { FailureCode } from "../../domain/failure.js";
+export interface DeviceAssignment {
+    role: string;
+    deviceSerial: string;
+}
+export type DeviceAssignmentFailureCode = Extract<FailureCode, "CONFIG_INVALID" | "DEVICE_UNAVAILABLE" | "DEVICE_ROLE_UNMAPPED">;
+export type DeviceAssignmentResolution = {
+    ok: true;
+    assignments: DeviceAssignment[];
+} | {
+    ok: false;
+    code: DeviceAssignmentFailureCode;
+    message: string;
+    missingRoles?: string[];
+};
+export interface ResolveDeviceAssignmentsInput {
+    declaredRoles: readonly string[];
+    explicit: readonly DeviceAssignment[];
+    onlineSerials: readonly string[];
+}
+export declare function resolveDeviceAssignments(input: ResolveDeviceAssignmentsInput): DeviceAssignmentResolution;