taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/application/checkpoint/baseline-capturer.js

@@ -0,0 +1,163 @@
+import { BaselineSchema } from "../../domain/checkpoint.js";
+import { BaselineError } from "./baseline-error.js";
+function activityFacts(report) {
+    const facts = [];
+    for (const step of report.steps) {
+        const before = step.activity?.before.actual;
+        const after = step.activity?.after.actual;
+        if (before === undefined || after === undefined) {
+            continue;
+        }
+        facts.push({
+            stepIndex: step.index,
+            before,
+            after
+        });
+    }
+    return facts;
+}
+function elementFacts(report) {
+    const facts = [];
+    const seen = new Set();
+    for (const step of report.steps) {
+        const locator = step.locator;
+        if (locator === undefined) {
+            continue;
+        }
+        if (locator.status !== "found") {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Passed report has an unverified locator at step ${String(step.index)}`);
+        }
+        if (locator.anchorId === undefined && locator.requested === undefined) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Locator at step ${String(step.index)} has no stable identity`);
+        }
+        const identity = locator.anchorId === undefined
+            ? { locator: locator.requested }
+            : { anchorId: locator.anchorId };
+        const key = JSON.stringify([step.index, identity]);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        facts.push({
+            ...identity,
+            stepIndex: step.index,
+            kind: "present",
+            ...(locator.matchedBy === undefined
+                ? {}
+                : { matchedBy: locator.matchedBy }),
+            fallbackUsed: locator.fallbackUsed
+        });
+    }
+    return facts;
+}
+function screenFacts(report, hookOutcomes) {
+    const facts = [];
+    for (const screen of report.screens ?? []) {
+        facts.push(screen);
+    }
+    const afterOutcome = hookOutcomes?.find((outcome) => (outcome.phase === "afterSteps"
+        && outcome.status === "passed"
+        && outcome.screen !== undefined));
+    if (afterOutcome?.screen === undefined) {
+        return facts;
+    }
+    if (!facts.some((fact) => fact.screen === afterOutcome.screen)) {
+        facts.push({
+            screen: afterOutcome.screen,
+            status: "matched"
+        });
+    }
+    return facts;
+}
+function checkpointFacts(report) {
+    const facts = [];
+    const seen = new Set();
+    for (const checkpoint of report.checkpoints ?? []) {
+        if (checkpoint.status !== "passed" || seen.has(checkpoint.id)) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Checkpoint ${checkpoint.id} is not a unique passed result`);
+        }
+        seen.add(checkpoint.id);
+        for (const condition of checkpoint.conditions) {
+            if (condition.status !== "passed") {
+                throw new BaselineError("BASELINE_INCOMPARABLE", `Checkpoint ${checkpoint.id} has an unverified condition`);
+            }
+            const identity = {
+                checkpointId: checkpoint.id,
+                ...(checkpoint.stepIndex === undefined ? {} : { stepIndex: checkpoint.stepIndex })
+            };
+            switch (condition.kind) {
+                case "activity":
+                case "screen":
+                    facts.push({ ...identity, kind: condition.kind, expected: condition.expected });
+                    break;
+                case "logcatEvent":
+                    if (report.logcatEvidence?.some((entry) => (entry.lastDroppedAtMs === undefined
+                        || entry.lastDroppedAtMs >= condition.startedAtMs)) === true
+                        || condition.matchedCount !== 1 || condition.matchedLineSha256 === undefined
+                        || condition.matchedAtMs === undefined
+                        || condition.evidenceRef === undefined) {
+                        throw new BaselineError("BASELINE_INCOMPARABLE", `Checkpoint ${checkpoint.id} has incomplete Logcat event evidence`);
+                    }
+                    facts.push({ ...identity, kind: condition.kind, expect: condition.expect });
+                    break;
+                default:
+                    facts.push({ ...identity, kind: condition.kind, locator: condition.locator });
+            }
+        }
+    }
+    return facts;
+}
+/**
+ * Captures a Baseline from a completed (passing) verification run. The
+ * capture is read-only with respect to the device: it derives deterministic
+ * facts from the published report and hook outcomes.
+ */
+export class BaselineCapturer {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    capture = (input) => {
+        if (input.result.status !== "passed"
+            || input.result.report.status !== "passed") {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Baseline capture requires a passed run; got ${input.result.status}`);
+        }
+        if (input.journeySha256 !== input.result.report.journey.sha256) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "Baseline Journey binding does not match the source report");
+        }
+        if (input.runId !== input.result.report.runId
+            || input.packageName !== input.result.report.project.packageName) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "Baseline run or package identity does not match the source report");
+        }
+        const activities = activityFacts(input.result.report);
+        const elements = elementFacts(input.result.report);
+        const checkpoints = checkpointFacts(input.result.report);
+        const screens = input.includeScreenFacts === false
+            ? []
+            : screenFacts(input.result.report, input.result.hookOutcomes);
+        if (screens.some((screen) => screen.status !== "matched")) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "A Baseline can only freeze resolved Screen matches");
+        }
+        if (activities.length + elements.length + screens.length + checkpoints.length === 0) {
+            throw new BaselineError("BASELINE_EMPTY", "Cannot capture a Baseline without comparable facts");
+        }
+        const baseline = BaselineSchema.parse({
+            version: 1,
+            id: input.id,
+            journeySha256: input.journeySha256,
+            ...(input.contractSha256 === undefined
+                ? {}
+                : { contractSha256: input.contractSha256 }),
+            capturedAt: input.capturedAt,
+            packageName: input.packageName,
+            runId: input.runId,
+            activities,
+            elements,
+            screens,
+            ...(checkpoints.length === 0 ? {} : { checkpoints }),
+            requiredEvidence: { screens: screens.length > 0 },
+            sourceReportPath: input.result.reportPath
+        });
+        return baseline;
+    };
+}

