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:
Thang Luu
2026-10-14 03:00:27 +08:00
committed by GitHub
co-authored by morluto OpenAI Codex
parent e4186af31b
commit 45a3509db3
24 changed files with 1023 additions and 162 deletions
+31 -2
View File
@@ -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>;
+33 -6
View File
@@ -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,
+14 -2
View File
@@ -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;
+42 -35
View File
@@ -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."],
};
};
+28 -9
View File
@@ -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.`,
]),
];
+37 -2
View File
@@ -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),
});
}
}