@lumy-pack/line-lore 0.0.5 → 0.0.6

package/README.md

@@ -40,6 +40,9 @@ npx @lumy-pack/line-lore graph pr 42 --depth 2
 # Check system health
 npx @lumy-pack/line-lore health
 
+# Return cached results only (no API calls)
+npx @lumy-pack/line-lore trace src/auth.ts -L 42 --cache-only
+
 # Clear caches
 npx @lumy-pack/line-lore cache clear
 
@@ -95,6 +98,48 @@ console.log(`Git version: ${report.gitVersion}`);
 
 No ML or heuristics — results are always reproducible.
 
+### PR Lookup Algorithm
+
+Once a commit is identified, line-lore resolves it to a PR using a **cost-ascending sequential fallback chain**. Each strategy is tried in order; the first success returns immediately.
+
+```
+lookupPR(commitSha)
+  │
+  ▼
+Strategy 1 — Cache ─────────────────── cost: O(1), instant
+  │ ShardedCache<PRInfo> lookup by SHA
+  │ hit? → return cached PRInfo
+  │ miss + --cache-only? → return null (skip all fallbacks)
+  ▼
+Strategy 2 — Ancestry-path + Message ─ cost: 1 git-log
+  │ 1st: git log --merges --ancestry-path --first-parent sha..HEAD
+  │ 2nd: (fallback) full ancestry-path without --first-parent
+  │ Parse merge subject with 3 regex patterns:
+  │   • /Merge pull request #(\d+)/  — GitHub merge commit
+  │   • /\(#(\d+)\)\s*$/             — Squash merge convention
+  │   • /!(\d+)\s*$/                 — GitLab merge commit
+  │ If PR# found + adapter available → enrich via API
+  │ found? → return PRInfo
+  ▼
+Strategy 3 — Platform API ──────────── cost: 1 HTTP request
+  │ gh api repos/{owner}/{repo}/commits/{sha}/pulls
+  │ Filter: merged PRs only (mergedAt != null)
+  │ found? → return PRInfo
+  ▼
+Strategy 4 — Patch-ID matching ─────── cost: streaming 500+ commits
+  │ Compute target: git diff sha^..sha | git patch-id --stable
+  │ Batch scan:     git log -500 -p HEAD | git patch-id --stable
+  │                 (--deep mode: 2000 commits)
+  │ Find candidate with same patch-id but different SHA
+  │ match? → lookupPR(matchedSha) recursively
+  ▼
+All failed → null
+```
+
+**Why this order?** The chain is sorted by cost. Most repositories use merge or squash workflows, so Strategy 2 resolves >90% of lookups with zero API calls. Strategy 3 (single HTTP) is cheaper than Strategy 4 (streaming hundreds of commit diffs), so API is tried before patch-id scanning.
+
+**Patch-ID explained**: `git patch-id --stable` generates a content-based hash from a commit's diff, ignoring all metadata (author, date, message). When a commit is rebased, its SHA changes but the patch-id stays the same — enabling deterministic matching of rebased commits.
+
 ## Understanding the Output
 
 ### TraceNode — the core unit of output
@@ -302,6 +347,7 @@ Trace a code line to its originating PR.
 | `deep` | `boolean` | no | `false` | Expand patch-id scan range (500→2000), continue search after merge commit match |
 | `noAst` | `boolean` | no | `false` | Disable AST analysis |
 | `noCache` | `boolean` | no | `false` | Disable cache reads and writes |
+| `cacheOnly` | `boolean` | no | `false` | Return cached results only — skip API calls, ancestry traversal, and patch-id scan. If both `cacheOnly` and `noCache` are set, `cacheOnly` takes precedence (cache reads remain enabled) and a warning is emitted. |
 
 **Returns (`TraceFullResult`):**
 
