@lumy-pack/line-lore 0.0.1

package/dist/output/formats.d.ts

@@ -0,0 +1,5 @@
+import type { TraceFullResult } from '../core/core.js';
+export declare function formatHuman(result: TraceFullResult): string;
+export declare function formatJson(result: TraceFullResult): string;
+export declare function formatLlm(result: TraceFullResult): string;
+export declare function formatQuiet(result: TraceFullResult): string;

package/dist/output/index.d.ts

@@ -0,0 +1,2 @@
+export { formatHuman, formatJson, formatLlm, formatQuiet } from './formats.js';
+export { createErrorResponse, createPartialResponse, createSuccessResponse, } from './normalizer.js';

package/dist/output/normalizer.d.ts

@@ -0,0 +1,11 @@
+import type { NormalizedResponse, OperatingLevel } from '../types/index.js';
+export declare function createSuccessResponse<T>(command: string, data: T, operatingLevel: OperatingLevel, options?: {
+    warnings?: string[];
+    cacheHit?: boolean;
+}): NormalizedResponse<T>;
+export declare function createPartialResponse<T>(command: string, partialData: Partial<T>, operatingLevel: OperatingLevel, warnings: string[]): NormalizedResponse<T>;
+export declare function createErrorResponse(command: string, code: string, message: string, operatingLevel: OperatingLevel, options?: {
+    stage?: number;
+    recoverable?: boolean;
+    suggestion?: string;
+}): NormalizedResponse<never>;

package/dist/platform/github/github-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { AuthStatus, IssueInfo, PRInfo, PlatformAdapter, RateLimitInfo } from '../../types/index.js';
+import { RequestScheduler } from '../scheduler/index.js';
+export declare class GitHubAdapter implements PlatformAdapter {
+    readonly platform: PlatformAdapter['platform'];
+    private readonly scheduler;
+    private readonly hostname;
+    constructor(options?: {
+        hostname?: string;
+        scheduler?: RequestScheduler;
+    });
+    checkAuth(): Promise<AuthStatus>;
+    getPRForCommit(sha: string): Promise<PRInfo | null>;
+    getPRCommits(prNumber: number): Promise<string[]>;
+    getLinkedIssues(prNumber: number): Promise<IssueInfo[]>;
+    getLinkedPRs(issueNumber: number): Promise<PRInfo[]>;
+    getRateLimit(): Promise<RateLimitInfo>;
+}

package/dist/platform/github/github-enterprise-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { RequestScheduler } from '../scheduler/index.js';
+import { GitHubAdapter } from './github-adapter.js';
+export declare class GitHubEnterpriseAdapter extends GitHubAdapter {
+    readonly platform: "github-enterprise";
+    constructor(hostname: string, options?: {
+        scheduler?: RequestScheduler;
+    });
+}

package/dist/platform/github/index.d.ts

@@ -0,0 +1,2 @@
+export { GitHubAdapter } from './github-adapter.js';
+export { GitHubEnterpriseAdapter } from './github-enterprise-adapter.js';

package/dist/platform/gitlab/gitlab-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { AuthStatus, IssueInfo, PRInfo, PlatformAdapter, RateLimitInfo } from '../../types/index.js';
+import { RequestScheduler } from '../scheduler/index.js';
+export declare class GitLabAdapter implements PlatformAdapter {
+    readonly platform: PlatformAdapter['platform'];
+    private readonly scheduler;
+    private readonly hostname;
+    constructor(options?: {
+        hostname?: string;
+        scheduler?: RequestScheduler;
+    });
+    checkAuth(): Promise<AuthStatus>;
+    getPRForCommit(sha: string): Promise<PRInfo | null>;
+    getPRCommits(prNumber: number): Promise<string[]>;
+    getLinkedIssues(prNumber: number): Promise<IssueInfo[]>;
+    getLinkedPRs(issueNumber: number): Promise<PRInfo[]>;
+    getRateLimit(): Promise<RateLimitInfo>;
+}

package/dist/platform/gitlab/gitlab-self-hosted-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { RequestScheduler } from '../scheduler/index.js';
+import { GitLabAdapter } from './gitlab-adapter.js';
+export declare class GitLabSelfHostedAdapter extends GitLabAdapter {
+    readonly platform: "gitlab-self-hosted";
+    constructor(hostname: string, options?: {
+        scheduler?: RequestScheduler;
+    });
+}

package/dist/platform/gitlab/index.d.ts

