Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

11.8 KB
Raw Blame
import { createReadStream } from "node:fs";
import { open } from "node:fs/promises";
import { join } from "node:path";

import { AnalysisError } from "../domain/analysisErrorBase.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import {
  AnalysisCancelledError,
  AnalysisResourceConstraintError,
} from "../domain/analysisErrorCore.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { err, ok, type Result } from "../domain/result.js";
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
import {
  RegularFileCancelled,
  RegularFileCleanupFailure,
  withOwnedFileHandle,
} from "../filesystem/OwnedRegularFile.js";
import { RegularFileOperationCancelled } from "../filesystem/RegularFile.js";
import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";
import type { KunaProject } from "./KunaProjectCache.js";
import {
  scanKunaAssembly,
  type KunaAssemblyIndex,
  type KunaProjectFunction,
} from "./KunaProjectFiles.js";
import { KUNA_PROVIDER_ID } from "./KunaRelease.js";
import { KUNA_FUNCTION_TEXT_BYTES } from "./KunaLimits.js";
import { kunaUnavailable } from "./KunaUnavailable.js";

/** The exact producing range for one facet, including a failed C block. */
export interface KunaProjectFileSpan {
  readonly facet: "pseudocode" | "assembly";
  readonly path: string;
  readonly byteOffset: number;
  readonly byteLength: number;
}

export interface KunaProjectText {
  readonly result: string | null;
  readonly files?: readonly KunaProjectFileSpan[];
  readonly limitations: readonly string[];
}

/** Session scope that adopts a span descriptor before the read opens it. */
export interface KunaSpanOwnership {
  readonly retainFailedClose?: (path: string, owner: OwnedFileHandle) => void;
  readonly bindSpanCleanup?: (
    owner: OwnedFileHandle,
    marker: ProviderCleanupError,
  ) => void;
  /**
   * Check retained cleanup and open one descriptor. The session holds this
   * together with finishSpan so a failed close is retained before the next open.
   */
  readonly admitSpan?: <T>(
    operation: string,
    signal: AbortSignal | undefined,
    open: () => Promise<T>,
  ) => Promise<Result<T, AnalysisError>>;
  /** Close one admitted descriptor before another span may open. */
  readonly finishSpan?: <T>(finish: () => Promise<T>) => Promise<T>;
}

const readSpan = async (
  operation: string,
  path: string,
  offset: number,
  length: number,
  ownership: KunaSpanOwnership,
  signal?: AbortSignal,
): Promise<Result<string, AnalysisError>> => {
  if (length > KUNA_FUNCTION_TEXT_BYTES)
    return err(
      new AnalysisResourceConstraintError(
        operation,
        "capacity",
        "Kuna's function text exceeds the buffered source-facet capacity; the complete export remains accessible locally.",
        {
          limit_bytes: KUNA_FUNCTION_TEXT_BYTES,
          requested_bytes: length,
          file: path,
          byte_offset: offset,
        },
      ),
    );
  const callerAborted = (): AbortSignal | undefined =>
    signal?.aborted === true ? signal : undefined;
  const cancelled = callerAborted();
  if (cancelled !== undefined)
    return err(
      new AnalysisCancelledError(operation, { cause: cancelled.reason }),
    );
  const opened =
    ownership.admitSpan === undefined
      ? ok(await open(path, "r"))
      : await ownership.admitSpan(operation, signal, () => open(path, "r"));
  if (!opened.ok) return opened;
  const owner = new OwnedFileHandle(opened.value);
  let text: string | undefined;
  let readFailure: unknown;
  try {
    const buffer = Buffer.alloc(length);
    const { bytesRead } = await owner.handle.read(buffer, 0, length, offset);
    if (bytesRead !== length)
      throw new Error(`${path} is shorter than its recorded span`);
    text = buffer.toString("utf8");
  } catch (cause: unknown) {
    readFailure = cause;
  }
  const finish = () =>
    withOwnedFileHandle(
      path,
      owner,
      {
        // A failed read keeps its own diagnostic. A completed read records
        // cancellation when the caller aborts before the queued close settles.
        ...(readFailure === undefined && signal !== undefined
          ? { signal }
          : {}),
        ...(ownership.retainFailedClose === undefined
          ? {}
          : {
              retainFailedClose: (failed) =>
                ownership.retainFailedClose?.(path, failed),
            }),
      },
      async () => {
        if (readFailure !== undefined) throw readFailure;
        return text ?? "";
      },
    );
  try {
    const value =
      ownership.finishSpan === undefined
        ? await finish()
        : await ownership.finishSpan(finish);
    return ok(value);
  } catch (cause: unknown) {
    if (cause instanceof RegularFileCleanupFailure)
      return err(
        spanCloseFailure(
          operation,
          path,
          offset,
          length,
          spanCloseAfterRead(cause, text, readFailure, signal),
          ownership,
        ),
      );
    // Close succeeded. The caller's abort reason is the cancellation cause,
    // not the wrapper thrown after that close.
    const aborted = callerAborted();
    if (
      aborted !== undefined &&
      (cause instanceof RegularFileOperationCancelled ||
        cause instanceof RegularFileCancelled)
    )
      return err(
        new AnalysisCancelledError(operation, { cause: aborted.reason }),
      );
    throw cause;
  }
};

