@lumy-pack/line-lore 0.0.5 → 0.0.7

package/dist/cli.mjs

@@ -369,14 +369,51 @@ var init_executor = __esm({
 import { filter as filter4, isTruthy as isTruthy4 } from "@winglet/common-utils";
 async function findMergeCommit(commitSha, options) {
   const ref = options?.ref ?? "HEAD";
+  const budget = options?.timeout ?? DEFAULT_ANCESTRY_TIMEOUT;
+  const startTime = Date.now();
   const firstParentResult = await findMergeCommitWithArgs(
     commitSha,
     ref,
     ["--first-parent"],
-    options
+    { ...options, timeout: budget }
   );
   if (firstParentResult) return firstParentResult;
-  return findMergeCommitWithArgs(commitSha, ref, [], options);
+  const elapsed = Date.now() - startTime;
+  const remaining = budget - elapsed;
+  if (remaining <= 0) return null;
+  return findMergeCommitWithArgs(commitSha, ref, [], {
+    ...options,
+    timeout: remaining
+  });
+}
+async function verifyMergeIntroducesCommit(targetSha, mergeResult, options) {
+  if (mergeResult.parentShas.length < 2) return true;
+  const firstParent = mergeResult.parentShas[0];
+  const branchParents = mergeResult.parentShas.slice(1);
+  const onMainline = await isAncestor(targetSha, firstParent, options);
+  if (onMainline === null) return false;
+  if (onMainline) return false;
+  for (const branchParent of branchParents) {
+    const onBranch = await isAncestor(targetSha, branchParent, options);
+    if (onBranch === null) return false;
+    if (onBranch) return true;
+  }
+  return false;
+}
+async function isAncestor(commitA, commitB, options) {
+  try {
+    const result = await gitExec(
+      ["merge-base", "--is-ancestor", commitA, commitB],
+      {
+        cwd: options?.cwd,
+        timeout: options?.timeout ?? 5e3,
+        allowExitCodes: [1]
+      }
+    );
+    return result.exitCode === 0;
+  } catch {
+    return null;
+  }
 }
 async function findMergeCommitWithArgs(commitSha, ref, extraArgs, options) {
   try {
@@ -395,7 +432,25 @@ async function findMergeCommitWithArgs(commitSha, ref, extraArgs, options) {
     );
     const lines = filter4(result.stdout.trim().split("\n"), isTruthy4);
     if (lines.length === 0) return null;
-    return parseMergeLogLine(lines[0]);
+    const candidateCount = Math.min(lines.length, MAX_CANDIDATES);
+    let verifiedCount = 0;
+    for (let i = 0; i < candidateCount; i++) {
+      const candidate = parseMergeLogLine(lines[i]);
+      if (!candidate) continue;
+      verifiedCount++;
+      const verified = await verifyMergeIntroducesCommit(
+        commitSha,
+        candidate,
+        options
+      );
+      if (verified) return candidate;
+    }
+    if (verifiedCount > 0 && options?.warnings) {
+      options.warnings.push(
+        `ancestry: all ${verifiedCount} merge candidate(s) failed verification for ${commitSha.slice(0, 8)}`
+      );
+    }
+    return null;
   } catch {
     return null;
   }
@@ -417,19 +472,38 @@ function parseMergeLogLine(line) {
   const subject = parts.slice(subjectStart).join(" ");
   return { mergeCommitSha, parentShas, subject };
 }
-function extractPRFromMergeMessage(subject) {
+async function getCommitSubject(sha, options) {
+  try {
+    const result = await gitExec(["log", "-1", "--format=%s", sha], {
+      cwd: options?.cwd,
+      timeout: options?.timeout ?? 5e3
+    });
+    const subject = result.stdout.trim();
+    return subject || null;
+  } catch {
+    return null;
+  }
+}
+function extractPRFromMergeMessage(subject, platform) {
   const ghMatch = /Merge pull request #(\d+)/.exec(subject);
   if (ghMatch) return parseInt(ghMatch[1], 10);
   const squashMatch = /\(#(\d+)\)\s*$/.exec(subject);
   if (squashMatch) return parseInt(squashMatch[1], 10);
-  const glMatch = /!(\d+)\s*$/.exec(subject);
-  if (glMatch) return parseInt(glMatch[1], 10);
+  if (!platform || platform === "gitlab" || platform === "gitlab-self-hosted") {
+    const glMatch = /See merge request\s+\S*!(\d+)\s*$/.exec(subject);
+    if (glMatch) return parseInt(glMatch[1], 10);
+  }
+  const adoMatch = /Merged PR (\d+):/.exec(subject);
+  if (adoMatch) return parseInt(adoMatch[1], 10);
   return null;
 }
+var DEFAULT_ANCESTRY_TIMEOUT, MAX_CANDIDATES;
 var init_ancestry = __esm({
   "src/core/ancestry/ancestry.ts"() {
     "use strict";
     init_executor();
+    DEFAULT_ANCESTRY_TIMEOUT = 3e4;
+    MAX_CANDIDATES = 10;
   }
 });
 
@@ -549,19 +623,67 @@ function getCache2(repoId, noCache) {
   }
   return cache;
 }
-async function lookupPR(commitSha, adapter, options) {
-  const cache = getCache2(options?.repoId, options?.noCache);
+function toCachedPR(pr) {
+  return {
+    number: pr.number,
+    title: pr.title,
+    author: pr.author,
+    url: pr.url,
+    mergeCommit: pr.mergeCommit,
+    baseBranch: pr.baseBranch,
+    mergedAt: pr.mergedAt ? new Date(pr.mergedAt).getTime() : void 0,
+    resolvedVia: pr.resolvedVia
+  };
+}
+function fromCachedPR(cached) {
+  let mergedAt;
+  if (cached.mergedAt != null) {
+    mergedAt = typeof cached.mergedAt === "number" ? new Date(cached.mergedAt).toISOString() : String(cached.mergedAt);
+  }
+  return {
+    number: cached.number,
+    title: cached.title,
+    author: cached.author,
+    url: cached.url,
+    mergeCommit: cached.mergeCommit,
+    baseBranch: cached.baseBranch,
+    mergedAt,
+    // Preserve original resolvedVia; fallback to url heuristic for legacy cache entries
+    resolvedVia: cached.resolvedVia ?? (cached.url ? "api" : "message")
+  };
+}
+async function lookupPR(commitSha, adapter, options, _recursionDepth = 0) {
+  const cache = getCache2(
+    options?.repoId,
+    options?.cacheOnly ? false : options?.noCache
+  );
   const cached = await cache.get(commitSha);
-  if (cached) return cached;
+  if (cached) return fromCachedPR(cached);
+  if (options?.cacheOnly) return null;
+  const prSelectOptions = options?.preferredBase ? { preferredBase: options.preferredBase } : void 0;
+  if (adapter) {
+    const directPR = await adapter.getPRForCommit(commitSha, prSelectOptions);
+    if (directPR?.mergedAt) {
+      const result = { ...directPR, resolvedVia: "api" };
+      await cache.set(commitSha, toCachedPR(result));
+      return result;
+    }
+  }
   let mergeBasedPR = null;
   const mergeResult = await findMergeCommit(commitSha, options);
   if (mergeResult) {
-    const prNumber = extractPRFromMergeMessage(mergeResult.subject);
+    const prNumber = extractPRFromMergeMessage(
+      mergeResult.subject,
+      options?.platform
+    );
     if (prNumber) {
       if (adapter) {
-        const prInfo = await adapter.getPRForCommit(mergeResult.mergeCommitSha);
+        const prInfo = await adapter.getPRForCommit(
+          mergeResult.mergeCommitSha,
+          prSelectOptions
+        );
         if (prInfo?.mergedAt) {
-          mergeBasedPR = prInfo;
+          mergeBasedPR = { ...prInfo, resolvedVia: "ancestry" };
         }
       }
       if (!mergeBasedPR) {
@@ -571,35 +693,56 @@ async function lookupPR(commitSha, adapter, options) {
           author: "",
           url: "",
           mergeCommit: mergeResult.mergeCommitSha,
-          baseBranch: ""
+          baseBranch: "",
+          resolvedVia: "ancestry"
         };
       }
       if (!options?.deep || mergeBasedPR.mergedAt) {
-        await cache.set(commitSha, mergeBasedPR);
+        await cache.set(commitSha, toCachedPR(mergeBasedPR));
         return mergeBasedPR;
       }
     }
   }
   if (mergeBasedPR) {
-    await cache.set(commitSha, mergeBasedPR);
+    await cache.set(commitSha, toCachedPR(mergeBasedPR));
     return mergeBasedPR;
   }
-  if (adapter) {
-    const prInfo = await adapter.getPRForCommit(commitSha);
-    if (prInfo?.mergedAt) {
-      await cache.set(commitSha, prInfo);
-      return prInfo;
+  const commitSubject = await getCommitSubject(commitSha, options);
+  if (commitSubject) {
+    const directPrNumber = extractPRFromMergeMessage(
+      commitSubject,
+      options?.platform
+    );
+    if (directPrNumber) {
+      const subjectPR = {
+        number: directPrNumber,
+        title: commitSubject,
+        author: "",
+        url: "",
+        mergeCommit: commitSha,
+        baseBranch: "",
+        resolvedVia: "message"
+      };
+      await cache.set(commitSha, toCachedPR(subjectPR));
+      return subjectPR;
     }
   }
-  const patchIdMatch = await findPatchIdMatch(commitSha, {
-    ...options,
-    scanDepth: options?.deep ? DEEP_SCAN_DEPTH : void 0
-  });
-  if (patchIdMatch) {
-    const result = await lookupPR(patchIdMatch.matchedSha, adapter, options);
-    if (result) {
-      await cache.set(commitSha, result);
-      return result;
+  if (!options?.skipPatchIdScan && _recursionDepth < MAX_RECURSION_DEPTH) {
+    const patchIdMatch = await findPatchIdMatch(commitSha, {
+      ...options,
+      scanDepth: options?.deep ? DEEP_SCAN_DEPTH : void 0
+    });
+    if (patchIdMatch) {
+      const result = await lookupPR(
+        patchIdMatch.matchedSha,
+        adapter,
+        options,
+        _recursionDepth + 1
+      );
+      if (result) {
+        await cache.set(commitSha, toCachedPR(result));
+        return result;
+      }
     }
   }
   return null;
@@ -607,7 +750,7 @@ async function lookupPR(commitSha, adapter, options) {
 function resetPRCache() {
   cacheRegistry2.clear();
 }
-var cacheRegistry2, DEEP_SCAN_DEPTH;
+var cacheRegistry2, DEEP_SCAN_DEPTH, MAX_RECURSION_DEPTH;
 var init_pr_lookup = __esm({
   "src/core/pr-lookup/pr-lookup.ts"() {
     "use strict";
@@ -616,6 +759,7 @@ var init_pr_lookup = __esm({
     init_patch_id2();
     cacheRegistry2 = /* @__PURE__ */ new Map();
     DEEP_SCAN_DEPTH = 2e3;
+    MAX_RECURSION_DEPTH = 2;
   }
 });
 
@@ -637,7 +781,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.0.5";
+    VERSION = "0.0.7";
   }
 });
 
@@ -734,6 +878,7 @@ import { Command } from "commander";
 
 // src/core/core.ts
 import { createHash as createHash2 } from "crypto";
+import { dirname, isAbsolute, relative } from "path";
 import { map as map8 } from "@winglet/common-utils";
 
 // src/ast/parser.ts
@@ -962,6 +1107,27 @@ function isVersionAtLeast(version2, minVersion) {
   }
   return true;
 }
+async function checkCloneStatus(options) {
+  let partialClone = false;
+  let shallow = false;
+  try {
+    const shallowResult = await gitExec(
+      ["rev-parse", "--is-shallow-repository"],
+      { cwd: options?.cwd }
+    );
+    shallow = shallowResult.stdout.trim() === "true";
+  } catch {
+  }
+  try {
+    const partialResult = await gitExec(
+      ["config", "--get", "extensions.partialclone"],
+      { cwd: options?.cwd }
+    );
+    partialClone = partialResult.stdout.trim().length > 0;
+  } catch {
+  }
+  return { partialClone, shallow };
+}
 async function checkGitHealth(options) {
   const hints = [];
   let gitVersion = "0.0.0";
@@ -988,7 +1154,18 @@ async function checkGitHealth(options) {
       `Upgrade git to ${BLOOM_FILTER_MIN_VERSION.join(".")}+ for bloom filter support (current: ${gitVersion}).`
     );
   }
-  return { commitGraph, bloomFilter, gitVersion, hints };
+  const cloneStatus = await checkCloneStatus({ cwd: options?.cwd });
+  if (cloneStatus.partialClone) {
+    hints.push(
+      "Partial clone detected. Patch-ID scan (Strategy 5) will be skipped to avoid blob downloads."
+    );
+  }
+  if (cloneStatus.shallow) {
+    hints.push(
+      "Shallow repository detected. Ancestry-path results may be incomplete."
+    );
+  }
+  return { commitGraph, bloomFilter, gitVersion, hints, ...cloneStatus };
 }
 
 // src/git/remote.ts
@@ -1081,7 +1258,7 @@ var GitHubAdapter = class {
       return { authenticated: false, hostname: this.hostname };
     }
   }
-  async getPRForCommit(sha) {
+  async getPRForCommit(sha, options) {
     if (this.scheduler.isRateLimited()) return null;
     try {
       const result = await shellExec(
@@ -1098,18 +1275,20 @@ var GitHubAdapter = class {
       );
       const prs = JSON.parse(result.stdout);
       if (!isArray(prs) || prs.length === 0) return null;
-      const defaultBranch = await this.detectDefaultBranch();
-      const defaultBranchPR = prs.find(
-        (pr) => pr.base === defaultBranch
-      );
-      const data = defaultBranchPR ?? prs[0];
+      let data = prs[0];
+      if (options?.preferredBase) {
+        const preferred = prs.find(
+          (pr) => pr.base === options.preferredBase
+        );
+        if (preferred) data = preferred;
+      }
       return {
         number: data.number,
         title: data.title ?? "",
         author: data.user ?? "",
         url: data.html_url ?? "",
         mergeCommit: data.merge_commit_sha ?? sha,
-        baseBranch: data.base ?? defaultBranch,
+        baseBranch: data.base ?? "",
         mergedAt: data.merged_at
       };
     } catch {
@@ -1286,7 +1465,7 @@ var GitLabAdapter = class {
       return { authenticated: false, hostname: this.hostname };
     }
   }
-  async getPRForCommit(sha) {
+  async getPRForCommit(sha, options) {
     if (this.scheduler.isRateLimited()) return null;
     try {
       const result = await shellExec(
@@ -1310,18 +1489,20 @@ var GitLabAdapter = class {
         return aTime - bTime;
       });
       if (mergedMRs.length === 0) return null;
-      const defaultBranch = await this.detectDefaultBranch();
-      const defaultBranchMR = mergedMRs.find(
-        (mr2) => mr2.target_branch === defaultBranch
-      );
-      const mr = defaultBranchMR ?? mergedMRs[0];
+      let mr = mergedMRs[0];
+      if (options?.preferredBase) {
+        const preferred = mergedMRs.find(
+          (m) => m.target_branch === options.preferredBase
+        );
+        if (preferred) mr = preferred;
+      }
       return {
         number: mr.iid,
         title: mr.title ?? "",
         author: mr.author?.username ?? "",
         url: mr.web_url ?? "",
         mergeCommit: mr.merge_commit_sha ?? sha,
-        baseBranch: mr.target_branch ?? defaultBranch,
+        baseBranch: mr.target_branch ?? "",
         mergedAt: mr.merged_at
       };
     } catch {
@@ -2098,6 +2279,28 @@ async function traverse(adapter, type, number, depth, maxDepth, nodes, edges, vi
 
 // src/core/core.ts
 init_pr_lookup2();
+function resolvedViaToTrackingMethod(resolvedVia) {
+  switch (resolvedVia) {
+    case "api":
+      return "api";
+    case "ancestry":
+      return "ancestry-path";
+    case "message":
+      return "message-parse";
+    case "patch-id":
+      return "patch-id";
+  }
+}
+function resolvedViaToConfidence(resolvedVia) {
+  switch (resolvedVia) {
+    case "api":
+    case "ancestry":
+      return "exact";
+    case "message":
+    case "patch-id":
+      return "heuristic";
+  }
+}
 function computeFeatureFlags(operatingLevel, options) {
   return {
     astDiff: isAstAvailable() && !options.noAst,
@@ -2115,6 +2318,22 @@ async function resolveRepoIdentity(cwd) {
     return { host: "_local", owner: "_", repo: "_unknown" };
   }
 }
+async function resolveFileContext(file, cwd) {
+  if (cwd || !isAbsolute(file)) return { file, cwd };
+  const fileDir = dirname(file);
+  try {
+    const result = await gitExec(["rev-parse", "--show-toplevel"], {
+      cwd: fileDir
+    });
+    const repoRoot = result.stdout.trim();
+    return {
+      file: relative(repoRoot, file),
+      cwd: repoRoot
+    };
+  } catch {
+    return { file, cwd };
+  }
+}
 async function detectPlatform2(options) {
   const warnings = [];
   let adapter = null;
@@ -2161,7 +2380,7 @@ async function runBlameAndAuth(adapter, options, execOptions) {
   }
   return { analyzed: blameResult.value, operatingLevel, warnings };
 }
-async function processEntry(entry, featureFlags, adapter, options, execOptions, repoId) {
+async function processEntry(entry, featureFlags, adapter, options, execOptions, repoId, skipPatchIdScan, preferredBase) {
   const nodes = [];
   const commitNode = {
     type: entry.isCosmetic ? "cosmetic_commit" : "original_commit",
@@ -2192,15 +2411,19 @@ async function processEntry(entry, featureFlags, adapter, options, execOptions,
     const prInfo = await lookupPR(targetSha, adapter, {
       ...execOptions,
       noCache: options.noCache,
+      cacheOnly: options.cacheOnly,
       deep: featureFlags.deepTrace,
-      repoId
+      repoId,
+      skipPatchIdScan,
+      preferredBase,
+      platform: adapter?.platform
     });
     if (prInfo) {
       nodes.push({
         type: "pull_request",
         sha: prInfo.mergeCommit,
-        trackingMethod: prInfo.url ? "api" : "message-parse",
-        confidence: prInfo.url ? "exact" : "heuristic",
+        trackingMethod: resolvedViaToTrackingMethod(prInfo.resolvedVia),
+        confidence: resolvedViaToConfidence(prInfo.resolvedVia),
         prNumber: prInfo.number,
         prUrl: prInfo.url || void 0,
         prTitle: prInfo.title || void 0,
@@ -2210,24 +2433,35 @@ async function processEntry(entry, featureFlags, adapter, options, execOptions,
   }
   return nodes;
 }
-async function buildTraceNodes(analyzed, featureFlags, adapter, options, execOptions, repoId) {
+async function buildTraceNodes(analyzed, featureFlags, adapter, options, execOptions, repoId, skipPatchIdScan, preferredBase) {
   const results = await Promise.allSettled(
     map8(
       analyzed,
-      (entry) => processEntry(entry, featureFlags, adapter, options, execOptions, repoId)
+      (entry) => processEntry(
+        entry,
+        featureFlags,
+        adapter,
+        options,
+        execOptions,
+        repoId,
+        skipPatchIdScan,
+        preferredBase
+      )
     )
   );
   return results.flatMap((r) => r.status === "fulfilled" ? r.value : []);
 }
 var legacyCacheCleaned = false;
 async function trace(options) {
-  const execOptions = { cwd: options.cwd };
+  const { file, cwd } = await resolveFileContext(options.file, options.cwd);
+  const warnings = [];
+  const execOptions = { cwd, warnings };
   if (!legacyCacheCleaned) {
     legacyCacheCleaned = true;
     cleanupLegacyCache().catch(() => {
     });
   }
-  const platform = await detectPlatform2(options);
+  const platform = await detectPlatform2({ ...options, cwd });
   let repoId;
   if (platform.remote) {
     repoId = {
@@ -2236,23 +2470,58 @@ async function trace(options) {
       repo: platform.remote.repo
     };
   } else {
-    repoId = await resolveRepoIdentity(options.cwd);
+    repoId = await resolveRepoIdentity(cwd);
   }
   const blameAuth = await runBlameAndAuth(
     platform.adapter,
-    options,
+    { ...options, file, cwd },
     execOptions
   );
   const operatingLevel = blameAuth.operatingLevel || platform.operatingLevel;
-  const warnings = [...platform.warnings, ...blameAuth.warnings];
+  warnings.push(...platform.warnings, ...blameAuth.warnings);
+  if (options.cacheOnly && options.noCache) {
+    warnings.push(
+      "Both cacheOnly and noCache are set. cacheOnly takes precedence \u2014 cache reads are enabled."
+    );
+  }
   const featureFlags = computeFeatureFlags(operatingLevel, options);
+  let cloneStatus = { partialClone: false, shallow: false };
+  try {
+    const result = await checkCloneStatus({ cwd });
+    if (result) cloneStatus = result;
+  } catch {
+  }
+  if (cloneStatus.partialClone) {
+    warnings.push(
+      "Partial clone detected. Patch-ID scan (Strategy 5) will be skipped to avoid blob downloads."
+    );
+  }
+  if (cloneStatus.shallow) {
+    warnings.push(
+      "Shallow repository detected. Ancestry-path results may be incomplete."
+    );
+  }
+  let preferredBase;
+  try {
+    const branchResult = await gitExec(
+      ["rev-parse", "--abbrev-ref", "HEAD"],
+      execOptions
+    );
+    const branch = branchResult.stdout.trim();
+    if (branch && branch !== "HEAD") {
+      preferredBase = branch;
+    }
+  } catch {
+  }
   const nodes = await buildTraceNodes(
     blameAuth.analyzed,
     featureFlags,
     platform.adapter,
-    options,
+    { ...options, file, cwd },
     execOptions,
-    repoId
+    repoId,
+    cloneStatus.partialClone || void 0,
+    preferredBase
   );
   return { nodes, operatingLevel, featureFlags, warnings };
 }
@@ -2459,7 +2728,7 @@ function formatNodeHuman(node) {
 init_normalizer();
 init_errors();
 function registerTraceCommand(program2) {
-  program2.command("trace <file>").description("Trace a file line to its originating PR").requiredOption("-L, --line <range>", 'Line number or range (e.g., "42" or "10,50")').option("--deep", "Enable deep trace for squash PRs").option("--no-ast", "Disable AST diff analysis").option("--no-cache", "Disable cache").option("--json", "Output in JSON format").option("-q, --quiet", "Output PR number only").option("--output <format>", "Output format: human, json, llm", "human").option("--no-color", "Disable colored output").action(async (file, opts) => {
+  program2.command("trace <file>").description("Trace a file line to its originating PR").requiredOption("-L, --line <range>", 'Line number or range (e.g., "42" or "10,50")').option("--deep", "Enable deep trace for squash PRs").option("--no-ast", "Disable AST diff analysis").option("--no-cache", "Disable cache").option("--cache-only", "Return cached results only (no API calls)").option("--json", "Output in JSON format").option("-q, --quiet", "Output PR number only").option("--output <format>", "Output format: human, json, llm", "human").option("--no-color", "Disable colored output").action(async (file, opts) => {
     const lineStr = opts.line;
     const parts = lineStr.split(",");
     const line = parseInt(parts[0], 10);
@@ -2470,7 +2739,8 @@ function registerTraceCommand(program2) {
       endLine,
       deep: opts.deep,
       noAst: opts.ast === false,
-      noCache: opts.cache === false
+      noCache: opts.cache === false,
+      cacheOnly: opts.cacheOnly
     };
     const cliOptions = {
       json: opts.json,

package/dist/core/ancestry/ancestry.d.ts

@@ -4,7 +4,21 @@ export interface AncestryResult {
     parentShas: string[];
     subject: string;
 }
+export declare const DEFAULT_ANCESTRY_TIMEOUT = 30000;
 export declare function findMergeCommit(commitSha: string, options?: GitExecOptions & {
     ref?: string;
 }): Promise<AncestryResult | null>;
-export declare function extractPRFromMergeMessage(subject: string): number | null;
+/**
+ * Verify that a merge commit actually introduced the target commit
+ * through its branch side (non-first parent), not from the mainline.
+ *
+ * Dual condition:
+ * 1. Target IS an ancestor of at least one non-first parent (branch side)
+ * 2. Target is NOT an ancestor of the first parent (mainline side)
+ *
+ * Returns false on git command failure (fail-skip policy).
+ */
+export declare function verifyMergeIntroducesCommit(targetSha: string, mergeResult: AncestryResult, options?: GitExecOptions): Promise<boolean>;
+/** Retrieve the subject line of a single commit. Returns null on git failure. */
+export declare function getCommitSubject(sha: string, options?: GitExecOptions): Promise<string | null>;
+export declare function extractPRFromMergeMessage(subject: string, platform?: string): number | null;

package/dist/core/ancestry/index.d.ts

@@ -1,2 +1,2 @@
-export { extractPRFromMergeMessage, findMergeCommit } from './ancestry.js';
+export { extractPRFromMergeMessage, findMergeCommit, getCommitSubject, verifyMergeIntroducesCommit, } from './ancestry.js';
 export type { AncestryResult } from './ancestry.js';

package/dist/core/pr-lookup/index.d.ts

@@ -1 +1,2 @@
 export { lookupPR, resetPRCache } from './pr-lookup.js';
+export type { PRLookupResult, ResolvedVia } from './pr-lookup.js';

package/dist/core/pr-lookup/pr-lookup.d.ts

@@ -1,9 +1,31 @@
 import type { RepoIdentity } from '../../cache/index.js';
 import type { GitExecOptions, PRInfo, PlatformAdapter } from '../../types/index.js';
+export type ResolvedVia = 'api' | 'ancestry' | 'message' | 'patch-id';
+export interface PRLookupResult extends PRInfo {
+    resolvedVia: ResolvedVia;
+}
 export interface PRLookupOptions extends GitExecOptions {
     noCache?: boolean;
+    /** Return cached results only — skip all fallback strategies */
+    cacheOnly?: boolean;
     deep?: boolean;
     repoId?: RepoIdentity;
+    /** Skip Strategy 5 (patch-id scan) — set automatically for partial clone environments */
+    skipPatchIdScan?: boolean;
+    /** Preferred base branch for PR selection — when multiple PRs match, prefer the one targeting this branch */
+    preferredBase?: string;
+    /** Platform type for platform-aware merge message parsing */
+    platform?: string;
 }
-export declare function lookupPR(commitSha: string, adapter: PlatformAdapter | null, options?: PRLookupOptions): Promise<PRInfo | null>;
+/**
+ * Multi-strategy PR lookup pipeline:
+ *   Strategy 1: Cache
+ *   Strategy 2: API direct (ground truth — Level 2)
+ *   Strategy 3: Ancestry-path + merge commit verification (structural proof)
+ *   Strategy 4: Blame commit message parsing (heuristic — squash merge detection)
+ *   Strategy 5: Patch-ID matching + recursion (last resort)
+ */
+export declare function lookupPR(commitSha: string, adapter: PlatformAdapter | null, options?: PRLookupOptions, 
+/** @internal recursion depth tracker — do not set from external callers */
+_recursionDepth?: number): Promise<PRLookupResult | null>;
 export declare function resetPRCache(): void;