@@ -0,0 +1,2 @@
+export { GitLabAdapter } from './gitlab-adapter.js';
+export { GitLabSelfHostedAdapter } from './gitlab-self-hosted-adapter.js';

package/dist/platform/index.d.ts

@@ -0,0 +1,6 @@
+export { createAdapter, detectPlatformAdapter } from './platform.js';
+export { GitHubAdapter } from './github/index.js';
+export { GitHubEnterpriseAdapter } from './github/index.js';
+export { GitLabAdapter } from './gitlab/index.js';
+export { GitLabSelfHostedAdapter } from './gitlab/index.js';
+export { RequestScheduler } from './scheduler/index.js';

package/dist/platform/platform.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformAdapter, RemoteInfo } from '../types/index.js';
+export declare function detectPlatformAdapter(options?: {
+    cwd?: string;
+    remoteName?: string;
+}): Promise<{
+    adapter: PlatformAdapter;
+    remote: RemoteInfo;
+}>;
+export declare function createAdapter(remote: RemoteInfo): PlatformAdapter;

package/dist/platform/scheduler/index.d.ts

@@ -0,0 +1,2 @@
+export { RequestScheduler } from './request-scheduler.js';
+export type { SchedulerOptions } from './request-scheduler.js';

package/dist/platform/scheduler/request-scheduler.d.ts

@@ -0,0 +1,17 @@
+import type { RateLimitInfo } from '../../types/index.js';
+export interface SchedulerOptions {
+    rateLimitThreshold?: number;
+}
+export declare class RequestScheduler {
+    private rateLimitInfo;
+    private readonly threshold;
+    private etagCache;
+    private responseCache;
+    constructor(options?: SchedulerOptions);
+    updateRateLimit(info: RateLimitInfo): void;
+    isRateLimited(): boolean;
+    getRateLimit(): RateLimitInfo | null;
+    setEtag(url: string, etag: string, response: string): void;
+    getEtag(url: string): string | null;
+    getCachedResponse(url: string): string | null;
+}

package/dist/types/ast.d.ts

@@ -0,0 +1,28 @@
+import type { Confidence } from './pipeline.js';
+export type SymbolKind = 'function' | 'method' | 'class' | 'arrow_function';
+export interface SymbolInfo {
+    name: string;
+    kind: SymbolKind;
+    startLine: number;
+    endLine: number;
+    bodyText: string;
+}
+export interface ContentHash {
+    exact: string;
+    structural: string;
+}
+export type ChangeType = 'rename' | 'move' | 'extract' | 'identical' | 'new' | 'modified';
+export interface ComparisonResult {
+    change: ChangeType;
+    fromName?: string;
+    toName?: string;
+    fromFile?: string;
+    confidence: Confidence;
+}
+export interface AstTraceResult {
+    originSha: string;
+    originSymbol: SymbolInfo;
+    trackingMethod: 'ast-signature';
+    confidence: Confidence;
+    changes: ComparisonResult[];
+}

package/dist/types/blame.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Result of parsing `git blame --porcelain` output for a specific line.
+ */
+export interface BlameResult {
+    /** Full 40-character commit hash */
+    commitHash: string;
+    /** Author name */
+    author: string;
+    /** Author email */
+    authorEmail: string;
+    /** Commit timestamp (ISO 8601) */
+    date: string;
+    /** The actual content of the blamed line */
+    lineContent: string;
+    /** Original filename if the line was moved/renamed */
+    originalFile?: string;
+    /** Original line number before any moves/renames */
+    originalLine?: number;
+}
+/**
+ * Basic commit information from git log.
+ */
+export interface CommitInfo {
+    /** Full 40-character commit hash */
+    hash: string;
+    /** Short (7-character) commit hash */
+    shortHash: string;
+    /** Commit subject line */
+    subject: string;
+    /** Commit author name */
+    author: string;
+    /** Commit timestamp (ISO 8601) */
+    date: string;
+}

package/dist/types/cache.d.ts

@@ -0,0 +1,5 @@
+export interface CacheEntry<T> {
+    key: string;
+    value: T;
+    createdAt: number;
+}

package/dist/types/git.d.ts

@@ -0,0 +1,23 @@
+import type { PlatformType } from './platform.js';
+export interface GitExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface GitExecOptions {
+    cwd?: string;
+    timeout?: number;
+    allowExitCodes?: number[];
+}
+export interface RemoteInfo {
+    owner: string;
+    repo: string;
+    host: string;
+    platform: PlatformType | 'unknown';
+}
+export interface HealthReport {
+    commitGraph: boolean;
+    bloomFilter: boolean;
+    gitVersion: string;
+    hints: string[];
+}

