@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/cli/commands/validate.d.ts

@@ -1,249 +1,9 @@
-import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
-import type { GlobalOptions } from "../../core/shared/command-types.js";
-import { listAllItemMetadataWithBody } from "../../core/store/item-store.js";
-import { type CloseReasonBackfillRow, type EstimateBackfillRow, type StaleLinkPruneRow, type TerminalParentFixRow, type ValidateFixRecord } from "../../core/validate/fix-planning.js";
-import { type DuplicateIssueCode } from "../../core/governance/issue-codes.js";
-import { type MissingFieldOccurrence } from "../../core/validate/missing-by-type.js";
-import type { ValidateMetadataProfile, ValidateMetadataRequiredField } from "../../types/index.js";
-type ValidateCheckName = "metadata" | "resolution" | "lifecycle" | "dependency_references" | "files" | "command_references" | "history_drift" | "format_version";
-type ValidateStatus = "ok" | "warn" | "error";
-type ValidateDependencyCycleSeverity = "off" | "warn" | "error";
-type ValidateFileScanMode = "default" | "tracked-all" | "tracked-all-strict";
-type ItemWithBody = Awaited<ReturnType<typeof listAllItemMetadataWithBody>>[number];
-type OrphanedPathClassification = "docs_unowned" | "tests_unowned" | "source_unowned" | "unlinked_existing";
-declare const LIFECYCLE_PATTERN_FIELD_KEYS: readonly ["blocked_reason", "resolution", "actual_result"];
-type LifecyclePatternFieldKey = (typeof LIFECYCLE_PATTERN_FIELD_KEYS)[number];
-/** Documents the validate command options payload exchanged by command, SDK, and package integrations. */
-export interface ValidateCommandOptions {
-    /** Value that configures or reports check metadata for this contract. */
-    checkMetadata?: boolean;
-    /** Value that configures or reports check resolution for this contract. */
-    checkResolution?: boolean;
-    /** Value that configures or reports check lifecycle for this contract. */
-    checkLifecycle?: boolean;
-    /** Value that configures or reports check stale blockers for this contract. */
-    checkStaleBlockers?: boolean;
-    /** Value that configures or reports dependency cycle severity for this contract. */
-    dependencyCycleSeverity?: string;
-    /** Value that configures or reports parent cycle severity for this contract. */
-    parentCycleSeverity?: string;
-    /** Value that configures or reports check files for this contract. */
-    checkFiles?: boolean;
-    /** Value that configures or reports include pm internals for this contract. */
-    includePmInternals?: boolean;
-    /** Value that configures or reports verbose file lists for this contract. */
-    verboseFileLists?: boolean;
-    /** Value that configures or reports verbose diagnostics for this contract. */
-    verboseDiagnostics?: boolean;
-    /** Emit complete *_item_ids diagnostic lists (no 5-item cap); implied by --json. */
-    allAffectedIds?: boolean;
-    /** Value that configures or reports check history drift for this contract. */
-    checkHistoryDrift?: boolean;
-    /** Value that configures or reports check command references for this contract. */
-    checkCommandReferences?: boolean;
-    /** Strategy used to control scan behavior. */
-    scanMode?: string;
-    /** Value that configures or reports metadata profile for this contract. */
-    metadataProfile?: string;
-    /** Value that configures or reports fix hints for this contract. */
-    fixHints?: boolean;
-    /** Value that configures or reports auto fix for this contract. */
-    autoFix?: boolean;
-    /** Value that configures or reports dry run for this contract. */
-    dryRun?: boolean;
-    /** Value that configures or reports fix scope for this contract. */
-    fixScope?: string[];
-    /** Value that configures or reports prune missing for this contract. */
-    pruneMissing?: boolean;
-}
-/** Documents the validate check payload exchanged by command, SDK, and package integrations. */
-export interface ValidateCheck {
-    /** Value that configures or reports name for this contract. */
-    name: ValidateCheckName;
-    /** Lifecycle state reported for status. */
-    status: ValidateStatus;
-    /** Value that configures or reports details for this contract. */
-    details: Record<string, unknown>;
-}
-/** Documents the validate fixes summary payload exchanged by command, SDK, and package integrations. */
-export interface ValidateFixesSummary {
-    /** Value that configures or reports mode for this contract. */
-    mode: "apply" | "dry_run";
-    /** Value that configures or reports auto fix for this contract. */
-    auto_fix: boolean;
-    /** Value that configures or reports prune missing for this contract. */
-    prune_missing: boolean;
-    /** Value that configures or reports granted fix scopes for this contract. */
-    granted_fix_scopes: string[];
-    /** Number of planned entries represented by this result. */
-    planned_count: number;
-    /** Number of applied entries represented by this result. */
-    applied_count: number;
-    /** Number of gated entries represented by this result. */
-    gated_count: number;
-    /** Number of failed entries represented by this result. */
-    failed_count: number;
-    /** Value that configures or reports planned fixes for this contract. */
-    planned_fixes: Array<Record<string, unknown>>;
-    /** Value that configures or reports applied fixes for this contract. */
-    applied_fixes: Array<Record<string, unknown>>;
-    /** Value that configures or reports gated fixes for this contract. */
-    gated_fixes: Array<Record<string, unknown>>;
-    /** Value that configures or reports failed fixes for this contract. */
-    failed_fixes: Array<Record<string, unknown>>;
-}
-/** Documents the validate result payload exchanged by command, SDK, and package integrations. */
-export interface ValidateResult {
-    /** Whether the operation completed without a blocking failure. */
-    ok: boolean;
-    /** Whether warnings applies to this operation. */
-    has_warnings: boolean;
-    /** Value that configures or reports checks for this contract. */
-    checks: ValidateCheck[];
-    /** Value that configures or reports warnings for this contract. */
-    warnings: string[];
-    /** Present when --auto-fix or --prune-missing was requested; checks always reflect the PRE-fix state. */
-    fixes?: ValidateFixesSummary;
-    /** ISO 8601 timestamp recording when generated occurred. */
-    generated_at: string;
-}
-declare function toMeaningfulString(value: unknown): string | undefined;
-interface ValidateMetadataPolicy {
-    profile: ValidateMetadataProfile;
-    profile_source: "default" | "settings" | "option";
-    required_fields: ValidateMetadataRequiredField[];
-    configured_custom_fields: ValidateMetadataRequiredField[];
-    fallback_to_core: boolean;
-    warnings: string[];
-}
-type LifecyclePatternSource = "default" | "settings";
-interface LifecyclePatternPolicy {
-    stale_blocker_reason_patterns: string[];
-    stale_blocker_reason_pattern_source: LifecyclePatternSource;
-    closure_like_metadata_field_patterns: Record<LifecyclePatternFieldKey, string[]>;
-    closure_like_metadata_field_pattern_sources: Record<LifecyclePatternFieldKey, LifecyclePatternSource>;
-}
-declare function resolveValidateMetadataProfile(value: string | undefined): ValidateMetadataProfile;
-declare function resolveDependencyCycleSeverity(value: string | undefined): ValidateDependencyCycleSeverity;
-declare function resolveParentCycleSeverity(value: string | undefined): ValidateDependencyCycleSeverity;
-declare function isMetadataFieldMissing(item: ItemWithBody, field: ValidateMetadataRequiredField, statusRegistry: RuntimeStatusRegistry, enforcePlanningFieldsOnTerminal: boolean): boolean;
-declare function resolveFileScanMode(scanMode: string | undefined): ValidateFileScanMode;
-declare function resolveWorkspaceRoot(pmRoot: string): string;
-declare function listFilesRecursive(basePath: string, relativePath: string, output: string[]): Promise<void>;
-declare function collectDefaultProjectFileCandidates(workspaceRoot: string): Promise<string[]>;
-declare function collectTrackedGitFileCandidates(workspaceRoot: string): Promise<string[] | null>;
-/** Attach a uniform, machine-executable `fix_hints` array to a validate check's details when `--fix-hints` is requested. The resolution check's existing per-row remediation commands (which already carry concrete item ids) are aliased in so agents read one uniform field across every check; all other checks derive one generic command per distinct warning code from the shared remediation registry. Generic hints may contain `<id>`/`<field>`/`<path>` placeholders the caller substitutes before running — they are templates, not always directly executable as-is. Read-only: this only enriches the diagnostic output, never mutates any item. */
-declare function attachValidateFixHints(check: ValidateCheck, checkWarnings: string[]): void;
-declare function resolveRequestedChecks(options: ValidateCommandOptions): Set<ValidateCheckName>;
-/** Project the duplicate logical issue-code findings (GH-235) into the metadata-check `details` shape plus an advisory warning token. Duplicate codes are advisory (warn), never an error — matching every other metadata finding — so an otherwise clean tracker that simply reuses a title prefix is not failed by `pm validate`. Kept outside the c8-ignored builder block so the projection/remediation logic is fully covered by unit tests. */
-declare function summarizeDuplicateIssueCodes(duplicates: DuplicateIssueCode[], verboseDiagnostics: boolean): {
-    rows: Array<Record<string, unknown>>;
-    truncated: boolean;
-    warnings: string[];
-};
-declare function buildMetadataCounts(metadataPolicy: ValidateMetadataPolicy, missingByField: Record<ValidateMetadataRequiredField, string[]>): Record<string, number>;
-declare function buildMissingFieldOccurrences(metadataPolicy: ValidateMetadataPolicy, missingByField: Record<ValidateMetadataRequiredField, string[]>, itemsById: Map<string, ItemWithBody>): MissingFieldOccurrence[];
-declare function buildCloseReasonBackfillRows(metadataPolicy: ValidateMetadataPolicy, missingByField: Record<ValidateMetadataRequiredField, string[]>, itemsById: Map<string, ItemWithBody>): CloseReasonBackfillRow[];
-declare function buildEstimateBackfillRows(metadataPolicy: ValidateMetadataPolicy, missingByField: Record<ValidateMetadataRequiredField, string[]>, itemsById: Map<string, ItemWithBody>): EstimateBackfillRow[];
-declare function escapeRegExp(value: string): string;
-declare function buildLifecycleDependencyGraph(activeItems: ItemWithBody[], idPrefix?: string): Map<string, string[]>;
-declare function buildDependencyReferencesCheck(items: ItemWithBody[], verboseDiagnostics: boolean, statusRegistry?: RuntimeStatusRegistry): {
-    check: ValidateCheck;
-    warnings: string[];
-};
-declare function extractItemIds(value: string, idPrefix?: string): string[];
-declare function findLifecycleDependencyCycleComponents(graph: Map<string, string[]>): string[][];
-declare function resolveLifecycleDependencyCycleSamplePath(component: string[], graph: Map<string, string[]>): string[];
-declare function detectLifecycleDependencyCycles(activeItems: ItemWithBody[], idPrefix?: string): {
-    cycle_count: number;
-    cycle_item_ids: string[];
-    cycle_sample_paths: string[];
-};
-declare function buildLifecycleParentGraph(items: ItemWithBody[]): Map<string, string[]>;
-declare function detectLifecycleParentCycles(items: ItemWithBody[]): {
-    cycle_count: number;
-    cycle_item_ids: string[];
-    cycle_sample_paths: string[];
-};
-interface OrphanedPathRow {
-    path: string;
-    classification: OrphanedPathClassification;
-    owner_candidate: {
-        id: string;
-        type: string;
-        title: string;
-        status: string;
-        confidence: "path_prefix" | "same_directory" | "shared_directory";
-    } | null;
-    remediation_hint: string;
-}
-declare function classifyOrphanedPath(pathValue: string): OrphanedPathClassification;
-declare function sharedDirectoryPrefixLength(left: string, right: string): number;
-declare function buildOrphanedPathRows(orphanedFiles: readonly string[], items: readonly ItemWithBody[]): OrphanedPathRow[];
-declare function summarizeOrphanedPathRows(rows: readonly OrphanedPathRow[]): string[];
-declare function linkedArtifactPathExceedsFilesystemLimits(artifactPath: string): boolean;
-declare function buildLifecycleCheck(items: ItemWithBody[], includeStaleBlockers: boolean, dependencyCycleSeverity: ValidateDependencyCycleSeverity, parentCycleSeverity: ValidateDependencyCycleSeverity, statusRegistry: RuntimeStatusRegistry, lifecyclePatternPolicy: LifecyclePatternPolicy, verboseDiagnostics: boolean, idPrefix?: string): {
-    check: ValidateCheck;
-    warnings: string[];
-    terminalParentFixRows: TerminalParentFixRow[];
-};
-declare function buildFilesCheck(items: ItemWithBody[], workspaceRoot: string, pmRoot: string, fileScanMode: ValidateFileScanMode, includePmInternals: boolean, verboseFileLists: boolean): Promise<{
-    check: ValidateCheck;
-    warnings: string[];
-    staleLinkPruneRows: StaleLinkPruneRow[];
-}>;
-declare function buildCommandReferencesCheck(items: ItemWithBody[], idPrefix: string, verboseDiagnostics: boolean): {
-    check: ValidateCheck;
-    warnings: string[];
-};
-/** 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. */
-declare function applyValidateFix(fix: ValidateFixRecord, global: GlobalOptions): Promise<void>;
-declare function applyValidateFixes(applicable: ValidateFixRecord[], global: GlobalOptions): Promise<{
-    applied: ValidateFixRecord[];
-    failed: Array<{
-        fix: ValidateFixRecord;
-        error: unknown;
-    }>;
-}>;
-/** Public contract for test only validate command, shared by SDK and presentation-layer consumers. */
-export declare const _testOnlyValidateCommand: {
-    applyValidateFix: typeof applyValidateFix;
-    applyValidateFixes: typeof applyValidateFixes;
-    attachValidateFixHints: typeof attachValidateFixHints;
-    buildCommandReferencesCheck: typeof buildCommandReferencesCheck;
-    buildDependencyReferencesCheck: typeof buildDependencyReferencesCheck;
-    buildCloseReasonBackfillRows: typeof buildCloseReasonBackfillRows;
-    buildFilesCheck: typeof buildFilesCheck;
-    buildLifecycleCheck: typeof buildLifecycleCheck;
-    buildLifecycleDependencyGraph: typeof buildLifecycleDependencyGraph;
-    buildLifecycleParentGraph: typeof buildLifecycleParentGraph;
-    buildEstimateBackfillRows: typeof buildEstimateBackfillRows;
-    buildMetadataCounts: typeof buildMetadataCounts;
-    buildMissingFieldOccurrences: typeof buildMissingFieldOccurrences;
-    buildOrphanedPathRows: typeof buildOrphanedPathRows;
-    classifyOrphanedPath: typeof classifyOrphanedPath;
-    collectDefaultProjectFileCandidates: typeof collectDefaultProjectFileCandidates;
-    collectTrackedGitFileCandidates: typeof collectTrackedGitFileCandidates;
-    detectLifecycleDependencyCycles: typeof detectLifecycleDependencyCycles;
-    detectLifecycleParentCycles: typeof detectLifecycleParentCycles;
-    escapeRegExp: typeof escapeRegExp;
-    extractItemIds: typeof extractItemIds;
-    findLifecycleDependencyCycleComponents: typeof findLifecycleDependencyCycleComponents;
-    isMetadataFieldMissing: typeof isMetadataFieldMissing;
-    linkedArtifactPathExceedsFilesystemLimits: typeof linkedArtifactPathExceedsFilesystemLimits;
-    listFilesRecursive: typeof listFilesRecursive;
-    resolveDependencyCycleSeverity: typeof resolveDependencyCycleSeverity;
-    resolveParentCycleSeverity: typeof resolveParentCycleSeverity;
-    resolveFileScanMode: typeof resolveFileScanMode;
-    resolveLifecycleDependencyCycleSamplePath: typeof resolveLifecycleDependencyCycleSamplePath;
-    resolveRequestedChecks: typeof resolveRequestedChecks;
-    resolveValidateMetadataProfile: typeof resolveValidateMetadataProfile;
-    resolveWorkspaceRoot: typeof resolveWorkspaceRoot;
-    sharedDirectoryPrefixLength: typeof sharedDirectoryPrefixLength;
-    summarizeOrphanedPathRows: typeof summarizeOrphanedPathRows;
-    summarizeDuplicateIssueCodes: typeof summarizeDuplicateIssueCodes;
-    toMeaningfulString: typeof toMeaningfulString;
-};
-/** Implements run validate for the public runtime surface of this module. */
-export declare function runValidate(options: ValidateCommandOptions, global: GlobalOptions): Promise<ValidateResult>;
-export {};
+/**
+ * @module cli/commands/validate
+ *
+ * Compatibility adapter for the SDK-owned governance validation engine.
+ */
+import { runValidate as runSdkValidate } from "../../sdk/governance/validate.js";
+export * from "../../sdk/governance/validate.js";
+/** Run SDK validation with the CLI's canonical audited update mutation service. */
+export declare const runValidate: (options: Parameters<typeof runSdkValidate>[0], global: Parameters<typeof runSdkValidate>[1]) => Promise<import("../../sdk/governance/validate.js").ValidateResult>;