@@ -499,6 +545,30 @@ async function analyzeChangedLines(file: string, lines: number[]) {
 }
 ```
 
+### Cache-Only Lookups
+
+Use `cacheOnly` to instantly return previously cached PR data without any API calls or git operations beyond blame. Ideal for IDE integrations and repeated lookups where speed matters more than freshness.
+
+```typescript
+import { trace } from '@lumy-pack/line-lore';
+
+async function getCachedPR(filePath: string, lineNumber: number) {
+  const result = await trace({
+    file: filePath,
+    line: lineNumber,
+    cacheOnly: true, // return cached data only, never fetch
+  });
+
+  const pr = result.nodes.find(n => n.type === 'pull_request');
+  if (pr) {
+    return { number: pr.prNumber, url: pr.prUrl };
+  }
+
+  // Cache miss — no PR data available without fetching
+  return null;
+}
+```
+
 ### Batch Processing with Cache Control
 
 ```typescript
@@ -566,6 +636,7 @@ import type {
 | `--end-line <num>` | Ending line for range |
 | `--deep` | Deep trace (squash merges) |
 | `--output <format>` | Output as json, llm, or human |
+| `--cache-only` | Return cached results only (no API calls) |
 | `--quiet` | Suppress formatting |
 | `npx @lumy-pack/line-lore health` | Check system health |
 | `npx @lumy-pack/line-lore graph pr <num>` | Show issues linked to a PR |

package/dist/cli.mjs

@@ -369,14 +369,22 @@ 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 findMergeCommitWithArgs(commitSha, ref, extraArgs, options) {
   try {
@@ -424,12 +432,16 @@ function extractPRFromMergeMessage(subject) {
   if (squashMatch) return parseInt(squashMatch[1], 10);
   const glMatch = /!(\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;
 var init_ancestry = __esm({
   "src/core/ancestry/ancestry.ts"() {
     "use strict";
     init_executor();
+    DEFAULT_ANCESTRY_TIMEOUT = 3e4;
   }
 });
 
@@ -549,10 +561,40 @@ 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
+  };
+}
+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
+  };
+}
+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;
   let mergeBasedPR = null;
   const mergeResult = await findMergeCommit(commitSha, options);
   if (mergeResult) {
@@ -575,31 +617,38 @@ async function lookupPR(commitSha, adapter, options) {
         };
       }
       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);
+      await cache.set(commitSha, toCachedPR(prInfo));
       return prInfo;
     }
   }
-  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 +656,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 +665,7 @@ var init_pr_lookup = __esm({
     init_patch_id2();
     cacheRegistry2 = /* @__PURE__ */ new Map();
     DEEP_SCAN_DEPTH = 2e3;
+    MAX_RECURSION_DEPTH = 2;
   }
 });
 
@@ -637,7 +687,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.0.5";
+    VERSION = "0.0.6";
   }
 });
 
@@ -962,6 +1012,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 +1059,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 4) 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
@@ -2161,7 +2243,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) {
   const nodes = [];
   const commitNode = {
     type: entry.isCosmetic ? "cosmetic_commit" : "original_commit",
@@ -2192,8 +2274,10 @@ 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
     });
     if (prInfo) {
       nodes.push({
@@ -2210,11 +2294,19 @@ 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) {
   const results = await Promise.allSettled(
     map8(
       analyzed,
-      (entry) => processEntry(entry, featureFlags, adapter, options, execOptions, repoId)
+      (entry) => processEntry(
+        entry,
+        featureFlags,
+        adapter,
+        options,
+        execOptions,
+        repoId,
+        skipPatchIdScan
+      )
     )
   );
   return results.flatMap((r) => r.status === "fulfilled" ? r.value : []);
@@ -2245,14 +2337,36 @@ async function trace(options) {
   );
   const operatingLevel = blameAuth.operatingLevel || platform.operatingLevel;
   const warnings = [...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: options.cwd });
+    if (result) cloneStatus = result;
+  } catch {
+  }
+  if (cloneStatus.partialClone) {
+    warnings.push(
+      "Partial clone detected. Patch-ID scan (Strategy 4) will be skipped to avoid blob downloads."
+    );
+  }
+  if (cloneStatus.shallow) {
+    warnings.push(
+      "Shallow repository detected. Ancestry-path results may be incomplete."
+    );
+  }
   const nodes = await buildTraceNodes(
     blameAuth.analyzed,
     featureFlags,
     platform.adapter,
     options,
     execOptions,
-    repoId
+    repoId,
+    cloneStatus.partialClone || void 0
   );
   return { nodes, operatingLevel, featureFlags, warnings };
 }
