@depup/nx 23.2.1-depup.7 → 23.3.0-depup.0

package/dist/src/command-line/migrate/run/issues.d.ts

@@ -0,0 +1,127 @@
+import { issueFingerprint, type MigrateCommitLedgerEntry, type MigrateIssueDisposition, type MigrateRunIssue, type MigrateRunState, type MigrateStep } from './run-state';
+export { issueFingerprint };
+export interface ReportedIssue {
+    summary: string;
+    detail?: string;
+    applicableMigrations: string[] | 'unknown';
+    disposition?: MigrateIssueDisposition;
+}
+export interface ReportedIssueUpdate {
+    id: string;
+    disposition: Exclude<MigrateIssueDisposition, 'recorded'>;
+    note?: string;
+}
+export type ParsedHandoffIssues = {
+    ok: true;
+    issues: ReportedIssue[];
+    updates: ReportedIssueUpdate[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a handoff's `issues` / `issueUpdates` against the run's current
+ * state. Absent fields parse as empty; any invalid entry rejects the whole
+ * report with a reason the awaiting dispense hands back to the agent. Also
+ * rejects unrecognized top-level handoff fields: a misspelled "issueUpates"
+ * would otherwise read as an absent report and be discarded with the handoff.
+ */
+export declare function parseHandoffIssues(extras: Record<string, unknown> | undefined, state: MigrateRunState, reportingStep: MigrateStep): ParsedHandoffIssues;
+export interface IssueArchiveUpdate {
+    issueId: string;
+    stepId: string;
+    disposition: MigrateIssueDisposition;
+    note?: string;
+    detail?: string;
+    applicableMigrations?: string[];
+}
+export interface IssueApplication {
+    state: MigrateRunState;
+    newIssues: {
+        entry: MigrateRunIssue;
+        report: ReportedIssue;
+    }[];
+    updates: IssueArchiveUpdate[];
+}
+/**
+ * Mints the run issue carrying a given-up step's last failure to the completion
+ * report: unscoped and deferred, so no later step claims it, with the migration
+ * id in the summary so identical failures stay apart. A report with the same
+ * text is taken over, not merged: the fingerprint is derived from the summary,
+ * so the ledger cannot hold both, and a merge would keep the report's scope.
+ * Same locking contract as {@link applyReportedIssues}.
+ */
+export declare function mintUnresolvedIssue(state: MigrateRunState, step: MigrateStep): {
+    application: IssueApplication;
+    issueId: string;
+};
+/**
+ * Pure. Must run on state read fresh inside the fold's locked write, or ids
+ * collide and the claim checks test state that is no longer on disk.
+ */
+export declare function applyReportedIssues(state: MigrateRunState, reportingStep: MigrateStep, issues: ReportedIssue[], updates: ReportedIssueUpdate[], resolvedAtCommitCount?: number): IssueApplication;
+/**
+ * The issue ids a landed commit naming `stepIds` carries. Attribution rides on
+ * the persisted `resolvedByStepId`, so a resolution whose own commit attempt
+ * failed still reaches the later commit that absorbs that step's tree.
+ */
+export declare function issueIdsForCommit(state: MigrateRunState, stepIds: string[]): string[];
+/**
+ * Attaches the issue ids a landed entry carries; non-landed entries pass
+ * through. Every commit append (worker, fold, adopt) routes through this so
+ * attribution cannot diverge between terminal paths.
+ */
+export declare function attachIssueIdsToCommitEntry(state: MigrateRunState, entry: MigrateCommitLedgerEntry): MigrateCommitLedgerEntry;
+/**
+ * Adds to a landed entry the resolutions it can now carry, keeping the ids it
+ * has; other entries pass through. Repeating it is a no-op, since
+ * `issueIdsForCommit` skips resolutions an entry already carries.
+ */
+export declare function enrichCommitEntryIssueIds(state: MigrateRunState, index: number): MigrateRunState;
+/**
+ * Reverts resolutions not carried by a landed commit and releases claims
+ * during a reset-backed retry. Returned disposition changes form the archive
+ * trail; claim releases do not.
+ */
+export declare function reopenResolutionsForStep(state: MigrateRunState, stepId: string): {
+    state: MigrateRunState;
+    updates: IssueArchiveUpdate[];
+};
+/**
+ * Claims the still-recorded issues applicable to the step being dispensed, up
+ * to what the digest can publish. Must run inside the dispense's locked write:
+ * serial dispensing is what makes reassignment to the next applicable step
+ * deterministic when an earlier one left the issue unresolved.
+ */
+export declare function claimIssuesForStep(state: MigrateRunState, stepId: string, runId: string): MigrateRunState;
+/**
+ * Before rendering, release terminal claims and defer issues no remaining
+ * step can claim; report-time routing can become stale as steps finish. Do
+ * not archive Nx-driven progression.
+ */
+export declare function settleUnclaimableIssues(state: MigrateRunState): MigrateRunState;
+/**
+ * The bounded "Known issues" digest a work dispense carries. Assigned entries
+ * lead and share claimIssuesForStep's prefix bound, so every kept claim appears.
+ */
+export declare function renderIssueDigestLines(state: MigrateRunState, currentStepId: string, runId: string): string[];
+export declare function renderUnresolvedIssueLines(state: MigrateRunState, runId: string): string[];
+export declare function unresolvedIssues(state: MigrateRunState): MigrateRunIssue[];
+export declare function hasUnresolvedIssues(state: MigrateRunState): boolean;
+export declare function issueArchivePath(runDirPath: string, issueId: string): string;
+export declare function warnReconstructedArchives(issueIds: string[]): void;
+/**
+ * Archives an application's new issues (with the detail the ledger does not
+ * carry) and appends its updates to the archived files. Failures propagate;
+ * the caller then keeps the handoff file as the fallback detail store.
+ * `reconstructedIds` is filled as it goes rather than returned alone: a retry
+ * finds a rebuilt shell healthy, so a throw-interrupted pass is the only
+ * chance to warn that an archive was lost.
+ */
+export declare function archiveIssues(runDirPath: string, application: IssueApplication, reconstructedIds?: string[]): string[];
+/**
+ * Verifies the archive state expected after phase 1. New-issue fields must
+ * match the report and have no updates; existing-issue updates must end with
+ * this application's whole batch.
+ */
+export declare function applicationArchivesIntact(runDirPath: string, application: IssueApplication): boolean;