package/dist/types/graph.d.ts

@@ -0,0 +1,15 @@
+import type { TraceNode } from './pipeline.js';
+export interface GraphOptions {
+    type: 'pr' | 'issue';
+    number: number;
+    depth?: number;
+    json?: boolean;
+}
+export interface GraphResult {
+    nodes: TraceNode[];
+    edges: Array<{
+        from: string;
+        to: string;
+        relation: string;
+    }>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+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 { GraphOptions, GraphResult } from './graph.js';
+export type { NormalizedResponse } from './output.js';
+export type { TraceNodeType, TrackingMethod, Confidence, TraceNode, OperatingLevel, FeatureFlags, } from './pipeline.js';
+export type { PlatformType, AuthStatus, PRInfo, IssueInfo, RateLimitInfo, PlatformAdapter, } from './platform.js';
+export type { CosmeticReason, BlameStageResult, AstDiffStageResult, } from './stage.js';
+export type { TraceResult, TraceOptions } from './trace.js';
+export type { LineRange } from './util.js';

package/dist/types/output.d.ts

@@ -0,0 +1,24 @@
+import type { OperatingLevel } from './pipeline.js';
+export interface NormalizedResponse<T> {
+    tool: 'line-lore';
+    command: string;
+    version: string;
+    timestamp: string;
+    status: 'success' | 'partial' | 'error';
+    operatingLevel: OperatingLevel;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        stage?: number;
+        recoverable: boolean;
+        suggestion?: string;
+    };
+    partialData?: Partial<T>;
+    warnings?: string[];
+    hints?: {
+        canRetryWithFlags?: string[];
+        relatedCommands?: string[];
+        cacheHit?: boolean;
+    };
+}

package/dist/types/pipeline.d.ts

@@ -0,0 +1,28 @@
+export type TraceNodeType = 'original_commit' | 'cosmetic_commit' | 'merge_commit' | 'rebased_commit' | 'pull_request' | 'issue';
+export type TrackingMethod = 'blame' | 'blame-CMw' | 'ast-signature' | 'ancestry-path' | 'patch-id' | 'api' | 'message-parse' | 'issue-link';
+export type Confidence = 'exact' | 'structural' | 'heuristic';
+export interface TraceNode {
+    type: TraceNodeType;
+    sha?: string;
+    trackingMethod: TrackingMethod;
+    confidence: Confidence;
+    prNumber?: number;
+    prUrl?: string;
+    prTitle?: string;
+    patchId?: string;
+    note?: string;
+    mergedAt?: string;
+    issueNumber?: number;
+    issueUrl?: string;
+    issueTitle?: string;
+    issueState?: 'open' | 'closed';
+    issueLabels?: string[];
+}
+export type OperatingLevel = 0 | 1 | 2;
+export interface FeatureFlags {
+    astDiff: boolean;
+    deepTrace: boolean;
+    commitGraph: boolean;
+    issueGraph: boolean;
+    graphql: boolean;
+}

package/dist/types/platform.d.ts

@@ -0,0 +1,44 @@
+export type PlatformType = 'github' | 'github-enterprise' | 'gitlab' | 'gitlab-self-hosted';
+export interface AuthStatus {
+    authenticated: boolean;
+    username?: string;
+    scopes?: string[];
+    hostname?: string;
+}
+export interface PRInfo {
+    /** PR number (e.g., 123) */
+    number: number;
+    /** PR title */
+    title: string;
+    /** PR author username */
+    author: string;
+    /** Full URL to the PR */
+    url: string;
+    /** Merge commit hash */
+    mergeCommit: string;
+    /** Base branch the PR was merged into */
+    baseBranch: string;
+    /** Timestamp when the PR was merged (ISO 8601) */
+    mergedAt?: string;
+}
+export interface IssueInfo {
+    number: number;
+    title: string;
+    url: string;
+    state: 'open' | 'closed';
+    labels: string[];
+}
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetAt: string;
+}
+export interface PlatformAdapter {
+    readonly platform: PlatformType;
+    checkAuth(): Promise<AuthStatus>;
+    getPRForCommit(sha: string): Promise<PRInfo | null>;
+    getPRCommits(prNumber: number): Promise<string[]>;
+    getLinkedIssues(prNumber: number): Promise<IssueInfo[]>;
+    getLinkedPRs(issueNumber: number): Promise<PRInfo[]>;
+    getRateLimit(): Promise<RateLimitInfo>;
+}

package/dist/types/stage.d.ts