@@ -2459,7 +2573,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 +2584,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,6 +4,7 @@ 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>;

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

@@ -2,8 +2,14 @@ import type { RepoIdentity } from '../../cache/index.js';
 import type { GitExecOptions, PRInfo, PlatformAdapter } from '../../types/index.js';
 export interface PRLookupOptions extends GitExecOptions {
     noCache?: boolean;
+    /** Return cached results only — skip all fallback strategies */
+    cacheOnly?: boolean;
     deep?: boolean;
     repoId?: RepoIdentity;
+    /** Skip Strategy 4 (patch-id scan) — set automatically for partial clone environments */
+    skipPatchIdScan?: boolean;
 }
-export declare function lookupPR(commitSha: string, adapter: PlatformAdapter | null, options?: PRLookupOptions): Promise<PRInfo | null>;
+export declare function lookupPR(commitSha: string, adapter: PlatformAdapter | null, options?: PRLookupOptions, 
+/** @internal recursion depth tracker — do not set from external callers */
+_recursionDepth?: number): Promise<PRInfo | null>;
 export declare function resetPRCache(): void;

package/dist/git/health.d.ts

@@ -1,4 +1,7 @@
-import type { HealthReport } from '../types/index.js';
+import type { CloneStatus, HealthReport } from '../types/index.js';
+export declare function checkCloneStatus(options?: {
+    cwd?: string;
+}): Promise<CloneStatus>;
 export declare function checkGitHealth(options?: {
     cwd?: string;
 }): Promise<HealthReport>;

package/dist/git/index.d.ts

@@ -1,3 +1,3 @@
 export { gitExec, gitPipe, shellExec } from './executor.js';
 export { detectPlatform, getRemoteInfo, parseRemoteUrl } from './remote.js';
-export { checkGitHealth } from './health.js';
+export { checkCloneStatus, checkGitHealth } from './health.js';

package/dist/index.cjs

@@ -383,14 +383,22 @@ var init_executor = __esm({
 // src/core/ancestry/ancestry.ts
 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 findMergeCommitWithArgs(commitSha, ref, extraArgs, options) {
   try {
@@ -438,15 +446,18 @@ function extractPRFromMergeMessage(subject) {
   if (squashMatch) return parseInt(squashMatch[1], 10);
   const glMatch = /!(\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 import_common_utils9;
+var import_common_utils9, DEFAULT_ANCESTRY_TIMEOUT;
 var init_ancestry = __esm({
   "src/core/ancestry/ancestry.ts"() {
     "use strict";
     init_cjs_shims();
     import_common_utils9 = require("@winglet/common-utils");
     init_executor();
+    DEFAULT_ANCESTRY_TIMEOUT = 3e4;
   }
 });
 
@@ -569,10 +580,40 @@ 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
+  };
+}
+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
+  };
+}
+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;
   let mergeBasedPR = null;
   const mergeResult = await findMergeCommit(commitSha, options);
   if (mergeResult) {
@@ -595,31 +636,38 @@ async function lookupPR(commitSha, adapter, options) {
         };
       }
       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);
+      await cache.set(commitSha, toCachedPR(prInfo));
       return prInfo;
     }
   }
