@unbrained/pm-cli 2026.6.11 → 2026.6.13

package/dist/cli/commands/validate.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="776e2ca9-52d6-5274-9230-4d9b961456e5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="24c5f96e-8535-5063-87d2-bb17fe0d4d1f")}catch(e){}}();
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
@@ -19,6 +19,9 @@ import { nowIso } from "../../core/shared/time.js";
 import { listAllFrontMatterWithBody } from "../../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
+import { partitionFixesByGrant, planCloseReasonBackfillFixes, planResolutionBackfillFixes, planStaleLinkPruneFixes, planTerminalParentFixes, resolveGrantedFixScopes, toFixOutputRow, } from "../../core/validate/fix-planning.js";
+import { buildMissingByTypeCounts } from "../../core/validate/missing-by-type.js";
+import { classifyStaleLinkedPaths, summarizeStaleLinkedPathClassifications, } from "../../core/validate/stale-file-classification.js";
 import { extractReferencedPmItemIdsFromCommand } from "./test.js";
 const FILE_SCAN_DIRECTORIES = ["src", "tests", "docs"];
 const FILE_SCAN_ROOT_FILES = [
@@ -540,17 +543,38 @@ function resolveRequestedChecks(options) {
         requested.add("command_references");
     }
     if (requested.size === 0) {
-        requested.add("metadata");
-        requested.add("resolution");
-        requested.add("lifecycle");
+        // Remediation flags without explicit --check-* flags scope the run to the
+        // checks that can produce fixes: --auto-fix plans metadata/resolution
+        // backfills and gated lifecycle fixes; --prune-missing needs the files
+        // scan. With neither, the historical run-everything default applies.
+        if (options.autoFix) {
+            requested.add("metadata");
+            requested.add("resolution");
+            requested.add("lifecycle");
+        }
+        if (options.pruneMissing) {
+            requested.add("files");
+        }
+        if (requested.size === 0) {
+            requested.add("metadata");
+            requested.add("resolution");
+            requested.add("lifecycle");
+            requested.add("files");
+            requested.add("command_references");
+            requested.add("history_drift");
+        }
+        return requested;
+    }
+    // Explicit check flags are respected as-is, except --prune-missing always
+    // needs the files scan it acts on.
+    if (options.pruneMissing) {
         requested.add("files");
-        requested.add("command_references");
-        requested.add("history_drift");
     }
     return requested;
 }
 function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagnostics) {
     const missingByField = Object.fromEntries(SUPPORTED_METADATA_REQUIRED_FIELDS.map((field) => [field, []]));
+    const itemsById = new Map(items.map((item) => [item.id, item]));
     for (const item of items) {
         for (const field of SUPPORTED_METADATA_REQUIRED_FIELDS) {
             if (!isMetadataFieldMissing(item, field, statusRegistry)) {
@@ -582,6 +606,18 @@ function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagno
             counts[countKey] = value;
         }
     }
+    // Per-item-type grouping of missing required-field counts (pm-pmyq /
+    // GH-172): counts only — never row dumps — and only for the ACTIVE required
+    // fields, so the grouping mirrors `counts` at type granularity (e.g.
+    // `{ Task: { close_reason: 3 } }`). Zero-suppressed at both levels.
+    const missingFieldOccurrences = [];
+    for (const field of metadataPolicy.required_fields) {
+        for (const itemId of missingByField[field] ?? []) {
+            const itemType = itemsById.get(itemId)?.type;
+            missingFieldOccurrences.push({ item_type: typeof itemType === "string" && itemType.length > 0 ? itemType : "Unknown", field });
+        }
+    }
+    const missingByType = buildMissingByTypeCounts(missingFieldOccurrences);
     const details = {
         checked_items: items.length,
         metadata_profile: metadataPolicy.profile,
@@ -590,6 +626,7 @@ function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagno
         required_fields: [...metadataPolicy.required_fields],
         supported_required_fields: [...SUPPORTED_METADATA_REQUIRED_FIELDS],
         counts,
+        missing_by_type: missingByType,
     };
     if (metadataPolicy.configured_custom_fields.length > 0) {
         details.configured_custom_required_fields = [...metadataPolicy.configured_custom_fields];
@@ -616,6 +653,16 @@ function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagno
         details[idsKey] = summarized.values;
         details[truncatedKey] = summarized.truncated;
     }
+    // Auto-fix planning input (pm-c3sz): closed items flagged for a missing
+    // close_reason whose resolution can serve as the derivable source value.
+    // Only collected when close_reason is an active required field, so fixes
+    // always trace back to an actual finding of this run.
+    const closeReasonBackfillRows = metadataPolicy.required_fields.includes("close_reason")
+        ? (missingByField.close_reason ?? []).map((itemId) => ({
+            id: itemId,
+            resolution: toNonEmptyStringOrUndefined(itemsById.get(itemId)?.resolution),
+        }))
+        : [];
     return {
         check: {
             name: "metadata",
@@ -623,6 +670,7 @@ function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagno
             details,
         },
         warnings: warningTokens,
+        closeReasonBackfillRows,
     };
 }
 function buildResolutionCheck(items, statusRegistry, verboseDiagnostics) {
@@ -630,6 +678,7 @@ function buildResolutionCheck(items, statusRegistry, verboseDiagnostics) {
     terminalDoneStatuses.add(statusRegistry.close_status);
     const closedItems = items.filter((item) => terminalDoneStatuses.has(normalizeStatusForRegistry(item.status, statusRegistry)));
     const missingResolutionRows = [];
+    const resolutionBackfillRows = [];
     for (const item of closedItems) {
         const missingFields = RESOLUTION_FIELD_KEYS.filter((field) => !toNonEmptyStringOrUndefined(item[field]));
         if (missingFields.length === 0) {
@@ -639,6 +688,13 @@ function buildResolutionCheck(items, statusRegistry, verboseDiagnostics) {
             id: item.id,
             missing_fields: missingFields,
         });
+        // Auto-fix planning input (pm-c3sz): the planner backfills only the
+        // `resolution` field, deriving from the item's close_reason when present.
+        resolutionBackfillRows.push({
+            id: item.id,
+            missing_fields: missingFields,
+            close_reason: toNonEmptyStringOrUndefined(item.close_reason),
+        });
     }
     const warnings = missingResolutionRows.length > 0 ? [`validate_resolution_missing_fields:${missingResolutionRows.length}`] : [];
     const diagnosticLimit = verboseDiagnostics ? Number.POSITIVE_INFINITY : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
@@ -659,6 +715,7 @@ function buildResolutionCheck(items, statusRegistry, verboseDiagnostics) {
             },
         },
         warnings,
+        resolutionBackfillRows,
     };
 }
 function buildLifecycleDependencyGraph(activeItems) {
@@ -782,6 +839,7 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
     const activeItems = items.filter((item) => !isTerminalStatus(item.status, statusRegistry));
     const closureLikeRows = [];
     const terminalParentRows = [];
+    const terminalParentFixRows = [];
     const staleBlockerRows = [];
     for (const item of activeItems) {
         const closureLikeFields = Object.entries(lifecyclePatternPolicy.closure_like_metadata_field_patterns)
@@ -810,6 +868,17 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
                     parent_id: parent.id,
                     parent_status: parent.status,
                 });
