480 lines
16 KiB
TypeScript
480 lines
16 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
|
|
import canonicalize from "canonicalize";
|
|
|
|
import type { JavaScriptApplicationGraph } from "./javascriptApplicationGraph.js";
|
|
import type { HistoricalSourceGraph } from "./referenceSourceGraph.js";
|
|
import {
|
|
SOURCE_TO_BUNDLE_SIGNAL_WEIGHTS,
|
|
sourceToBundleComparisonResultSchema,
|
|
type CompareSourceToBundleInput,
|
|
type SourceToBundleCandidate,
|
|
type SourceToBundleComparisonItem,
|
|
type SourceToBundleComparisonResult,
|
|
} from "./sourceToBundleComparisonSchemas.js";
|
|
import {
|
|
buildSourceToBundleCandidateIndex,
|
|
candidateIdsForSource,
|
|
historicalSourceFiles,
|
|
scoreSourceToBundleCandidate,
|
|
sourceBearingNodes,
|
|
type SourceToBundleCandidateIndex,
|
|
} from "./sourceToBundleSignals.js";
|
|
|
|
interface SourceToBundleComparisonInput {
|
|
readonly reference: HistoricalSourceGraph;
|
|
readonly application: {
|
|
readonly evidenceId: string;
|
|
readonly rootArtifactSha256: string;
|
|
readonly graph: JavaScriptApplicationGraph;
|
|
};
|
|
readonly limits: CompareSourceToBundleInput["limits"];
|
|
}
|
|
|
|
interface ClassifiedMapping {
|
|
readonly status: SourceToBundleComparisonItem["status"];
|
|
readonly confidence: SourceToBundleComparisonItem["confidence"];
|
|
readonly currentNodeIds: string[];
|
|
readonly limitations: string[];
|
|
}
|
|
|
|
interface ComparisonProjection {
|
|
readonly sources: ReturnType<typeof historicalSourceFiles>;
|
|
readonly currentNodes: ReturnType<typeof sourceBearingNodes>;
|
|
readonly index: SourceToBundleCandidateIndex;
|
|
readonly absenceComplete: boolean;
|
|
readonly factors: CoverageFactors;
|
|
}
|
|
|
|
interface MappingProjection {
|
|
readonly items: SourceToBundleComparisonItem[];
|
|
readonly candidateEvaluations: number;
|
|
readonly omittedCandidateEvaluations: number;
|
|
readonly omittedCandidateReferences: number;
|
|
}
|
|
|
|
/** Compare historical source files to static source-bearing application nodes. */
|
|
export const compareSourceToBundle = (
|
|
input: SourceToBundleComparisonInput,
|
|
): SourceToBundleComparisonResult => {
|
|
const projection = projectComparison(input);
|
|
const mappings = compareMappings(input, projection);
|
|
const factors = {
|
|
...projection.factors,
|
|
omittedCandidateEvaluations: mappings.omittedCandidateEvaluations,
|
|
omittedCandidateReferences: mappings.omittedCandidateReferences,
|
|
};
|
|
const mappedCurrentIds = new Set(
|
|
mappings.items.flatMap(({ current_node_ids: nodeIds }) => nodeIds),
|
|
);
|
|
const unmappedCurrentNodeIds = projection.currentNodes
|
|
.map(({ node_id: nodeId }) => nodeId)
|
|
.filter((nodeId) => !mappedCurrentIds.has(nodeId));
|
|
const semanticResult = {
|
|
reference: {
|
|
root_sha256: input.reference.root_sha256,
|
|
inventory_state: input.reference.inventory_state,
|
|
},
|
|
application: {
|
|
evidence_id: input.application.evidenceId,
|
|
graph_id: input.application.graph.graph_id,
|
|
root_artifact_sha256: input.application.rootArtifactSha256,
|
|
},
|
|
scoring: scoringModel(),
|
|
summary: comparisonSummary(mappings.items),
|
|
items: mappings.items,
|
|
unmapped_current_node_ids: unmappedCurrentNodeIds,
|
|
coverage: comparisonCoverage(projection, mappings, factors),
|
|
evidence_links: [input.application.evidenceId],
|
|
limitations: comparisonLimitations(factors),
|
|
};
|
|
return sourceToBundleComparisonResultSchema.parse({
|
|
...semanticResult,
|
|
comparison_id: `stbc_${digestCanonical(semanticResult)}`,
|
|
});
|
|
};
|
|
|
|
const projectComparison = (
|
|
input: SourceToBundleComparisonInput,
|
|
): ComparisonProjection => {
|
|
const allSources = historicalSourceFiles(input.reference);
|
|
const allCurrentNodes = sourceBearingNodes(input.application.graph.nodes);
|
|
const sources = allSources.slice(0, input.limits.max_source_files);
|
|
const currentNodes = allCurrentNodes.slice(
|
|
0,
|
|
input.limits.max_application_nodes,
|
|
);
|
|
const omittedSourceFiles = allSources.length - sources.length;
|
|
const omittedApplicationNodes = allCurrentNodes.length - currentNodes.length;
|
|
const index = buildSourceToBundleCandidateIndex(currentNodes);
|
|
return {
|
|
sources,
|
|
currentNodes,
|
|
index,
|
|
absenceComplete:
|
|
input.reference.inventory_state === "complete" &&
|
|
input.application.graph.coverage.status === "complete" &&
|
|
!input.application.graph.coverage.truncated &&
|
|
omittedSourceFiles === 0 &&
|
|
omittedApplicationNodes === 0 &&
|
|
!index.pathIndexTruncated,
|
|
factors: {
|
|
input,
|
|
omittedSourceFiles,
|
|
omittedApplicationNodes,
|
|
omittedCandidateEvaluations: 0,
|
|
omittedCandidateReferences: 0,
|
|
pathIndexTruncated: index.pathIndexTruncated,
|
|
},
|
|
};
|
|
};
|
|
|
|
const compareMappings = (
|
|
input: SourceToBundleComparisonInput,
|
|
projection: ComparisonProjection,
|
|
): MappingProjection => {
|
|
let evaluationsRemaining = input.limits.max_candidate_evaluations;
|
|
let candidateEvaluations = 0;
|
|
let omittedCandidateEvaluations = 0;
|
|
let omittedCandidateReferences = 0;
|
|
const provisionalItems: SourceToBundleComparisonItem[] = [];
|
|
for (const source of projection.sources) {
|
|
const candidateIds = candidateIdsForSource(source, projection.index);
|
|
const retainedIds = candidateIds.slice(0, evaluationsRemaining);
|
|
const omittedEvaluations = candidateIds.length - retainedIds.length;
|
|
evaluationsRemaining -= retainedIds.length;
|
|
candidateEvaluations += retainedIds.length;
|
|
omittedCandidateEvaluations += omittedEvaluations;
|
|
const scored = retainedIds
|
|
.map((nodeId) =>
|
|
scoreSourceToBundleCandidate(source, nodeId, projection.index),
|
|
)
|
|
.filter(
|
|
(candidate): candidate is SourceToBundleCandidate => candidate !== null,
|
|
)
|
|
.sort(compareCandidates);
|
|
const retainedCandidates = scored.slice(
|
|
0,
|
|
input.limits.max_candidate_nodes,
|
|
);
|
|
const omittedCandidates =
|
|
omittedEvaluations + scored.length - retainedCandidates.length;
|
|
omittedCandidateReferences += omittedCandidates;
|
|
const classification = classifyMapping(
|
|
retainedCandidates,
|
|
omittedCandidates === 0,
|
|
projection.absenceComplete,
|
|
);
|
|
const semantic = {
|
|
source_path: source.path,
|
|
source_sha256: source.sha256,
|
|
source_language: source.language,
|
|
status: classification.status,
|
|
confidence: classification.confidence,
|
|
current_node_ids: classification.currentNodeIds,
|
|
candidates: retainedCandidates,
|
|
omitted_candidates: omittedCandidates,
|
|
limitations: uniqueSorted([
|
|
...source.limitations,
|
|
...classification.limitations,
|
|
...(omittedCandidates > 0
|
|
? [
|
|
`${String(omittedCandidates)} candidate references were omitted by comparison limits.`,
|
|
]
|
|
: []),
|
|
]),
|
|
};
|
|
provisionalItems.push({
|
|
mapping_id: mappingId(input, semantic),
|
|
...semantic,
|
|
});
|
|
}
|
|
return {
|
|
items: markMergedMappings(input, provisionalItems),
|
|
candidateEvaluations,
|
|
omittedCandidateEvaluations,
|
|
omittedCandidateReferences,
|
|
};
|
|
};
|
|
|
|
const comparisonCoverage = (
|
|
projection: ComparisonProjection,
|
|
mappings: MappingProjection,
|
|
factors: CoverageFactors,
|
|
): SourceToBundleComparisonResult["coverage"] => ({
|
|
status: coverageStatus(factors),
|
|
reference_inventory_state: factors.input.reference.inventory_state,
|
|
application_graph_status: factors.input.application.graph.coverage.status,
|
|
retained_source_files: projection.sources.length,
|
|
omitted_source_files: factors.omittedSourceFiles,
|
|
retained_application_nodes: projection.currentNodes.length,
|
|
omitted_application_nodes: factors.omittedApplicationNodes,
|
|
candidate_evaluations: mappings.candidateEvaluations,
|
|
omitted_candidate_evaluations: mappings.omittedCandidateEvaluations,
|
|
omitted_candidate_references: mappings.omittedCandidateReferences,
|
|
omitted_unmapped_current_nodes: 0,
|
|
});
|
|
|
|
const scoringModel = (): SourceToBundleComparisonResult["scoring"] => ({
|
|
algorithm: "rea-source-to-bundle-signals/v1",
|
|
minimum_candidate_score: 20,
|
|
weights: SOURCE_TO_BUNDLE_SIGNAL_WEIGHTS.map(([signal, weight]) => ({
|
|
signal,
|
|
weight,
|
|
})),
|
|
});
|
|
|
|
const classifyMapping = (
|
|
candidates: readonly SourceToBundleCandidate[],
|
|
evaluationComplete: boolean,
|
|
absenceComplete: boolean,
|
|
): ClassifiedMapping => {
|
|
if (!evaluationComplete)
|
|
return {
|
|
status: "unknown",
|
|
confidence: "unknown",
|
|
currentNodeIds: [],
|
|
limitations: [
|
|
"Candidate evaluation stopped at the declared limit; a stronger match may be omitted.",
|
|
],
|
|
};
|
|
const exact = candidates.filter((candidate) =>
|
|
hasSignal(candidate, "exact-source-digest"),
|
|
);
|
|
if (exact.length === 1)
|
|
return {
|
|
status: "unchanged",
|
|
confidence: "exact",
|
|
currentNodeIds: [exact[0]?.current_node_id ?? ""].filter(Boolean),
|
|
limitations: [
|
|
"Exact byte identity does not establish equivalent load context or runtime behavior.",
|
|
],
|
|
};
|
|
if (exact.length > 1)
|
|
return {
|
|
status: "duplicated",
|
|
confidence: "exact",
|
|
currentNodeIds: exact.map(({ current_node_id: nodeId }) => nodeId),
|
|
limitations: [
|
|
"The same historical source digest occurs in multiple current graph nodes.",
|
|
],
|
|
};
|
|
const pathCandidates = candidates.filter((candidate) =>
|
|
candidate.signals.some(({ kind }) =>
|
|
[
|
|
"source-map-original-path",
|
|
"current-path-exact",
|
|
"current-path-suffix",
|
|
].includes(kind),
|
|
),
|
|
);
|
|
const topScore = pathCandidates[0]?.score;
|
|
const topPathCandidates =
|
|
topScore === undefined
|
|
? []
|
|
: pathCandidates.filter(({ score }) => score === topScore);
|
|
if (topPathCandidates.length === 1) {
|
|
const candidate = topPathCandidates[0];
|
|
return {
|
|
status: "unknown",
|
|
confidence: "unknown",
|
|
currentNodeIds:
|
|
candidate === undefined ? [] : [candidate.current_node_id],
|
|
limitations: [
|
|
"Location evidence links the source to the current node, but comparable source digests are unavailable.",
|
|
],
|
|
};
|
|
}
|
|
if (topPathCandidates.length > 1)
|
|
return {
|
|
status: "split",
|
|
confidence: "medium",
|
|
currentNodeIds: topPathCandidates.map(
|
|
({ current_node_id: nodeId }) => nodeId,
|
|
),
|
|
limitations: [
|
|
"Multiple equally scored current nodes retain the historical source path; this is a static split inference, not runtime proof.",
|
|
],
|
|
};
|
|
if (candidates.length > 0)
|
|
return {
|
|
status: "unknown",
|
|
confidence: "unknown",
|
|
currentNodeIds: [],
|
|
limitations: [
|
|
"Only weak basename or extension signals were available; no mapping was forced.",
|
|
],
|
|
};
|
|
return absenceComplete
|
|
? {
|
|
status: "removed",
|
|
confidence: "high",
|
|
currentNodeIds: [],
|
|
limitations: [
|
|
"No retained current node matched exact digest or path signals within complete static inventories.",
|
|
],
|
|
}
|
|
: {
|
|
status: "unknown",
|
|
confidence: "unknown",
|
|
currentNodeIds: [],
|
|
limitations: [
|
|
"No candidate was observed, but incomplete input or graph coverage prevents a removal claim.",
|
|
],
|
|
};
|
|
};
|
|
|
|
const markMergedMappings = (
|
|
input: SourceToBundleComparisonInput,
|
|
items: readonly SourceToBundleComparisonItem[],
|
|
): SourceToBundleComparisonItem[] => {
|
|
const sourcesByNode = new Map<string, SourceToBundleComparisonItem[]>();
|
|
for (const item of items) {
|
|
if (item.status !== "unchanged" || item.current_node_ids.length !== 1)
|
|
continue;
|
|
const nodeId = item.current_node_ids[0];
|
|
if (nodeId === undefined) continue;
|
|
sourcesByNode.set(nodeId, [...(sourcesByNode.get(nodeId) ?? []), item]);
|
|
}
|
|
const mergedSources = new Set(
|
|
[...sourcesByNode.values()]
|
|
.filter((group) => group.length > 1)
|
|
.flatMap((group) => group.map(({ source_path: path }) => path)),
|
|
);
|
|
return items.map((item) => {
|
|
if (!mergedSources.has(item.source_path)) return item;
|
|
const { mapping_id: previousMappingId, ...base } = item;
|
|
void previousMappingId;
|
|
const semantic = {
|
|
...base,
|
|
status: "merged" as const,
|
|
confidence: "exact" as const,
|
|
limitations: uniqueSorted([
|
|
...item.limitations,
|
|
"Multiple historical source paths have exact digest identity with the same current graph node.",
|
|
]),
|
|
};
|
|
return { ...semantic, mapping_id: mappingId(input, semantic) };
|
|
});
|
|
};
|
|
|
|
const mappingId = (
|
|
input: SourceToBundleComparisonInput,
|
|
item: Omit<SourceToBundleComparisonItem, "mapping_id">,
|
|
): string =>
|
|
`stbc_item_${digestCanonical({
|
|
reference_root_sha256: input.reference.root_sha256,
|
|
application_graph_id: input.application.graph.graph_id,
|
|
...item,
|
|
})}`;
|
|
|
|
const comparisonSummary = (
|
|
items: readonly SourceToBundleComparisonItem[],
|
|
): SourceToBundleComparisonResult["summary"] => ({
|
|
unchanged: countStatus(items, "unchanged"),
|
|
modified: countStatus(items, "modified"),
|
|
removed: countStatus(items, "removed"),
|
|
split: countStatus(items, "split"),
|
|
merged: countStatus(items, "merged"),
|
|
duplicated: countStatus(items, "duplicated"),
|
|
unknown: countStatus(items, "unknown"),
|
|
});
|
|
|
|
const countStatus = (
|
|
items: readonly SourceToBundleComparisonItem[],
|
|
status: SourceToBundleComparisonItem["status"],
|
|
): number => items.filter((item) => item.status === status).length;
|
|
|
|
interface CoverageFactors {
|
|
readonly input: SourceToBundleComparisonInput;
|
|
readonly omittedSourceFiles: number;
|
|
readonly omittedApplicationNodes: number;
|
|
readonly omittedCandidateEvaluations: number;
|
|
readonly omittedCandidateReferences: number;
|
|
readonly pathIndexTruncated: boolean;
|
|
}
|
|
|
|
const coverageStatus = (
|
|
factors: CoverageFactors,
|
|
): SourceToBundleComparisonResult["coverage"]["status"] => {
|
|
if (
|
|
factors.omittedSourceFiles > 0 ||
|
|
factors.omittedApplicationNodes > 0 ||
|
|
factors.omittedCandidateEvaluations > 0 ||
|
|
factors.omittedCandidateReferences > 0 ||
|
|
factors.pathIndexTruncated
|
|
)
|
|
return "truncated";
|
|
return factors.input.reference.inventory_state === "complete" &&
|
|
factors.input.application.graph.coverage.status === "complete"
|
|
? "complete-within-inputs"
|
|
: "partial";
|
|
};
|
|
|
|
const comparisonLimitations = (factors: CoverageFactors): string[] =>
|
|
uniqueSorted([
|
|
"Static digest and location signals do not establish runtime behavior, semantic equivalence, or absence of dynamically generated modules.",
|
|
...factors.input.reference.limitations,
|
|
...factors.input.application.graph.limitations,
|
|
...(factors.input.reference.inventory_state === "complete"
|
|
? []
|
|
: [
|
|
`Historical source inventory is ${factors.input.reference.inventory_state}; unmatched files remain unknown.`,
|
|
]),
|
|
...(factors.input.application.graph.coverage.status === "complete"
|
|
? []
|
|
: [
|
|
`Application graph coverage is ${factors.input.application.graph.coverage.status}; unmatched files remain unknown.`,
|
|
]),
|
|
...(factors.omittedSourceFiles > 0
|
|
? [
|
|
`${String(factors.omittedSourceFiles)} historical source files were omitted by max_source_files.`,
|
|
]
|
|
: []),
|
|
...(factors.omittedApplicationNodes > 0
|
|
? [
|
|
`${String(factors.omittedApplicationNodes)} source-bearing application nodes were omitted by max_application_nodes.`,
|
|
]
|
|
: []),
|
|
...(factors.omittedCandidateEvaluations > 0
|
|
? [
|
|
`${String(factors.omittedCandidateEvaluations)} candidate evaluations were omitted by max_candidate_evaluations.`,
|
|
]
|
|
: []),
|
|
...(factors.omittedCandidateReferences > 0
|
|
? [
|
|
`${String(factors.omittedCandidateReferences)} candidate references were omitted from item output.`,
|
|
]
|
|
: []),
|
|
...(factors.pathIndexTruncated
|
|
? [
|
|
"At least one current path exceeded the 128-segment suffix index bound.",
|
|
]
|
|
: []),
|
|
]);
|
|
|
|
const hasSignal = (
|
|
candidate: SourceToBundleCandidate,
|
|
kind: SourceToBundleCandidate["signals"][number]["kind"],
|
|
): boolean => candidate.signals.some((signal) => signal.kind === kind);
|
|
|
|
const compareCandidates = (
|
|
left: SourceToBundleCandidate,
|
|
right: SourceToBundleCandidate,
|
|
): number =>
|
|
right.score - left.score ||
|
|
compareText(left.current_node_id, right.current_node_id);
|
|
|
|
const digestCanonical = (value: unknown): string => {
|
|
const encoded = canonicalize(value);
|
|
if (encoded === undefined)
|
|
throw new TypeError("Source-to-bundle comparison could not canonicalize");
|
|
return createHash("sha256").update(encoded).digest("hex");
|
|
};
|
|
|
|
const uniqueSorted = (values: readonly string[]): string[] =>
|
|
[...new Set(values)].sort(compareText);
|
|
|
|
const compareText = (left: string, right: string): number =>
|
|
left < right ? -1 : left > right ? 1 : 0;
|