-  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;
@@ -627,7 +675,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";
@@ -637,6 +685,7 @@ var init_pr_lookup = __esm({
     init_patch_id2();
     cacheRegistry2 = /* @__PURE__ */ new Map();
     DEEP_SCAN_DEPTH = 2e3;
+    MAX_RECURSION_DEPTH = 2;
   }
 });
 
@@ -905,6 +954,27 @@ function isVersionAtLeast(version, 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";
@@ -931,7 +1001,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 4) 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/platform/index.ts
@@ -2155,7 +2236,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) {
   const nodes = [];
   const commitNode = {
     type: entry.isCosmetic ? "cosmetic_commit" : "original_commit",
@@ -2186,8 +2267,10 @@ 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
     });
     if (prInfo) {
       nodes.push({
@@ -2204,11 +2287,19 @@ 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) {
   const results = await Promise.allSettled(
     (0, import_common_utils11.map)(
       analyzed,
-      (entry) => processEntry(entry, featureFlags, adapter, options, execOptions, repoId)
+      (entry) => processEntry(
+        entry,
+        featureFlags,
+        adapter,
+        options,
+        execOptions,
+        repoId,
+        skipPatchIdScan
+      )
     )
   );
   return results.flatMap((r) => r.status === "fulfilled" ? r.value : []);
@@ -2239,14 +2330,36 @@ async function trace(options) {
   );
   const operatingLevel = blameAuth.operatingLevel || platform.operatingLevel;
   const warnings = [...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: options.cwd });
+    if (result) cloneStatus = result;
+  } catch {
+  }
+  if (cloneStatus.partialClone) {
+    warnings.push(
+      "Partial clone detected. Patch-ID scan (Strategy 4) will be skipped to avoid blob downloads."
+    );
+  }
+  if (cloneStatus.shallow) {
+    warnings.push(
+      "Shallow repository detected. Ancestry-path results may be incomplete."
+    );
+  }
   const nodes = await buildTraceNodes(
     blameAuth.analyzed,
     featureFlags,
     platform.adapter,
     options,
     execOptions,
-    repoId
+    repoId,
+    cloneStatus.partialClone || void 0
   );
   return { nodes, operatingLevel, featureFlags, warnings };
 }

package/dist/index.mjs

@@ -370,14 +370,22 @@ 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 findMergeCommitWithArgs(commitSha, ref, extraArgs, options) {
   try {
@@ -425,13 +433,17 @@ function extractPRFromMergeMessage(subject) {
   if (squashMatch) return parseInt(squashMatch[1], 10);
   const glMatch = /!(\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;
 var init_ancestry = __esm({
   "src/core/ancestry/ancestry.ts"() {
     "use strict";
     init_esm_shims();
     init_executor();
+    DEFAULT_ANCESTRY_TIMEOUT = 3e4;
   }
 });
 
@@ -554,10 +566,40 @@ 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
+  };
+}
+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
+  };
+}
+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;
   let mergeBasedPR = null;
   const mergeResult = await findMergeCommit(commitSha, options);
   if (mergeResult) {
@@ -580,31 +622,38 @@ async function lookupPR(commitSha, adapter, options) {
         };
       }
       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);
+      await cache.set(commitSha, toCachedPR(prInfo));
       return prInfo;
     }
   }
-  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;
@@ -612,7 +661,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";
@@ -622,6 +671,7 @@ var init_pr_lookup = __esm({
     init_patch_id2();
     cacheRegistry2 = /* @__PURE__ */ new Map();
     DEEP_SCAN_DEPTH = 2e3;
+    MAX_RECURSION_DEPTH = 2;
   }
 });
 