/**
 * Finalization checks the signal before replaying a read that already
 * finished. Put that text back on the close failure so cancellation stays
 * the primary error and the descriptor stays retained.
 */
const spanCloseAfterRead = (
  failure: RegularFileCleanupFailure<string>,
  text: string | undefined,
  readFailure: unknown,
  signal: AbortSignal | undefined,
): RegularFileCleanupFailure<string> => {
  if (
    failure.completionCancellation !== undefined ||
    text === undefined ||
    readFailure !== undefined ||
    signal?.aborted !== true ||
    failure.outcome.kind !== "failed" ||
    !(failure.outcome.cause instanceof RegularFileOperationCancelled)
  )
    return failure;
  return new RegularFileCleanupFailure(
    failure.path,
    failure.owner,
    { kind: "completed", value: text },
    failure.cleanupCause,
    failure.retention,
    { reason: signal.reason },
  );
};

/** Keep the span text or the short-read diagnostic with the exact handle. */
const spanCloseFailure = (
  operation: string,
  path: string,
  offset: number,
  length: number,
  failure: RegularFileCleanupFailure<string>,
  ownership: KunaSpanOwnership,
): AnalysisError => {
  const reason =
    failure.cleanupCause instanceof Error
      ? failure.cleanupCause.message
      : String(failure.cleanupCause);
  const completed = failure.outcome.kind === "completed";
  const marker = new ProviderCleanupError(
    KUNA_PROVIDER_ID,
    [failure.path],
    {
      reason,
      path,
      byte_offset: offset,
      byte_length: length,
      span_read: completed ? "completed" : "failed",
      ...(completed ? { span_text: failure.outcome.value } : {}),
    },
    { operation, cause: failure },
  );
  ownership.bindSpanCleanup?.(failure.owner, marker);
  if (failure.completionCancellation !== undefined)
    return analysisErrorWithCleanupFailure(
      new AnalysisCancelledError(operation, {
        cause: failure.completionCancellation.reason,
      }),
      marker,
      operation,
    ).bindCleanupDependencies([marker]);
  if (failure.outcome.kind !== "failed") return marker;
  const primaryCause = failure.outcome.cause;
  const primary =
    primaryCause instanceof AnalysisError
      ? primaryCause
      : new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
          cause: primaryCause,
          userMessage:
            primaryCause instanceof Error
              ? primaryCause.message
              : String(primaryCause),
        });
  return analysisErrorWithCleanupFailure(
    primary,
    marker,
    operation,
  ).bindCleanupDependencies([marker]);
};

