@deftai/directive-core 0.104.0 → 0.105.0

package/dist/policy/sync-default.d.ts

@@ -0,0 +1,129 @@
+/**
+ * scm:sync-default (#3391 / #3377 Wave 3).
+ *
+ * Consumes the shared #3388 detector and #3390 syncMaxFiles. Opens dest-targeted
+ * sync PRs. Over the file limit, cut at merge commits when possible so each
+ * dest-based leg is at or under the threshold. Each leg is a new branch and a
+ * new PR. Never retarget or reuse an oversized PR.
+ */
+import { type GitRunner } from "../session/git.js";
+import { type BranchSyncDetection } from "./branch-sync.js";
+import { type SyncMaxFilesProvenance } from "./sync-max-files.js";
+export declare const SYNC_DEFAULT_VERB = "scm:sync-default";
+export declare const FORBIDDEN_SYNC_PR_RETARGET = "gh pr edit --base";
+export type SyncDefaultAction = "noop" | "single" | "staged";
+export type SyncDefaultNoopReason = "not-sync" | "already-synced" | "zero-files" | "fetch-failed" | "diff-failed";
+export type SyncDefaultCutKind = "merge" | "commit" | "tip";
+export interface SyncDefaultCommit {
+    readonly sha: string;
+    readonly isMerge: boolean;
+}
+export interface SyncDefaultLeg {
+    readonly index: number;
+    readonly sha: string;
+    readonly fileCount: number;
+    readonly cutKind: SyncDefaultCutKind;
+    readonly branchName: string;
+}
+export interface SyncDefaultPlan {
+    readonly action: SyncDefaultAction;
+    readonly noopReason: SyncDefaultNoopReason | null;
+    readonly dest: string;
+    readonly source: string;
+    readonly threshold: number;
+    readonly provenance: SyncMaxFilesProvenance;
+    readonly totalCount: number | null;
+    readonly legs: readonly SyncDefaultLeg[];
+    readonly nextLegIndex: number | null;
+    readonly message: string;
+    readonly detectorReason: BranchSyncDetection["reason"];
+}
+export interface SyncDefaultOpenPull {
+    readonly number: number;
+    readonly htmlUrl: string;
+    readonly headRef: string;
+    readonly headSha: string;
+    readonly baseRef: string;
+}
+export interface SyncDefaultForge {
+    listOpenPulls(repo: string, base: string): readonly SyncDefaultOpenPull[];
+    createPull(repo: string, input: {
+        readonly title: string;
+        readonly head: string;
+        readonly base: string;
+        readonly body: string;
+    }): {
+        readonly number: number;
+        readonly htmlUrl: string;
+    };
+}
+export interface SyncDefaultOpened {
+    readonly leg: SyncDefaultLeg;
+    readonly prNumber: number;
+    readonly prUrl: string;
+    readonly branch: string;
+    readonly reusedExisting: boolean;
+}
+export interface SyncDefaultApplyResult {
+    readonly plan: SyncDefaultPlan;
+    readonly opened: readonly SyncDefaultOpened[];
+    readonly retargeted: false;
+}
+export declare function syncDefaultBranchName(dest: string, source: string, index: number, sha: string): string;
+export declare function parseGithubOwnerRepo(remoteUrl: string): string | null;
+export declare function countChangedFilesOnRange(options: {
+    readonly projectRoot: string;
+    readonly left: string;
+    readonly right: string;
+    readonly runGit?: GitRunner;
+}): {
+    readonly count: number | null;
+    readonly error: string | null;
+};
+export declare function listCommitsAfter(options: {
+    readonly projectRoot: string;
+    readonly dest: string;
+    readonly source: string;
+    readonly runGit?: GitRunner;
+}): {
+    readonly commits: readonly SyncDefaultCommit[];
+    readonly error: string | null;
+};
+/**
+ * Cut dest..source into dest-targeted legs whose dest-based file count is at
+ * or under the threshold when a merge (or other) cut exists.
+ */
+export declare function cutSyncLegs(options: {
+    readonly dest: string;
+    readonly source: string;
+    readonly destRef: string;
+    readonly sourceSha: string;
+    readonly commits: readonly SyncDefaultCommit[];
+    readonly threshold: number;
+    readonly countFiles: (left: string, right: string) => number | null;
+    /** When set, later cuts must be descendants of the previous cut. */
+    readonly isAncestor?: (ancestor: string, descendant: string) => boolean;
+}): {
+    readonly legs: readonly SyncDefaultLeg[];
+    readonly error: string | null;
+};
+export declare function planSyncDefault(options: {
+    readonly projectRoot: string;
+    readonly maxFiles?: number | null;
+    readonly destTipSha?: string;
+    readonly runGit?: GitRunner;
+}): SyncDefaultPlan;
+export declare function nextOpenableLeg(legs: readonly SyncDefaultLeg[], destTipSha: string, projectRoot: string, runGit: GitRunner): SyncDefaultLeg | null;
+export declare function applySyncDefault(options: {
+    readonly projectRoot: string;
+    readonly repo: string;
+    readonly plan?: SyncDefaultPlan;
+    readonly maxFiles?: number | null;
+    readonly destTipSha?: string;
+    readonly dryRun?: boolean;
+    readonly runGit?: GitRunner;
+    readonly forge?: SyncDefaultForge;
+}): SyncDefaultApplyResult;
+export declare function syncDefaultPrBody(plan: SyncDefaultPlan, leg: SyncDefaultLeg): string;
+export declare function formatSyncDefaultHuman(result: SyncDefaultApplyResult): string;
+//# sourceMappingURL=sync-default.d.ts.map