+                // Gated lifecycle auto-fix input (pm-8jss): when the terminal parent
+                // has its own ACTIVE parent, the child can be reparented one level up;
+                // otherwise the suggested fix clears the parent link.
+                const grandparentId = toMeaningfulString(parent.parent);
+                const grandparent = grandparentId ? itemsById.get(grandparentId) : undefined;
+                terminalParentFixRows.push({
+                    id: item.id,
+                    parent_id: parent.id,
+                    grandparent_id: grandparent?.id,
+                    grandparent_active: grandparent !== undefined && !isTerminalStatus(grandparent.status, statusRegistry),
+                });
             }
         }
         if (includeStaleBlockers) {
@@ -849,6 +918,7 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
     }
     closureLikeRows.sort((left, right) => left.id.localeCompare(right.id));
     terminalParentRows.sort((left, right) => left.id.localeCompare(right.id) || left.parent_id.localeCompare(right.parent_id));
+    terminalParentFixRows.sort((left, right) => left.id.localeCompare(right.id) || left.parent_id.localeCompare(right.parent_id));
     staleBlockerRows.sort((left, right) => left.id.localeCompare(right.id));
     const dependencyCycleDiagnostics = detectLifecycleDependencyCycles(activeItems);
     const warnings = [];
@@ -912,32 +982,44 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
             },
         },
         warnings,
