@dependfix/engine 0.3.0 → 0.5.0

package/dist/chunks/index.d.mts

@@ -0,0 +1,262 @@
+import { Octokit } from "@octokit/rest";
+//#region src/auth/auth-provider.d.ts
+/**
+ * GitHub 认证抽象层。
+ *
+ * 支持 PAT（classic / fine-grained）与 GitHub App installation token 两种认证路径。
+ * 调用方通过 `getOctokit()` 获取已认证的 Octokit 实例；通过 `getGitCredential()`
+ * 获取推送/clone 用的 Git 凭据；通过 `getCommitAuthor()` 获取 commit author 信息。
+ *
+ * `authProvider` 字段用于审计与调试（区分 PAT vs App 路径）。
+ *
+ * @example
+ * ```typescript
+ * // 推荐：从 fromPat / fromApp 工厂构造
+ * const auth = fromPat('ghp_xxxx')
+ * const octokit = auth.getOctokit()
+ *
+ * // git push 凭据
+ * const { username, token } = auth.getGitCredential()
+ *
+ * // commit author（PAT 路径固定；App 路径动态）
+ * const { name, email } = auth.getCommitAuthor()
+ * ```
+ */
+interface AuthProvider {
+  /** 获取已认证的 Octokit 实例 */
+  getOctokit(): Octokit;
+  /** 获取推送 / clone 用的 Git 凭据（用户名 + token） */
+  getGitCredential(): {
+    username: string;
+    token: string;
+  };
+  /**
+   * 获取 commit author 信息。
+   *
+   * - PAT 路径：固定返回 `{ name: 'dependfix[bot]', email: 'dependfix[bot]@users.noreply.github.com' }`（保持现有行为零变化）
+   * - GitHub App 路径：动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`（GitHub App 协议要求）
+   */
+  getCommitAuthor(): {
+    name: string;
+    email: string;
+  };
+  /** 认证路径标识（用于审计 + 调试） */
+  readonly authProvider: 'pat' | 'github-app';
+}
+/** 工厂函数统一选项（与 OctokitClientOptions.retry 字段对齐） */
+interface AuthProviderOptions {
+  /** API 限流 / 次要限流指数退避重试策略。默认 maxRetries=3。 */
+  retry?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxBackoffMs?: number;
+  };
+}
+/** PAT 工厂参数（仅 token；retry 在 options 注入） */
+type FromPatParams = string;
+/** GitHub App 工厂参数 */
+interface FromAppParams {
+  /** GitHub App ID */
+  appId: string;
+  /** PEM 格式私钥 */
+  privateKey: string;
+  /** Installation ID */
+  installationId: string;
+  /** Bot 用户名（用于 commit author 动态生成） */
+  botLogin?: string;
+}
+/**
+ * PAT 路径固定 commit author（保持现有行为零变化）。
+ *
+ * 注：现有 PAT 路径硬编码 `dependfix[bot]@users.noreply.github.com`，虽非真实 bot 身份（字符串约定），
+ * 但保持行为不变以确保 PAT 用户无感升级。已知缺陷由后续阶段修复。
+ */
+declare const PAT_COMMIT_AUTHOR: {
+  readonly name: "dependfix[bot]";
+  readonly email: "dependfix[bot]@users.noreply.github.com";
+};
+/** PAT 路径固定 Git 用户名（用于 git push 时的 Basic Auth） */
+declare const PAT_GIT_USERNAME = "x-access-token";
+//#endregion
+//#region src/auth/pat-provider.d.ts
+/**
+ * PAT 工厂函数。委托给 `PatAuthProvider` 类。
+ *
+ * 保留 `fromPat` 命名习惯便于与 `fromApp` 对齐（统一工厂语义）。
+ *
+ * @example
+ * ```typescript
+ * const auth = fromPat('ghp_xxxx')
+ * const octokit = auth.getOctokit()
+ * const { username, token } = auth.getGitCredential()
+ * ```
+ */
+declare function fromPat(token: FromPatParams, options?: AuthProviderOptions): AuthProvider;
+/**
+ * PAT 认证路径实现。
+ *
+ * `getOctokit()` 委托给 [`createGitHubClient`](../github/client.ts) 以复用现有 retry policy 与限流重试实现；
+ * Octokit 实例缓存以避免重复构造（每次 `new Octokit()` + `hook.wrap()` 都有开销）。
+ *
+ * 行为与原 `createGitHubClient({ token })` 等价：
+ * - `getOctokit()` 返回通过 PAT 认证的 Octokit 实例（含限流重试 hook）
+ * - `getGitCredential()` 返回推送用的 Basic Auth（username = `'x-access-token'`）
+ * - `getCommitAuthor()` 返回固定 `dependfix[bot]`（PAT 路径用户行为零变化）
+ *
+ * @example
+ * ```typescript
+ * const auth = new PatAuthProvider('ghp_xxxx', { retry: { maxRetries: 3 } })
+ * const octokit = auth.getOctokit()
+ * ```
+ */
+declare class PatAuthProvider implements AuthProvider {
+  readonly authProvider: "pat";
+  private readonly token;
+  private readonly retry?;
+  private cachedOctokit;
+  constructor(token: FromPatParams, options?: AuthProviderOptions);
+  /**
+   * 获取已认证的 Octokit 实例（首次调用构造并缓存）。
+   */
+  getOctokit(): Octokit;
+  /** 获取推送 / clone 用的 Git 凭据（username = `'x-access-token'`，token = PAT） */
+  getGitCredential(): {
+    username: string;
+    token: string;
+  };
+  /** 获取 commit author（PAT 路径固定 `dependfix[bot]`） */
+  getCommitAuthor(): {
+    name: string;
+    email: string;
+  };
+}
+//#endregion
+//#region src/auth/app-provider.d.ts
+/**
+ * GitHub App 工厂函数。
+ *
+ * 委托给 [`AppAuthProvider`] 类。
+ *
+ * @example
+ * ```typescript
+ * const auth = fromApp({
+ *     appId: '123456',
+ *     privateKey: '-----BEGIN RSA PRIVATE KEY-----\n...',
+ *     installationId: '7890123',
+ *     botLogin: 'dependfix-bot[bot]',
+ * })
+ * const octokit = auth.getOctokit()
+ * ```
+ */
+declare function fromApp(params: FromAppParams, options?: AuthProviderOptions): AuthProvider;
+/**
+ * GitHub App 认证路径实现。
+ *
+ * 使用 [`@octokit/auth-app`](https://github.com/octokit/auth-app.js) 提供：
+ * - JWT signing（App 身份认证）
+ * - `getInstallationOctokit`（installation token 获取；库内置 59 分钟 LRU TTL 缓存）
+ * - 自动 installation token 轮换
+ *
+ * 注意：
+ * - `getGitCredential()` 返回的 `token` 字段为占位符（installation token 不能直接从 AppAuthProvider 获取；
+ *   由 [`@octokit/auth-app`](https://github.com/octokit/auth-app.js) 内部管理）；调用方应通过 `getOctokit()`
+ *   拿到的 Octokit 实例进行 API 调用
+ * - `getCommitAuthor()` 按 GitHub App 协议动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`
+ * - Octokit 实例缓存以避免重复构造
+ *
+ * @see [C22 PAT 无感升级评估 §4.2 AuthProvider 接口设计](../../../../docs/design/governance/c22-pat-backward-compat.md)
+ */
+declare class AppAuthProvider implements AuthProvider {
+  readonly authProvider: "github-app";
+  private readonly params;
+  private readonly _options?;
+  private cachedOctokit;
+  constructor(params: FromAppParams, options?: AuthProviderOptions);
+  /**
+   * 获取已认证的 Octokit 实例。
+   *
+   * 首次调用时构造并缓存；后续调用复用同一实例。
+   * installation token 由 `@octokit/auth-app` 内部管理（59 分钟 LRU TTL 缓存）。
+   *
+   * **构造方式**：使用 `authStrategy: createAppAuth` + `auth: {appId, privateKey, installationId}`
+   * 双字段组合（`@octokit/auth-app` v8.x README 标准用法），**而非** `auth: createAppAuth(...)`
+   * 单字段调用——后者被 `@octokit/core` 视作字符串 token 路径抛 `Token passed to createTokenAuth is not a string`，
+   * 或被 `authStrategy` 字段调用后命中 `auth(state, authOptions)` 的 `default` 分支抛 `Invalid auth type: undefined`
+   * （todo.md §M18.4 e2e 验证 + audit quick depth Reject 后补修发现）。
+   *
+   * @see [@octokit/auth-app README §installation authentication](https://github.com/octokit/auth-app.js#installation-authentication)
+   */
+  getOctokit(): Octokit;
+  /**
+   * 获取推送 / clone 用的 Git 凭据。
+   *
+   * 注意：installation token 由 `@octokit/auth-app` 内部管理，**不**能从 AppAuthProvider 直接获取；
+   * 本方法返回的 `token` 字段为占位符（`'installation-token-managed-by-octokit-auth-app'`）。
+   * 调用方应通过 `getOctokit()` 拿到的 Octokit 实例进行 API 调用（含 git push / clone 等写操作）。
+   */
+  getGitCredential(): {
+    username: string;
+    token: string;
+  };
+  /**
+   * 获取 commit author。
+   *
+   * 按 GitHub App 协议动态生成 `{app_id}+{bot_login}[bot]@users.noreply.github.com`：
+   * - `name`：`{app_id}[bot]`（GitHub 自动识别 bot 身份）
+   * - `email`：`{app_id}+{bot_login}[bot]@users.noreply.github.com`（GitHub noreply email 格式）
+   *
+   * 当 `params.botLogin` 未提供时，使用 `dependfix[bot]` 作为 fallback（保持与 PAT 路径一致的格式）；
+   * 但建议调用方显式提供 `botLogin` 以确保 commit author 真实 bot 身份归属。
+   */
+  getCommitAuthor(): {
+    name: string;
+    email: string;
+  };
+}
+//#endregion
+//#region src/auth/installation-token-cache.d.ts
+/**
+ * Installation token 缓存层（**M18.1 commit 4 实施**）。
+ *
+ * 当前实现：**依赖 [@octokit/auth-app](https://github.com/octokit/auth-app.js) 内置缓存**
+ * （59 分钟 LRU TTL；GitHub token 有效期 60 分钟 - 1 分钟缓冲）。
+ *
+ * 本类作为未来扩展点：
+ * - 缓存统计（命中率 / 大小 / 清理 API）
+ * - 失败重试 + 报警（M18.2 集成时实施）
+ * - 多 worker 共享（Redis-backed；超出 M18.1 范围）
+ *
+ * 注意：
+ * - `getOrRefresh` 当前委托给 `createAppAuthentication` + `getInstallationOctokit`
+ * - 当 [@octokit/auth-app](https://github.com/octokit/auth-app.js) 内部缓存命中时不会触发 API 调用
+ * - 缓存未命中时自动调用 `POST /app/installations/{installation_id}/access_tokens` 获取新 token
+ *
+ * @see [C22 PAT 无感升级评估 §4.7 commit 拆分纪律](../../../../docs/design/governance/c22-pat-backward-compat.md)
+ */
+declare class InstallationTokenCache {
+  private readonly params;
+  private readonly ttlMs;
+  constructor(params: FromAppParams, options?: {
+    ttlMs?: number;
+    refreshThresholdMs?: number;
+  });
+  /**
+   * 获取或刷新 installation token。
+   *
+   * 当前为占位实现：直接返回 `'installation-token-managed-by-octokit-auth-app'` 占位字符串。
+   * 调用方应使用 `fromApp(params).getOctokit()` 获取真实 Octokit 实例（由 `@octokit/auth-app`
+   * 自动管理 installation token 缓存）。
+   *
+   * @throws 永不抛错（占位实现）
+   */
+  getOrRefresh(): Promise<string>;
+  /** 清理过期缓存项（占位实现） */
+  clear(): void;
+  /** 获取缓存 TTL 配置（毫秒） */
+  getTtlMs(): number;
+  /** 获取 cache key（基于 installationId） */
+  static getCacheKey(params: FromAppParams): string;
+}
+//#endregion
+export { fromPat as a, FromAppParams as c, PAT_GIT_USERNAME as d, PatAuthProvider as i, FromPatParams as l, AppAuthProvider as n, AuthProvider as o, fromApp as r, AuthProviderOptions as s, InstallationTokenCache as t, PAT_COMMIT_AUTHOR as u };
+//# sourceMappingURL=index.d.mts.map