package/dist/application/checkpoint/baseline-error.d.ts

@@ -0,0 +1,5 @@
+import type { FailureCode } from "../../domain/failure.js";
+export declare class BaselineError extends Error {
+    readonly code: Extract<FailureCode, "BASELINE_INCOMPARABLE" | "BASELINE_EMPTY">;
+    constructor(code: Extract<FailureCode, "BASELINE_INCOMPARABLE" | "BASELINE_EMPTY">, message: string);
+}

package/dist/application/checkpoint/baseline-error.js

@@ -0,0 +1,8 @@
+export class BaselineError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "BaselineError";
+    }
+}

package/dist/application/checkpoint/baseline-service.d.ts

@@ -0,0 +1,31 @@
+import type { Baseline, RegressionCompareResult } from "../../domain/checkpoint.js";
+export interface BaselineServiceDependencies {
+    readText: (path: string) => Promise<string>;
+    writeText: (path: string, content: string) => Promise<void>;
+    now: () => Date;
+}
+export declare class BaselineService {
+    private readonly dependencies;
+    private readonly capturer;
+    constructor(dependencies: BaselineServiceDependencies);
+    readonly captureFromReport: (reportPath: string, input: {
+        id?: string | undefined;
+        journeySha256?: string | undefined;
+        contractSha256?: string | undefined;
+        verdictPath?: string | undefined;
+        includeScreenFacts?: boolean | undefined;
+    }) => Promise<Baseline>;
+    readonly write: (input: {
+        path: string;
+        baseline: Baseline;
+    }) => Promise<void>;
+    readonly compare: (input: {
+        baselinePath: string;
+        reportPath: string;
+        journeySha256?: string | undefined;
+        verdictPath?: string | undefined;
+    }) => Promise<RegressionCompareResult>;
+    private readonly readBaseline;
+    private readonly readReport;
+    private readonly readPassingVerdict;
+}

package/dist/application/checkpoint/baseline-service.js