@@ -879,6 +929,27 @@ function isVersionAtLeast(version, 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";
@@ -905,7 +976,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 4) 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/platform/index.ts
@@ -2129,7 +2211,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) {
   const nodes = [];
   const commitNode = {
     type: entry.isCosmetic ? "cosmetic_commit" : "original_commit",
@@ -2160,8 +2242,10 @@ 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
     });
     if (prInfo) {
       nodes.push({
@@ -2178,11 +2262,19 @@ 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) {
   const results = await Promise.allSettled(
     map8(
       analyzed,
-      (entry) => processEntry(entry, featureFlags, adapter, options, execOptions, repoId)
+      (entry) => processEntry(
+        entry,
+        featureFlags,
+        adapter,
+        options,
+        execOptions,
+        repoId,
+        skipPatchIdScan
+      )
     )
   );
   return results.flatMap((r) => r.status === "fulfilled" ? r.value : []);
@@ -2213,14 +2305,36 @@ async function trace(options) {
   );
   const operatingLevel = blameAuth.operatingLevel || platform.operatingLevel;
   const warnings = [...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: options.cwd });
+    if (result) cloneStatus = result;
+  } catch {
+  }
+  if (cloneStatus.partialClone) {
+    warnings.push(
+      "Partial clone detected. Patch-ID scan (Strategy 4) will be skipped to avoid blob downloads."
+    );
+  }
+  if (cloneStatus.shallow) {
+    warnings.push(
+      "Shallow repository detected. Ancestry-path results may be incomplete."
+    );
+  }
   const nodes = await buildTraceNodes(
     blameAuth.analyzed,
     featureFlags,
     platform.adapter,
     options,
     execOptions,
-    repoId
+    repoId,
+    cloneStatus.partialClone || void 0
   );
   return { nodes, operatingLevel, featureFlags, warnings };
 }

package/dist/types/cache.d.ts

@@ -3,3 +3,14 @@ export interface CacheEntry<T> {
     value: T;
     createdAt: number;
 }
+/** Disk-serialized PRInfo — date fields stored as numeric timestamps (ms) */
+export interface CachedPRInfo {
+    number: number;
+    title: string;
+    author: string;
+    url: string;
+    mergeCommit: string;
+    baseBranch: string;
+    /** Unix timestamp in milliseconds, NOT ISO 8601 string */
+    mergedAt?: number;
+}

package/dist/types/git.d.ts

@@ -15,9 +15,15 @@ export interface RemoteInfo {
     host: string;
     platform: PlatformType | 'unknown';
 }
+export interface CloneStatus {
+    partialClone: boolean;
+    shallow: boolean;
+}
 export interface HealthReport {
     commitGraph: boolean;
     bloomFilter: boolean;
     gitVersion: string;
     hints: string[];
+    partialClone: boolean;
+    shallow: boolean;
 }

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export type { SymbolKind, SymbolInfo, ContentHash, ChangeType, ComparisonResult, AstTraceResult, } from './ast.js';
 export type { BlameResult, CommitInfo } from './blame.js';
-export type { CacheEntry } from './cache.js';
-export type { GitExecResult, GitExecOptions, RemoteInfo, HealthReport, } from './git.js';
+export type { CacheEntry, CachedPRInfo } from './cache.js';
+export type { GitExecResult, GitExecOptions, RemoteInfo, HealthReport, CloneStatus, } from './git.js';
 export type { GraphOptions, GraphResult } from './graph.js';
 export type { NormalizedResponse } from './output.js';
 export type { TraceNodeType, TrackingMethod, Confidence, TraceNode, OperatingLevel, FeatureFlags, } from './pipeline.js';

package/dist/types/trace.d.ts

@@ -29,4 +29,6 @@ export interface TraceOptions {
     noAst?: boolean;
     /** Disable cache for this invocation */
     noCache?: boolean;
+    /** Return cached results only — skip API calls, ancestry traversal, and patch-id scan */
+    cacheOnly?: boolean;
 }

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * Current package version from package.json
  * Automatically synchronized during build process
  */
-export declare const VERSION = "0.0.5";
+export declare const VERSION = "0.0.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumy-pack/line-lore",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "CLI tool for tracing code lines to their originating Pull Requests via git blame",
   "keywords": [
     "cli",