+        terminalParentFixRows,
     };
 }
 async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, includePmInternals, verboseFileLists) {
     const linkedProjectPaths = new Set();
     const missingLinkedPaths = [];
+    const staleLinkRows = [];
     for (const item of items) {
-        const linkedArtifacts = [...(item.files ?? []), ...(item.docs ?? [])];
-        for (const artifact of linkedArtifacts) {
-            if (artifact.scope !== "project") {
-                continue;
-            }
-            const normalizedPath = normalizeRelativePath(artifact.path);
-            if (normalizedPath.length === 0) {
-                continue;
-            }
-            linkedProjectPaths.add(normalizedPath);
-            const absolutePath = path.isAbsolute(artifact.path) ? artifact.path : path.resolve(workspaceRoot, artifact.path);
-            try {
-                const stats = await fs.stat(absolutePath);
-                if (!stats.isFile()) {
+        const linkedArtifactGroups = [
+            { link_kind: "files", artifacts: item.files ?? [] },
+            { link_kind: "docs", artifacts: item.docs ?? [] },
+        ];
+        for (const group of linkedArtifactGroups) {
+            for (const artifact of group.artifacts) {
+                if (artifact.scope !== "project") {
+                    continue;
+                }
+                const normalizedPath = normalizeRelativePath(artifact.path);
+                if (normalizedPath.length === 0) {
+                    continue;
+                }
+                linkedProjectPaths.add(normalizedPath);
+                const absolutePath = path.isAbsolute(artifact.path) ? artifact.path : path.resolve(workspaceRoot, artifact.path);
+                let missing = false;
+                try {
+                    const stats = await fs.stat(absolutePath);
+                    if (!stats.isFile() && !stats.isDirectory()) {
+                        missing = true;
+                    }
+                }
+                catch {
+                    missing = true;
+                }
+                if (missing) {
                     missingLinkedPaths.push(normalizedPath);
+                    staleLinkRows.push({ item_id: item.id, path: normalizedPath, link_kind: group.link_kind });
                 }
             }
-            catch {
-                missingLinkedPaths.push(normalizedPath);
-            }
         }
     }
     const uniqueMissingLinkedPaths = [...new Set(missingLinkedPaths)].sort((left, right) => left.localeCompare(right));
@@ -964,6 +1046,20 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
         };
     }
     const orphanedFiles = candidateFiles.filter((candidate) => !linkedProjectPaths.has(candidate));
+    // Stale-path classification (pm-0v2m / GH-184): a missing linked path whose
+    // basename still exists in the candidate scan is reported as `moved` (with
+    // relink candidates); otherwise it is `deleted` and safe to prune.
+    const classifiedStalePaths = classifyStaleLinkedPaths(uniqueMissingLinkedPaths, candidateFiles);
+    const classificationByPath = new Map(classifiedStalePaths.map((entry) => [entry.path, entry.classification]));
+    const movedStalePathCount = classifiedStalePaths.filter((entry) => entry.classification === "moved").length;
+    const staleLinkPruneRows = staleLinkRows
+        .map((row) => ({
+        ...row,
+        classification: classificationByPath.get(row.path) ?? "deleted",
+    }))
+        .sort((left, right) => left.item_id.localeCompare(right.item_id) ||
+        left.path.localeCompare(right.path) ||
+        left.link_kind.localeCompare(right.link_kind));
     const warnings = [];
     if (strictModeForcesPmInternals) {
         warnings.push("validate_files_tracked_all_strict_forces_pm_internals");
@@ -976,6 +1072,7 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
     }
     const summarizedMissing = summarizeFileList(uniqueMissingLinkedPaths, verboseFileLists);
     const summarizedOrphaned = summarizeFileList(orphanedFiles, verboseFileLists);
+    const summarizedClassifications = summarizeFileList(summarizeStaleLinkedPathClassifications(classifiedStalePaths), verboseFileLists);
     return {
         check: {
             name: "files",
@@ -1008,6 +1105,10 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
                 missing_linked_paths_total: summarizedMissing.total,
                 missing_linked_paths: summarizedMissing.values,
                 missing_linked_paths_truncated: summarizedMissing.truncated,
+                missing_linked_paths_moved_count: movedStalePathCount,
+                missing_linked_paths_deleted_count: uniqueMissingLinkedPaths.length - movedStalePathCount,
+                missing_linked_path_classifications: summarizedClassifications.values,
+                missing_linked_path_classifications_truncated: summarizedClassifications.truncated,
                 orphaned_paths_count: orphanedFiles.length,
                 orphaned_paths_total: summarizedOrphaned.total,
                 orphaned_paths: summarizedOrphaned.values,
@@ -1015,6 +1116,7 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
             },
         },
         warnings,
+        staleLinkPruneRows,
     };
 }
 async function buildHistoryDriftCheck(pmRoot, items, verboseDiagnostics) {
@@ -1115,7 +1217,110 @@ function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics) {
         warnings,
     };
 }