@@ -0,0 +1,14 @@
+import type { ChangeType } from './ast.js';
+import type { BlameResult } from './blame.js';
+import type { Confidence } from './pipeline.js';
+export type CosmeticReason = 'whitespace' | 'import-order' | 'formatting';
+export interface BlameStageResult {
+    blame: BlameResult;
+    isCosmetic: boolean;
+    cosmeticReason?: CosmeticReason;
+}
+export interface AstDiffStageResult {
+    originalSha: string;
+    confidence: Confidence;
+    changeType: ChangeType;
+}

package/dist/types/trace.d.ts

@@ -0,0 +1,38 @@
+import type { BlameResult } from './blame.js';
+import type { PRInfo } from './platform.js';
+/**
+ * Combined result of tracing a line back to its PR.
+ */
+export interface TraceResult {
+    /** Blame information for the target line */
+    blame: BlameResult;
+    /** PR information if found, null if commit is not from a PR */
+    pr: PRInfo | null;
+}
+/**
+ * Options for the trace operation.
+ */
+export interface TraceOptions {
+    /** Path to the file to trace */
+    file: string;
+    /** Starting line number (1-indexed) */
+    line: number;
+    /** Ending line number for range queries (inclusive) */
+    endLine?: number;
+    /** Git remote name to use for PR lookups (default: 'origin') */
+    remote?: string;
+    /** Output in JSON format */
+    json?: boolean;
+    /** Enable deep trace (squash PR recursive exploration) */
+    deep?: boolean;
+    /** Issue graph traversal depth (0=PR only, 1=issues, 2+=multi-hop) */
+    graphDepth?: number;
+    /** Disable AST diff analysis */
+    noAst?: boolean;
+    /** Disable cache */
+    noCache?: boolean;
+    /** Output format */
+    output?: 'human' | 'json' | 'llm';
+    /** Suppress output (return PR number only) */
+    quiet?: boolean;
+}

package/dist/types/util.d.ts

@@ -0,0 +1,4 @@
+export interface LineRange {
+    start: number;
+    end: number;
+}

package/dist/utils/command-registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Central command registry for line-lore CLI.
+ * Single source of truth for command metadata, used by --describe and --help.
+ */
+export interface CommandOption {
+    flag: string;
+    description: string;
+    type?: 'boolean' | 'string' | 'number';
+    default?: string;
+}
+export interface CommandArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface CommandInfo {
+    name: string;
+    description: string;
+    usage?: string;
+    arguments?: CommandArgument[];
+    options?: CommandOption[];
+    subcommands?: CommandInfo[];
+    examples?: string[];
+}
+export declare const TRACE_COMMAND: CommandInfo;
+export declare const HEALTH_COMMAND: CommandInfo;
+export declare const CACHE_COMMAND: CommandInfo;
+export declare const GRAPH_COMMAND: CommandInfo;
+export declare const ALL_COMMANDS: CommandInfo[];

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export { parseLineRange } from './line-range.js';

package/dist/utils/line-range.d.ts

@@ -0,0 +1,2 @@
+import type { LineRange } from '../types/index.js';
+export declare function parseLineRange(input: string): LineRange;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.0.1";

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@lumy-pack/line-lore",
+  "version": "0.0.1",
+  "description": "CLI tool for tracing code lines to their originating Pull Requests via git blame",
+  "keywords": [
+    "cli",
+    "git",
+    "blame",
+    "pr",
+    "pull-request",
+    "trace",
+    "line-lore"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vincent-kk/lumy-pack.git",
+    "directory": "packages/line-lore"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Vincent K. Kelvin",
+    "email": "lunox273@gmail.com"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "bin": "dist/cli.mjs",
+  "files": [
+    "dist",
+    "!dist/tsconfig.tsbuildinfo",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/inject-version.js && tsup && yarn build:types",
+    "build:types": "tsc -p ./tsconfig.declarations.json",
+    "dev": "node scripts/inject-version.js && tsx src/cli.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\"",
+    "publish:npm": "yarn npm publish --access public",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "version:major": "yarn version major",
+    "version:minor": "yarn version minor",
+    "version:patch": "yarn version patch"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "execa": "^9.5.0",
+    "ink": "^5.0.0",
+    "ink-spinner": "^5.0.0",
+    "picocolors": "^1.1.1",
+    "react": "^18.0.0"
+  },
+  "devDependencies": {
+    "@lumy-pack/shared": "0.0.1",
+    "@types/node": "^20.11.0",
+    "@types/react": "^18.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "ink-testing-library": "^4.0.0"
+  }
+}