fix(artifacts): compare inventories using declared coverage (#2214)
* fix(artifacts): preserve complete root inventory comparisons * fix(artifacts): declare inventory coverage before comparison * fix(artifacts): preserve traversal omissions and materialization limits * fix(artifacts): preserve coverage declarations and projection scope Remove the duplicate inventory-schema import. Compare original coverage declarations, including field omission, before adapting legacy pages. Require explicit scope for completeness and container-entry coverage for application projections. Source inspection and git diff --check only. Tests, builds and typechecks skipped by explicit user request. GitHub review writes paused globally. * fix(artifacts): require entry coverage for child changes * fix(artifacts): accept source-valid inventory limitations * style(artifacts): format mobile graph projection --------- Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> Co-authored-by: OpenAI Codex <openai-codex@users.noreply.github.com>
This commit is contained in:
co-authored by
morluto
OpenAI Codex
parent
e4186af31b
commit
45a3509db3
@@ -1,5 +1,8 @@
|
||||
import type { Readable } from "node:stream";
|
||||
import type { ArtifactCommand } from "../domain/artifactGraph.js";
|
||||
import type {
|
||||
ArtifactCommand,
|
||||
ArtifactInventoryCoverage,
|
||||
} from "../domain/artifactGraph.js";
|
||||
import type { ZipPackageFormat } from "../domain/zipPackageFormat.js";
|
||||
import type {
|
||||
AnalysisCleanupObservation,
|
||||
@@ -90,10 +93,36 @@ export const sameArtifactEntry = (
|
||||
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): AsyncIterable<ArtifactEntry>;
|
||||
entries(
|
||||
signal?: AbortSignal,
|
||||
options?: ArtifactTraversalOptions,
|
||||
): AsyncIterable<ArtifactEntry>;
|
||||
open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable>;
|
||||
provenance(): readonly ArtifactCommand[];
|
||||
close(): Promise<void>;
|
||||
|
||||
@@ -14,12 +14,18 @@ import {
|
||||
sameArtifactSourceIdentity,
|
||||
type ArtifactEntry,
|
||||
type ArtifactReader,
|
||||
type ArtifactTraversalOmission,
|
||||
type ArtifactTraversalOptions,
|
||||
} from "./ArtifactReader.js";
|
||||
import { hostExecutableMarking } from "./hostExecutableMarking.js";
|
||||
import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
|
||||
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
|
||||
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
|
||||
|
||||
interface DirectoryTraversalOptions extends ArtifactTraversalOptions {
|
||||
readonly descendInto?: (path: string) => boolean;
|
||||
}
|
||||
|
||||
/** Non-symlink-following directory reader. */
|
||||
export class DirectoryArtifactReader implements ArtifactReader {
|
||||
readonly format = "directory" as const;
|
||||
@@ -35,9 +41,11 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
/** Enumerate entries, optionally restricting descent while retaining directories. */
|
||||
async *entries(
|
||||
signal?: AbortSignal,
|
||||
descendInto?: (path: string) => boolean,
|
||||
selection?: DirectoryTraversalOptions | ((path: string) => boolean),
|
||||
): AsyncIterable<ArtifactEntry> {
|
||||
const root = await this.#resolveRoot();
|
||||
const options =
|
||||
typeof selection === "function" ? { descendInto: selection } : selection;
|
||||
const pending = [root];
|
||||
while (pending.length > 0) {
|
||||
abortIfNeeded(signal);
|
||||
@@ -50,7 +58,7 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
directory,
|
||||
pending,
|
||||
signal,
|
||||
descendInto,
|
||||
options,
|
||||
))
|
||||
yield entry;
|
||||
await withDirectoryIoContext("inspect directory", directory, () =>
|
||||
@@ -75,7 +83,7 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
directory: string,
|
||||
pending: string[],
|
||||
signal?: AbortSignal,
|
||||
descendInto?: (path: string) => boolean,
|
||||
options?: DirectoryTraversalOptions,
|
||||
): AsyncIterable<ArtifactEntry> {
|
||||
const root = await this.#resolveRoot();
|
||||
const handle = new OwnedDirectoryHandle(
|
||||
@@ -103,10 +111,16 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
);
|
||||
const path = relative(root, absolute).split(sep).join("/");
|
||||
const entry = artifactEntry(path, absolute, metadata);
|
||||
if (entry === undefined) continue;
|
||||
if (entry === undefined) {
|
||||
options?.onOmission?.({ path, kind: unsupportedEntryKind(metadata) });
|
||||
continue;
|
||||
}
|
||||
yield entry;
|
||||
if (entry.kind === "directory" && (descendInto?.(path) ?? true))
|
||||
childDirectories.push(absolute);
|
||||
if (entry.kind === "directory") {
|
||||
if (options?.descendInto?.(path) ?? true)
|
||||
childDirectories.push(absolute);
|
||||
else options?.onOmission?.({ path, kind: "directory-descendants" });
|
||||
}
|
||||
}
|
||||
} catch (cause: unknown) {
|
||||
traversal = {
|
||||
@@ -256,6 +270,19 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
}
|
||||
}
|
||||
|
||||
const unsupportedEntryKind = (
|
||||
metadata: BigIntStats,
|
||||
): ArtifactTraversalOmission["kind"] =>
|
||||
metadata.isFIFO()
|
||||
? "fifo"
|
||||
: metadata.isSocket()
|
||||
? "socket"
|
||||
: metadata.isBlockDevice()
|
||||
? "block-device"
|
||||
: metadata.isCharacterDevice()
|
||||
? "character-device"
|
||||
: "unsupported";
|
||||
|
||||
const artifactEntry = (
|
||||
path: string,
|
||||
absolute: string,
|
||||
|
||||
@@ -8,6 +8,7 @@ import {
|
||||
ArtifactReaderFailure,
|
||||
type ArtifactEntry,
|
||||
type ArtifactReader,
|
||||
type ArtifactTraversalOptions,
|
||||
} from "./ArtifactReader.js";
|
||||
import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
|
||||
import {
|
||||
@@ -149,13 +150,24 @@ export class NativeDmgArtifactReader implements ArtifactReader {
|
||||
this.host = host ?? createSystemHost(environment);
|
||||
}
|
||||
|
||||
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
|
||||
async *entries(
|
||||
signal?: AbortSignal,
|
||||
options?: ArtifactTraversalOptions,
|
||||
): AsyncIterable<ArtifactEntry> {
|
||||
await this.#ensureAttached(signal);
|
||||
const directory = this.#directory;
|
||||
if (directory === undefined)
|
||||
throw new ArtifactReaderFailure("unavailable", "DMG is not attached");
|
||||
const prefix = basename(this.path);
|
||||
const entries = directory.entries(signal)[Symbol.asyncIterator]();
|
||||
const entries = directory
|
||||
.entries(signal, {
|
||||
onOmission: (omission) =>
|
||||
options?.onOmission?.({
|
||||
...omission,
|
||||
path: `${prefix}/${omission.path}`,
|
||||
}),
|
||||
})
|
||||
[Symbol.asyncIterator]();
|
||||
try {
|
||||
for (;;) {
|
||||
if (this.#closed) return;
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import type { ArtifactReader } from "../ArtifactReader.js";
|
||||
import type {
|
||||
ArtifactReader,
|
||||
ArtifactReaderTraversal,
|
||||
} from "../ArtifactReader.js";
|
||||
import { DirectoryArtifactReader } from "../DirectoryArtifactReader.js";
|
||||
import { MachOSliceArtifactReader } from "../MachOSliceArtifactReader.js";
|
||||
import { NativeDmgArtifactReader } from "../NativeDmgArtifactReader.js";
|
||||
@@ -7,7 +10,6 @@ import { ZipArtifactReader } from "../ZipArtifactReader.js";
|
||||
import type {
|
||||
ArtifactInventoryCoverage,
|
||||
ArtifactOccurrence,
|
||||
IntegrityContradiction,
|
||||
} from "../../domain/artifactGraph.js";
|
||||
import {
|
||||
isZipPackageFormat,
|
||||
@@ -40,42 +42,47 @@ export const createReader = (
|
||||
}
|
||||
};
|
||||
|
||||
/** Classify source coverage and preserve its user-facing explanation once. */
|
||||
export const inventoryAssessment = (
|
||||
/** Decide traversal scope and availability once, independently of diagnostic wording. */
|
||||
export const inventoryCoverage = (
|
||||
format: ArtifactOccurrence["artifact_format"],
|
||||
reader: ArtifactReader | undefined,
|
||||
integrityContradictions: readonly IntegrityContradiction[],
|
||||
caseCollisionLimitation: string | undefined,
|
||||
traversal: ArtifactReaderTraversal,
|
||||
): {
|
||||
readonly coverage_status: ArtifactInventoryCoverage;
|
||||
readonly coverage: ArtifactInventoryCoverage;
|
||||
readonly limitations: string[];
|
||||
} => {
|
||||
let coverageStatus: ArtifactInventoryCoverage = "complete";
|
||||
const limitations: string[] = [];
|
||||
if (reader !== undefined) {
|
||||
if (isZipPackageFormat(reader.format))
|
||||
limitations.push(ZIP_NON_ENTRY_TAIL_LIMITATION);
|
||||
} else if (format === "dmg" || format === "pkg") {
|
||||
coverageStatus = "partial";
|
||||
limitations.push(
|
||||
`${format.toUpperCase()} root hash is observed; child inventory requires a native macOS adapter.`,
|
||||
);
|
||||
} else if (format === "mach-o-universal" && process.platform !== "darwin") {
|
||||
coverageStatus = "partial";
|
||||
limitations.push(
|
||||
"Universal Mach-O slices require the native macOS lipo adapter.",
|
||||
);
|
||||
} else {
|
||||
// The graph's modeled scope is the root itself for recognized leaf formats.
|
||||
limitations.push("Artifact has no child container entries.");
|
||||
}
|
||||
if (caseCollisionLimitation !== undefined) {
|
||||
coverageStatus = "partial";
|
||||
limitations.push(caseCollisionLimitation);
|
||||
}
|
||||
if (integrityContradictions.length > 0)
|
||||
limitations.push(
|
||||
`${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
|
||||
);
|
||||
return { coverage_status: coverageStatus, limitations };
|
||||
if (reader !== undefined)
|
||||
return {
|
||||
coverage: { scope: "container-entries", status: traversal.status },
|
||||
limitations: [
|
||||
...(isZipPackageFormat(reader.format)
|
||||
? [ZIP_NON_ENTRY_TAIL_LIMITATION]
|
||||
: []),
|
||||
...traversal.limitations,
|
||||
],
|
||||
};
|
||||
// dmg and pkg reach here only after classifyRootFormat matched their bytes.
|
||||
if (format === "dmg" || format === "pkg")
|
||||
return {
|
||||
coverage: { scope: "container-entries", status: "unknown" },
|
||||
limitations: [
|
||||
`${format.toUpperCase()} root hash is observed; child inventory requires a native macOS adapter.`,
|
||||
],
|
||||
};
|
||||
if (format === "mach-o-universal")
|
||||
return {
|
||||
coverage: { scope: "container-entries", status: "unknown" },
|
||||
limitations: [
|
||||
"Universal Mach-O slices require the native macOS lipo adapter.",
|
||||
],
|
||||
};
|
||||
if (isZipPackageFormat(format) || format === "directory" || format === "asar")
|
||||
return {
|
||||
coverage: { scope: "container-entries", status: "unknown" },
|
||||
limitations: [`${format} child inventory reader is unavailable.`],
|
||||
};
|
||||
return {
|
||||
coverage: { scope: "root", status: "complete" },
|
||||
limitations: ["Artifact has no child container entries."],
|
||||
};
|
||||
};
|
||||
|
||||
@@ -10,6 +10,7 @@ import type { RootInventorySource } from "./classify.js";
|
||||
import {
|
||||
ArtifactReaderFailure,
|
||||
type ArtifactReader,
|
||||
type ArtifactReaderTraversal,
|
||||
} from "../ArtifactReader.js";
|
||||
import type { ArtifactResourceOwner } from "../ArtifactResourceScope.js";
|
||||
import {
|
||||
@@ -40,7 +41,7 @@ import {
|
||||
hashStableRootArtifact,
|
||||
hashStableRootArtifactHandle,
|
||||
} from "./hashStableRootArtifact.js";
|
||||
import { createReader, inventoryAssessment } from "./reader.js";
|
||||
import { createReader, inventoryCoverage } from "./reader.js";
|
||||
import {
|
||||
scanReader,
|
||||
type PendingIntegrityContradiction,
|
||||
@@ -99,6 +100,7 @@ export const scanCanonicalArtifactInventoryInScope = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation,
|
||||
traversal,
|
||||
} = await scanReader(reader, ownedReaders, options.signal, integrity);
|
||||
outcome = {
|
||||
kind: "completed",
|
||||
@@ -115,6 +117,7 @@ export const scanCanonicalArtifactInventoryInScope = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation,
|
||||
traversal,
|
||||
}),
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
@@ -196,6 +199,7 @@ interface SnapshotBuildInput {
|
||||
readonly occurrences: MutableOccurrence[];
|
||||
readonly pendingContradictions: PendingIntegrityContradiction[];
|
||||
readonly caseCollisionLimitation: string | undefined;
|
||||
readonly traversal: ArtifactReaderTraversal;
|
||||
}
|
||||
|
||||
const buildInventorySnapshot = async (
|
||||
@@ -268,12 +272,7 @@ const buildInventorySnapshot = async (
|
||||
orderedOccurrences,
|
||||
orderedEdges,
|
||||
});
|
||||
const assessment = inventoryAssessment(
|
||||
rootFormat,
|
||||
reader,
|
||||
integrityContradictions,
|
||||
input.caseCollisionLimitation,
|
||||
);
|
||||
const traversal = inventoryCoverage(rootFormat, reader, input.traversal);
|
||||
return {
|
||||
manifest,
|
||||
nodes: orderedNodes,
|
||||
@@ -281,8 +280,14 @@ const buildInventorySnapshot = async (
|
||||
edges: orderedEdges,
|
||||
provenance: reader?.provenance() ?? [],
|
||||
integrity_contradictions: integrityContradictions,
|
||||
coverage_status: assessment.coverage_status,
|
||||
limitations: assessment.limitations,
|
||||
coverage: traversal.coverage,
|
||||
coverage_status:
|
||||
traversal.coverage.status === "complete" ? "complete" : "partial",
|
||||
limitations: buildLimitations(
|
||||
traversal.limitations,
|
||||
integrityContradictions,
|
||||
input.caseCollisionLimitation,
|
||||
),
|
||||
};
|
||||
};
|
||||
|
||||
@@ -395,3 +400,17 @@ const buildManifest = ({
|
||||
occurrence_count: orderedOccurrences.length,
|
||||
edge_count: orderedEdges.length,
|
||||
});
|
||||
|
||||
const buildLimitations = (
|
||||
scopeLimitations: readonly string[],
|
||||
integrityContradictions: readonly IntegrityContradiction[],
|
||||
caseCollisionLimitation: string | undefined,
|
||||
): string[] => [
|
||||
...scopeLimitations,
|
||||
...(caseCollisionLimitation === undefined ? [] : [caseCollisionLimitation]),
|
||||
...(integrityContradictions.length === 0
|
||||
? []
|
||||
: [
|
||||
`${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
|
||||
]),
|
||||
];
|
||||
|
||||
@@ -9,9 +9,12 @@ import {
|
||||
ArtifactReaderFailure,
|
||||
type ArtifactEntry,
|
||||
type ArtifactReader,
|
||||
type ArtifactReaderTraversal,
|
||||
type ArtifactTraversalOmission,
|
||||
} from "../ArtifactReader.js";
|
||||
import { AsarArtifactReader } from "../AsarArtifactReader.js";
|
||||
import type { ArtifactNode } from "../../domain/artifactGraph.js";
|
||||
import { compareUnicodeCodePoints } from "../../domain/unicodeCodePointOrder.js";
|
||||
import {
|
||||
classifyArtifactContent,
|
||||
classifyArtifactBytes,
|
||||
@@ -55,6 +58,7 @@ interface ScanContext {
|
||||
readonly registry: ArtifactPathRegistry;
|
||||
readonly expandedContainerIds: Set<string>;
|
||||
readonly ownedReaders: ArtifactReader[];
|
||||
readonly omissions: ArtifactTraversalOmission[];
|
||||
}
|
||||
|
||||
export const scanReader = async (
|
||||
@@ -67,6 +71,7 @@ export const scanReader = async (
|
||||
readonly occurrences: MutableOccurrence[];
|
||||
readonly pendingContradictions: PendingIntegrityContradiction[];
|
||||
readonly caseCollisionLimitation: string | undefined;
|
||||
readonly traversal: ArtifactReaderTraversal;
|
||||
}> => {
|
||||
const { nodes, occurrences, pendingContradictions } = emptyScan();
|
||||
if (reader === undefined)
|
||||
@@ -75,6 +80,7 @@ export const scanReader = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation: undefined,
|
||||
traversal: { status: "complete", limitations: [] },
|
||||
};
|
||||
const context: ScanContext = {
|
||||
reader,
|
||||
@@ -87,6 +93,7 @@ export const scanReader = async (
|
||||
registry: new ArtifactPathRegistry(),
|
||||
expandedContainerIds: new Set<string>(),
|
||||
ownedReaders,
|
||||
omissions: [],
|
||||
};
|
||||
await visitArtifactEntries(context, reader, "");
|
||||
// Archive directories may appear after their children. Resolve containment
|
||||
@@ -101,9 +108,37 @@ export const scanReader = async (
|
||||
occurrences,
|
||||
pendingContradictions,
|
||||
caseCollisionLimitation: annotateEnglishUnicodeCaseCollisions(occurrences),
|
||||
traversal: {
|
||||
status: context.omissions.length === 0 ? "complete" : "unknown",
|
||||
limitations: [
|
||||
...new Set(
|
||||
context.omissions.map(
|
||||
({ path, kind }) =>
|
||||
`Artifact traversal omitted ${kind} at ${JSON.stringify(path)}.`,
|
||||
),
|
||||
),
|
||||
].sort(compareUnicodeCodePoints),
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
const inventoryEntries = (
|
||||
context: ScanContext,
|
||||
reader: ArtifactReader,
|
||||
prefix: string,
|
||||
): AsyncIterator<ArtifactEntry> =>
|
||||
reader
|
||||
.entries(context.signal, {
|
||||
onOmission: (omission) =>
|
||||
context.omissions.push({
|
||||
...omission,
|
||||
path: normalizeArtifactPath(
|
||||
prefix.length === 0 ? omission.path : `${prefix}/${omission.path}`,
|
||||
),
|
||||
}),
|
||||
})
|
||||
[Symbol.asyncIterator]();
|
||||
|
||||
const visitArtifactEntries = async (
|
||||
context: ScanContext,
|
||||
currentReader: ArtifactReader,
|
||||
@@ -117,7 +152,7 @@ const visitArtifactEntries = async (
|
||||
{
|
||||
reader: currentReader,
|
||||
prefix,
|
||||
iterator: currentReader.entries(context.signal)[Symbol.asyncIterator](),
|
||||
iterator: inventoryEntries(context, currentReader, prefix),
|
||||
},
|
||||
];
|
||||
let failure: { readonly cause: unknown } | undefined;
|
||||
@@ -191,7 +226,7 @@ const visitArtifactEntries = async (
|
||||
stack.push({
|
||||
reader: nested,
|
||||
prefix: logicalPath,
|
||||
iterator: nested.entries(context.signal)[Symbol.asyncIterator](),
|
||||
iterator: inventoryEntries(context, nested, logicalPath),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user