package/dist/policy/sync-default.js

@@ -0,0 +1,452 @@
+/**
+ * scm:sync-default (#3391 / #3377 Wave 3).
+ *
+ * Consumes the shared #3388 detector and #3390 syncMaxFiles. Opens dest-targeted
+ * sync PRs. Over the file limit, cut at merge commits when possible so each
+ * dest-based leg is at or under the threshold. Each leg is a new branch and a
+ * new PR. Never retarget or reuse an oversized PR.
+ */
+import { defaultGitRunner, gitIsAncestor } from "../session/git.js";
+import { detectBranchSync, resolveSyncPolicyFromDestRef, } from "./branch-sync.js";
+import { resolveGitDefaultDeliveryBranch } from "./delivery-branch.js";
+import { resolveSyncMaxFiles } from "./sync-max-files.js";
+export const SYNC_DEFAULT_VERB = "scm:sync-default";
+export const FORBIDDEN_SYNC_PR_RETARGET = "gh pr edit --base";
+function shortSha(sha) {
+    return sha.length >= 7 ? sha.slice(0, 7) : sha;
+}
+export function syncDefaultBranchName(dest, source, index, sha) {
+    const safe = (value) => value.replace(/[^A-Za-z0-9._-]+/g, "-");
+    return `sync/${safe(dest)}-from-${safe(source)}/leg-${index}-${shortSha(sha)}`;
+}
+export function parseGithubOwnerRepo(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    const withoutGit = trimmed.toLowerCase().endsWith(".git") ? trimmed.slice(0, -4) : trimmed;
+    const marker = "github.com";
+    const idx = withoutGit.toLowerCase().lastIndexOf(marker);
+    if (idx < 0)
+        return null;
+    const after = withoutGit.slice(idx + marker.length);
+    const rest = after.startsWith(":") || after.startsWith("/") ? after.slice(1) : after;
+    const parts = rest.split("/").filter((part) => part.length > 0);
+    const owner = parts[0];
+    const repo = parts[1];
+    if (owner === undefined || repo === undefined)
+        return null;
+    return `${owner}/${repo}`;
+}
+export function countChangedFilesOnRange(options) {
+    const left = options.left.trim();
+    const right = options.right.trim();
+    if (left.length === 0 || right.length === 0) {
+        return { count: null, error: "empty diff range" };
+    }
+    const runGit = options.runGit ?? defaultGitRunner;
+    const ranged = `${left}...${right}`;
+    const diffed = runGit(options.projectRoot, ["diff", "--name-only", ranged]);
+    if (diffed.code !== 0) {
+        return { count: null, error: diffed.stderr || `git diff failed for ${ranged}` };
+    }
+    const files = diffed.stdout.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    return { count: files.length, error: null };
+}
+export function listCommitsAfter(options) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const logged = runGit(options.projectRoot, [
+        "log",
+        "--reverse",
+        "--format=%H%x09%P",
+        `origin/${options.dest}..origin/${options.source}`,
+    ]);
+    if (logged.code !== 0) {
+        return { commits: [], error: logged.stderr || "git log failed" };
+    }
+    const commits = [];
+    for (const line of logged.stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const tab = trimmed.indexOf("\t");
+        const sha = tab === -1 ? trimmed : trimmed.slice(0, tab);
+        const parents = tab === -1 ? "" : trimmed.slice(tab + 1).trim();
+        if (sha.length === 0)
+            continue;
+        commits.push({
+            sha,
+            isMerge: parents.split(/\s+/).filter((part) => part.length > 0).length > 1,
+        });
+    }
+    return { commits, error: null };
+}
+/**
+ * Cut dest..source into dest-targeted legs whose dest-based file count is at
+ * or under the threshold when a merge (or other) cut exists.
+ */
+export function cutSyncLegs(options) {
+    const { dest, source, destRef, sourceSha, commits, threshold, countFiles, isAncestor } = options;
+    const legs = [];
+    let left = destRef;
+    let guard = 0;
+    while (guard < commits.length + 2) {
+        guard += 1;
+        const remaining = countFiles(left, sourceSha);
+        if (remaining === null) {
+            return { legs: [], error: `git diff failed for ${left}...${sourceSha}` };
+        }
+        if (remaining <= threshold) {
+            if (left !== sourceSha && remaining > 0) {
+                const tip = commits.find((commit) => commit.sha === sourceSha);
+                const cutKind = legs.length === 0 ? "tip" : tip?.isMerge === true ? "merge" : "tip";
+                const index = legs.length + 1;
+                legs.push({
+                    index,
+                    sha: sourceSha,
+                    fileCount: remaining,
+                    cutKind,
+                    branchName: syncDefaultBranchName(dest, source, index, sourceSha),
+                });
+            }
+            return { legs, error: null };
+        }
+        const afterLeft = left === destRef
+            ? commits
+            : commits.filter((commit) => {
+                if (isAncestor !== undefined) {
+                    return commit.sha !== left && isAncestor(left, commit.sha);
+                }
+                const leftIdx = commits.findIndex((row) => row.sha === left);
+                const idx = commits.findIndex((row) => row.sha === commit.sha);
+                return leftIdx >= 0 ? idx > leftIdx : true;
+            });
+        let bestMerge = null;
+        let bestCommit = null;
+        for (const commit of afterLeft) {
+            const counted = countFiles(left, commit.sha);
+            if (counted === null) {
+                return { legs: [], error: `git diff failed for ${left}...${commit.sha}` };
+            }
+            if (counted <= threshold) {
+                bestCommit = { sha: commit.sha, count: counted };
+                if (commit.isMerge)
+                    bestMerge = { sha: commit.sha, count: counted };
+            }
+        }
+        const chosen = bestMerge ??
+            bestCommit ??
+            (afterLeft[0]
+                ? {
+                    sha: afterLeft[0].sha,
+                    count: countFiles(left, afterLeft[0].sha),
+                }
+                : null);
+        if (chosen === null || chosen.count === null) {
+            return { legs: [], error: "no commit to cut after dest" };
+        }
+        const cutKind = bestMerge !== null && chosen.sha === bestMerge.sha ? "merge" : "commit";
+        const index = legs.length + 1;
+        legs.push({
+            index,
+            sha: chosen.sha,
+            fileCount: chosen.count,
+            cutKind,
+            branchName: syncDefaultBranchName(dest, source, index, chosen.sha),
+        });
+        if (chosen.sha === sourceSha)
+            return { legs, error: null };
+        left = chosen.sha;
+    }
+    return { legs: [], error: "cut loop exceeded commit count" };
+}
+function formatPlanMessage(plan) {
+    if (plan.action === "noop") {
+        if (plan.noopReason === "not-sync") {
+            return `scm:sync-default: no-op (detector=${plan.detectorReason})`;
+        }
+        if (plan.noopReason === "already-synced") {
+            return `scm:sync-default: no-op (origin/${plan.source} already on origin/${plan.dest})`;
+        }
+        if (plan.noopReason === "zero-files") {
+            return `scm:sync-default: no-op (0 files origin/${plan.dest}...origin/${plan.source})`;
+        }
+        if (plan.noopReason === "fetch-failed") {
+            return "scm:sync-default: fetch failed";
+        }
+        return `scm:sync-default: no-op (${plan.noopReason ?? "unknown"})`;
+    }
+    if (plan.action === "single") {
+        return (`scm:sync-default: one new PR origin/${plan.source} -> origin/${plan.dest} ` +
+            `(${plan.totalCount ?? "?"} files, syncMaxFiles=${plan.threshold} ${plan.provenance})`);
+    }
+    const next = plan.nextLegIndex ?? 1;
+    return (`scm:sync-default: staged ${plan.legs.length} new-PR legs; ` +
+        `next is leg ${next} (each leg is a new branch + new PR; never ${FORBIDDEN_SYNC_PR_RETARGET})`);
+}
+export function planSyncDefault(options) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const guessedDest = resolveGitDefaultDeliveryBranch(options.projectRoot, runGit);
+    const policy = resolveSyncPolicyFromDestRef({
+        projectRoot: options.projectRoot,
+        prBase: guessedDest,
+        runGit,
+    });
+    const dest = policy.dest;
+    const source = policy.source;
+    const fetchedDest = runGit(options.projectRoot, ["fetch", "--quiet", "origin", dest]);
+    if (fetchedDest.code !== 0) {
+        const resolvedEarly = resolveSyncMaxFiles(options.projectRoot, options.maxFiles);
+        return {
+            action: "noop",
+            noopReason: "fetch-failed",
+            dest,
+            source,
+            threshold: resolvedEarly.maxFiles,
+            provenance: resolvedEarly.provenance,
+            totalCount: null,
+            legs: [],
+            nextLegIndex: null,
+            detectorReason: "fetch-failed",
+            message: "scm:sync-default: fetch failed",
+        };
+    }
+    const resolved = resolveSyncMaxFiles(options.projectRoot, options.maxFiles);
+    const empty = (extra) => {
+        const base = {
+            dest,
+            source,
+            threshold: resolved.maxFiles,
+            provenance: resolved.provenance,
+            totalCount: extra.totalCount ?? null,
+            legs: extra.legs ?? [],
+            nextLegIndex: extra.nextLegIndex ?? null,
+            ...extra,
+        };
+        return { ...base, message: formatPlanMessage(base) };
+    };
+    const fetchedSource = runGit(options.projectRoot, ["fetch", "--quiet", "origin", source]);
+    if (fetchedSource.code !== 0) {
+        return empty({
+            action: "noop",
+            noopReason: "fetch-failed",
+            detectorReason: "fetch-failed",
+        });
+    }
+    const tipParsed = runGit(options.projectRoot, ["rev-parse", "--verify", `origin/${source}`]);
+    if (tipParsed.code !== 0 || tipParsed.stdout.trim().length === 0) {
+        return empty({
+            action: "noop",
+            noopReason: "fetch-failed",
+            detectorReason: "fetch-failed",
+        });
+    }
+    const sourceSha = tipParsed.stdout.trim();
+    const destParsed = runGit(options.projectRoot, ["rev-parse", "--verify", `origin/${dest}`]);
+    const destSha = destParsed.code === 0 ? destParsed.stdout.trim() : "";
+    const destTip = options.destTipSha ?? destSha;
+    const sync = detectBranchSync({
+        dest,
+        source,
+        sourceTyped: policy.sourceTyped,
+        prBase: dest,
+        headSha: sourceSha,
+        projectRoot: options.projectRoot,
+        developHint: policy.developHint,
+        runGit,
+    });
+    if (!sync.isSync) {
+        return empty({
+            action: "noop",
+            noopReason: sync.reason === "fetch-failed" ? "fetch-failed" : "not-sync",
+            detectorReason: sync.reason,
+        });
+    }
+    if (destTip.length > 0 &&
+        gitIsAncestor(options.projectRoot, sourceSha, destTip, runGit) === true) {
+        return empty({
+            action: "noop",
+            noopReason: "already-synced",
+            detectorReason: "sync",
+        });
+    }
+    const destRef = `origin/${dest}`;
+    const total = countChangedFilesOnRange({
+        projectRoot: options.projectRoot,
+        left: destRef,
+        right: `origin/${source}`,
+        runGit,
+    });
+    if (total.count === null) {
+        return empty({
+            action: "noop",
+            noopReason: "diff-failed",
+            detectorReason: "sync",
+        });
+    }
+    if (total.count === 0) {
+        return empty({
+            action: "noop",
+            noopReason: "zero-files",
+            detectorReason: "sync",
+            totalCount: 0,
+        });
+    }
+    const listed = listCommitsAfter({
+        projectRoot: options.projectRoot,
+        dest,
+        source,
+        runGit,
+    });
+    if (listed.error !== null) {
+        return empty({
+            action: "noop",
+            noopReason: "diff-failed",
+            detectorReason: "sync",
+            totalCount: total.count,
+        });
+    }
+    const cut = cutSyncLegs({
+        dest,
+        source,
+        destRef,
+        sourceSha,
+        commits: listed.commits,
+        threshold: resolved.maxFiles,
+        countFiles: (left, right) => countChangedFilesOnRange({
+            projectRoot: options.projectRoot,
+            left,
+            right,
+            runGit,
+        }).count,
+        isAncestor: (ancestor, descendant) => gitIsAncestor(options.projectRoot, ancestor, descendant, runGit) === true,
+    });
+    if (cut.error !== null || cut.legs.length === 0) {
+        return empty({
+            action: "noop",
+            noopReason: "diff-failed",
+            detectorReason: "sync",
+            totalCount: total.count,
+        });
+    }
+    const next = nextOpenableLeg(cut.legs, destTip, options.projectRoot, runGit);
+    const action = cut.legs.length === 1 ? "single" : "staged";
+    return empty({
+        action,
+        noopReason: null,
+        detectorReason: "sync",
+        totalCount: total.count,
+        legs: cut.legs,
+        nextLegIndex: next?.index ?? null,
+    });
+}
+export function nextOpenableLeg(legs, destTipSha, projectRoot, runGit) {
+    for (const leg of legs) {
+        if (destTipSha.length > 0 && gitIsAncestor(projectRoot, leg.sha, destTipSha, runGit) === true) {
+            continue;
+        }
+        return leg;
+    }
+    return null;
+}
+function matchingOpenPull(pulls, dest, leg) {
+    for (const pull of pulls) {
+        if (pull.baseRef !== dest)
+            continue;
+        if (pull.headRef === leg.branchName && pull.headSha === leg.sha)
+            return pull;
+    }
+    return null;
+}
+export function applySyncDefault(options) {
+    const runGit = options.runGit ?? defaultGitRunner;
+    const plan = options.plan ??
+        planSyncDefault({
+            projectRoot: options.projectRoot,
+            maxFiles: options.maxFiles,
+            destTipSha: options.destTipSha,
+            runGit,
+        });
+    if (plan.action === "noop" || plan.legs.length === 0) {
+        return { plan, opened: [], retargeted: false };
+    }
+    const destParsed = runGit(options.projectRoot, ["rev-parse", "--verify", `origin/${plan.dest}`]);
+    const destTip = options.destTipSha ?? (destParsed.code === 0 ? destParsed.stdout.trim() : "");
+    const next = nextOpenableLeg(plan.legs, destTip, options.projectRoot, runGit);
+    if (next === null) {
+        return { plan, opened: [], retargeted: false };
+    }
+    if (options.dryRun === true || options.forge === undefined) {
+        return { plan, opened: [], retargeted: false };
+    }
+    const openPulls = options.forge.listOpenPulls(options.repo, plan.dest);
+    const existing = matchingOpenPull(openPulls, plan.dest, next);
+    if (existing !== null) {
+        return {
+            plan,
+            opened: [
+                {
+                    leg: next,
+                    prNumber: existing.number,
+                    prUrl: existing.htmlUrl,
+                    branch: existing.headRef,
+                    reusedExisting: true,
+                },
+            ],
+            retargeted: false,
+        };
+    }
+    const pushed = runGit(options.projectRoot, [
+        "push",
+        "--quiet",
+        "origin",
+        `${next.sha}:refs/heads/${next.branchName}`,
+    ]);
+    if (pushed.code !== 0) {
+        throw new Error(pushed.stderr || `git push failed for ${next.branchName}`);
+    }
+    const created = options.forge.createPull(options.repo, {
+        title: `sync: ${plan.source} -> ${plan.dest} (leg ${next.index}/${plan.legs.length})`,
+        head: next.branchName,
+        base: plan.dest,
+        body: syncDefaultPrBody(plan, next),
+    });
+    return {
+        plan,
+        opened: [
+            {
+                leg: next,
+                prNumber: created.number,
+                prUrl: created.htmlUrl,
+                branch: next.branchName,
+                reusedExisting: false,
+            },
+        ],
+        retargeted: false,
+    };
+}
+export function syncDefaultPrBody(plan, leg) {
+    return [
+        `Staged dest sync via \`${SYNC_DEFAULT_VERB}\`.`,
+        "",
+        `- Dest: \`${plan.dest}\` (deliveryBranch)`,
+        `- Source: \`${plan.source}\` (typed baseBranch)`,
+        `- Leg ${leg.index} of ${plan.legs.length} at \`${leg.sha}\` (${leg.fileCount} files, cut=${leg.cutKind})`,
+        `- Threshold: syncMaxFiles=${plan.threshold} (${plan.provenance.replace(/\r?\n/g, " ")})`,
+        "",
+        "This PR is new. After it merges, run `task scm:sync-default` again.",
+        "The next leg is a new branch and a new PR. Do not retarget or reuse an oversized PR",
+        `(\`${FORBIDDEN_SYNC_PR_RETARGET}\` / close-reopen). Each leg must be new when the reviewer first sees it.`,
+        "",
+        "Required checks stay on. The only exemption is the Wave 1 core-guard sync predicate.",
+    ].join("\n");
+}
+export function formatSyncDefaultHuman(result) {
+    const lines = [result.plan.message];
+    for (const opened of result.opened) {
+        const reuse = opened.reusedExisting ? "existing" : "new";
+        lines.push(`  ${reuse} PR #${opened.prNumber} ${opened.prUrl} (${opened.branch} @ ${shortSha(opened.leg.sha)})`);
+    }
+    if (result.plan.action === "staged" && result.opened.length > 0) {
+        lines.push("  remaining legs open as new PRs after this one merges");
+    }
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=sync-default.js.map

package/dist/policy/sync-max-files.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Typed plan.policy.syncMaxFiles (#3390 / #3377 Wave 2).
+ *
+ * One integer. Unset is 400. `--max-files` overrides one run and does not
+ * write policy. Set 100 if SLizard is a required check. Do not probe
+ * reviewer APIs and do not encode vendor limits as code constants.
+ *
+ * File-count warn uses the shared #3388 detector. Count is
+ * `git diff --name-only origin/<dest>...origin/<source>`. No warn when
+ * the detector says this is not a sync. The #3391 verb consumes
+ * evaluateSyncMaxFilesWarn and the maxFiles one-run override.
+ */
+import { type GitRunner } from "../session/git.js";
+import { type BranchSyncDetection } from "./branch-sync.js";
+export declare const FIELD_SYNC_MAX_FILES = "plan.policy.syncMaxFiles";
+export declare const FIELD_SYNC_MAX_FILES_CLI_ALIAS = "syncMaxFiles";
+/** Unset threshold. Not a vendor limit. */
+export declare const DEFAULT_SYNC_MAX_FILES = 400;
+/**
+ * Operator docs for the threshold. Recommendation only — not a coded
+ * Greptile or SLizard constant.
+ */
+export declare const SYNC_MAX_FILES_DOCS = "Unset is 400. Set plan.policy.syncMaxFiles to 100 if SLizard is a required check.";
+export type SyncMaxFilesSource = "typed" | "default" | "default-on-error" | "flag";
+/** Provenance printed in the warn: default vs policy vs one-run flag. */
+export type SyncMaxFilesProvenance = "default" | "policy" | "flag";
+export interface SyncMaxFilesResolved {
+    readonly maxFiles: number;
+    readonly source: SyncMaxFilesSource;
+    readonly provenance: SyncMaxFilesProvenance;
+    readonly error: string | null;
+}
+export type SyncMaxFilesWarnReason = "not-sync" | "within-limit" | "exceeds" | "diff-failed";
+export interface SyncMaxFilesWarnResult {
+    readonly warn: boolean;
+    readonly reason: SyncMaxFilesWarnReason;
+    readonly count: number | null;
+    readonly threshold: number;
+    readonly provenance: SyncMaxFilesProvenance;
+    readonly dest: string;
+    readonly source: string;
+    readonly message: string;
+}
+/** Parse `--max-files`. Invalid or absent values are ignored. */
+export declare function parseMaxFilesFlag(raw: unknown): number | null;
+/**
+ * Resolve the file-count threshold.
+ *
+ * `--max-files` (maxFiles) wins for this call only and is never written.
+ */
+export declare function resolveSyncMaxFiles(projectRoot?: string | null, maxFiles?: number | null): SyncMaxFilesResolved;
+export interface SyncMaxFilesPolicyField {
+    readonly name: typeof FIELD_SYNC_MAX_FILES;
+    readonly current: number;
+    readonly default: number;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=syncMaxFiles`. */
+export declare function inspectSyncMaxFiles(_data: Record<string, unknown> | null, projectRoot?: string): SyncMaxFilesPolicyField;
+/** Count files in `origin/<dest>...origin/<source>`. */
+export declare function countSyncChangedFiles(options: {
+    readonly dest: string;
+    readonly source: string;
+    readonly projectRoot: string;
+    readonly runGit?: GitRunner;
+}): {
+    readonly count: number | null;
+    readonly error: string | null;
+};
+export declare function formatSyncMaxFilesWarn(options: {
+    readonly count: number;
+    readonly threshold: number;
+    readonly provenance: SyncMaxFilesProvenance;
+    readonly dest: string;
+    readonly source: string;
+}): string;
+export interface EvaluateSyncMaxFilesWarnInput {
+    readonly projectRoot: string;
+    readonly prBase: string;
+    readonly headSha: string;
+    /** `--max-files` one-run override. Does not write policy. */
+    readonly maxFiles?: number | null;
+    readonly runGit?: GitRunner;
+    /** Optional precomputed detector result. */
+    readonly sync?: BranchSyncDetection;
+}
+/**
+ * Warn when a detected sync exceeds syncMaxFiles.
+ *
+ * No warn when the shared detector says this is not a sync.
+ */
+export declare function evaluateSyncMaxFilesWarn(input: EvaluateSyncMaxFilesWarnInput): SyncMaxFilesWarnResult;
+//# sourceMappingURL=sync-max-files.d.ts.map