import type { Readable } from "node:stream"; import type { ArtifactCommand, ArtifactInventoryCoverage, } from "../domain/artifactGraph.js"; import type { ZipPackageFormat } from "../domain/zipPackageFormat.js"; import type { AnalysisCleanupObservation, AnalysisPartialObservation, } from "../domain/analysisErrorBase.js"; export interface ArtifactReaderFailureOptions extends ErrorOptions { readonly cleanup?: AnalysisCleanupObservation; readonly partialObservation?: AnalysisPartialObservation; } /** Archive-neutral entry metadata. Reader adapters never choose output paths. */ export interface ArtifactEntry { readonly path: string; readonly kind: "file" | "directory" | "symlink" | "slice"; readonly declaredSize: number | null; readonly compressedSize: number | null; readonly executable: boolean; readonly encrypted: boolean; readonly byteOffset: number | null; readonly declaredSha256: string | null; readonly unpacked: boolean; readonly limitations: readonly string[]; readonly adapterKey: string; /** Filesystem identity captured during traversal, when supplied by an adapter. */ readonly sourceIdentity?: { readonly device: bigint; readonly inode: bigint; readonly size: bigint; readonly mode: bigint; readonly mtimeNs: bigint; readonly ctimeNs: bigint; }; } /** Compare captured filesystem identity and mutable metadata at a read boundary. */ export const sameArtifactSourceIdentity = ( expected: ArtifactEntry["sourceIdentity"], observed: { readonly dev: bigint; readonly ino: bigint; readonly size: bigint; readonly mode: bigint; readonly mtimeNs: bigint; readonly ctimeNs: bigint; }, ): boolean => expected !== undefined && observed.dev === expected.device && observed.ino === expected.inode && observed.size === expected.size && observed.mode === expected.mode && observed.mtimeNs === expected.mtimeNs && observed.ctimeNs === expected.ctimeNs; /** Snapshot mutable entry metadata before the producer later validates open(). */ export const copyArtifactEntry = (entry: ArtifactEntry): ArtifactEntry => ({ ...entry, limitations: [...entry.limitations], ...(entry.sourceIdentity === undefined ? {} : { sourceIdentity: { ...entry.sourceIdentity } }), }); /** Compare every portable and adapter-owned fact supplied with an entry. */ export const sameArtifactEntry = ( entry: ArtifactEntry, produced: ArtifactEntry, ): boolean => entry.path === produced.path && entry.kind === produced.kind && entry.declaredSize === produced.declaredSize && entry.compressedSize === produced.compressedSize && entry.executable === produced.executable && entry.encrypted === produced.encrypted && entry.byteOffset === produced.byteOffset && entry.declaredSha256 === produced.declaredSha256 && entry.unpacked === produced.unpacked && entry.adapterKey === produced.adapterKey && entry.limitations.length === produced.limitations.length && entry.limitations.every( (limitation, index) => limitation === produced.limitations[index], ) && entry.sourceIdentity?.device === produced.sourceIdentity?.device && entry.sourceIdentity?.inode === produced.sourceIdentity?.inode && entry.sourceIdentity?.size === produced.sourceIdentity?.size && entry.sourceIdentity?.mode === produced.sourceIdentity?.mode && entry.sourceIdentity?.mtimeNs === produced.sourceIdentity?.mtimeNs && entry.sourceIdentity?.ctimeNs === produced.sourceIdentity?.ctimeNs; /** One entry or subtree deliberately excluded from a traversal. */ export interface ArtifactTraversalOmission { readonly path: string; readonly kind: | "fifo" | "socket" | "block-device" | "character-device" | "unsupported" | "directory-descendants"; } /** Facts from an exhausted traversal, separate from entry content certainty. */ export interface ArtifactReaderTraversal { readonly status: ArtifactInventoryCoverage["status"]; readonly limitations: readonly string[]; } /** Per-iterator observation sink; adapters report intentional omissions without shared state. */ export interface ArtifactTraversalOptions { readonly onOmission?: (omission: ArtifactTraversalOmission) => void; } /** Read-only adapter over one directory, archive, or virtual container. */ export interface ArtifactReader { readonly format: "directory" | ZipPackageFormat | "asar" | "file"; entries( signal?: AbortSignal, options?: ArtifactTraversalOptions, ): AsyncIterable; open(entry: ArtifactEntry, signal?: AbortSignal): Promise; provenance(): readonly ArtifactCommand[]; close(): Promise; } /** Typed adapter failure translated at provider boundary. */ export class ArtifactReaderFailure extends Error { readonly cleanup: AnalysisCleanupObservation | undefined; readonly partialObservation: AnalysisPartialObservation | undefined; constructor( readonly reason: | "cancelled" | "format" | "integrity" | "io" | "limit" | "path" | "unavailable", message: string, options?: ArtifactReaderFailureOptions, readonly details?: Readonly<{ logicalPath: string; declaredSha256: string | null; calculatedSha256: string | null; unpacked: boolean; }>, ) { super(message, options); this.name = "ArtifactReaderFailure"; this.cleanup = options?.cleanup; this.partialObservation = options?.partialObservation; } /** Preserve the primary failure while attaching cleanup and any complete observation. */ static withCleanup( cause: unknown, cleanup: AnalysisCleanupObservation, partialObservation?: AnalysisPartialObservation, ): ArtifactReaderFailure { const primary = cause instanceof ArtifactReaderFailure ? cause : new ArtifactReaderFailure("io", errorMessage(cause), { cause }); const mergedObservation = partialObservation ?? primary.partialObservation; return new ArtifactReaderFailure( primary.reason, primary.message, { cause: primary, cleanup: combineCleanup(primary.cleanup, cleanup), ...(mergedObservation === undefined ? {} : { partialObservation: mergedObservation }), }, primary.details, ); } /** Give otherwise opaque cleanup failures a concrete owned resource. */ static cleanupObservation( cause: unknown, resource: string, ): AnalysisCleanupObservation { if (cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined) return cause.cleanup; return { reason: errorMessage(cause), resources: [resource] }; } } const combineCleanup = ( primary: AnalysisCleanupObservation | undefined, cleanup: AnalysisCleanupObservation, ): AnalysisCleanupObservation => primary === undefined || primary === cleanup ? cleanup : { reason: `${primary.reason}; ${cleanup.reason}`, resources: [...new Set([...primary.resources, ...cleanup.resources])], }; const errorMessage = (cause: unknown): string => cause instanceof Error ? cause.message : String(cause);