@@ -0,0 +1,147 @@
+import { dirname, join, resolve } from "node:path";
+import { BaselineSchema, RegressionCompareResultSchema } from "../../domain/checkpoint.js";
+import { ContractVerdictViewSchema } from "../../domain/contract.js";
+import { TapHoundReportV4Schema } from "../../domain/report.js";
+import { BaselineError } from "./baseline-error.js";
+import { BaselineCapturer } from "./baseline-capturer.js";
+import { compareRegression } from "./regression-comparator.js";
+export class BaselineService {
+    dependencies;
+    capturer;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        this.capturer = new BaselineCapturer({ now: dependencies.now });
+    }
+    captureFromReport = async (reportPath, input) => {
+        const report = await this.readReport(reportPath);
+        if (report.status !== "passed") {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "Baseline capture requires a passed report");
+        }
+        if (input.journeySha256 !== undefined
+            && input.journeySha256 !== report.journey.sha256) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "Requested Journey hash differs from the report");
+        }
+        const contractSha256 = input.contractSha256 === undefined
+            && input.verdictPath === undefined
+            ? undefined
+            : await this.readPassingVerdict(input.verdictPath ?? join(dirname(reportPath), "verdict.json"), reportPath, report, input.contractSha256);
+        const baseline = this.capturer.capture({
+            id: input.id ?? report.runId,
+            journeySha256: report.journey.sha256,
+            ...(contractSha256 === undefined
+                ? {}
+                : { contractSha256 }),
+            ...(input.includeScreenFacts === undefined
+                ? {}
+                : { includeScreenFacts: input.includeScreenFacts }),
+            capturedAt: new Date(this.dependencies.now()).toISOString(),
+            runId: report.runId,
+            packageName: report.project.packageName,
+            result: {
+                report,
+                hookOutcomes: [],
+                status: "passed",
+                reportPath
+            }
+        });
+        return baseline;
+    };
+    write = async (input) => {
+        await this.dependencies.writeText(input.path, `${JSON.stringify(input.baseline, null, 2)}\n`);
+    };
+    compare = async (input) => {
+        const baseline = await this.readBaseline(input.baselinePath);
+        const report = await this.readReport(input.reportPath);
+        const checkpointFailure = report.status === "failed"
+            && report.primaryFailure?.code === "CHECKPOINT_FAILED"
+            && report.layers.run === "failed"
+            && report.steps.every((step) => step.status === "passed")
+            && report.checkpoints?.some((checkpoint) => checkpoint.status === "failed")
+            && report.checkpoints.every((checkpoint) => checkpoint.status !== "unresolved")
+            && (baseline.checkpoints?.length ?? 0) > 0
+            && report.checkpoints.filter((checkpoint) => checkpoint.status === "failed").every((checkpoint) => baseline.checkpoints?.some((fact) => fact.checkpointId === checkpoint.id))
+            && baseline.activities.every((fact) => report.steps.some((step) => step.index === fact.stepIndex && step.status === "passed"))
+            && baseline.elements.every((fact) => report.steps.some((step) => step.index === fact.stepIndex && step.status === "passed"));
+        if ((report.status !== "passed" && !checkpointFailure)
+            || report.journey.sha256 !== baseline.journeySha256
+            || report.project.packageName !== baseline.packageName
+            || (input.journeySha256 !== undefined
+                && input.journeySha256 !== report.journey.sha256)) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Report identity or status does not match Baseline ${baseline.id}`);
+        }
+        if (baseline.requiredEvidence.screens
+            && (report.screens?.length ?? 0) === 0) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "The current report has no Screen evidence required by the Baseline");
+        }
+        if (baseline.contractSha256 !== undefined) {
+            await this.readPassingVerdict(input.verdictPath ?? join(dirname(input.reportPath), "verdict.json"), input.reportPath, report, baseline.contractSha256, checkpointFailure);
+        }
+        const result = compareRegression({
+            baseline,
+            current: report,
+            journeySha256: report.journey.sha256,
+            comparedAt: new Date(this.dependencies.now()).toISOString()
+        });
+        if (checkpointFailure && result.equivalent) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "A failed Checkpoint run cannot establish Baseline equivalence");
+        }
+        return RegressionCompareResultSchema.parse(result);
+    };
+    readBaseline = async (path) => {
+        let value;
+        try {
+            value = JSON.parse(await this.dependencies.readText(path));
+        }
+        catch {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Baseline is missing or not valid JSON: ${path}`);
+        }
+        const parsed = BaselineSchema.safeParse(value);
+        if (parsed.success) {
+            return parsed.data;
+        }
+        if (parsed.error.issues.some((issue) => (issue.message === "A Baseline needs at least one comparable fact"))) {
+            throw new BaselineError("BASELINE_EMPTY", "Baseline contains no comparable facts");
+        }
+        throw new BaselineError("BASELINE_INCOMPARABLE", `Baseline does not match its schema: ${parsed.error.message}`);
+    };
+    readReport = async (path) => {
+        let report;
+        try {
+            report = TapHoundReportV4Schema.parse(JSON.parse(await this.dependencies.readText(path)));
+        }
+        catch {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `A valid V4 report is required: ${path}`);
+        }
+        if (report.status === "passed"
+            && (report.primaryFailure !== undefined
+                || report.layers.run !== "passed"
+                || report.steps.some((step) => step.status !== "passed")
+                || report.checkpoints?.some((checkpoint) => checkpoint.status !== "passed"))) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "A passed report contains failed or incomplete replay evidence");
+        }
+        return report;
+    };
+    readPassingVerdict = async (path, reportPath, report, expectedContractSha256, allowCheckpointFailure = false) => {
+        let verdict;
+        try {
+            verdict = ContractVerdictViewSchema.parse(JSON.parse(await this.dependencies.readText(path)));
+        }
+        catch {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `A valid passing Contract Verdict is required: ${path}`);
+        }
+        if (!((verdict.verdict === "pass" && verdict.reportStatus === "passed")
+            || (allowCheckpointFailure
+                && verdict.verdict === "fail"
+                && verdict.reason === "CHECKPOINT_FAILED"
+                && verdict.reportStatus === "failed"))
+            || verdict.reportPath === undefined
+            || resolve(verdict.reportPath) !== resolve(reportPath)
+            || verdict.journeySha256 !== report.journey.sha256
+            || verdict.environment.packageName !== report.project.packageName
+            || (expectedContractSha256 !== undefined
+                && verdict.contractSha256 !== expectedContractSha256)) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", "Contract Verdict does not establish this report and Contract identity");
+        }
+        return verdict.contractSha256;
+    };
+}

