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),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@@ -68,7 +68,7 @@ export const androidApplicationProjectionResultSchema = z.strictObject({
|
||||
// Count completeness is separate from the declared coverage status.
|
||||
inventory_complete: z.boolean(),
|
||||
}),
|
||||
limitations: z.array(z.string().min(1)),
|
||||
limitations: z.array(z.string()),
|
||||
});
|
||||
|
||||
export type AndroidApplicationProjectionInput = z.infer<
|
||||
@@ -99,7 +99,8 @@ export const projectAndroidApplication = (
|
||||
);
|
||||
const components = classified;
|
||||
const limitations = [
|
||||
...(!hasCompleteInventoryCoverage(inventory)
|
||||
...inventory.limitations,
|
||||
...(!hasCompleteInventoryCoverage(inventory, "container-entries")
|
||||
? ["Source inventory coverage is partial; absence is unknown."]
|
||||
: []),
|
||||
"Manifest, resource, signing, and bytecode semantics require a dedicated Android provider; this projection reports exact inventory paths and hashes only.",
|
||||
|
||||
@@ -94,7 +94,7 @@ export const appleApplicationProjectionResultSchema = z.strictObject({
|
||||
// Count completeness is separate from the declared coverage status.
|
||||
inventory_complete: z.boolean(),
|
||||
}),
|
||||
limitations: z.array(z.string().min(1)),
|
||||
limitations: z.array(z.string()),
|
||||
});
|
||||
|
||||
export type AppleApplicationProjectionInput = z.infer<
|
||||
@@ -169,18 +169,24 @@ export const projectAppleApplication = (
|
||||
);
|
||||
const uninventoriedImage =
|
||||
rootFormat === "dmg" && inventory.occurrences.length === 1;
|
||||
const inventoryComplete = hasCompleteInventoryCoverage(inventory);
|
||||
const inventoryComplete = hasCompleteInventoryCoverage(
|
||||
inventory,
|
||||
"container-entries",
|
||||
);
|
||||
const complete = inventoryComplete && !uninventoriedImage;
|
||||
const limitations = projectionLimitations({
|
||||
complete: inventoryComplete,
|
||||
uninventoriedImage,
|
||||
roots,
|
||||
bundles,
|
||||
sidecars: entries.some(({ path }) => isSidecar(path)),
|
||||
symlinks: entries.some(({ kind }) => kind === "symlink"),
|
||||
unattributed,
|
||||
bridgeCandidateCoverage: bridgeProjection.coverage,
|
||||
});
|
||||
const limitations = [
|
||||
...inventory.limitations,
|
||||
...projectionLimitations({
|
||||
complete: inventoryComplete,
|
||||
uninventoriedImage,
|
||||
roots,
|
||||
bundles,
|
||||
sidecars: entries.some(({ path }) => isSidecar(path)),
|
||||
symlinks: entries.some(({ kind }) => kind === "symlink"),
|
||||
unattributed,
|
||||
bridgeCandidateCoverage: bridgeProjection.coverage,
|
||||
}),
|
||||
];
|
||||
const withoutId = {
|
||||
root_sha256: inventory.manifest.root_sha256,
|
||||
root_format: rootFormat,
|
||||
|
||||
@@ -104,13 +104,51 @@ export const compareArtifacts = (
|
||||
const right = parseArtifactInventoryEvidence(rightEvidence);
|
||||
const leftComplete = left.inventory.complete;
|
||||
const rightComplete = right.inventory.complete;
|
||||
const leftCovered = hasCompleteInventoryCoverage(left.inventory);
|
||||
const rightCovered = hasCompleteInventoryCoverage(right.inventory);
|
||||
const sameScope =
|
||||
left.inventory.coverage.scope === right.inventory.coverage.scope;
|
||||
const rootCoverageComplete =
|
||||
sameScope &&
|
||||
left.inventory.complete &&
|
||||
right.inventory.complete &&
|
||||
left.inventory.coverage.status === "complete" &&
|
||||
right.inventory.coverage.status === "complete";
|
||||
const entryCoverageComplete =
|
||||
rootCoverageComplete &&
|
||||
left.inventory.coverage.scope === "container-entries";
|
||||
const leftCovered =
|
||||
sameScope &&
|
||||
hasCompleteInventoryCoverage(left.inventory, left.inventory.coverage.scope);
|
||||
const rightCovered =
|
||||
sameScope &&
|
||||
hasCompleteInventoryCoverage(
|
||||
right.inventory,
|
||||
right.inventory.coverage.scope,
|
||||
);
|
||||
const fullyCovered =
|
||||
leftCovered &&
|
||||
rightCovered &&
|
||||
(entryCoverageComplete ||
|
||||
(rootCoverageComplete &&
|
||||
left.inventory.manifest.occurrence_count === 1 &&
|
||||
right.inventory.manifest.occurrence_count === 1));
|
||||
const limitations = [
|
||||
...left.inventory.limitations.map((item) => `Left: ${item}`),
|
||||
...right.inventory.limitations.map((item) => `Right: ${item}`),
|
||||
...(leftComplete ? [] : ["Left artifact inventory is incomplete."]),
|
||||
...(rightComplete ? [] : ["Right artifact inventory is incomplete."]),
|
||||
...(sameScope ? [] : ["Artifact inventory scopes differ."]),
|
||||
...(sameScope &&
|
||||
left.inventory.coverage.scope === "root" &&
|
||||
(left.inventory.manifest.occurrence_count > 1 ||
|
||||
right.inventory.manifest.occurrence_count > 1)
|
||||
? ["Container entry coverage is unavailable for child paths."]
|
||||
: []),
|
||||
...(left.inventory.coverage.status === "complete"
|
||||
? []
|
||||
: ["Left artifact inventory traversal coverage is unknown."]),
|
||||
...(right.inventory.coverage.status === "complete"
|
||||
? []
|
||||
: ["Right artifact inventory traversal coverage is unknown."]),
|
||||
];
|
||||
const changes = compareOccurrences(
|
||||
left.inventory,
|
||||
@@ -119,7 +157,7 @@ export const compareArtifacts = (
|
||||
...left.evidence.map(({ evidence_id: id }) => id),
|
||||
...right.evidence.map(({ evidence_id: id }) => id),
|
||||
],
|
||||
leftCovered && rightCovered,
|
||||
{ root: rootCoverageComplete, entries: entryCoverageComplete },
|
||||
);
|
||||
applyRootHashChange(left.inventory, right.inventory, changes, [
|
||||
...left.evidence.map(({ evidence_id: id }) => id),
|
||||
@@ -129,7 +167,7 @@ export const compareArtifacts = (
|
||||
left.inventory,
|
||||
right.inventory,
|
||||
changes,
|
||||
leftCovered && rightCovered,
|
||||
fullyCovered,
|
||||
);
|
||||
return artifactComparisonResultSchema.parse({
|
||||
status:
|
||||
@@ -139,7 +177,7 @@ export const compareArtifacts = (
|
||||
({ classification }) => classification === "contradiction",
|
||||
)
|
||||
? "contradiction"
|
||||
: !leftCovered || !rightCovered
|
||||
: !fullyCovered
|
||||
? "unknown"
|
||||
: changes.some(({ classification }) => classification === "unknown")
|
||||
? "unknown"
|
||||
@@ -158,7 +196,7 @@ const compareOccurrences = (
|
||||
left: InventorySet,
|
||||
right: InventorySet,
|
||||
evidenceLinks: readonly string[],
|
||||
complete: boolean,
|
||||
coverage: { readonly root: boolean; readonly entries: boolean },
|
||||
): ArtifactChange[] => {
|
||||
const leftByPath = new Map(
|
||||
left.occurrences.map((item) => [item.logical_path, item]),
|
||||
@@ -187,7 +225,8 @@ const compareOccurrences = (
|
||||
rightNode: nodeFor(rightOccurrence, rightNodes),
|
||||
leftRelations: leftRelations.get(path) ?? [],
|
||||
rightRelations: rightRelations.get(path) ?? [],
|
||||
complete,
|
||||
rootCovered: coverage.root,
|
||||
entriesCovered: coverage.entries,
|
||||
evidenceLinks,
|
||||
});
|
||||
if (change !== null) output.push(change);
|
||||
@@ -203,7 +242,8 @@ interface ClassifyPathInput {
|
||||
readonly rightNode: ArtifactNode | undefined;
|
||||
readonly leftRelations: readonly RelationProjection[];
|
||||
readonly rightRelations: readonly RelationProjection[];
|
||||
readonly complete: boolean;
|
||||
readonly rootCovered: boolean;
|
||||
readonly entriesCovered: boolean;
|
||||
readonly evidenceLinks: readonly string[];
|
||||
}
|
||||
|
||||
@@ -217,17 +257,18 @@ const buildArtifactChangeBase = (input: ClassifyPathInput) => ({
|
||||
});
|
||||
|
||||
const classifyPresence = (input: ClassifyPathInput): ArtifactChange | null => {
|
||||
const covered = input.path === "." ? input.rootCovered : input.entriesCovered;
|
||||
if (input.leftOccurrence === undefined)
|
||||
return {
|
||||
...buildArtifactChangeBase(input),
|
||||
classification: input.complete ? "added" : "unknown",
|
||||
dimensions: [input.complete ? "content" : "availability"],
|
||||
classification: covered ? "added" : "unknown",
|
||||
dimensions: [covered ? "content" : "availability"],
|
||||
};
|
||||
if (input.rightOccurrence === undefined)
|
||||
return {
|
||||
...buildArtifactChangeBase(input),
|
||||
classification: input.complete ? "removed" : "unknown",
|
||||
dimensions: [input.complete ? "content" : "availability"],
|
||||
classification: covered ? "removed" : "unknown",
|
||||
dimensions: [covered ? "content" : "availability"],
|
||||
};
|
||||
return null;
|
||||
};
|
||||
|
||||
@@ -188,8 +188,11 @@ export const artifactGraphManifestSchema = z.object({
|
||||
edge_count: z.number().int().min(0),
|
||||
});
|
||||
|
||||
/** Whether the inventory producer covered its modeled child-entry scope. */
|
||||
export const artifactInventoryCoverageSchema = z.enum(["complete", "partial"]);
|
||||
/** Producer-owned traversal coverage; content certainty remains on each occurrence. */
|
||||
export const artifactInventoryCoverageSchema = z.strictObject({
|
||||
scope: z.enum(["root", "container-entries"]),
|
||||
status: z.enum(["complete", "unknown"]),
|
||||
});
|
||||
export type ArtifactInventoryCoverage = z.infer<
|
||||
typeof artifactInventoryCoverageSchema
|
||||
>;
|
||||
@@ -202,15 +205,19 @@ export const artifactInventoryResultSchema = z.object({
|
||||
edges: z.array(artifactEdgeSchema),
|
||||
provenance: z.array(artifactCommandSchema),
|
||||
integrity_contradictions: z.array(integrityContradictionSchema).default([]),
|
||||
// Omitted by older retained Evidence; the inventory parser owns its compatibility policy.
|
||||
coverage: artifactInventoryCoverageSchema.optional(),
|
||||
limitations: z.array(z.string()),
|
||||
/** Optional only for persisted inventory Evidence written before this field. */
|
||||
coverage_status: artifactInventoryCoverageSchema.optional(),
|
||||
coverage_status: z.enum(["complete", "partial"]).optional(),
|
||||
});
|
||||
|
||||
/** Current inventory producers always classify the coverage they examined. */
|
||||
/** Current producers always declare coverage; historical Evidence inputs may omit it. */
|
||||
export const artifactInventoryOutputSchema =
|
||||
artifactInventoryResultSchema.extend({
|
||||
coverage_status: artifactInventoryCoverageSchema,
|
||||
artifactInventoryResultSchema.safeExtend({
|
||||
coverage: artifactInventoryCoverageSchema,
|
||||
coverage_status:
|
||||
artifactInventoryResultSchema.shape.coverage_status.unwrap(),
|
||||
});
|
||||
export type ArtifactInventoryOutput = z.infer<
|
||||
typeof artifactInventoryOutputSchema
|
||||
|
||||
@@ -18,7 +18,10 @@ import {
|
||||
} from "./artifactIdentity.js";
|
||||
import { parseEvidence, type Evidence } from "./evidence.js";
|
||||
import { artifactInspectionResultSchema } from "./artifactInspection.js";
|
||||
import { ZIP_NON_ENTRY_TAIL_LIMITATION } from "./zipPackageFormat.js";
|
||||
import {
|
||||
isZipPackageFormat,
|
||||
ZIP_NON_ENTRY_TAIL_LIMITATION,
|
||||
} from "./zipPackageFormat.js";
|
||||
|
||||
/** Complete or partially assembled inventory used by comparison workflows. */
|
||||
export interface InventorySet {
|
||||
@@ -30,13 +33,17 @@ export interface InventorySet {
|
||||
readonly limitations: readonly string[];
|
||||
/** True when merged node, occurrence, and edge counts match the manifest. */
|
||||
readonly complete: boolean;
|
||||
readonly coverage_status: ArtifactInventoryCoverage;
|
||||
readonly coverage: ArtifactInventoryCoverage;
|
||||
}
|
||||
|
||||
/** Whether all graph members are present and the producer reports full coverage. */
|
||||
export const hasCompleteInventoryCoverage = (
|
||||
inventory: InventorySet,
|
||||
): boolean => inventory.complete && inventory.coverage_status === "complete";
|
||||
requiredScope: ArtifactInventoryCoverage["scope"],
|
||||
): boolean =>
|
||||
inventory.complete &&
|
||||
inventory.coverage.scope === requiredScope &&
|
||||
inventory.coverage.status === "complete";
|
||||
|
||||
export interface ParsedInventorySet {
|
||||
readonly evidence: readonly Evidence[];
|
||||
@@ -132,11 +139,14 @@ const assembleInventoryResults = (
|
||||
const first = pages[0];
|
||||
if (first === undefined)
|
||||
throw new TypeError("Artifact inventory requires Evidence pages");
|
||||
const coverageStatuses = new Set(pages.map(resolveInventoryCoverageStatus));
|
||||
if (coverageStatuses.size !== 1)
|
||||
throw new TypeError("Artifact inventory pages disagree on coverage status");
|
||||
const coverageStatus = [...coverageStatuses][0]!;
|
||||
const manifestJson = canonicalJson(first.manifest, "Artifact inventory");
|
||||
const coverageJson = canonicalJson(
|
||||
{
|
||||
coverage: first.coverage ?? null,
|
||||
coverage_status: first.coverage_status ?? null,
|
||||
},
|
||||
"Artifact inventory coverage",
|
||||
);
|
||||
const nodes = new Map<string, ArtifactNode>();
|
||||
const occurrences = new Map<string, ArtifactOccurrence>();
|
||||
const paths = new Map<string, ArtifactOccurrence>();
|
||||
@@ -144,6 +154,18 @@ const assembleInventoryResults = (
|
||||
for (const page of pages) {
|
||||
if (canonicalJson(page.manifest, "Artifact inventory") !== manifestJson)
|
||||
throw new TypeError("Artifact inventory pages do not share one manifest");
|
||||
if (
|
||||
canonicalJson(
|
||||
{
|
||||
coverage: page.coverage ?? null,
|
||||
coverage_status: page.coverage_status ?? null,
|
||||
},
|
||||
"Artifact inventory coverage",
|
||||
) !== coverageJson
|
||||
)
|
||||
throw new TypeError(
|
||||
"Artifact inventory pages do not share one coverage declaration",
|
||||
);
|
||||
if (
|
||||
canonicalJson(page.integrity_contradictions, "Artifact inventory") !==
|
||||
canonicalJson(first.integrity_contradictions, "Artifact inventory")
|
||||
@@ -165,12 +187,11 @@ const assembleInventoryResults = (
|
||||
for (const edge of page.edges)
|
||||
mergeExact(edges, edge.edge_id, edge, "edge");
|
||||
}
|
||||
const inventory = orderedInventory(
|
||||
first,
|
||||
pages,
|
||||
{ nodes, occurrences, edges },
|
||||
coverageStatus,
|
||||
);
|
||||
const inventory = orderedInventory(first, pages, {
|
||||
nodes,
|
||||
occurrences,
|
||||
edges,
|
||||
});
|
||||
if (inventory.complete) validateCompleteInventory(inventory);
|
||||
return inventory;
|
||||
};
|
||||
@@ -186,7 +207,6 @@ const orderedInventory = (
|
||||
ArtifactInventoryResult["edges"][number]
|
||||
>;
|
||||
},
|
||||
coverageStatus: ArtifactInventoryCoverage,
|
||||
): InventorySet => {
|
||||
const nodes = [...values.nodes.values()].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.artifact_id, right.artifact_id),
|
||||
@@ -197,40 +217,78 @@ const orderedInventory = (
|
||||
const edges = [...values.edges.values()].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.edge_id, right.edge_id),
|
||||
);
|
||||
const limitations = [
|
||||
...new Set(pages.flatMap((inventory) => inventory.limitations)),
|
||||
].sort(compareUnicodeCodePoints);
|
||||
return {
|
||||
manifest: first.manifest,
|
||||
nodes,
|
||||
occurrences,
|
||||
edges,
|
||||
integrityContradictions: first.integrity_contradictions,
|
||||
limitations: [
|
||||
...new Set(pages.flatMap((inventory) => inventory.limitations)),
|
||||
].sort(compareUnicodeCodePoints),
|
||||
limitations,
|
||||
coverage: resolveInventoryCoverage({ ...first, limitations }),
|
||||
complete:
|
||||
nodes.length === first.manifest.node_count &&
|
||||
occurrences.length === first.manifest.occurrence_count &&
|
||||
edges.length === first.manifest.edge_count,
|
||||
coverage_status: coverageStatus,
|
||||
};
|
||||
};
|
||||
|
||||
const resolveInventoryCoverageStatus = (
|
||||
// Normalize both retained coverage formats at this owning boundary.
|
||||
const resolveInventoryCoverage = (
|
||||
inventory: ArtifactInventoryResult,
|
||||
): ArtifactInventoryCoverage => {
|
||||
if (inventory.coverage_status !== undefined) return inventory.coverage_status;
|
||||
// Older retained Evidence has no typed status. Keep only its known
|
||||
// informational notices complete; unknown limitation text fails closed.
|
||||
return inventory.limitations.every(isKnownNonCoverageNotice)
|
||||
? "complete"
|
||||
: "partial";
|
||||
const legacy = legacyInventoryCoverage(
|
||||
inventory.manifest.root_format,
|
||||
inventory.limitations,
|
||||
inventory.integrity_contradictions.length,
|
||||
);
|
||||
if (inventory.coverage !== undefined) {
|
||||
if (
|
||||
inventory.coverage_status !== undefined &&
|
||||
(inventory.coverage.status === "complete") !==
|
||||
(inventory.coverage_status === "complete")
|
||||
)
|
||||
throw new TypeError(
|
||||
"Artifact inventory has conflicting coverage declarations",
|
||||
);
|
||||
return inventory.coverage;
|
||||
}
|
||||
return inventory.coverage_status === undefined
|
||||
? legacy
|
||||
: {
|
||||
...legacy,
|
||||
status:
|
||||
inventory.coverage_status === "complete" ? "complete" : "unknown",
|
||||
};
|
||||
};
|
||||
|
||||
const isKnownNonCoverageNotice = (limitation: string): boolean =>
|
||||
limitation === "Artifact has no child container entries." ||
|
||||
limitation === ZIP_NON_ENTRY_TAIL_LIMITATION ||
|
||||
/^\d+ integrity contradiction\(s\) were recorded; mismatched content is observed-untrusted\.$/u.test(
|
||||
limitation,
|
||||
);
|
||||
// Retained pre-coverage records cannot classify arbitrary prose. Recognize only
|
||||
// the historical producer vocabulary here; unfamiliar diagnostics remain unknown.
|
||||
const legacyInventoryCoverage = (
|
||||
format: ArtifactInventoryResult["manifest"]["root_format"],
|
||||
limitations: readonly string[],
|
||||
contradictionCount: number,
|
||||
): ArtifactInventoryCoverage => ({
|
||||
scope:
|
||||
isZipPackageFormat(format) ||
|
||||
["directory", "asar", "dmg", "pkg", "mach-o-universal"].includes(format)
|
||||
? "container-entries"
|
||||
: "root",
|
||||
status: limitations.some(
|
||||
(limitation) =>
|
||||
limitation !== "Artifact has no child container entries." &&
|
||||
limitation !== ZIP_NON_ENTRY_TAIL_LIMITATION &&
|
||||
!(
|
||||
contradictionCount > 0 &&
|
||||
limitation ===
|
||||
`${String(contradictionCount)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`
|
||||
),
|
||||
)
|
||||
? "unknown"
|
||||
: "complete",
|
||||
});
|
||||
|
||||
const validateCompleteInventory = (inventory: InventorySet): void => {
|
||||
const nodeIds = new Set(inventory.nodes.map(({ artifact_id: id }) => id));
|
||||
|
||||
@@ -7,7 +7,9 @@ import type {
|
||||
|
||||
/** Immutable inventory produced by one complete artifact scan. */
|
||||
export interface ArtifactInventorySnapshot {
|
||||
readonly coverage_status: ArtifactInventoryCoverage;
|
||||
readonly coverage_status: NonNullable<
|
||||
ArtifactInventoryResult["coverage_status"]
|
||||
>;
|
||||
readonly manifest: ArtifactInventoryResult["manifest"];
|
||||
readonly nodes: readonly ArtifactNode[];
|
||||
readonly occurrences: ArtifactInventoryResult["occurrences"];
|
||||
@@ -16,5 +18,6 @@ export interface ArtifactInventorySnapshot {
|
||||
ArtifactInventoryResult["provenance"][number]
|
||||
>;
|
||||
readonly integrity_contradictions: readonly IntegrityContradiction[];
|
||||
readonly coverage?: ArtifactInventoryCoverage;
|
||||
readonly limitations: readonly string[];
|
||||
}
|
||||
|
||||
@@ -72,7 +72,7 @@ export const harmonyApplicationProjectionResultSchema = z.strictObject({
|
||||
// Count completeness is separate from the declared coverage status.
|
||||
inventory_complete: z.boolean(),
|
||||
}),
|
||||
limitations: z.array(z.string().min(1)),
|
||||
limitations: z.array(z.string()),
|
||||
});
|
||||
|
||||
export type HarmonyApplicationProjectionInput = z.infer<
|
||||
@@ -112,7 +112,8 @@ export const projectHarmonyApplication = (
|
||||
classified.native_libraries,
|
||||
);
|
||||
const limitations = [
|
||||
...(!hasCompleteInventoryCoverage(inventory)
|
||||
...inventory.limitations,
|
||||
...(!hasCompleteInventoryCoverage(inventory, "container-entries")
|
||||
? ["Source inventory coverage is partial; absence is unknown."]
|
||||
: []),
|
||||
...(unavailable.length > 0
|
||||
|
||||
@@ -56,7 +56,8 @@ export const projectionCoverage = (
|
||||
inventory_complete: boolean;
|
||||
} => ({
|
||||
status:
|
||||
hasCompleteInventoryCoverage(inventory) && budgetComplete
|
||||
hasCompleteInventoryCoverage(inventory, "container-entries") &&
|
||||
budgetComplete
|
||||
? ("complete-within-inventory" as const)
|
||||
: ("partial" as const),
|
||||
inventory_complete: inventory.complete,
|
||||
|
||||
Reference in New Issue
Block a user