/** One immutable export owns both its text ranges and its parsed label indexes. */
export class KunaProjectReader {
  #blocks: ReadonlyMap<string, KunaProjectFunction> | undefined;
  #assembly: Promise<Result<KunaAssemblyIndex, string>> | undefined;

  constructor(
    readonly project: KunaProject,
    readonly lifetime: {
      readonly signal: AbortSignal;
      readonly own: <T>(work: Promise<T>) => Promise<T>;
    } & KunaSpanOwnership,
  ) {}

  async pseudocode(
    address: string,
    operation: string,
    signal?: AbortSignal,
  ): Promise<Result<KunaProjectText, AnalysisError>> {
    this.#blocks ??= new Map(
      this.project.functions.map((block) => [block.address, block]),
    );
    const block = this.#blocks.get(address);
    if (block === undefined)
      return ok({
        result: null,
        limitations: [
          "Kuna's export decompiles code entries only; this inventory entry, such as an import slot, has no body.",
        ],
      });
    const files = [
      {
        facet: "pseudocode" as const,
        path: this.project.manifest.files.c.path,
        byteOffset: block.cOffset,
        byteLength: block.cLength,
      },
    ];
    if (block.error !== null)
      return ok({
        result: null,
        files,
        limitations: [`Kuna could not decompile this function: ${block.error}`],
      });
    const text = await readSpan(
      operation,
      join(this.project.directory, this.project.manifest.files.c.path),
      block.cOffset,
      block.cLength,
      this.lifetime,
      signal ?? this.lifetime.signal,
    );
    if (!text.ok) return text;
    return ok({
      result: text.value
        .slice(text.value.indexOf("\n") + 1)
        .replace(/\n+$/u, ""),
      files,
      limitations: [],
    });
  }

  async assembly(
    address: string,
    operation: string,
    signal?: AbortSignal,
  ): Promise<Result<KunaProjectText, AnalysisError>> {
    const index = await this.#index(operation, signal);
    if (!index.ok) return index;
    const span = index.value.code.get(address);
    if (span === undefined)
      return err(
        kunaUnavailable(
          operation,
          `Kuna's export lists no code at ${address}; import slots and data entries have no listing.`,
        ),
      );
    const text = await readSpan(
      operation,
      join(this.project.directory, this.project.manifest.files.asm.path),
      span.offset,
      span.length,
      this.lifetime,
      signal ?? this.lifetime.signal,
    );
    if (!text.ok) return text;
    return ok({
      result: text.value.replace(/\n+$/u, ""),
      files: [
        {
          facet: "assembly",
          path: this.project.manifest.files.asm.path,
          byteOffset: span.offset,
          byteLength: span.length,
        },
      ],
      limitations: [],
    });
  }

  async dataName(
    address: string,
    operation: string,
    signal?: AbortSignal,
  ): Promise<Result<string | null, AnalysisError>> {
    const index = await this.#index(operation, signal);
    return index.ok ? ok(index.value.data.get(address) ?? null) : index;
  }

  async #index(
    operation: string,
    signal: AbortSignal | undefined,
  ): Promise<Result<KunaAssemblyIndex, AnalysisError>> {
    this.#assembly ??= this.lifetime.own(
      scanKunaAssembly(
        createReadStream(
          join(this.project.directory, this.project.manifest.files.asm.path),
          { signal: this.lifetime.signal },
        ),
      ),
    );
    const index = await waitForAbortable(this.#assembly, signal);
    if (index === ABORTED)
      return err(
        new AnalysisCancelledError(operation, { cause: signal?.reason }),
      );
    return index.ok
      ? index
      : err(
          new ProviderAdapterError(KUNA_PROVIDER_ID, operation, {
            userMessage: `Kuna's .asm cannot be indexed: ${index.error}`,
          }),
        );
  }
}