feat(native): inspect oversized retained function dossiers via bounded views
Add caller-selected native dossier facets with preserved Evidence identity, provenance, unknowns and transport recovery. Refs #1247 and #1065. Co-authored-by: jhuang-tw <77732008+jhuang-tw@users.noreply.github.com> Co-authored-by: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com>
This commit is contained in:
@@ -0,0 +1,202 @@
|
||||
import type { AnalysisError } from "../analysisErrorBase.js";
|
||||
import { uniqueSorted } from "../canonicalOrdering.js";
|
||||
import type { FunctionDossier } from "../hopperValues.js";
|
||||
import { jsonValueSchema } from "../jsonValue.js";
|
||||
import { err, ok, type Result } from "../result.js";
|
||||
import {
|
||||
analysisViewInputError,
|
||||
type AnalysisViewCoverage,
|
||||
type AnalysisViewParent,
|
||||
type AnalysisViewRequest,
|
||||
type UnsignedAnalysisView,
|
||||
} from "./analysisView.js";
|
||||
import {
|
||||
completeWithinViewCoverage,
|
||||
pageViewCoverage,
|
||||
} from "./analysisViewCoverage.js";
|
||||
|
||||
type Artifact = { readonly path: string; readonly sha256: string };
|
||||
|
||||
const viewError = (message: string): AnalysisError =>
|
||||
analysisViewInputError([
|
||||
{ path: ["view"], reason: "invalid_value", message },
|
||||
]);
|
||||
|
||||
const parentFields = (
|
||||
parent: AnalysisViewParent,
|
||||
dossier: FunctionDossier,
|
||||
artifact: Artifact,
|
||||
) => {
|
||||
const flow = dossier.native_value_flow;
|
||||
const api = dossier.native_api;
|
||||
const unknowns: string[] = [];
|
||||
if (flow === null) unknowns.push("native_value_flow was not recorded");
|
||||
else if (!flow.available)
|
||||
unknowns.push("native_value_flow unavailable: " + flow.reason);
|
||||
else if (flow.truncated)
|
||||
unknowns.push(
|
||||
"native_value_flow is truncated; omitted observations remain unknown",
|
||||
);
|
||||
if (api === null) unknowns.push("native_api was not recorded");
|
||||
else if (!api.available)
|
||||
unknowns.push(
|
||||
"native_api unavailable: " + api.reason,
|
||||
...api.residual_unknowns,
|
||||
);
|
||||
return {
|
||||
parent_evidence_id: parent.evidenceId,
|
||||
parent_operation: "analyze_function" as const,
|
||||
parent_digest: parent.evidenceId.slice(3),
|
||||
procedure_address: dossier.procedure.address,
|
||||
artifact,
|
||||
limitations: uniqueSorted([
|
||||
...parent.limitations,
|
||||
...dossier.limitations,
|
||||
...(flow?.limitations ?? []),
|
||||
...(api?.available ? api.limitations : []),
|
||||
]),
|
||||
unknowns: uniqueSorted(unknowns),
|
||||
};
|
||||
};
|
||||
|
||||
const pseudocodePage = (
|
||||
body: string,
|
||||
offset: number,
|
||||
limit: number,
|
||||
): Result<
|
||||
{
|
||||
readonly item: { readonly text: string; readonly unit: "utf16-code-units" };
|
||||
readonly coverage: AnalysisViewCoverage;
|
||||
},
|
||||
AnalysisError
|
||||
> => {
|
||||
const start = Math.min(offset, body.length);
|
||||
const high = (n: number) => n >= 0xd800 && n <= 0xdbff;
|
||||
const low = (n: number) => n >= 0xdc00 && n <= 0xdfff;
|
||||
if (
|
||||
start > 0 &&
|
||||
start < body.length &&
|
||||
high(body.charCodeAt(start - 1)) &&
|
||||
low(body.charCodeAt(start))
|
||||
)
|
||||
return err(viewError("Pseudocode offset splits a UTF-16 surrogate pair."));
|
||||
let end = Math.min(start + limit, body.length);
|
||||
if (
|
||||
end > start &&
|
||||
end < body.length &&
|
||||
high(body.charCodeAt(end - 1)) &&
|
||||
low(body.charCodeAt(end))
|
||||
)
|
||||
end--;
|
||||
if (end === start && start < body.length)
|
||||
return err(
|
||||
viewError(
|
||||
"Increase pseudocode limit to include the next complete Unicode character.",
|
||||
),
|
||||
);
|
||||
return ok({
|
||||
item: { text: body.slice(start, end), unit: "utf16-code-units" },
|
||||
coverage: pageViewCoverage(start, end - start, body.length),
|
||||
});
|
||||
};
|
||||
|
||||
const nativeRows = (
|
||||
dossier: FunctionDossier,
|
||||
facet: Exclude<
|
||||
Extract<AnalysisViewRequest, { readonly kind: "native" }>["facet"],
|
||||
"procedure" | "pseudocode" | "value_flow_summary"
|
||||
>,
|
||||
) => {
|
||||
const sourceFlow = dossier.native_value_flow;
|
||||
const flow = sourceFlow?.available ? sourceFlow : undefined;
|
||||
return {
|
||||
assembly: dossier.assembly,
|
||||
callers: dossier.callers,
|
||||
callees: dossier.callees,
|
||||
incoming_references: dossier.incoming_references,
|
||||
outgoing_references: dossier.outgoing_references,
|
||||
value_flow_operations: flow?.operations,
|
||||
value_flow_def_use: flow?.def_use,
|
||||
value_flow_effects: flow?.effects,
|
||||
value_flow_parameters: flow?.parameters,
|
||||
value_flow_parameter_uses: flow?.parameter_uses,
|
||||
}[facet];
|
||||
};
|
||||
|
||||
/** Project bounded native function facets from complete retained Evidence without reanalysis. */
|
||||
export const projectNativeFunctionView = (
|
||||
parent: AnalysisViewParent,
|
||||
dossier: FunctionDossier,
|
||||
view: AnalysisViewRequest,
|
||||
): Result<UnsignedAnalysisView, AnalysisError> => {
|
||||
if (view.kind !== "native")
|
||||
return err(viewError("analyze_function Evidence requires a native view."));
|
||||
const artifact = parent.artifact;
|
||||
if (!artifact)
|
||||
return err(
|
||||
analysisViewInputError([
|
||||
{
|
||||
path: ["source", "subject"],
|
||||
reason: "invalid_value",
|
||||
message:
|
||||
"Native function Evidence requires an artifact-bound subject.",
|
||||
},
|
||||
]),
|
||||
);
|
||||
const common = parentFields(parent, dossier, artifact);
|
||||
const singleton = (item: unknown): UnsignedAnalysisView => ({
|
||||
kind: "native",
|
||||
view,
|
||||
item: jsonValueSchema.parse(item),
|
||||
coverage: completeWithinViewCoverage(1, 1),
|
||||
...common,
|
||||
});
|
||||
const flow = dossier.native_value_flow;
|
||||
if (view.facet === "procedure" || view.facet === "value_flow_summary") {
|
||||
if (view.offset !== 0)
|
||||
return err(viewError("Singleton native facets require offset 0."));
|
||||
if (view.facet === "procedure") return ok(singleton(dossier.procedure));
|
||||
const status =
|
||||
flow === null
|
||||
? { available: false, reason: "not recorded" }
|
||||
: !flow.available
|
||||
? { available: false, reason: flow.reason }
|
||||
: {
|
||||
available: true,
|
||||
provenance: flow.provenance,
|
||||
truncated: flow.truncated,
|
||||
omitted_operations_lower_bound:
|
||||
flow.omitted_operations_lower_bound,
|
||||
known_omitted_inputs: flow.known_omitted_inputs,
|
||||
known_omitted_edges: flow.known_omitted_edges,
|
||||
operations: flow.operations.length,
|
||||
def_use: flow.def_use.length,
|
||||
effects: flow.effects.length,
|
||||
parameters: flow.parameters.length,
|
||||
parameter_uses: flow.parameter_uses.length,
|
||||
};
|
||||
return ok(singleton(status));
|
||||
}
|
||||
if (view.facet === "pseudocode") {
|
||||
const page = pseudocodePage(dossier.pseudocode, view.offset, view.limit);
|
||||
return page.ok
|
||||
? ok({ kind: "native", view, ...page.value, ...common })
|
||||
: page;
|
||||
}
|
||||
const rows = nativeRows(dossier, view.facet);
|
||||
if (rows === undefined)
|
||||
return ok(
|
||||
singleton({
|
||||
available: false,
|
||||
reason: flow?.available === false ? flow.reason : "not recorded",
|
||||
}),
|
||||
);
|
||||
const items = rows.slice(view.offset, view.offset + view.limit);
|
||||
return ok({
|
||||
kind: "native",
|
||||
view,
|
||||
item: jsonValueSchema.parse(items),
|
||||
coverage: pageViewCoverage(view.offset, items.length, rows.length),
|
||||
...common,
|
||||
});
|
||||
};
|
||||
Reference in New Issue
Block a user