@ue-shed/map-history 0.1.0

package/dist/playback.js

@@ -0,0 +1,168 @@
+import { actorIdentityKey, actorIdentityOf, savedWorldPositionsEqual } from "./diff.js";
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function playbackActor(actor, identity = actorIdentityOf(actor)) {
+    return { actor, identity, key: actorIdentityKey(identity) };
+}
+function ambiguousIdentityDiagnostic(key) {
+    return {
+        code: "ambiguous_actor_identity",
+        message: `Playback withheld ambiguous actor identity ${key}.`,
+        retrySafe: false
+    };
+}
+function stateFromActors(actors) {
+    const indexed = new Map();
+    const ambiguous = new Set();
+    for (const actor of actors) {
+        const entry = playbackActor(actor);
+        if (ambiguous.has(entry.key))
+            continue;
+        if (indexed.has(entry.key)) {
+            indexed.delete(entry.key);
+            ambiguous.add(entry.key);
+            continue;
+        }
+        indexed.set(entry.key, entry);
+    }
+    return {
+        actors: indexed,
+        diagnostics: [...ambiguous].sort(compareText).map(ambiguousIdentityDiagnostic)
+    };
+}
+function writeAfterChange(actors, change) {
+    switch (change.kind) {
+        case "actor_added":
+            actors.set(actorIdentityKey(change.identity), playbackActor(change.after, change.identity));
+            return;
+        case "actor_removed":
+            actors.delete(actorIdentityKey(change.identity));
+            return;
+        case "snapshot_coverage_changed":
+            return;
+        default:
+            actors.set(actorIdentityKey(change.identity), playbackActor(change.after, change.identity));
+    }
+}
+function writeBeforeChange(actors, change) {
+    switch (change.kind) {
+        case "actor_added":
+            actors.delete(actorIdentityKey(change.identity));
+            return;
+        case "actor_removed":
+            actors.set(actorIdentityKey(change.identity), playbackActor(change.before, change.identity));
+            return;
+        case "snapshot_coverage_changed":
+            return;
+        default:
+            actors.set(actorIdentityKey(change.identity), playbackActor(change.before, change.identity));
+    }
+}
+function orderedActors(state) {
+    return [...state.actors.values()].sort((left, right) => compareText(left.key, right.key));
+}
+function savedWorldActorsEqual(left, right) {
+    return (left.actorGuid === right.actorGuid &&
+        left.actorPath === right.actorPath &&
+        left.classPath === right.classPath &&
+        left.label === right.label &&
+        left.packageName === right.packageName &&
+        savedWorldPositionsEqual(left.position, right.position));
+}
+function initialSnapshot(history) {
+    if (history.rangeStartSnapshot !== undefined)
+        return history.rangeStartSnapshot;
+    if (history.baseline.status === "map_not_yet_created")
+        return undefined;
+    throw new Error("Map History has a baseline but no rangeStartSnapshot. Re-run the scan with a playback-capable Map History producer.");
+}
+/** Creates the actor state immediately before the requested history range. */
+export function createMapHistoryPlaybackState(input) {
+    return stateFromActors(initialSnapshot(input.history)?.actors ?? []);
+}
+/** Applies one submitted map revision to a playback state without mutating the prior state. */
+export function applyMapHistoryRevision(input) {
+    const actors = new Map(input.state.actors);
+    for (const change of input.revision.changes)
+        writeAfterChange(actors, change);
+    return { actors, diagnostics: input.state.diagnostics };
+}
+/** Reverts one submitted map revision without mutating the later playback state. */
+export function revertMapHistoryRevision(input) {
+    const actors = new Map(input.state.actors);
+    for (const change of [...input.revision.changes].reverse())
+        writeBeforeChange(actors, change);
+    return { actors, diagnostics: input.state.diagnostics };
+}
+/**
+ * Reconstructs the range-start frame or the saved state immediately after one in-range submitted
+ * changelist. This performs no Perforce or filesystem work and retains only the requested state.
+ */
+export function mapHistoryPlaybackFrameAt(input) {
+    const startSnapshot = initialSnapshot(input.history);
+    let state = createMapHistoryPlaybackState({ history: input.history });
+    if (input.revisionIndex === undefined) {
+        return {
+            actors: orderedActors(state),
+            completeness: startSnapshot?.completeness ?? "complete",
+            diagnostics: [...(startSnapshot?.diagnostics ?? []), ...state.diagnostics],
+            kind: "range_start",
+            state,
+            unclassifiedPackageChanges: []
+        };
+    }
+    if (!Number.isInteger(input.revisionIndex) ||
+        input.revisionIndex < 0 ||
+        input.revisionIndex >= input.history.revisions.length) {
+        throw new RangeError(`Map History revision index ${input.revisionIndex} is outside this result.`);
+    }
+    for (let index = 0; index <= input.revisionIndex; index += 1) {
+        const revision = input.history.revisions[index];
+        if (revision === undefined)
+            throw new Error(`Missing Map History revision ${index}.`);
+        state = applyMapHistoryRevision({ revision, state });
+    }
+    const revision = input.history.revisions[input.revisionIndex];
+    if (revision === undefined)
+        throw new Error(`Missing Map History revision ${input.revisionIndex}.`);
+    return {
+        actors: orderedActors(state),
+        completeness: revision.completeness,
+        diagnostics: [...revision.diagnostics, ...state.diagnostics],
+        kind: "revision",
+        revision,
+        revisionIndex: input.revisionIndex,
+        state,
+        unclassifiedPackageChanges: revision.unclassifiedPackageChanges
+    };
+}
+/**
+ * Returns `undefined` when a complete comparison is impossible; otherwise verifies that replayed
+ * actor facts exactly equal the retained end-of-range saved-world projection.
+ */
+export function mapHistoryPlaybackMatchesRangeEnd(input) {
+    const snapshot = input.history.rangeEndSnapshot;
+    if (snapshot === undefined || snapshot.completeness !== "complete")
+        return undefined;
+    const frame = mapHistoryPlaybackFrameAt({
+        history: input.history,
+        revisionIndex: input.history.revisions.length === 0 ? undefined : input.history.revisions.length - 1
+    });
+    if (frame.completeness !== "complete")
+        return undefined;
+    const expected = stateFromActors(snapshot.actors);
+    if (expected.diagnostics.length > 0 || frame.state.diagnostics.length > 0)
+        return false;
+    if (frame.state.actors.size !== expected.actors.size)
+        return false;
+    for (const [key, expectedActor] of expected.actors) {
+        const actualActor = frame.state.actors.get(key);
+        if (actualActor === undefined ||
+            !savedWorldActorsEqual(actualActor.actor, expectedActor.actor)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=playback.js.map

package/dist/playback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playback.js","sourceRoot":"","sources":["../src/playback.ts"],"names":[],"mappings":"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"}

package/dist/revision-materialization.d.ts

@@ -0,0 +1,14 @@
+import { Effect } from "effect";
+import type { HistoricalProjectTree } from "./historical-project-tree.js";
+import { MapHistoryError } from "./errors.js";
+import { PerforceHistorySource } from "./perforce.js";
+import type { ScopedRevisionPlan } from "./revision-plan.js";
+/** Materializes exact Perforce revisions and applies their scoped mutations atomically to one tree. */
+export declare function materializePlannedRevision(options: {
+    readonly change: number;
+    readonly concurrency: number;
+    readonly maxFiles: number;
+    readonly plan: ScopedRevisionPlan;
+    readonly tree: HistoricalProjectTree;
+}): Effect.Effect<number, MapHistoryError, PerforceHistorySource>;
+//# sourceMappingURL=revision-materialization.d.ts.map

package/dist/revision-materialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision-materialization.d.ts","sourceRoot":"","sources":["../src/revision-materialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,KAAK,EAA0B,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAA0B,MAAM,eAAe,CAAC;AAC9E,OAAO,KAAK,EAAuB,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AA4BlF,uGAAuG;AACvG,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;CACrC,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,qBAAqB,CAAC,CAuDhE"}

package/dist/revision-materialization.js

@@ -0,0 +1,68 @@
+import { Effect } from "effect";
+import { MapHistoryError } from "./errors.js";
+import { PerforceHistorySource } from "./perforce.js";
+function materializationError(message, recovery) {
+    return new MapHistoryError({
+        kind: "materialization",
+        message,
+        recovery,
+        retrySafe: false
+    });
+}
+function materializedKey(file) {
+    return `${file.depotPath}\u0000${file.revision}`;
+}
+function perforceFile(change, file) {
+    return {
+        action: file.action,
+        changelist: change,
+        depotPath: file.depotPath,
+        revision: file.revision,
+        type: file.type
+    };
+}
+/** Materializes exact Perforce revisions and applies their scoped mutations atomically to one tree. */
+export function materializePlannedRevision(options) {
+    return Effect.fn("MapHistory.materializePlannedRevision")(function* () {
+        if (options.plan.kind === "invalid")
+            return yield* Effect.fail(options.plan.error);
+        const materializedFiles = options.plan.files.filter((file) => file.action !== "delete");
+        if (materializedFiles.length > options.maxFiles) {
+            return yield* Effect.fail(new MapHistoryError({
+                kind: "resource_limit",
+                message: `Changelist ${options.change} needs ${materializedFiles.length} materialized files, exceeding the limit of ${options.maxFiles}.`,
+                recovery: "Narrow the selected map scope or raise maxMaterializedFiles explicitly.",
+                retrySafe: false
+            }));
+        }
+        const source = yield* PerforceHistorySource;
+        const materialized = materializedFiles.length === 0
+            ? []
+            : (yield* source.materializeDepotFiles({
+                concurrency: options.concurrency,
+                directory: options.tree.materializationRoot,
+                files: materializedFiles.map((file) => perforceFile(options.change, file)),
+                maxFiles: options.maxFiles
+            })).files;
+        const localPaths = new Map(materialized.map((file) => [materializedKey(file.file), file.localPath]));
+        const mutations = [];
+        for (const file of options.plan.files) {
+            if (file.action === "delete") {
+                mutations.push({ action: "delete", projectRelativePath: file.projectRelativePath });
+                continue;
+            }
+            const localPath = localPaths.get(materializedKey(file));
+            if (localPath === undefined) {
+                return yield* Effect.fail(materializationError(`Perforce did not materialize ${file.depotPath}#${file.revision}.`, "Check the exact depot revision and retry the historical reconstruction."));
+            }
+            mutations.push({
+                action: file.action,
+                materializedPath: localPath,
+                projectRelativePath: file.projectRelativePath
+            });
+        }
+        yield* options.tree.applyRevision(mutations);
+        return materializedFiles.length;
+    })();
+}
+//# sourceMappingURL=revision-materialization.js.map

package/dist/revision-materialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision-materialization.js","sourceRoot":"","sources":["../src/revision-materialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAA0B,MAAM,eAAe,CAAC;AAG9E,SAAS,oBAAoB,CAAC,OAAe,EAAE,QAAgB;IAC9D,OAAO,IAAI,eAAe,CAAC;QAC1B,IAAI,EAAE,iBAAiB;QACvB,OAAO;QACP,QAAQ;QACR,SAAS,EAAE,KAAK;KAChB,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,IAA+D;IACvF,OAAO,GAAG,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED,SAAS,YAAY,CACpB,MAAc,EACd,IAAiE;IAEjE,OAAO;QACN,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,MAAM;QAClB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;KACf,CAAC;AACH,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,0BAA0B,CAAC,OAM1C;IACA,OAAO,MAAM,CAAC,EAAE,CAAC,uCAAuC,CAAC,CAAC,QAAQ,CAAC;QAClE,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnF,MAAM,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAClD,CAAC,IAAI,EAAuE,EAAE,CAC7E,IAAI,CAAC,MAAM,KAAK,QAAQ,CACzB,CAAC;QACF,IAAI,iBAAiB,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YACjD,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CACxB,IAAI,eAAe,CAAC;gBACnB,IAAI,EAAE,gBAAgB;gBACtB,OAAO,EAAE,cAAc,OAAO,CAAC,MAAM,UAAU,iBAAiB,CAAC,MAAM,+CAA+C,OAAO,CAAC,QAAQ,GAAG;gBACzI,QAAQ,EACP,yEAAyE;gBAC1E,SAAS,EAAE,KAAK;aAChB,CAAC,CACF,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,qBAAqB,CAAC;QAC5C,MAAM,YAAY,GACjB,iBAAiB,CAAC,MAAM,KAAK,CAAC;YAC7B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,qBAAqB,CAAC;gBACrC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB;gBAC3C,KAAK,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAC1E,QAAQ,EAAE,OAAO,CAAC,QAAQ;aAC1B,CAAC,CAAC,CAAC,KAAK,CAAC;QACb,MAAM,UAAU,GAAG,IAAI,GAAG,CACzB,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CACxE,CAAC;QACF,MAAM,SAAS,GAA6B,EAAE,CAAC;QAC/C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACvC,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC9B,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,EAAE,CAAC,CAAC;gBACpF,SAAS;YACV,CAAC;YACD,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;YACxD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CACxB,oBAAoB,CACnB,gCAAgC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,QAAQ,GAAG,EAClE,yEAAyE,CACzE,CACD,CAAC;YACH,CAAC;YACD,SAAS,CAAC,IAAI,CAAC;gBACd,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,gBAAgB,EAAE,SAAS;gBAC3B,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;aAC7C,CAAC,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC7C,OAAO,iBAAiB,CAAC,MAAM,CAAC;IACjC,CAAC,CAAC,EAAE,CAAC;AACN,CAAC"}

package/dist/revision-plan.d.ts

@@ -0,0 +1,44 @@
+import type { PerforceChangedFile } from "./perforce.js";
+import { MapHistoryError } from "./errors.js";
+export interface ScopedPerforceFile {
+    readonly depotPath: string;
+    readonly packageName: string;
+    readonly projectRelativePath: string;
+}
+export interface PlannedPackageChange {
+    readonly action: string;
+    readonly afterRevision: number | null;
+    readonly beforeRevision: number | null;
+    readonly depotPath: string;
+    readonly packageName: string;
+}
+export type PlannedRevisionFile = {
+    readonly action: "delete";
+    readonly depotPath: string;
+    readonly packageName: string;
+    readonly projectRelativePath: string;
+} | {
+    readonly action: "add" | "edit";
+    readonly depotPath: string;
+    readonly packageName: string;
+    readonly projectRelativePath: string;
+    readonly revision: number;
+    readonly type: string;
+};
+export type ScopedRevisionPlan = {
+    readonly kind: "ready";
+    readonly packageChanges: readonly PlannedPackageChange[];
+    readonly files: readonly PlannedRevisionFile[];
+} | {
+    readonly kind: "invalid";
+    readonly error: MapHistoryError;
+};
+/**
+ * Reduces a described changelist to exact, already-resolved map files. Files outside the selected
+ * map scope cannot enter the historical project tree.
+ */
+export declare function planScopedRevision(options: {
+    readonly files: readonly PerforceChangedFile[];
+    readonly scope: readonly ScopedPerforceFile[];
+}): ScopedRevisionPlan;
+//# sourceMappingURL=revision-plan.d.ts.map

package/dist/revision-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision-plan.d.ts","sourceRoot":"","sources":["../src/revision-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,mBAAmB,GAC5B;IACA,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACpC,GACD;IACA,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACrB,CAAC;AAEL,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC9C,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;CAAE,CAAC;AA+BjE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC9C,GAAG,kBAAkB,CA+DrB"}

package/dist/revision-plan.js

@@ -0,0 +1,84 @@
+import { MapHistoryError } from "./errors.js";
+function planError(message, recovery) {
+    return {
+        kind: "invalid",
+        error: new MapHistoryError({
+            kind: "materialization",
+            message,
+            recovery,
+            retrySafe: false
+        })
+    };
+}
+function isDeletion(action) {
+    return action === "delete" || action === "move/delete" || action === "purge";
+}
+function isAddition(action) {
+    return action === "add" || action === "branch" || action === "move/add";
+}
+function beforeRevision(action, revision) {
+    if (isAddition(action) || revision === null || revision <= 1)
+        return null;
+    return revision - 1;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+ * Reduces a described changelist to exact, already-resolved map files. Files outside the selected
+ * map scope cannot enter the historical project tree.
+ */
+export function planScopedRevision(options) {
+    const scopeByDepotPath = new Map(options.scope.map((file) => [file.depotPath, file]));
+    const targets = new Set();
+    const files = [];
+    const packageChanges = [];
+    for (const described of options.files) {
+        const scoped = scopeByDepotPath.get(described.depotPath);
+        if (scoped === undefined)
+            continue;
+        const target = scoped.projectRelativePath.toLocaleLowerCase("en-US");
+        if (targets.has(target)) {
+            return planError(`Changelist contains multiple updates for ${scoped.projectRelativePath}.`, "Resolve the changelist file records before reconstructing history.");
+        }
+        targets.add(target);
+        const deletion = isDeletion(described.action);
+        const revision = described.revision;
+        const type = described.type;
+        if (!deletion && (revision === null || type === null)) {
+            return planError(`Changelist file ${described.depotPath} has no exact revision metadata.`, "Perforce must report a numeric revision and file type before history can materialize it.");
+        }
+        const priorRevision = beforeRevision(described.action, described.revision);
+        packageChanges.push({
+            action: described.action,
+            afterRevision: deletion ? null : revision,
+            beforeRevision: priorRevision,
+            depotPath: described.depotPath,
+            packageName: scoped.packageName
+        });
+        if (deletion) {
+            files.push({
+                action: "delete",
+                depotPath: described.depotPath,
+                packageName: scoped.packageName,
+                projectRelativePath: scoped.projectRelativePath
+            });
+            continue;
+        }
+        if (revision === null || type === null) {
+            return planError(`Changelist file ${described.depotPath} has no exact revision metadata.`, "Perforce must report a numeric revision and file type before history can materialize it.");
+        }
+        files.push({
+            action: isAddition(described.action) ? "add" : "edit",
+            depotPath: described.depotPath,
+            packageName: scoped.packageName,
+            projectRelativePath: scoped.projectRelativePath,
+            revision,
+            type
+        });
+    }
+    files.sort((left, right) => compareText(left.projectRelativePath, right.projectRelativePath));
+    packageChanges.sort((left, right) => compareText(left.depotPath, right.depotPath));
+    return { files, kind: "ready", packageChanges };
+}
+//# sourceMappingURL=revision-plan.js.map

package/dist/revision-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision-plan.js","sourceRoot":"","sources":["../src/revision-plan.ts"],"names":[],"mappings":"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"}