@lumy-pack/line-lore 0.0.5 → 0.0.7

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 |