package/dist/application/checkpoint/checkpoint-evaluator.d.ts

@@ -0,0 +1,35 @@
+import type { CheckpointDefinition } from "../../domain/checkpoint.js";
+import type { CheckpointReport } from "../../domain/report.js";
+import type { LoadedKnowledgeBundle } from "../../ports/knowledge-registry.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { UiSnapshotProvider } from "../../ports/ui-snapshot.js";
+import type { UiSnapshot } from "../../ports/ui-snapshot.js";
+import type { Clock } from "../../ports/clock.js";
+import type { LogcatCollector } from "../collector/logcat-collector.js";
+export interface CheckpointEvaluation {
+    report: CheckpointReport;
+    matchedScreen?: string | undefined;
+}
+export interface CheckpointEvaluateInput {
+    checkpoint: CheckpointDefinition;
+    provider: UiSnapshotProvider;
+    adb: AdbPort;
+    packageName: string;
+    deviceSerial: string;
+    timeoutMs: number;
+    knowledge?: LoadedKnowledgeBundle | undefined;
+    knowledgeError?: string | undefined;
+    signal?: AbortSignal | undefined;
+    clock?: Clock | undefined;
+    logcat?: LogcatCollector | undefined;
+    stepStartedAt?: number | undefined;
+    runStartedAt?: number | undefined;
+    markers?: ReadonlyMap<string, number> | undefined;
+    logcatEvidenceRef?: string | undefined;
+    writeSnapshot?: ((path: string, snapshot: UiSnapshot) => Promise<void>) | undefined;
+}
+export declare class CheckpointEvaluator {
+    private readonly detector;
+    private readonly observeUi;
+    readonly evaluate: (input: CheckpointEvaluateInput) => Promise<CheckpointEvaluation>;
+}