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

package/dist/application/collector/logcat-collector.js

@@ -1,11 +1,13 @@
-const THREADTIME = /^\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d+\s+(\d+)\s+(\d+)\s+([VDIWEFA])\s+([^:]+):\s?(.*)$/;
+const THREADTIME = /^(\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}\.\d+)\s+(\d+)\s+(\d+)\s+([VDIWEFA])\s+(.+?):\s(.*)$/;
 function parseLine(raw, receivedAt) {
     const match = THREADTIME.exec(raw);
     if (match === null) {
         return { receivedAt, raw };
     }
-    const [, pid, tid, level, tag, message] = match;
-    if (pid === undefined
+    const [, deviceTimestamp, pid, tid, level, tag, message] = match;
+    if (deviceTimestamp === undefined
+        ||
+            pid === undefined
         || tid === undefined
         || level === undefined
         || tag === undefined
@@ -14,6 +16,7 @@ function parseLine(raw, receivedAt) {
     }
     return {
         receivedAt,
+        deviceTimestamp,
         raw,
         pid: Number(pid),
         tid: Number(tid),
@@ -31,30 +34,106 @@ function startupFailure(result) {
                 ? "Logcat startup timed out"
                 : `Logcat exited during startup with code ${String(result.exitCode)}`);
 }
+const COMPACT_THRESHOLD = 1024;
 export class LogcatCollector {
     adb;
     clock;
+    limits;
+    /** Live lines are `collected[head..]`; dropped lines are compacted lazily. */
     collected = [];
+    head = 0;
+    bufferedBytes = 0;
+    droppedByPid = new Map();
     stderr = [];
     scopedPids = new Set();
     running;
     streamMetadata;
     stopPromise;
-    constructor(adb, clock) {
+    constructor(adb, clock, limits = {
+        maxLines: 10000,
+        maxBytes: 2 * 1024 * 1024
+    }) {
         this.adb = adb;
         this.clock = clock;
+        this.limits = limits;
+        if (!Number.isInteger(limits.maxLines) || limits.maxLines < 1
+            || !Number.isInteger(limits.maxBytes) || limits.maxBytes < 1) {
+            throw new Error("Logcat buffer limits must be positive integers");
+        }
+    }
+    append(line) {
+        const parsed = parseLine(line, this.clock.now());
+        if (this.scopedPids.size > 0 && parsed.pid !== undefined
+            && !this.scopedPids.has(parsed.pid)) {
+            return;
+        }
+        const bytes = Buffer.byteLength(line, "utf8") + 1;
+        this.collected.push(parsed);
+        this.bufferedBytes += bytes;
+        while (this.collected.length - this.head > this.limits.maxLines
+            || this.bufferedBytes > this.limits.maxBytes) {
+            const dropped = this.collected[this.head];
+            if (dropped === undefined) {
+                break;
+            }
+            this.head += 1;
+            const size = Buffer.byteLength(dropped.raw, "utf8") + 1;
+            this.bufferedBytes -= size;
+            const previous = this.droppedByPid.get(dropped.pid);
+            this.droppedByPid.set(dropped.pid, {
+                lines: (previous?.lines ?? 0) + 1,
+                bytes: (previous?.bytes ?? 0) + size,
+                lastDroppedAt: dropped.receivedAt
+            });
+        }
+        // Array#shift is O(n); a saturated buffer would otherwise move every
+        // retained line on each append. Compaction is amortized O(1) per line.
+        if (this.head >= COMPACT_THRESHOLD
+            && this.head * 2 >= this.collected.length) {
+            this.collected.splice(0, this.head);
+            this.head = 0;
+        }
+    }
+    retained() {
+        return this.head === 0 ? this.collected : this.collected.slice(this.head);
+    }
+    addScopedPids(pids) {
+        for (const pid of pids) {
+            if (!Number.isInteger(pid) || pid <= 0) {
+                throw new Error("Logcat PID must be a positive integer");
+            }
+            this.scopedPids.add(pid);
+        }
+    }
+    droppedEvidence() {
+        const relevant = [
+            this.droppedByPid.get(undefined),
+            ...[...this.scopedPids].map((pid) => this.droppedByPid.get(pid))
+        ].filter((entry) => entry !== undefined);
+        if (relevant.length === 0) {
+            return undefined;
+        }
+        return {
+            lines: relevant.reduce((total, entry) => total + entry.lines, 0),
+            bytes: relevant.reduce((total, entry) => total + entry.bytes, 0),
+            lastDroppedAt: Math.max(...relevant.map((entry) => entry.lastDroppedAt))
+        };
     }
     async start(options) {
         if (this.running !== undefined) {
             throw new Error("Logcat collector already started");
         }
+        this.addScopedPids(options.pids ?? []);
         const logcatOptions = {
             deviceSerial: options.deviceSerial,
             onStdoutLine: (line) => {
-                this.collected.push(parseLine(line, this.clock.now()));
+                this.append(line);
             },
             onStderrLine: (line) => {
                 this.stderr.push(line);
+                if (this.stderr.length > 100) {
+                    this.stderr.shift();
+                }
             },
             ...(options.signal === undefined ? {} : { signal: options.signal })
         };
@@ -62,34 +141,43 @@ export class LogcatCollector {
         this.streamMetadata = { deviceSerial: options.deviceSerial };
         const startupResult = await this.running.started;
         if (startupResult !== undefined) {
-            throw new Error(startupFailure(startupResult));
+            throw new Error(this.stderr.join("\n").trim() || startupFailure(startupResult));
         }
     }
     scopeToPids(pids) {
         if (this.streamMetadata === undefined) {
             throw new Error("Logcat collector has not started");
         }
-        for (const pid of pids) {
-            if (!Number.isInteger(pid) || pid <= 0) {
-                throw new Error("Logcat PID must be a positive integer");
-            }
-            this.scopedPids.add(pid);
-        }
+        this.addScopedPids(pids);
     }
     metadata() {
         if (this.streamMetadata === undefined) {
             throw new Error("Logcat collector has not started");
         }
+        const dropped = this.droppedEvidence();
         return {
             deviceSerial: this.streamMetadata.deviceSerial,
-            pids: [...this.scopedPids].sort((left, right) => left - right)
+            pids: [...this.scopedPids].sort((left, right) => left - right),
+            ...(dropped === undefined ? {} : {
+                droppedLines: dropped.lines,
+                droppedBytes: dropped.bytes,
+                lastDroppedAtMs: dropped.lastDroppedAt
+            })
         };
     }
     lines() {
         if (this.scopedPids.size === 0) {
-            return [...this.collected];
+            return [];
         }
-        return this.collected.filter((line) => line.pid === undefined || this.scopedPids.has(line.pid));
+        return this.retained().filter((line) => line.pid !== undefined && this.scopedPids.has(line.pid));
+    }
+    /** Includes unparsed lines as raw artifacts, within the declared buffer limit. */
+    rawLines() {
+        return this.retained().filter((line) => line.pid === undefined || this.scopedPids.has(line.pid));
+    }
+    completeSince(startedAt) {
+        const dropped = this.droppedEvidence();
+        return dropped === undefined || dropped.lastDroppedAt < startedAt;
     }
     diagnosticLines() {
         return [...this.stderr];

package/dist/application/collector/logcat-event.d.ts

@@ -0,0 +1,8 @@
+import type { EventCapture, LogcatEventExpect } from "../../domain/logcat-event.js";
+import type { LogcatLine } from "./logcat-collector.js";
+/** Events are JSON objects in the message, with an `event` and `fields` object. */
+export declare function matchesLogcatEvent(line: LogcatLine, expect: LogcatEventExpect): boolean;
+/** Read only a declared field from the uniquely matched structured event. */
+export declare function captureLogcatEvent(line: LogcatLine, expect: LogcatEventExpect, capture: EventCapture): string | undefined;
+/** Only a stable, structured app-emitted class is accepted. */
+export declare function requestErrorClassFor(line: LogcatLine): "client" | "auth" | "network" | "server" | undefined;

package/dist/application/collector/logcat-event.js

@@ -0,0 +1,79 @@
+/** Events are JSON objects in the message, with an `event` and `fields` object. */
+export function matchesLogcatEvent(line, expect) {
+    if (line.pid === undefined || line.tag !== expect.tag
+        || line.message === undefined) {
+        return false;
+    }
+    let value;
+    try {
+        value = JSON.parse(line.message);
+    }
+    catch {
+        return false;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    if (record.event !== expect.event) {
+        return false;
+    }
+    const fields = record.fields;
+    if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
+        return false;
+    }
+    const facts = fields;
+    return Object.entries(expect.fields).every(([key, item]) => facts[key] === item)
+        && (expect.correlation === undefined
+            || facts[expect.correlation.key] === expect.correlation.value);
+}
+/** Read only a declared field from the uniquely matched structured event. */
+export function captureLogcatEvent(line, expect, capture) {
+    if (!matchesLogcatEvent(line, expect) || line.message === undefined)
+        return undefined;
+    const event = JSON.parse(line.message);
+    const key = capture.field ?? expect.correlation?.key;
+    if (key === undefined)
+        return undefined;
+    const value = event.fields[key];
+    if (capture.valueType === "integer") {
+        return typeof value === "number" && Number.isSafeInteger(value)
+            ? String(value) : undefined;
+    }
+    if (typeof value !== "string")
+        return undefined;
+    if (capture.valueType === "identifier") {
+        return /^[a-zA-Z0-9_-]{1,64}$/.test(value) ? value : undefined;
+    }
+    if (value.length === 0 || value.length > 128)
+        return undefined;
+    for (const character of value) {
+        const point = character.codePointAt(0) ?? 0;
+        if (point < 32 || point === 127)
+            return undefined;
+    }
+    return value;
+}
+/** Only a stable, structured app-emitted class is accepted. */
+export function requestErrorClassFor(line) {
+    if (line.message === undefined)
+        return undefined;
+    let event;
+    try {
+        event = JSON.parse(line.message);
+    }
+    catch {
+        return undefined;
+    }
+    if (event === null || typeof event !== "object" || Array.isArray(event)) {
+        return undefined;
+    }
+    const fields = event.fields;
+    if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
+        return undefined;
+    }
+    const value = fields.errorClass;
+    return value === "client" || value === "auth"
+        || value === "network" || value === "server"
+        ? value : undefined;
+}

package/dist/application/collector/logcat-stop.d.ts

@@ -0,0 +1,2 @@
+import type { CommandResult } from "../../ports/process-runner.js";
+export declare function logcatStopFailed(result: Pick<CommandResult, "exitCode" | "signal" | "timedOut" | "cancelled" | "terminationRequested" | "spawnError">): boolean;

package/dist/application/collector/logcat-stop.js

@@ -0,0 +1,11 @@
+export function logcatStopFailed(result) {
+    if (result.timedOut
+        || result.cancelled
+        || result.spawnError !== undefined) {
+        return true;
+    }
+    return result.exitCode !== 0
+        && !(result.terminationRequested === true
+            && (result.signal === "SIGTERM"
+                || result.signal === "SIGKILL"));
+}

package/dist/application/context/context-generator.d.ts

@@ -0,0 +1,45 @@
+import type { ProjectIdentityInspector } from "../../ports/project-identity-inspector.js";
+import type { ProjectModuleDiscoverer } from "../../ports/project-module-discoverer.js";
+import type { ContextDocumentWriter } from "../../ports/context-document-writer.js";
+import type { ProjectFileInspector } from "../../ports/project-file-inspector.js";
+import type { ProjectInventoryInspector } from "../../ports/project-inventory-inspector.js";
+export type ContextGenerateErrorCode = "CONTEXT_INVALID" | "MODULE_DISCOVERY_FAILED" | "IDENTITY_INSPECTION_FAILED" | "NO_EVIDENCE" | "CONTEXT_WRITE_FAILED" | "CONTEXT_ALREADY_EXISTS";
+export declare class ContextGenerateError extends Error {
+    readonly code: ContextGenerateErrorCode;
+    readonly name = "ContextGenerateError";
+    constructor(code: ContextGenerateErrorCode, message: string);
+}
+export interface ContextGenerateInput {
+    readonly projectRoot: string;
+    readonly contextPath: string;
+    readonly force?: boolean;
+}
+export interface ContextGenerateModuleResult {
+    readonly id: string;
+    readonly projectDir: string;
+    readonly kind: string;
+    readonly status: "notAnalyzed";
+    readonly evidenceCount: number;
+    readonly contextPath: string;
+    readonly sha256: string;
+}
+export interface ContextGenerateResult {
+    readonly status: "generated";
+    readonly packageName: string;
+    readonly launchActivity: string;
+    readonly modules: readonly ContextGenerateModuleResult[];
+    readonly indexHash: string;
+    readonly contextPath: string;
+}
+export interface ContextGeneratorDependencies {
+    readonly discoverer: ProjectModuleDiscoverer;
+    readonly identity: ProjectIdentityInspector;
+    readonly files: ProjectFileInspector;
+    readonly inventory: ProjectInventoryInspector;
+    readonly writer: ContextDocumentWriter;
+}
+export declare class ContextGenerator {
+    private readonly dependencies;
+    constructor(dependencies: ContextGeneratorDependencies);
+    readonly generate: (input: ContextGenerateInput) => Promise<ContextGenerateResult>;
+}

package/dist/application/context/context-generator.js

@@ -0,0 +1,228 @@
+import { isAbsolute, resolve } from "node:path";
+import { ProjectContextModuleSchema, ProjectContextSchema } from "../../domain/project-context.js";
+import { assertProjectPathUnder, CONTEXT_DIR } from "../../domain/workspace.js";
+import { projectRelativePath } from "../../shared/paths.js";
+import { compareStrings } from "../../shared/strings.js";
+import { MAX_CONTEXT_EVIDENCE_BYTES } from "./context-validator.js";
+import { semanticSha256 } from "./evidence-hash.js";
+export class ContextGenerateError extends Error {
+    code;
+    name = "ContextGenerateError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const INVENTORY_CATEGORIES = ["manifests", "sources", "layouts", "navigation"];
+const DEFAULT_INTERACTION_POLICY = {
+    allowedActions: ["click", "inputText", "back", "wait"],
+    confirmationRequiredActions: [],
+    forbiddenActions: []
+};
+const ROOT_EVIDENCE_CANDIDATES = [
+    "settings.gradle.kts",
+    "settings.gradle",
+    "build.gradle.kts",
+    "build.gradle",
+    "gradle.properties",
+    "gradle/libs.versions.toml"
+];
+function moduleIdToContextPath(moduleId) {
+    const sanitized = moduleId.replace(/^:/, "").replace(/:/g, "-");
+    return `${CONTEXT_DIR}/modules/${sanitized}.json`;
+}
+async function collectEvidence(files, projectRoot, paths) {
+    const evidence = [];
+    for (const path of paths) {
+        const inspection = await files.inspectProjectFile({
+            projectRoot,
+            relativePath: path,
+            maximumBytes: MAX_CONTEXT_EVIDENCE_BYTES
+        });
+        if (inspection.status === "inspected" && inspection.bytes !== undefined) {
+            evidence.push({
+                path: inspection.resolvedRelativePath,
+                sha256: inspection.sha256,
+                semanticSha256: semanticSha256(inspection.bytes)
+            });
+        }
+    }
+    return evidence;
+}
+async function collectRootEvidence(files, projectRoot) {
+    return collectEvidence(files, projectRoot, ROOT_EVIDENCE_CANDIDATES);
+}
+function buildShardDocument(module, evidence, pathSetSha256) {
+    const manifest = {
+        version: 1,
+        files: evidence.map((record) => ({
+            path: record.path,
+            sha256: record.sha256,
+            semanticSha256: record.semanticSha256,
+            confidence: "sourceConfirmed"
+        }))
+    };
+    return {
+        version: 2,
+        moduleId: module.id,
+        projectDir: module.projectDir,
+        status: "notAnalyzed",
+        inventory: {
+            version: 2,
+            pathSetSha256,
+            categories: [...INVENTORY_CATEGORIES]
+        },
+        manifest,
+        summary: {
+            features: [],
+            activities: [],
+            elements: [],
+            transitions: [],
+            logcat: []
+        }
+    };
+}
+function buildModuleReference(module, contextPath, sha256, dependsOn) {
+    return {
+        id: module.id,
+        projectDir: module.projectDir,
+        kind: module.kind,
+        contextPath,
+        sha256,
+        features: [],
+        activities: [],
+        dependsOn: [...dependsOn],
+        status: "notAnalyzed"
+    };
+}
+async function writeDocument(writer, projectRoot, relativePath, document) {
+    const result = await writer.writeContextDocument({
+        projectRoot,
+        relativePath,
+        document
+    });
+    if (result.status !== "written") {
+        throw new ContextGenerateError("CONTEXT_WRITE_FAILED", result.status === "escape"
+            ? `Context document resolves outside the project: ${relativePath}`
+            : `Context document cannot be written: ${relativePath}${"message" in result ? `: ${result.message}` : ""}`);
+    }
+    return result.sha256;
+}
+export class ContextGenerator {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    generate = async (input) => {
+        const contextRoot = input.projectRoot;
+        const contextPath = isAbsolute(input.contextPath)
+            ? input.contextPath
+            : resolve(contextRoot, input.contextPath);
+        const contextRelativePath = projectRelativePath(contextRoot, contextPath, (message) => new ContextGenerateError("CONTEXT_INVALID", message));
+        const documentRelativePath = contextRelativePath;
+        try {
+            assertProjectPathUnder(contextRoot, documentRelativePath, CONTEXT_DIR, "Project Context output");
+        }
+        catch (error) {
+            throw new ContextGenerateError("CONTEXT_INVALID", error instanceof Error ? error.message : String(error));
+        }
+        if (input.force !== true) {
+            const existing = await this.dependencies.files.inspectProjectFile({
+                projectRoot: contextRoot,
+                relativePath: documentRelativePath,
+                maximumBytes: 1
+            });
+            if (existing.status === "inspected") {
+                throw new ContextGenerateError("CONTEXT_ALREADY_EXISTS", `Project Context already exists: ${documentRelativePath} (use --force to overwrite)`);
+            }
+        }
+        const discovery = await this.dependencies.discoverer.discoverModules({
+            projectRoot: input.projectRoot
+        });
+        if (discovery.status !== "discovered") {
+            throw new ContextGenerateError("MODULE_DISCOVERY_FAILED", discovery.status === "noApplicationModule"
+                ? "No application module found in settings.gradle"
+                : discovery.status === "noSettingsFile"
+                    ? "No settings.gradle or settings.gradle.kts found"
+                    : `Module discovery failed: ${discovery.status}`);
+        }
+        const appModule = discovery.modules.find((module) => module.kind === "application");
+        if (appModule === undefined) {
+            throw new ContextGenerateError("MODULE_DISCOVERY_FAILED", "No application module found");
+        }
+        const identity = await this.dependencies.identity.inspectIdentity({
+            projectRoot: input.projectRoot,
+            moduleDir: appModule.projectDir
+        });
+        if (identity.status !== "inspected") {
+            throw new ContextGenerateError("IDENTITY_INSPECTION_FAILED", `Identity inspection failed: ${identity.status}`);
+        }
+        const moduleResults = [];
+        const moduleReferences = [];
+        for (const module of discovery.modules) {
+            const inventoryResult = await this.dependencies.inventory.inspectProjectInventory({
+                projectRoot: input.projectRoot,
+                projectDir: module.projectDir,
+                categories: [...INVENTORY_CATEGORIES]
+            });
+            if (inventoryResult.status !== "inspected") {
+                throw new ContextGenerateError("MODULE_DISCOVERY_FAILED", `Unable to inspect module inventory: ${module.id}`);
+            }
+            const evidence = await collectEvidence(this.dependencies.files, input.projectRoot, inventoryResult.paths);
+            if (evidence.length === 0) {
+                throw new ContextGenerateError("NO_EVIDENCE", `No evidence files collected for module: ${module.id}`);
+            }
+            const shardPath = moduleIdToContextPath(module.id);
+            const shardDocument = buildShardDocument(module, evidence, inventoryResult.pathSetSha256);
+            const parsed = ProjectContextModuleSchema.safeParse(shardDocument);
+            if (!parsed.success) {
+                throw new ContextGenerateError("CONTEXT_INVALID", `Generated shard does not match module schema: ${module.id}`);
+            }
+            const shardSha256 = await writeDocument(this.dependencies.writer, contextRoot, shardPath, parsed.data);
+            moduleResults.push({
+                id: module.id,
+                projectDir: module.projectDir,
+                kind: module.kind,
+                status: "notAnalyzed",
+                evidenceCount: evidence.length,
+                contextPath: shardPath,
+                sha256: shardSha256
+            });
+            moduleReferences.push(buildModuleReference(module, shardPath, shardSha256, module.dependsOn));
+        }
+        moduleReferences.sort((a, b) => compareStrings(a.id, b.id));
+        const rootEvidence = await collectRootEvidence(this.dependencies.files, input.projectRoot);
+        if (rootEvidence.length === 0) {
+            throw new ContextGenerateError("NO_EVIDENCE", "No root evidence files collected");
+        }
+        const indexDocument = {
+            version: 2,
+            packageName: identity.packageName,
+            launchActivity: identity.launchActivity,
+            manifest: {
+                version: 1,
+                files: rootEvidence.map((record) => ({
+                    path: record.path,
+                    sha256: record.sha256,
+                    semanticSha256: record.semanticSha256,
+                    confidence: "sourceConfirmed"
+                }))
+            },
+            interactionPolicy: { ...DEFAULT_INTERACTION_POLICY },
+            modules: moduleReferences
+        };
+        const parsedIndex = ProjectContextSchema.safeParse(indexDocument);
+        if (!parsedIndex.success) {
+            throw new ContextGenerateError("CONTEXT_INVALID", "Generated index does not match the version 2 schema");
+        }
+        const indexHash = await writeDocument(this.dependencies.writer, contextRoot, documentRelativePath, parsedIndex.data);
+        return {
+            status: "generated",
+            packageName: identity.packageName,
+            launchActivity: identity.launchActivity,
+            modules: moduleResults,
+            indexHash,
+            contextPath: contextRelativePath
+        };
+    };
+}

package/dist/application/context/context-loader.d.ts

@@ -0,0 +1,40 @@
+import { type ProjectContext, type ProjectContextModule, type ResolvedProjectContext } from "../../domain/project-context.js";
+import type { ProjectFileInspector } from "../../ports/project-file-inspector.js";
+import type { ProjectInventoryInspector } from "../../ports/project-inventory-inspector.js";
+export declare const MAX_CONTEXT_SHARD_BYTES: number;
+export type ContextLoadErrorCode = "CONTEXT_INVALID" | "CONTEXT_STALE" | "CONTEXT_MODULE_NOT_FOUND" | "CONTEXT_MODULE_INCOMPLETE";
+export declare class ContextLoadError extends Error {
+    readonly code: ContextLoadErrorCode;
+    readonly name = "ContextLoadError";
+    constructor(code: ContextLoadErrorCode, message: string);
+}
+export interface LoadedProjectContext {
+    context: ResolvedProjectContext;
+    bundle: ProjectContext;
+    modules: ProjectContextModule[];
+}
+export interface LoadedContextIndex {
+    bundle: ProjectContext;
+    indexHash: string;
+}
+export interface ContextLoadInput {
+    projectRoot: string;
+    contextPath: string;
+    moduleIds?: string[] | undefined;
+    allowIncomplete?: boolean | undefined;
+}
+export interface ContextLoaderDependencies {
+    files: ProjectFileInspector;
+    inventory: ProjectInventoryInspector;
+    readJson: (path: string) => Promise<unknown>;
+}
+export declare class ContextLoader {
+    private readonly dependencies;
+    constructor(dependencies: ContextLoaderDependencies);
+    private readonly readStableDocument;
+    readonly readIndex: (input: {
+        projectRoot: string;
+        contextPath: string;
+    }) => Promise<LoadedContextIndex>;
+    readonly load: (input: ContextLoadInput) => Promise<LoadedProjectContext>;
+}