Merge remote-tracking branch 'origin/main' into codex/legacy-cleanup-followup-20261022
This commit is contained in:
commit
421d527bfe
48 files changed
+4671
-196
No files matched your search
@@ -1,3 +1,4 @@
|
||||
import type { EvidenceCreationOptions } from "../domain/evidence.js";
|
||||
import type { ProviderInspectionScope } from "../providers/ProviderInspectionScope.js";
|
||||
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
|
||||
import type { OfficialToolName } from "../contracts/officialToolContracts.js";
|
||||
@@ -146,6 +147,7 @@ export const createAnalysisExecutionEvidence = (
|
||||
input: unknown,
|
||||
execution: AnalysisExecution,
|
||||
confidence: "observed" | "derived",
|
||||
options?: EvidenceCreationOptions,
|
||||
): Evidence =>
|
||||
createEvidence(
|
||||
execution.subject === undefined
|
||||
@@ -167,6 +169,7 @@ export const createAnalysisExecutionEvidence = (
|
||||
locations: execution.locations,
|
||||
confidence,
|
||||
},
|
||||
options,
|
||||
);
|
||||
|
||||
/** Provider-neutral application capability for one analysis operation. */
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
import type { ExecutableFormatHint } from "../domain/dosCom.js";
|
||||
import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js";
|
||||
import type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import type { DirectAnalysisDependencies } from "./DirectAnalysisDependencies.js";
|
||||
@@ -59,7 +60,11 @@ import {
|
||||
import type { AnalysisProviderSelector } from "../contracts/providerSelection.js";
|
||||
import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
|
||||
import { resolveXrefsAddress } from "./XrefsAddressResolution.js";
|
||||
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisInputError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import { deliverAnalysisEvidence } from "./EvidenceBundleCommands.js";
|
||||
import type { BinaryTargetError } from "../domain/configurationErrors.js";
|
||||
import {
|
||||
directAnalysisCleanupFailure,
|
||||
@@ -146,24 +151,81 @@ export const runDirectAnalysis = async (
|
||||
/** Execute one provider-native semantic operation with atomic provenance. */
|
||||
export const runProviderAnalysis = async (
|
||||
dependencies: DirectAnalysisDependencies,
|
||||
...[path, tool, arguments_, logger = silentLogger, signal]: readonly [
|
||||
path: string,
|
||||
tool: NativeToolName | ArtifactAnalysisOperation | ManagedToolName,
|
||||
arguments_: Readonly<Record<string, JsonValue>>,
|
||||
logger?: Logger,
|
||||
signal?: AbortSignal,
|
||||
]
|
||||
...[path, tool, arguments_, logger = silentLogger, signal, delivery]:
|
||||
| readonly [
|
||||
path: string,
|
||||
tool: NativeToolName | ArtifactAnalysisOperation | ManagedToolName,
|
||||
arguments_: Readonly<Record<string, JsonValue>>,
|
||||
logger?: Logger | undefined,
|
||||
signal?: AbortSignal | undefined,
|
||||
]
|
||||
| readonly [
|
||||
path: string,
|
||||
tool: "inspect_managed_members",
|
||||
arguments_: Readonly<Record<string, JsonValue>>,
|
||||
logger: Logger | undefined,
|
||||
signal: AbortSignal | undefined,
|
||||
delivery: {
|
||||
readonly detail?: "complete" | "summary";
|
||||
readonly evidenceBundlePath?: string;
|
||||
},
|
||||
]
|
||||
): Promise<JsonValue> => {
|
||||
if (isManagedToolName(tool))
|
||||
return runManagedProviderAnalysis(
|
||||
dependencies,
|
||||
path,
|
||||
tool,
|
||||
arguments_,
|
||||
signal,
|
||||
if (delivery !== undefined && tool !== "inspect_managed_members")
|
||||
return cliError(
|
||||
new AnalysisInputError(tool, undefined, [
|
||||
{
|
||||
path: ["delivery"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
"Evidence delivery options are only supported by inspect_managed_members",
|
||||
},
|
||||
]),
|
||||
);
|
||||
return withProcessCancellation(signal, (operationSignal) =>
|
||||
runAnalysis(dependencies, path, tool, arguments_, {
|
||||
if (
|
||||
delivery?.detail === "summary" &&
|
||||
delivery.evidenceBundlePath === undefined
|
||||
)
|
||||
return cliError(
|
||||
new AnalysisInputError(tool, undefined, [
|
||||
{
|
||||
path: ["evidence_bundle"],
|
||||
reason: "missing_argument",
|
||||
message:
|
||||
"summary detail requires --evidence-bundle so complete Evidence remains available to later CLI commands",
|
||||
},
|
||||
]),
|
||||
);
|
||||
return withProcessCancellation(signal, async (operationSignal) => {
|
||||
if (isManagedToolName(tool)) {
|
||||
const original = await runManagedProviderAnalysis(
|
||||
dependencies,
|
||||
path,
|
||||
tool,
|
||||
arguments_,
|
||||
operationSignal,
|
||||
);
|
||||
await dispatchQueuedInterrupts();
|
||||
if (!original.ok) return cliError(original.error);
|
||||
if (operationSignal.aborted)
|
||||
return cliError(
|
||||
new AnalysisCancelledError(tool, {
|
||||
cause: operationSignal.reason,
|
||||
partialObservation: original.value,
|
||||
}),
|
||||
);
|
||||
const result =
|
||||
delivery?.evidenceBundlePath === undefined
|
||||
? original
|
||||
: await deliverAnalysisEvidence(
|
||||
original.value,
|
||||
delivery.evidenceBundlePath,
|
||||
delivery.detail,
|
||||
operationSignal,
|
||||
);
|
||||
return result.ok ? result.value : cliError(result.error);
|
||||
}
|
||||
return runAnalysis(dependencies, path, tool, arguments_, {
|
||||
logger,
|
||||
snapshotPath: undefined,
|
||||
signal: operationSignal,
|
||||
@@ -172,8 +234,8 @@ export const runProviderAnalysis = async (
|
||||
: NATIVE_INSPECTION_OPERATIONS.has(tool)
|
||||
? { createSession: dependencies.createNativeBinarySession }
|
||||
: {}),
|
||||
}),
|
||||
);
|
||||
});
|
||||
});
|
||||
};
|
||||
|
||||
/** Execute managed metadata inspection in an isolated managed-only session. */
|
||||
@@ -199,13 +261,14 @@ export const runManagedProviderExecution = async (
|
||||
);
|
||||
});
|
||||
|
||||
/** Preserve typed managed Evidence before selecting its CLI delivery. */
|
||||
const runManagedProviderAnalysis = async (
|
||||
dependencies: DirectAnalysisDependencies,
|
||||
dependencies: Pick<DirectAnalysisDependencies, "createManagedBinarySession">,
|
||||
path: string,
|
||||
tool: ManagedToolName,
|
||||
arguments_: Readonly<Record<string, JsonValue>>,
|
||||
signal?: AbortSignal,
|
||||
): Promise<JsonValue> => {
|
||||
): Promise<Result<Evidence, AnalysisError>> => {
|
||||
const execution = await runManagedProviderExecution(
|
||||
dependencies,
|
||||
path,
|
||||
@@ -213,9 +276,13 @@ const runManagedProviderAnalysis = async (
|
||||
signal,
|
||||
arguments_,
|
||||
);
|
||||
if (!execution.ok) return cliError(execution.error);
|
||||
if (!execution.ok) return execution;
|
||||
const value = execution.value;
|
||||
return createAnalysisExecutionEvidence(tool, arguments_, value, "observed");
|
||||
return ok(
|
||||
createAnalysisExecutionEvidence(tool, arguments_, value, "observed", {
|
||||
immutable: true,
|
||||
}),
|
||||
);
|
||||
};
|
||||
|
||||
const runAnalysis = async (
|
||||
|
||||
@@ -1,9 +1,23 @@
|
||||
import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js";
|
||||
import { absoluteCallerPath } from "../filesystem/callerPath.js";
|
||||
import { requireAuthenticationHeadroom } from "./JsonAuthenticationHeadroom.js";
|
||||
|
||||
import {
|
||||
EvidenceFileError,
|
||||
EvidenceIntegrityError,
|
||||
type PublishedEvidenceFile,
|
||||
} from "../domain/evidenceErrors.js";
|
||||
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import type { EvidenceBundle } from "../domain/evidenceBundle.js";
|
||||
import {
|
||||
AnalysisCancelledError,
|
||||
AnalysisInputError,
|
||||
} from "../domain/analysisErrorCore.js";
|
||||
import type { Evidence } from "../domain/evidence.js";
|
||||
import {
|
||||
createImmutableEvidenceBundle,
|
||||
type EvidenceBundle,
|
||||
} from "../domain/evidenceBundle.js";
|
||||
import type { InspectAnalysisViewInput } from "../domain/analysisView/analysisView.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
@@ -14,12 +28,18 @@ import {
|
||||
readImmutableEvidenceBundle,
|
||||
writeEvidenceBundle,
|
||||
} from "./EvidenceBundleFiles.js";
|
||||
import { inspectAnalysisViewValidated } from "./analysisView/AnalysisViewService.js";
|
||||
|
||||
/** Validate a standalone bundle and report its complete record/revision counts. */
|
||||
export const importEvidenceBundleCommand = async (
|
||||
path: string,
|
||||
): Promise<Result<JsonValue, AnalysisError>> => {
|
||||
const loaded = await readEvidenceBundle(path);
|
||||
const loaded = await readEvidenceBundle(
|
||||
path,
|
||||
undefined,
|
||||
undefined,
|
||||
"import_evidence_bundle",
|
||||
);
|
||||
if (!loaded.ok) return loaded;
|
||||
return ok({
|
||||
imported: loaded.value.records.length,
|
||||
@@ -35,16 +55,136 @@ export const exportEvidenceBundleCommand = async (
|
||||
overwrite: boolean,
|
||||
): Promise<Result<JsonValue, AnalysisError>> => {
|
||||
// The sealed snapshot lets the writer reuse this authentication.
|
||||
const loaded = await readImmutableEvidenceBundle(sourcePath);
|
||||
const loaded = await readImmutableEvidenceBundle(
|
||||
sourcePath,
|
||||
undefined,
|
||||
undefined,
|
||||
"export_evidence_bundle",
|
||||
);
|
||||
if (!loaded.ok) return loaded;
|
||||
return projectWrite(
|
||||
loaded.value,
|
||||
await persistEvidenceBundleCommand(loaded.value, outputPath, overwrite),
|
||||
);
|
||||
};
|
||||
|
||||
/** Publish complete parent Evidence before delivering it or its linked summary. */
|
||||
export const deliverAnalysisEvidence = async (
|
||||
evidence: Evidence,
|
||||
outputPath: string,
|
||||
detail: "complete" | "summary" = "complete",
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<Evidence, AnalysisError>> => {
|
||||
const headroom = requireAuthenticationHeadroom(evidence, {
|
||||
operation: evidence.operation,
|
||||
path: absoluteCallerPath(outputPath),
|
||||
description:
|
||||
"Insufficient heap headroom to authenticate the complete parent Evidence",
|
||||
});
|
||||
if (!headroom.ok)
|
||||
return err(headroom.error.retainPartialObservation(evidence));
|
||||
const bundle = createImmutableEvidenceBundle([evidence]);
|
||||
const delivered =
|
||||
detail === "summary"
|
||||
? inspectAnalysisViewValidated(
|
||||
{
|
||||
source: {
|
||||
kind: "retained-evidence",
|
||||
evidence_id: evidence.evidence_id,
|
||||
},
|
||||
view: { kind: "summary" },
|
||||
},
|
||||
(id) => bundle.records.find((record) => record.evidence_id === id),
|
||||
)
|
||||
: ok(evidence);
|
||||
if (!delivered.ok) return delivered;
|
||||
const written = await persistEvidenceBundleCommand(
|
||||
bundle,
|
||||
outputPath,
|
||||
false,
|
||||
signal,
|
||||
evidence.operation,
|
||||
);
|
||||
// Deliver interrupts queued during final publication cleanup before the
|
||||
// command's signal owner accepts completion and removes its listeners.
|
||||
await dispatchQueuedInterrupts();
|
||||
if (!written.ok) return err(written.error.retainPartialObservation(evidence));
|
||||
if (signal?.aborted)
|
||||
return err(
|
||||
new AnalysisCancelledError(evidence.operation, {
|
||||
cause: signal.reason,
|
||||
partialObservation: delivered.value,
|
||||
diagnostics: { evidence_bundle: { ...written.value } },
|
||||
}),
|
||||
);
|
||||
return delivered;
|
||||
};
|
||||
|
||||
/** Resolve the caller's exact retained parent from an authenticated portable bundle. */
|
||||
export const inspectAnalysisViewFromBundle = async (
|
||||
input: InspectAnalysisViewInput,
|
||||
bundlePath: string,
|
||||
resources: ArtifactResourceScope,
|
||||
signal?: AbortSignal,
|
||||
): Promise<Result<Evidence, AnalysisError>> => {
|
||||
if (input.source.kind !== "retained-evidence")
|
||||
return err(
|
||||
new AnalysisInputError("inspect_analysis_view", undefined, [
|
||||
{
|
||||
path: ["source", "kind"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
"--evidence-bundle requires a retained-evidence source with the exact parent evidence_id; inline Evidence already supplies its source",
|
||||
},
|
||||
]),
|
||||
);
|
||||
const loaded = await readImmutableEvidenceBundle(
|
||||
bundlePath,
|
||||
signal,
|
||||
resources,
|
||||
"inspect_analysis_view",
|
||||
);
|
||||
// Authentication and projection are synchronous; dispatch queued interrupts before accepting either result.
|
||||
await dispatchQueuedInterrupts();
|
||||
if (!loaded.ok) return loaded;
|
||||
if (signal?.aborted)
|
||||
return err(
|
||||
new AnalysisCancelledError("inspect_analysis_view", {
|
||||
cause: signal.reason,
|
||||
}),
|
||||
);
|
||||
const projected = inspectAnalysisViewValidated(input, (id) =>
|
||||
loaded.value.records.find((record) => record.evidence_id === id),
|
||||
);
|
||||
await dispatchQueuedInterrupts();
|
||||
if (projected.ok && signal?.aborted)
|
||||
return err(
|
||||
new AnalysisCancelledError("inspect_analysis_view", {
|
||||
cause: signal.reason,
|
||||
partialObservation: projected.value,
|
||||
}),
|
||||
);
|
||||
return projected;
|
||||
};
|
||||
|
||||
/** Publish a completed bundle and retry its exact staged-output cleanup owner. */
|
||||
const persistEvidenceBundleCommand = async (
|
||||
bundle: EvidenceBundle,
|
||||
outputPath: string,
|
||||
overwrite: boolean,
|
||||
signal?: AbortSignal,
|
||||
operation?: string,
|
||||
): Promise<Result<PublishedEvidenceFile, AnalysisError>> => {
|
||||
const resources = new ArtifactResourceScope();
|
||||
const written = await writeEvidenceBundle(
|
||||
loaded.value,
|
||||
bundle,
|
||||
outputPath,
|
||||
overwrite,
|
||||
resources,
|
||||
signal,
|
||||
operation,
|
||||
);
|
||||
if (written.ok) return projectWrite(loaded.value, written);
|
||||
if (written.ok) return written;
|
||||
|
||||
// Confirmed release resolves the bound error to its primary outcome; a
|
||||
// failed retry leaves that error incomplete with its exact retained owner.
|
||||
@@ -54,10 +194,7 @@ export const exportEvidenceBundleCommand = async (
|
||||
written.error instanceof EvidenceFileError &&
|
||||
written.error.published
|
||||
) {
|
||||
return projectWrite(loaded.value, {
|
||||
ok: true,
|
||||
value: written.error.published,
|
||||
});
|
||||
return ok(written.error.published);
|
||||
}
|
||||
return written;
|
||||
};
|
||||
@@ -70,8 +207,18 @@ export const compareEvidenceBundlesCommand = async (input: {
|
||||
// Sealed snapshots let comparison and its bundle digests reuse this
|
||||
// authentication instead of re-validating every record twice more.
|
||||
const [left, right] = await Promise.all([
|
||||
readImmutableEvidenceBundle(input.leftPath),
|
||||
readImmutableEvidenceBundle(input.rightPath),
|
||||
readImmutableEvidenceBundle(
|
||||
input.leftPath,
|
||||
undefined,
|
||||
undefined,
|
||||
"compare_bundles",
|
||||
),
|
||||
readImmutableEvidenceBundle(
|
||||
input.rightPath,
|
||||
undefined,
|
||||
undefined,
|
||||
"compare_bundles",
|
||||
),
|
||||
]);
|
||||
if (!left.ok) return left;
|
||||
if (!right.ok) return right;
|
||||
@@ -88,7 +235,7 @@ export const compareEvidenceBundlesCommand = async (input: {
|
||||
|
||||
const projectWrite = (
|
||||
bundle: EvidenceBundle,
|
||||
written: Awaited<ReturnType<typeof writeEvidenceBundle>>,
|
||||
written: Result<PublishedEvidenceFile, AnalysisError>,
|
||||
): Result<JsonValue, AnalysisError> =>
|
||||
written.ok
|
||||
? ok({
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { requireAuthenticationHeadroom } from "./JsonAuthenticationHeadroom.js";
|
||||
import { absoluteCallerPath } from "../filesystem/callerPath.js";
|
||||
|
||||
import {
|
||||
@@ -39,45 +40,47 @@ export const readEvidenceBundle = (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
operation = "import_evidence_bundle",
|
||||
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> =>
|
||||
readBundle(path, parseEvidenceBundle, signal, resources);
|
||||
readBundle(path, parseEvidenceBundle, signal, resources, operation);
|
||||
|
||||
/** Read an authenticated immutable snapshot for a subsequent session import. */
|
||||
export const readImmutableEvidenceBundle = (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
operation = "import_evidence_bundle",
|
||||
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> =>
|
||||
readBundle(path, parseImmutableEvidenceBundle, signal, resources);
|
||||
readBundle(path, parseImmutableEvidenceBundle, signal, resources, operation);
|
||||
|
||||
const readBundle = async (
|
||||
path: string,
|
||||
parseBundle: (input: unknown) => EvidenceBundle,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
operation = "import_evidence_bundle",
|
||||
): Promise<Result<EvidenceBundle, EvidenceReadFailure>> => {
|
||||
if (signal?.aborted)
|
||||
return err(
|
||||
new AnalysisCancelledError("import_evidence_bundle", {
|
||||
new AnalysisCancelledError(operation, {
|
||||
cause: signal.reason,
|
||||
}),
|
||||
);
|
||||
const loaded = await readJsonFile(path, signal, resources);
|
||||
if (!loaded.ok) {
|
||||
if (loaded.error instanceof AnalysisCancelledError)
|
||||
return err(
|
||||
new AnalysisCancelledError("import_evidence_bundle", {
|
||||
cause: loaded.error.cause,
|
||||
}),
|
||||
);
|
||||
return loaded;
|
||||
}
|
||||
const loaded = await readJsonFile(path, signal, resources, operation);
|
||||
if (!loaded.ok) return loaded;
|
||||
if (signal?.aborted)
|
||||
return err(
|
||||
new AnalysisCancelledError("import_evidence_bundle", {
|
||||
new AnalysisCancelledError(operation, {
|
||||
cause: signal.reason,
|
||||
}),
|
||||
);
|
||||
const headroom = requireAuthenticationHeadroom(loaded.value, {
|
||||
operation,
|
||||
path: absoluteCallerPath(path),
|
||||
description:
|
||||
"Insufficient heap headroom to authenticate the Evidence bundle",
|
||||
});
|
||||
if (!headroom.ok) return headroom;
|
||||
let bundle: EvidenceBundle;
|
||||
try {
|
||||
bundle = parseBundle(loaded.value);
|
||||
@@ -121,6 +124,7 @@ export const writeEvidenceBundle = async (
|
||||
overwrite: boolean,
|
||||
resources: ArtifactResourceScope,
|
||||
signal?: AbortSignal,
|
||||
operation = "export_evidence_bundle",
|
||||
): Promise<
|
||||
Result<
|
||||
{ readonly path: string; readonly bytes: number },
|
||||
@@ -128,7 +132,11 @@ export const writeEvidenceBundle = async (
|
||||
>
|
||||
> => {
|
||||
if (signal?.aborted === true)
|
||||
return err(new AnalysisCancelledError("export_evidence_bundle"));
|
||||
return err(
|
||||
new AnalysisCancelledError(operation, {
|
||||
cause: signal.reason,
|
||||
}),
|
||||
);
|
||||
let checked: EvidenceBundle;
|
||||
try {
|
||||
checked = parseEvidenceBundle(bundle);
|
||||
@@ -144,8 +152,6 @@ export const writeEvidenceBundle = async (
|
||||
path,
|
||||
overwrite,
|
||||
resources,
|
||||
signal === undefined
|
||||
? undefined
|
||||
: { signal, operation: "export_evidence_bundle" },
|
||||
signal === undefined ? undefined : { signal, operation },
|
||||
);
|
||||
};
|
||||
@@ -22,7 +22,9 @@ describe("exact Evidence input resolution", () => {
|
||||
actual: null,
|
||||
},
|
||||
});
|
||||
expect(projected.message).toContain("not retained in this session");
|
||||
expect(projected.message).toContain(
|
||||
"not available from the selected source",
|
||||
);
|
||||
expect(projected.remediation.action).toContain(
|
||||
"complete inline Evidence",
|
||||
);
|
||||
|
||||
@@ -18,7 +18,7 @@ export const resolveEvidenceInput = (
|
||||
new EvidenceReferenceError(
|
||||
input.evidence_id,
|
||||
"missing",
|
||||
"Evidence retained in this session",
|
||||
"Evidence available to the selected source",
|
||||
null,
|
||||
),
|
||||
);
|
||||
|
||||
@@ -4,6 +4,50 @@ import {
|
||||
requireAuthenticationHeadroom,
|
||||
} from "./JsonAuthenticationHeadroom.js";
|
||||
describe("JSON authentication headroom", () => {
|
||||
it("does not queue every row while deciding whether a wide report can fit", () => {
|
||||
let pending = 0;
|
||||
let peak = 0;
|
||||
const rows: { admission_probe: boolean }[] = [];
|
||||
for (let index = 0; index < 512; index++) {
|
||||
const row = {
|
||||
get admission_probe() {
|
||||
pending--;
|
||||
return true;
|
||||
},
|
||||
};
|
||||
// Observe reading a row separately from examining its scalar. A width
|
||||
// queue reads every row first; an iterator finishes each row before advancing.
|
||||
Object.defineProperty(rows, index, {
|
||||
enumerable: true,
|
||||
get: () => {
|
||||
peak = Math.max(peak, ++pending);
|
||||
if (pending > 32)
|
||||
throw new Error(
|
||||
"Admission queued report rows before refusing their allocation",
|
||||
);
|
||||
return row;
|
||||
},
|
||||
});
|
||||
}
|
||||
const value = { rows };
|
||||
const result = requireAuthenticationHeadroom(value, {
|
||||
operation: "inspect_managed_members",
|
||||
path: "/tmp/parent.json",
|
||||
description: "Cannot authenticate",
|
||||
availableBytes: 0,
|
||||
});
|
||||
expect(pending).toBe(0);
|
||||
expect(peak).toBe(1);
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "AnalysisResourceConstraintError",
|
||||
reportedLimits: {
|
||||
serialized_json_utf16_bytes: JSON.stringify(value).length * 2,
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
it("estimates parsed JSON at no less than its UTF-16 text", () => {
|
||||
const text = "x".repeat(1000);
|
||||
expect(estimateJsonValueBytes(text)).toBeGreaterThanOrEqual(2000);
|
||||
@@ -42,3 +86,28 @@ describe("JSON authentication headroom", () => {
|
||||
).toEqual({ ok: true, value: undefined });
|
||||
});
|
||||
});
|
||||
|
||||
it.each([
|
||||
["control characters", { text: "\u0000\u0001\b\t\n\f\r".repeat(2000) }],
|
||||
[
|
||||
"escaped keys",
|
||||
{ ['\u0000\\"'.repeat(2000)]: [true, false, null, -0, 1e30] },
|
||||
],
|
||||
["surrogate boundaries", { text: "😀\ud800x\udfff".repeat(2000) }],
|
||||
])("reserves actual escaped JSON storage for %s", (_label, value) => {
|
||||
const result = requireAuthenticationHeadroom(value, {
|
||||
operation: "inspect_analysis_view",
|
||||
path: "/tmp/bundle.json",
|
||||
description: "Cannot authenticate bundle",
|
||||
availableBytes: estimateJsonValueBytes(value) * 2 + 1,
|
||||
});
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
_tag: "AnalysisResourceConstraintError",
|
||||
reportedLimits: {
|
||||
serialized_json_utf16_bytes: JSON.stringify(value).length * 2,
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
@@ -1,32 +1,66 @@
|
||||
import { jsonStringCodeUnits } from "../domain/jsonSerialization.js";
|
||||
import { getHeapStatistics } from "node:v8";
|
||||
import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";
|
||||
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
||||
import { err, ok, type Result } from "../domain/result.js";
|
||||
|
||||
/** Authentication clones parsed JSON and hashes its canonical commitment. */
|
||||
const AUTHENTICATION_COPIES = 2;
|
||||
|
||||
/** Conservative bytes a parsed JSON value occupies: UTF-16 text plus container and slot overhead. */
|
||||
export const estimateJsonValueBytes = (value: unknown): number => {
|
||||
let bytes = 0;
|
||||
const stack: unknown[] = [value];
|
||||
/** Parsed working copies and conservative UTF-16 storage for escaped JSON. */
|
||||
const estimateJsonStorage = (
|
||||
value: unknown,
|
||||
): { valueBytes: number; serializedUtf16Bytes: number } => {
|
||||
let valueBytes = 0;
|
||||
let serializedCharacters = 0;
|
||||
const stack: Iterator<unknown>[] = [[value][Symbol.iterator]()];
|
||||
while (stack.length > 0) {
|
||||
const item = stack.pop();
|
||||
if (typeof item === "string") bytes += 64 + item.length * 2;
|
||||
else if (Array.isArray(item)) {
|
||||
bytes += 128 + item.length * 16;
|
||||
for (const entry of item) stack.push(entry);
|
||||
const next = stack[stack.length - 1]!.next();
|
||||
if (next.done) {
|
||||
stack.pop();
|
||||
continue;
|
||||
}
|
||||
const item = next.value;
|
||||
if (typeof item === "string") {
|
||||
valueBytes += 64 + item.length * 2;
|
||||
serializedCharacters += jsonStringCodeUnits(item);
|
||||
} else if (Array.isArray(item)) {
|
||||
valueBytes += 128 + item.length * 16;
|
||||
serializedCharacters += 2 + Math.max(0, item.length - 1);
|
||||
stack.push(item.values());
|
||||
} else if (typeof item === "object" && item !== null) {
|
||||
bytes += 128;
|
||||
for (const [key, entry] of Object.entries(item)) {
|
||||
bytes += 64 + key.length * 2;
|
||||
stack.push(entry);
|
||||
}
|
||||
} else bytes += 16;
|
||||
valueBytes += 128;
|
||||
serializedCharacters += 2;
|
||||
stack.push(
|
||||
(function* () {
|
||||
let count = 0;
|
||||
for (const key in item) {
|
||||
if (!Object.hasOwn(item, key)) continue;
|
||||
valueBytes += 64 + key.length * 2;
|
||||
serializedCharacters +=
|
||||
jsonStringCodeUnits(key) + 1 + (count++ === 0 ? 0 : 1);
|
||||
yield (item as Record<string, unknown>)[key];
|
||||
}
|
||||
})(),
|
||||
);
|
||||
} else {
|
||||
valueBytes += 16;
|
||||
serializedCharacters +=
|
||||
typeof item === "number"
|
||||
? String(item).length
|
||||
: item === true
|
||||
? 4
|
||||
: item === false
|
||||
? 5
|
||||
: 4;
|
||||
}
|
||||
}
|
||||
return bytes;
|
||||
return { valueBytes, serializedUtf16Bytes: serializedCharacters * 2 };
|
||||
};
|
||||
|
||||
/** Conservative parsed JSON bytes, independent of its escaped representation. */
|
||||
export const estimateJsonValueBytes = (value: unknown): number =>
|
||||
estimateJsonStorage(value).valueBytes;
|
||||
|
||||
/** Refuse before authentication when live heap headroom cannot hold its validation and commitment working copies. */
|
||||
export const requireAuthenticationHeadroom = (
|
||||
value: unknown,
|
||||
@@ -36,11 +70,14 @@ export const requireAuthenticationHeadroom = (
|
||||
readonly description: string;
|
||||
readonly availableBytes?: number;
|
||||
},
|
||||
): Result<void, AnalysisError> => {
|
||||
): Result<void, AnalysisResourceConstraintError> => {
|
||||
const availableBytes =
|
||||
options.availableBytes ?? getHeapStatistics().total_available_size;
|
||||
const valueBytes = estimateJsonValueBytes(value);
|
||||
const requiredBytes = valueBytes * AUTHENTICATION_COPIES;
|
||||
const { valueBytes, serializedUtf16Bytes } = estimateJsonStorage(value);
|
||||
// Canonical hashing and manifest normalization can still encode scalars or
|
||||
// metadata; account for their escaped representations before allocating them.
|
||||
const requiredBytes =
|
||||
(valueBytes + serializedUtf16Bytes) * AUTHENTICATION_COPIES;
|
||||
if (requiredBytes <= availableBytes) return ok(undefined);
|
||||
return err(
|
||||
new AnalysisResourceConstraintError(
|
||||
@@ -50,6 +87,7 @@ export const requireAuthenticationHeadroom = (
|
||||
{
|
||||
input_path: options.path,
|
||||
projected_value_bytes: valueBytes,
|
||||
serialized_json_utf16_bytes: serializedUtf16Bytes,
|
||||
authentication_bytes: requiredBytes,
|
||||
available_heap_bytes: availableBytes,
|
||||
},
|
||||
|
||||
@@ -52,13 +52,14 @@ export const readJsonFile = async (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
operation = "read_evidence_file",
|
||||
): Promise<
|
||||
Result<
|
||||
unknown,
|
||||
EvidenceFileError | AnalysisResourceConstraintError | AnalysisCancelledError
|
||||
>
|
||||
> => {
|
||||
const read = await readJsonFileWithSource(path, signal, resources);
|
||||
const read = await readJsonFileWithSource(path, signal, resources, operation);
|
||||
return read.ok ? ok(read.value.data) : read;
|
||||
};
|
||||
|
||||
@@ -67,6 +68,7 @@ export const readJsonFileWithSource = (
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
resources?: ArtifactResourceScope,
|
||||
operation = "read_evidence_file",
|
||||
): Promise<
|
||||
Result<
|
||||
{ readonly data: unknown; readonly path: string },
|
||||
@@ -78,13 +80,14 @@ export const readJsonFileWithSource = (
|
||||
async (selected) => {
|
||||
const read = await readJsonInputFile(
|
||||
selected,
|
||||
"read_evidence_file",
|
||||
operation,
|
||||
signal,
|
||||
resources,
|
||||
);
|
||||
return read.ok ? ok({ data: read.value, path: selected }) : read;
|
||||
},
|
||||
signal,
|
||||
operation,
|
||||
);
|
||||
|
||||
/** Read selected JSON members through the same regular-file error boundary. */
|
||||
@@ -124,6 +127,7 @@ const readJsonFileInput = async <Value>(
|
||||
>
|
||||
>,
|
||||
signal?: AbortSignal,
|
||||
operation = "read_evidence_file",
|
||||
): Promise<
|
||||
Result<
|
||||
Value,
|
||||
@@ -153,7 +157,7 @@ const readJsonFileInput = async <Value>(
|
||||
if (cause instanceof AnalysisResourceConstraintError) return err(cause);
|
||||
if (cause instanceof JsonInputCancellationFailure)
|
||||
return err(
|
||||
new AnalysisCancelledError("read_evidence_file", {
|
||||
new AnalysisCancelledError(operation, {
|
||||
cause: cause.reason,
|
||||
}),
|
||||
);
|
||||
@@ -166,7 +170,7 @@ const readJsonFileInput = async <Value>(
|
||||
);
|
||||
if (isJsonReadCancellation(cause, signal))
|
||||
return err(
|
||||
new AnalysisCancelledError("read_evidence_file", {
|
||||
new AnalysisCancelledError(operation, {
|
||||
cause: signal?.reason,
|
||||
}),
|
||||
);
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { setImmediate } from "node:timers/promises";
|
||||
import { INSPECT_ANALYSIS_VIEW_OPERATION } from "../../domain/analysisView/analysisViewErrors.js";
|
||||
import { jsonValueSchema } from "../../domain/jsonValue.js";
|
||||
import { z } from "zod";
|
||||
|
||||
import { ANALYSIS_VIEW_PROVIDER } from "../InvestigationProviders.js";
|
||||
@@ -25,7 +26,6 @@ import {
|
||||
type AnalysisViewRequest,
|
||||
type InspectAnalysisViewInput,
|
||||
} from "../../domain/analysisView/analysisView.js";
|
||||
import { jsonValueSchema } from "../../domain/jsonValue.js";
|
||||
import {
|
||||
immutableJsonSnapshotMember,
|
||||
isImmutableJsonSnapshot,
|
||||
@@ -332,39 +332,44 @@ const createAnalysisViewEvidence = (
|
||||
? {}
|
||||
: { architecture: parent.subject.architecture }),
|
||||
};
|
||||
return createEvidence(target, ANALYSIS_VIEW_PROVIDER, {
|
||||
predicateType: "rea.analysis-view",
|
||||
operation: INSPECT_ANALYSIS_VIEW_OPERATION,
|
||||
parameters: {
|
||||
parent_evidence_id: parent.evidence_id,
|
||||
view: jsonValueSchema.parse(input.view),
|
||||
return createEvidence(
|
||||
target,
|
||||
ANALYSIS_VIEW_PROVIDER,
|
||||
{
|
||||
predicateType: "rea.analysis-view",
|
||||
operation: INSPECT_ANALYSIS_VIEW_OPERATION,
|
||||
parameters: {
|
||||
parent_evidence_id: parent.evidence_id,
|
||||
view: jsonValueSchema.parse(input.view),
|
||||
},
|
||||
result: jsonValueSchema.parse(result),
|
||||
rawResult: null,
|
||||
confidence:
|
||||
// Grouping is whole-capture, so any templated group or parameter makes the result inferred;
|
||||
// entity types and identity in an extracted state always are.
|
||||
result.kind === "environment-state" ||
|
||||
((result.kind === "api-surface" ||
|
||||
result.kind === "environment-manifest") &&
|
||||
result.templated_groups > 0)
|
||||
? "inferred"
|
||||
: "derived",
|
||||
authority: parent.authority,
|
||||
limitations: result.limitations,
|
||||
...(result.kind === "native" && parent.relationship_coverage !== null
|
||||
? { relationshipCoverage: parent.relationship_coverage }
|
||||
: {}),
|
||||
locations: [
|
||||
...(result.artifact != null && result.artifact.path.length > 0
|
||||
? [{ kind: "artifact-path" as const, path: result.artifact.path }]
|
||||
: []),
|
||||
...(result.kind === "native" &&
|
||||
result.procedure_address !== null &&
|
||||
result.procedure_address.length > 0
|
||||
? [{ kind: "address" as const, address: result.procedure_address }]
|
||||
: []),
|
||||
],
|
||||
evidenceLinks: [parent.evidence_id],
|
||||
},
|
||||
result: jsonValueSchema.parse(result),
|
||||
rawResult: null,
|
||||
confidence:
|
||||
// Grouping is whole-capture, so any templated group or parameter makes the result inferred;
|
||||
// entity types and identity in an extracted state always are.
|
||||
result.kind === "environment-state" ||
|
||||
((result.kind === "api-surface" ||
|
||||
result.kind === "environment-manifest") &&
|
||||
result.templated_groups > 0)
|
||||
? "inferred"
|
||||
: "derived",
|
||||
authority: parent.authority,
|
||||
limitations: result.limitations,
|
||||
...(result.kind === "native" && parent.relationship_coverage !== null
|
||||
? { relationshipCoverage: parent.relationship_coverage }
|
||||
: {}),
|
||||
locations: [
|
||||
...(result.artifact != null && result.artifact.path.length > 0
|
||||
? [{ kind: "artifact-path" as const, path: result.artifact.path }]
|
||||
: []),
|
||||
...(result.kind === "native" &&
|
||||
result.procedure_address !== null &&
|
||||
result.procedure_address.length > 0
|
||||
? [{ kind: "address" as const, address: result.procedure_address }]
|
||||
: []),
|
||||
],
|
||||
evidenceLinks: [parent.evidence_id],
|
||||
});
|
||||
{ immutable: true },
|
||||
);
|
||||
};
|
||||
@@ -32,16 +32,13 @@ export const readEvidenceFileSource = async (
|
||||
cause: signal.reason,
|
||||
}),
|
||||
);
|
||||
const loaded = await readJsonFile(path, signal, resources);
|
||||
if (!loaded.ok) {
|
||||
if (loaded.error instanceof AnalysisCancelledError)
|
||||
return err(
|
||||
new AnalysisCancelledError(INSPECT_ANALYSIS_VIEW_OPERATION, {
|
||||
cause: loaded.error.cause,
|
||||
}),
|
||||
);
|
||||
return loaded;
|
||||
}
|
||||
const loaded = await readJsonFile(
|
||||
path,
|
||||
signal,
|
||||
resources,
|
||||
INSPECT_ANALYSIS_VIEW_OPERATION,
|
||||
);
|
||||
if (!loaded.ok) return loaded;
|
||||
if (signal?.aborted)
|
||||
return err(
|
||||
new AnalysisCancelledError(INSPECT_ANALYSIS_VIEW_OPERATION, {
|
||||
|
||||
@@ -37,16 +37,13 @@ export const resolveSourceToBundleReference = async (
|
||||
}),
|
||||
);
|
||||
if (!("kind" in reference)) return ok({ reference });
|
||||
const read = await readJsonFileWithSource(reference.path, signal, resources);
|
||||
if (!read.ok) {
|
||||
return read.error instanceof AnalysisCancelledError
|
||||
? err(
|
||||
new AnalysisCancelledError("compare_source_to_bundle", {
|
||||
cause: read.error.cause,
|
||||
}),
|
||||
)
|
||||
: read;
|
||||
}
|
||||
const read = await readJsonFileWithSource(
|
||||
reference.path,
|
||||
signal,
|
||||
resources,
|
||||
"compare_source_to_bundle",
|
||||
);
|
||||
if (!read.ok) return read;
|
||||
await setImmediate();
|
||||
if (cancelled())
|
||||
return err(
|
||||
|
||||
@@ -83,6 +83,7 @@ export const loadNativeMatchingBundleSources = async ({
|
||||
paths[file]!,
|
||||
admission.signal,
|
||||
resources,
|
||||
admission.operation,
|
||||
);
|
||||
if (!loaded.ok) throw loaded.error;
|
||||
snapshots.push(await recordSnapshot(loaded.value, admission));
|
||||
@@ -141,6 +142,7 @@ export const loadNativeMatchingBundleSources = async ({
|
||||
paths[file]!,
|
||||
admission.signal,
|
||||
resources,
|
||||
admission.operation,
|
||||
);
|
||||
if (!loaded.ok) throw loaded.error;
|
||||
if ((await recordSnapshot(loaded.value, admission)) !== snapshots[file])
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
import { z } from "incur";
|
||||
|
||||
import { inspectAnalysisViewValidatedWithFiles } from "../application/analysisView/AnalysisViewService.js";
|
||||
import { inspectAnalysisViewFromBundle } from "../application/EvidenceBundleCommands.js";
|
||||
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
|
||||
import { ANALYSIS_VIEW_PROVIDER } from "../application/InvestigationProviders.js";
|
||||
import { readEvidenceBundle } from "../application/EvidenceBundleFiles.js";
|
||||
import { inspectEvidenceBundle } from "../application/investigation/InspectEvidenceBundle.js";
|
||||
import {
|
||||
@@ -12,9 +15,11 @@ import { parseCliJsonInput, resolveCliJsonPaths } from "../cliJsonInput.js";
|
||||
import { logCliCommand } from "../cliLogging.js";
|
||||
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
|
||||
import { jsonValueSchema } from "../domain/jsonValue.js";
|
||||
import type { Logger } from "pino";
|
||||
import type { CliInstance } from "./types.js";
|
||||
import { localPathStringSchema } from "../domain/localPath.js";
|
||||
import { withCommandCancellation } from "./commandCancellation.js";
|
||||
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
|
||||
|
||||
import { inspectAnalysisViewInputSchema } from "../domain/analysisView/analysisView.js";
|
||||
/** Project selected views of completed analysis Evidence through the CLI. */
|
||||
@@ -54,7 +59,12 @@ export const registerAnalysisViewCommands = (
|
||||
),
|
||||
),
|
||||
};
|
||||
const loaded = await readEvidenceBundle(parsed.data.path);
|
||||
const loaded = await readEvidenceBundle(
|
||||
parsed.data.path,
|
||||
undefined,
|
||||
undefined,
|
||||
"get_evidence_bundle",
|
||||
);
|
||||
if (!loaded.ok)
|
||||
return {
|
||||
error: "Evidence bundle inspection failed",
|
||||
@@ -75,34 +85,63 @@ export const registerAnalysisViewCommands = (
|
||||
args: z.object({
|
||||
inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
|
||||
}),
|
||||
run: ({ args }) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectAnalysisView, async () => {
|
||||
const input = await parseCliJsonInput(
|
||||
args.inputJson,
|
||||
CLI_COMMANDS.inspectAnalysisView,
|
||||
);
|
||||
if (!input.ok) return input.error;
|
||||
// An evidence-file path is resolved against the operator's working directory.
|
||||
const value = resolveCliJsonPaths(input.value, [["source", "path"]]);
|
||||
const parsed = inspectAnalysisViewInputSchema.safeParse(value);
|
||||
if (!parsed.success)
|
||||
return {
|
||||
error: "Application workflow failed",
|
||||
...projectAnalysisError(
|
||||
analysisInputErrorFromIssues(
|
||||
CLI_COMMANDS.inspectAnalysisView,
|
||||
parsed.error.issues,
|
||||
value,
|
||||
),
|
||||
),
|
||||
};
|
||||
const result = await inspectAnalysisViewValidatedWithFiles(parsed.data);
|
||||
return result.ok
|
||||
? jsonValueSchema.parse(result.value)
|
||||
: {
|
||||
options: z.object({
|
||||
evidenceBundle: localPathStringSchema
|
||||
.optional()
|
||||
.describe(
|
||||
"Read the exact retained-evidence source ID from this local Evidence bundle without reopening the target; omit for inline Evidence",
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(logger, CLI_COMMANDS.inspectAnalysisView, async () => {
|
||||
const input = await parseCliJsonInput(
|
||||
args.inputJson,
|
||||
CLI_COMMANDS.inspectAnalysisView,
|
||||
signal,
|
||||
);
|
||||
if (!input.ok) return input.error;
|
||||
// An evidence-file path is resolved against the operator's working directory.
|
||||
const value = resolveCliJsonPaths(input.value, [["source", "path"]]);
|
||||
const parsed = inspectAnalysisViewInputSchema.safeParse(value);
|
||||
if (!parsed.success)
|
||||
return {
|
||||
error: "Application workflow failed",
|
||||
...projectAnalysisError(result.error),
|
||||
...projectAnalysisError(
|
||||
analysisInputErrorFromIssues(
|
||||
CLI_COMMANDS.inspectAnalysisView,
|
||||
parsed.error.issues,
|
||||
value,
|
||||
),
|
||||
),
|
||||
};
|
||||
}),
|
||||
const resources = new ArtifactResourceScope();
|
||||
const bundlePath = options.evidenceBundle;
|
||||
const result = await finishAnalysisCommand(
|
||||
() =>
|
||||
bundlePath === undefined
|
||||
? inspectAnalysisViewValidatedWithFiles(
|
||||
parsed.data,
|
||||
undefined,
|
||||
{ signal, resources },
|
||||
)
|
||||
: inspectAnalysisViewFromBundle(
|
||||
parsed.data,
|
||||
bundlePath,
|
||||
resources,
|
||||
signal,
|
||||
),
|
||||
resources,
|
||||
ANALYSIS_VIEW_PROVIDER.id,
|
||||
"inspect_analysis_view",
|
||||
signal,
|
||||
);
|
||||
// Preserve the inline command's existing error label without copying
|
||||
// the authenticated completed Evidence or its partial observation.
|
||||
return bundlePath === undefined && "code" in result
|
||||
? { error: "Application workflow failed", ...result }
|
||||
: result;
|
||||
}),
|
||||
),
|
||||
});
|
||||
};
|
||||
@@ -9,6 +9,7 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
||||
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
|
||||
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
|
||||
import type { Result } from "../domain/result.js";
|
||||
import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js";
|
||||
|
||||
/** Finish a one-shot CLI operation while retaining primary results through close. */
|
||||
export const finishAnalysisCommand = async <
|
||||
@@ -59,16 +60,18 @@ export const finishAnalysisCommand = async <
|
||||
);
|
||||
}
|
||||
if (result.ok) cleanup.retainPartialObservation(result.value);
|
||||
return projectAnalysisError(
|
||||
result.ok
|
||||
result = {
|
||||
ok: false,
|
||||
error: result.ok
|
||||
? cleanup
|
||||
: analysisErrorWithCleanupFailure(
|
||||
result.error,
|
||||
cleanup,
|
||||
canonicalOperation,
|
||||
),
|
||||
);
|
||||
};
|
||||
}
|
||||
await dispatchQueuedInterrupts();
|
||||
if (result.ok && signal.aborted)
|
||||
return projectAnalysisError(
|
||||
new AnalysisCancelledError(canonicalOperation, {
|
||||
|
||||
@@ -17,6 +17,8 @@ import type { Logger } from "pino";
|
||||
import type { CliInstance } from "./types.js";
|
||||
import { registerProjectManagedApplicationGraph } from "./managedProjectGraphCommand.js";
|
||||
import { managedMembersInputSchema } from "../contracts/managed/managedToolContracts.js";
|
||||
import { localPathStringSchema } from "../domain/localPath.js";
|
||||
import { withCommandCancellation } from "./commandCancellation.js";
|
||||
|
||||
export const registerManagedCommands = (
|
||||
cli: CliInstance,
|
||||
@@ -64,14 +66,33 @@ const registerInspectManagedMembers = (
|
||||
type: managedMembersInputSchema.shape.type_names.describe(
|
||||
"Inspect only members declared by this exact type full name, and the string literals they load, such as System.Threading.Monitor; a nested type is named by its bare name, which selects every nested type of that name (repeatable)",
|
||||
),
|
||||
detail: managedMembersInputSchema.shape.detail.describe(
|
||||
"complete returns full Evidence (default); summary returns identity, selection, coverage, limitations and collection counts and requires --evidence-bundle",
|
||||
),
|
||||
evidenceBundle: localPathStringSchema
|
||||
.optional()
|
||||
.describe(
|
||||
"Write complete parent Evidence to a new local bundle for later inspect-analysis-view calls; never replaces an existing path",
|
||||
),
|
||||
}),
|
||||
run: ({ args, options }) =>
|
||||
logCliCommand(logger, "inspect-managed-members", () =>
|
||||
runProviderAnalysis(
|
||||
args.path,
|
||||
"inspect_managed_members",
|
||||
options.type === undefined ? {} : { type_names: options.type },
|
||||
logger,
|
||||
withCommandCancellation((signal) =>
|
||||
logCliCommand(logger, "inspect-managed-members", () =>
|
||||
runProviderAnalysis(
|
||||
args.path,
|
||||
"inspect_managed_members",
|
||||
options.type === undefined ? {} : { type_names: options.type },
|
||||
logger,
|
||||
signal,
|
||||
{
|
||||
...(options.detail === undefined
|
||||
? {}
|
||||
: { detail: options.detail }),
|
||||
...(options.evidenceBundle === undefined
|
||||
? {}
|
||||
: { evidenceBundlePath: options.evidenceBundle }),
|
||||
},
|
||||
),
|
||||
),
|
||||
),
|
||||
});
|
||||
|
||||
@@ -7,10 +7,13 @@ type DirectAnalysisStatusRuntime =
|
||||
typeof import("../application/DirectAnalysisStatus.js");
|
||||
|
||||
type BoundOperation<Operation> = Operation extends (
|
||||
dependencies: infer _Dependencies,
|
||||
...args: infer Arguments
|
||||
) => infer Result
|
||||
? (...args: Arguments) => Result
|
||||
? (
|
||||
...args: Arguments extends [unknown, ...infer BoundArguments]
|
||||
? BoundArguments
|
||||
: never
|
||||
) => Result
|
||||
: never;
|
||||
|
||||
/** Bind one-shot analysis and status commands to one caller-selected environment. */
|
||||
|
||||
@@ -118,7 +118,7 @@ export const analysisErrorRemediationAction = (
|
||||
? "Correct the reported address, document, or arguments and retry."
|
||||
: "Review the Hopper diagnostic details and correct the request or target; run `rea doctor` if the provider itself is failing. Repeating the unchanged request is not expected to succeed.";
|
||||
if (error instanceof EvidenceReferenceError)
|
||||
return "Use an exact Evidence reference retained by this session, supply the complete inline Evidence, re-run its producer, or import its Evidence bundle. close_binary clears retained records.";
|
||||
return "Use an exact Evidence reference available from the selected source, supply the complete inline Evidence, re-run its producer, or select/import its Evidence bundle. close_binary clears a server session's retained records.";
|
||||
if (
|
||||
error instanceof BinaryTargetError &&
|
||||
error.constraint === "directory_requires_file"
|
||||
@@ -286,7 +286,7 @@ export const analysisErrorUserMessage = (error: AnalysisError): string => {
|
||||
if (error instanceof ArtifactOperationError) return artifactMessage(error);
|
||||
if (error instanceof EvidenceReferenceError)
|
||||
return error.reason === "missing"
|
||||
? `Evidence ${error.evidenceId} is not retained in this session. Supply complete inline Evidence, re-run its producer, or import its bundle before using this reference.`
|
||||
? `Evidence ${error.evidenceId} is not available from the selected source. Supply complete inline Evidence, re-run its producer, or select/import its bundle before using this reference.`
|
||||
: `Evidence ${error.evidenceId} does not match the requested reference (${error.reason}). Check the expected and actual identity in the diagnostic details.`;
|
||||
if (error instanceof EvidenceIntegrityError)
|
||||
return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
|
||||
|
||||
+16
-1
@@ -24,6 +24,7 @@ import {
|
||||
} from "./jsonValue.js";
|
||||
import {
|
||||
freezeJsonSnapshot,
|
||||
freezeOwnedJsonTreeSnapshot,
|
||||
canBorrowParsedJsonSnapshot,
|
||||
isImmutableJsonSnapshot,
|
||||
} from "./immutableJson.js";
|
||||
@@ -346,11 +347,17 @@ const rememberImmutableEvidence = (evidence: Evidence): Evidence => {
|
||||
return evidence;
|
||||
};
|
||||
|
||||
/** Ownership policy for the freshly parsed Evidence snapshot. */
|
||||
export interface EvidenceCreationOptions {
|
||||
readonly immutable?: boolean;
|
||||
}
|
||||
|
||||
/** Build deterministic Evidence from an immutable artifact subject. */
|
||||
export const createEvidence = (
|
||||
target: EvidenceSubjectTarget | BinaryTarget | undefined,
|
||||
provider: EvidenceProvider,
|
||||
observation: EvidenceObservation,
|
||||
options?: EvidenceCreationOptions,
|
||||
): Evidence => {
|
||||
const { normalized, sharedResult } = normalizeEvidenceObservation(
|
||||
target,
|
||||
@@ -361,7 +368,15 @@ export const createEvidence = (
|
||||
...normalized,
|
||||
evidence_id: computeEvidenceId(normalized),
|
||||
};
|
||||
return sharedResult ? rememberImmutableEvidence(evidence) : evidence;
|
||||
// Seal this already parsed, exclusively owned snapshot without authenticating
|
||||
// or copying its payload again, including later partial-error delivery.
|
||||
if (sharedResult || options?.immutable === true) {
|
||||
// The normalizer's JSON parser clones mutable payloads into trees and only
|
||||
// borrows previously sealed roots. No graph-sized sealing scratch is needed.
|
||||
freezeOwnedJsonTreeSnapshot(evidence);
|
||||
immutableEvidenceSnapshots.set(evidence, evidence);
|
||||
}
|
||||
return evidence;
|
||||
};
|
||||
|
||||
/** Create Evidence from owned immutable JSON while exposing cooperative computation steps. */
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { equalJsonText } from "./jsonSerialization.js";
|
||||
import { z } from "zod";
|
||||
import canonicalize from "canonicalize";
|
||||
|
||||
@@ -322,7 +323,7 @@ const authenticateBundle = (
|
||||
}),
|
||||
parsed.unknowns,
|
||||
);
|
||||
if (JSON.stringify(parsed) !== JSON.stringify(canonical))
|
||||
if (!equalJsonText(parsed, canonical))
|
||||
throw new NonCanonicalEvidenceBundleError();
|
||||
if (seal) {
|
||||
freezeJsonSnapshot(canonical);
|
||||
|
||||
@@ -139,6 +139,74 @@ export const freezeJsonSnapshot = <T extends JsonValue>(value: T): T => {
|
||||
return value;
|
||||
};
|
||||
|
||||
/**
|
||||
* Seal a freshly parsed, exclusively owned JSON tree. Its parser has removed
|
||||
* aliases, accessors and hidden properties; existing sealed subtrees may be shared.
|
||||
* Keep only the active ancestry rather than retaining every completed object.
|
||||
* Unlike general graph sealing, failure can leave this provisional tree frozen.
|
||||
*/
|
||||
export const freezeOwnedJsonTreeSnapshot = <T extends JsonValue>(
|
||||
value: T,
|
||||
): T => {
|
||||
const frames: { value: object; children: Iterator<unknown> }[] = [];
|
||||
const ancestors = new Set<object>();
|
||||
const enter = (item: unknown): void => {
|
||||
if (isImmutableJsonSnapshot(item)) return;
|
||||
if (typeof item !== "object" || item === null)
|
||||
throw new TypeError("Immutable JSON snapshots require JSON values");
|
||||
if (isProxy(item))
|
||||
throw new TypeError("Immutable JSON snapshots cannot contain proxies");
|
||||
if (ancestors.has(item))
|
||||
throw new TypeError(
|
||||
"Immutable JSON snapshots cannot contain circular references",
|
||||
);
|
||||
const prototype: unknown = Object.getPrototypeOf(item);
|
||||
if (
|
||||
!Array.isArray(item) &&
|
||||
prototype !== Object.prototype &&
|
||||
prototype !== null
|
||||
)
|
||||
throw new TypeError("Immutable JSON snapshots require ordinary objects");
|
||||
ancestors.add(item);
|
||||
frames.push({ value: item, children: ownedTreeChildren(item) });
|
||||
};
|
||||
enter(value);
|
||||
while (frames.length > 0) {
|
||||
const frame = frames[frames.length - 1]!;
|
||||
const next = frame.children.next();
|
||||
if (!next.done) enter(next.value);
|
||||
else {
|
||||
Object.freeze(frame.value);
|
||||
ancestors.delete(frame.value);
|
||||
frames.pop();
|
||||
}
|
||||
}
|
||||
if (typeof value === "object" && value !== null)
|
||||
immutableSnapshots.add(value);
|
||||
return value;
|
||||
};
|
||||
|
||||
function* ownedTreeChildren(value: object): Generator<unknown> {
|
||||
if (Array.isArray(value)) {
|
||||
for (let index = 0; index < value.length; index++) {
|
||||
const descriptor = Object.getOwnPropertyDescriptor(value, index);
|
||||
if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
|
||||
throw new TypeError("Owned JSON trees require dense data arrays");
|
||||
yield descriptor.value;
|
||||
}
|
||||
} else {
|
||||
for (const key in value) {
|
||||
if (!Object.hasOwn(value, key)) continue;
|
||||
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
||||
if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))
|
||||
throw new TypeError(
|
||||
"Immutable JSON snapshots cannot contain accessors",
|
||||
);
|
||||
yield descriptor.value;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Seal exclusively owned JSON in bounded steps, authenticating only completion.
|
||||
* Abandonment or failure can leave the provisional input partly frozen.
|
||||
|
||||
@@ -5,6 +5,7 @@ import {
|
||||
bufferedJsonParts,
|
||||
canonicalJsonParts,
|
||||
jsonParts,
|
||||
equalJsonText,
|
||||
} from "./jsonSerialization.js";
|
||||
|
||||
/** Compact and pretty streamed JSON must equal native JSON. */
|
||||
@@ -104,3 +105,28 @@ describe("iterative JSON encoding", () => {
|
||||
expect(smallParts.length).toBeLessThan(20);
|
||||
});
|
||||
});
|
||||
|
||||
describe("JSON text equality without whole-document strings", () => {
|
||||
it.each([
|
||||
[null, null],
|
||||
[-0, 0],
|
||||
[
|
||||
{ first: 1, omitted: undefined, second: 2 },
|
||||
{ first: 1, second: 2 },
|
||||
],
|
||||
[
|
||||
{ first: 1, second: 2 },
|
||||
{ second: 2, first: 1 },
|
||||
],
|
||||
[
|
||||
{ ["\u0000".repeat(9000)]: "\u0001😀\ud800".repeat(20000) },
|
||||
{ ["\u0000".repeat(9000)]: "\u0001😀\ud800".repeat(20000) },
|
||||
],
|
||||
["prefix".repeat(20000) + "a", "prefix".repeat(20000) + "b"],
|
||||
["prefix".repeat(20000), "prefix".repeat(20000) + "a"],
|
||||
])("preserves native JSON comparison semantics", (left, right) => {
|
||||
expect(equalJsonText(left, right)).toBe(
|
||||
JSON.stringify(left) === JSON.stringify(right),
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,3 +1,23 @@
|
||||
/** Exact UTF-16 code units of a JSON string, including escaping and quotes. */
|
||||
export const jsonStringCodeUnits = (value: string): number => {
|
||||
let length = value.length + 2;
|
||||
for (let index = 0; index < value.length; index += 1) {
|
||||
const code = value.charCodeAt(index);
|
||||
if (code === 34 || code === 92) length += 1;
|
||||
else if (code < 32)
|
||||
length +=
|
||||
code === 8 || code === 9 || code === 10 || code === 12 || code === 13
|
||||
? 1
|
||||
: 5;
|
||||
else if (code >= 0xd800 && code <= 0xdfff) {
|
||||
const next = value.charCodeAt(index + 1);
|
||||
if (code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) index += 1;
|
||||
else length += 5;
|
||||
}
|
||||
}
|
||||
return length;
|
||||
};
|
||||
|
||||
/** Encode ordinary JSON as bounded string parts without a document-sized allocation. */
|
||||
export function* jsonParts(value: unknown, pretty = false): Generator<string> {
|
||||
yield* encodeValue(value, pretty, false);
|
||||
@@ -8,6 +28,37 @@ export function* canonicalJsonParts(value: unknown): Generator<string> {
|
||||
yield* encodeValue(value, false, true);
|
||||
}
|
||||
|
||||
/** Compare ordinary JSON text in bounded parts, preserving native key order. */
|
||||
export const equalJsonText = (left: unknown, right: unknown): boolean => {
|
||||
const a = jsonParts(left);
|
||||
const b = jsonParts(right);
|
||||
let x = a.next();
|
||||
let y = b.next();
|
||||
let i = 0;
|
||||
let j = 0;
|
||||
try {
|
||||
while (!x.done && !y.done) {
|
||||
const length = Math.min(x.value.length - i, y.value.length - j);
|
||||
if (x.value.slice(i, i + length) !== y.value.slice(j, j + length))
|
||||
return false;
|
||||
i += length;
|
||||
j += length;
|
||||
if (i === x.value.length) {
|
||||
x = a.next();
|
||||
i = 0;
|
||||
}
|
||||
if (j === y.value.length) {
|
||||
y = b.next();
|
||||
j = 0;
|
||||
}
|
||||
}
|
||||
return x.done === true && y.done === true;
|
||||
} finally {
|
||||
a.return(undefined);
|
||||
b.return(undefined);
|
||||
}
|
||||
};
|
||||
|
||||
/** Buffer JSON parts while preserving complete UTF-16 surrogate pairs. */
|
||||
export function* bufferedJsonParts(parts: Iterable<string>): Generator<string> {
|
||||
let buffer = "";
|
||||
|
||||
@@ -29,6 +29,7 @@ interface ManagedPeFixtureOptions {
|
||||
readonly moduleRowCount?: number;
|
||||
readonly assemblyRowCount?: number;
|
||||
readonly memberRefParentRaw?: number;
|
||||
readonly memberRefRowCount?: number;
|
||||
readonly memberRefName?: string;
|
||||
readonly memberRefSignature?: Buffer;
|
||||
/** Raw MethodDefOrRef coded values, one MethodSpec row each. */
|
||||
@@ -771,7 +772,7 @@ const fixtureIndexWidths = ({
|
||||
[4, 1],
|
||||
[6, options.methodRowCount ?? 1],
|
||||
[8, 0],
|
||||
[10, 1],
|
||||
[10, options.memberRefRowCount ?? 1],
|
||||
[
|
||||
12,
|
||||
options.targetFramework === null
|
||||
@@ -885,7 +886,7 @@ const fixtureMetadataRows = ({
|
||||
],
|
||||
[
|
||||
10,
|
||||
[
|
||||
repeatedRows(options.memberRefRowCount ?? 1, () =>
|
||||
memberRefRow({
|
||||
name: indexes.constructorName,
|
||||
signature: indexes.constructorSignature,
|
||||
@@ -896,7 +897,7 @@ const fixtureMetadataRows = ({
|
||||
? {}
|
||||
: { parentRaw: options.memberRefParentRaw }),
|
||||
}),
|
||||
],
|
||||
),
|
||||
],
|
||||
[12, customAttributeRows({ options, indexes, heapSizes }, widths)],
|
||||
...(indexes.pinvokeModuleName === null
|
||||
|
||||
@@ -0,0 +1,7 @@
|
||||
import { setImmediate } from "node:timers/promises";
|
||||
|
||||
/** Dispatch queued callbacks, then the OS signal notifications they may enqueue. */
|
||||
export const dispatchQueuedInterrupts = async (): Promise<void> => {
|
||||
await setImmediate();
|
||||
await setImmediate();
|
||||
};
|
||||
@@ -37,11 +37,13 @@ export const registerBundleComparisonTool = (
|
||||
input.left_bundle_path,
|
||||
context.mcpReq.signal,
|
||||
resources,
|
||||
contract.name,
|
||||
),
|
||||
readImmutableEvidenceBundle(
|
||||
input.right_bundle_path,
|
||||
context.mcpReq.signal,
|
||||
resources,
|
||||
contract.name,
|
||||
),
|
||||
]);
|
||||
if (!left.ok) return server.delivery.toCallToolResult(left, contract);
|
||||
|
||||
@@ -111,6 +111,7 @@ const registerImportEvidenceTool = ({
|
||||
path,
|
||||
signal,
|
||||
resources,
|
||||
importContract.name,
|
||||
);
|
||||
if (!loaded.ok)
|
||||
return server.delivery.toCallToolResult(loaded, importContract);
|
||||
|
||||
Reference in new issue
Block a user