+const VALIDATE_AUTO_FIX_MESSAGE = "pm validate auto-fix";
+/**
+ * Apply one planned fix through the SAME audited command paths an operator
+ * would use by hand (`pm update` / `pm files --remove` / `pm docs --remove`),
+ * so every applied fix carries normal history, locking, and hook behavior.
+ * Command modules are imported lazily: plain validate runs stay read-only and
+ * never pay the mutation-stack import cost.
+ */
+async function applyValidateFix(fix, global) {
+    switch (fix.kind) {
+        case "set_resolution":
+        case "set_close_reason":
+        case "reparent":
+        case "unset_parent": {
+            const { runUpdate } = await import("./update.js");
+            const updateOptions = { message: VALIDATE_AUTO_FIX_MESSAGE };
+            if (fix.kind === "set_resolution") {
+                updateOptions.resolution = fix.value;
+            }
+            else if (fix.kind === "set_close_reason") {
+                updateOptions.closeReason = fix.value;
+            }
+            else if (fix.kind === "reparent") {
+                updateOptions.parent = fix.parent_id;
+            }
+            else {
+                updateOptions.unset = ["parent"];
+            }
+            await runUpdate(fix.item_id, updateOptions, global);
+            return;
+        }
+        case "prune_file_link": {
+            throw new Error(`Unsupported non-batched fix kind: ${fix.kind}`);
+        }
+        case "prune_doc_link": {
+            throw new Error(`Unsupported non-batched fix kind: ${fix.kind}`);
+        }
+    }
+}
+function pruneBatchKey(fix) {
+    if (fix.kind !== "prune_file_link" && fix.kind !== "prune_doc_link") {
+        return null;
+    }
+    return `${fix.kind}:${fix.item_id}`;
+}
+async function applyValidateFixes(applicable, global) {
+    const applied = [];
+    const failed = [];
+    const pruneBatches = new Map();
+    for (const fix of applicable) {
+        const batchKey = pruneBatchKey(fix);
+        if (batchKey === null) {
+            try {
+                await applyValidateFix(fix, global);
+                applied.push(fix);
+            }
+            catch (error) {
+                failed.push({ fix, error });
+            }
+            continue;
+        }
+        const existing = pruneBatches.get(batchKey);
+        if (existing) {
+            existing.push(fix);
+        }
+        else {
+            pruneBatches.set(batchKey, [fix]);
+        }
+    }
+    for (const batch of pruneBatches.values()) {
+        const first = batch[0];
+        if (!first) {
+            continue;
+        }
+        const remove = batch
+            .map((fix) => fix.path)
+            .filter((value) => typeof value === "string" && value.length > 0);
+        try {
+            if (first.kind === "prune_file_link") {
+                const { runFiles } = await import("./files.js");
+                await runFiles(first.item_id, { remove, message: VALIDATE_AUTO_FIX_MESSAGE }, global);
+            }
+            else {
+                const { runDocs } = await import("./docs.js");
+                await runDocs(first.item_id, { remove, message: VALIDATE_AUTO_FIX_MESSAGE }, global);
+            }
+            applied.push(...batch);
+        }
+        catch (error) {
+            failed.push(...batch.map((fix) => ({ fix, error })));
+        }
+    }
+    return { applied, failed };
+}
 export async function runValidate(options, global) {
+    const fixesRequested = options.autoFix === true || options.pruneMissing === true;
+    if (options.dryRun === true && !fixesRequested) {
+        throw new PmCliError("--dry-run requires --auto-fix or --prune-missing (there is nothing to preview otherwise).", EXIT_CODE.USAGE);
+    }
+    if (options.fixScope !== undefined && options.fixScope.length > 0 && options.autoFix !== true) {
+        throw new PmCliError("--fix-scope requires --auto-fix.", EXIT_CODE.USAGE);
+    }
+    // Resolved up-front so unknown --fix-scope values fail fast before any scan.
+    const grantedFixScopes = resolveGrantedFixScopes(options.fixScope);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
@@ -1143,17 +1348,29 @@ export async function runValidate(options, global) {
         checks.push(built.check);
         warnings.push(...built.warnings);
     };
+    let closeReasonBackfillRows = [];
+    let resolutionBackfillRows = [];
+    let terminalParentFixRows = [];
+    let staleLinkPruneRows = [];
     if (requestedChecks.has("metadata")) {
-        record(buildMetadataCheck(items, metadataPolicy, statusRegistry, Boolean(options.verboseDiagnostics)));
+        const built = buildMetadataCheck(items, metadataPolicy, statusRegistry, Boolean(options.verboseDiagnostics));
+        closeReasonBackfillRows = built.closeReasonBackfillRows;
+        record(built);
     }
     if (requestedChecks.has("resolution")) {
-        record(buildResolutionCheck(items, statusRegistry, Boolean(options.verboseDiagnostics)));
+        const built = buildResolutionCheck(items, statusRegistry, Boolean(options.verboseDiagnostics));
+        resolutionBackfillRows = built.resolutionBackfillRows;
+        record(built);
     }
     if (requestedChecks.has("lifecycle")) {
-        record(buildLifecycleCheck(items, Boolean(options.checkStaleBlockers), dependencyCycleSeverity, statusRegistry, lifecyclePatternPolicy, Boolean(options.verboseDiagnostics)));
+        const built = buildLifecycleCheck(items, Boolean(options.checkStaleBlockers), dependencyCycleSeverity, statusRegistry, lifecyclePatternPolicy, Boolean(options.verboseDiagnostics));
+        terminalParentFixRows = built.terminalParentFixRows;
+        record(built);
     }
     if (requestedChecks.has("files")) {
-        record(await buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, Boolean(options.includePmInternals), Boolean(options.verboseFileLists)));
+        const built = await buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, Boolean(options.includePmInternals), Boolean(options.verboseFileLists));
+        staleLinkPruneRows = built.staleLinkPruneRows;
+        record(built);
     }
     if (requestedChecks.has("command_references")) {
         record(buildCommandReferencesCheck(items, settings.id_prefix, Boolean(options.verboseDiagnostics)));
@@ -1161,6 +1378,52 @@ export async function runValidate(options, global) {
     if (requestedChecks.has("history_drift")) {
         record(await buildHistoryDriftCheck(pmRoot, items, Boolean(options.verboseDiagnostics)));
     }
+    // Remediation phase (pm-c3sz / pm-8jss / pm-0v2m). Plans are derived from
+    // the findings of THIS run; checks above always report the pre-fix state.
+    // Safe field backfills apply by default under --auto-fix; gated lifecycle
+    // fixes are planned but withheld unless --fix-scope lifecycle grants them;
+    // --dry-run previews without mutating; failures never abort the run.
+    let fixes;
+    if (fixesRequested) {
+        const planned = [];
+        if (options.autoFix === true) {
+            planned.push(...planCloseReasonBackfillFixes(closeReasonBackfillRows));
+            planned.push(...planResolutionBackfillFixes(resolutionBackfillRows));
+            planned.push(...planTerminalParentFixes(terminalParentFixRows));
+        }
+        if (options.pruneMissing === true) {
+            planned.push(...planStaleLinkPruneFixes(staleLinkPruneRows));
+        }
+        const { applicable, gated } = partitionFixesByGrant(planned, grantedFixScopes);
+        const dryRun = options.dryRun === true;
+        const appliedFixRows = [];
+        const failedFixRows = [];
+        if (!dryRun) {
+            const applied = await applyValidateFixes(applicable, global);
+            appliedFixRows.push(...applied.applied.map(toFixOutputRow));
+            failedFixRows.push(...applied.failed.map(({ fix, error }) => ({
+                ...toFixOutputRow(fix),
+                error: error instanceof Error ? error.message : String(error),
+            })));
+        }
+        fixes = {
+            mode: dryRun ? "dry_run" : "apply",
+            auto_fix: options.autoFix === true,
+            prune_missing: options.pruneMissing === true,
+            granted_fix_scopes: [...grantedFixScopes].sort((left, right) => left.localeCompare(right)),
+            planned_count: planned.length,
+            applied_count: appliedFixRows.length,
+            gated_count: gated.length,
+            failed_count: failedFixRows.length,
+            planned_fixes: planned.map(toFixOutputRow),
+            applied_fixes: appliedFixRows,
+            gated_fixes: gated.map((fix) => ({
+                ...toFixOutputRow(fix),
+                gate_hint: `Withheld: re-run with --fix-scope ${fix.gate} to apply.`,
+            })),
+            failed_fixes: failedFixRows,
+        };
+    }
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const hasErrors = checks.some((check) => check.status === "error");
     return {
@@ -1168,8 +1431,9 @@ export async function runValidate(options, global) {
         has_warnings: normalizedWarnings.length > 0,
         checks,
         warnings: normalizedWarnings,
+        ...(fixes !== undefined ? { fixes } : {}),
         generated_at: nowIso(),
     };
 }
 //# sourceMappingURL=validate.js.map
-//# debugId=776e2ca9-52d6-5274-9230-4d9b961456e5
+//# debugId=24c5f96e-8535-5063-87d2-bb17fe0d4d1f