gennady 0.6.1 → 0.7.0

package/dist/services/vcs-client/abstract/vcs-client-merge-requests.d.ts

@@ -1,45 +1,62 @@
+import type { VcsMergeRequestChanges, VcsMergeRequestChangesQuery } from '../entities/vcs-merge-request-changes.type.js';
 /**
- * @purpose Параметры запроса списка Merge Requests: проект, ветка, состояние, пагинация.
+ * @purpose Parameters for querying Merge Request list: project, branch, state, pagination.
  * @consumer VcsClientMergeRequests
  */
 export type VcsMergeRequestsQuery = {
+    /** @purpose GitLab project path or ID */
     project: string;
+    /** @purpose Source branch name to filter MRs */
     sourceBranch?: string;
+    /** @purpose MR state filter: opened, closed, merged, etc. */
     state?: string;
+    /** @purpose Page size | @invariant Default: GitLab default when absent */
     perPage?: number;
+    /** @purpose Page number starting from 1 */
     page?: number;
 };
 /**
- * @purpose Параметры запроса Merge Request по IID.
+ * @purpose Parameters for querying a Merge Request by IID.
  * @consumer VcsClientMergeRequests
  */
 export type VcsMergeRequestByIidQuery = {
+    /** @purpose GitLab project path or ID */
     project: string;
+    /** @purpose Merge request internal ID */
     iid: string | number;
 };
 /**
- * @purpose Доступ к Merge Requests/Pull Requests.
+ * @purpose Access to Merge Requests/Pull Requests.
+ * @invariant Error Policy: Network/status errors are thrown outward from request().
  * @consumer VcsClient
- * @invariant Error Policy: Ошибки сети/статуса пробрасываются наружу из request().
  */
 export declare abstract class VcsClientMergeRequests {
     /**
-     * @purpose Получить список MR по проекту и фильтрам.
-     * @param query Объект запроса.
-     * @returns Список Merge Request'ов по минимальным фильтрам.
+     * @purpose Get MR list by project and filters.
+     * @param query Query object.
+     * @returns List of Merge Requests by minimal filters.
+     * @sideEffect Network: GET /projects/:project/merge_requests
      */
     abstract getList(query: VcsMergeRequestsQuery): Promise<unknown[]>;
     /**
-     * @purpose Получить первый MR, удовлетворяющий тем же фильтрам, что и getList.
-     * @param query Объект запроса.
-     * @returns Первый найденный MR или null.
-     * @sideEffect Network: Делегирует в getList() с ограничением per_page=1.
+     * @purpose Get the first MR matching the same filters as getList.
+     * @param query Query object.
+     * @returns First found MR or null.
+     * @sideEffect Network: Delegates to getList() with per_page=1 limit.
      */
     abstract getOne(query: VcsMergeRequestsQuery): Promise<unknown | null>;
     /**
-     * @purpose Получить Merge Request по IID в рамках проекта.
-     * @param query Параметры: { project, iid }.
-     * @returns Объект Merge Request или null при 404.
+     * @purpose Get Merge Request by IID within a project.
+     * @param query Parameters: { project, iid }.
+     * @returns Merge Request object or null on 404.
+     * @sideEffect Network: GET /projects/:project/merge_requests/:iid
      */
     abstract getByIid(query: VcsMergeRequestByIidQuery): Promise<unknown | null>;
+    /**
+     * @purpose Get list of changed files in MR/PR.
+     * @param query Parameters: { repository, iid, page?, perPage? }.
+     * @returns List of changed files with metadata.
+     * @sideEffect Network: GitLab GET /projects/:id/merge_requests/:iid/changes | GitHub GET /repos/:owner/:repo/pulls/:number/files
+     */
+    abstract getChanges(query: VcsMergeRequestChangesQuery): Promise<VcsMergeRequestChanges[]>;
 }

package/dist/services/vcs-client/abstract/vcs-client-repository-files.d.ts

@@ -0,0 +1,16 @@
+import type { VcsFileContent, VcsFileContentQuery } from '../entities/vcs-file-content.type.js';
+/**
+ * @purpose Access to VCS repository file contents.
+ * @invariant Error Policy: Network/status errors are thrown outward from request().
+ * @invariant Encoding Contract: Adapter decodes content (base64 → utf-8 for text).
+ * @consumer VcsClient
+ */
+export declare abstract class VcsClientRepositoryFiles {
+    /**
+     * @purpose Get file content from repository.
+     * @param query Parameters: { repository, path, ref }.
+     * @returns File content or null if file not found (404).
+     * @sideEffect Network: GitLab GET /projects/:id/repository/files/:path/raw?ref= | GitHub GET /repos/:owner/:repo/contents/:path?ref=
+     */
+    abstract getFileContent(query: VcsFileContentQuery): Promise<VcsFileContent | null>;
+}

package/dist/services/vcs-client/abstract/vcs-client.d.ts

@@ -1,13 +1,17 @@
 import type { VcsClientMergeDiscussions } from './vcs-client-merge-discussions.js';
 import type { VcsClientMergeRequests } from './vcs-client-merge-requests.js';
+import type { VcsClientRepositoryFiles } from './vcs-client-repository-files.js';
 /**
- * @purpose Абстрактный клиент для работы с VCS Сервисами (например GitLab, Github).
- * @invariant Error Policy: Любой ответ !2xx преобразуется в Error с подробностями статуса.
- * @invariant Retry Policy: Повторов нет; ответственность за ретраи на вызывающей стороне.
+ * @purpose Abstract client for working with VCS services (e.g. GitLab, GitHub).
+ * @invariant Error Policy: Any non-2xx response is converted to an Error with status details.
+ * @invariant Retry Policy: No retries; retry responsibility lies with the caller.
+ * @consumer cli/review-verify, cli/cat
  */
 export declare abstract class VcsClient {
     /** @see {VcsClientMergeRequests} in ./vcs-client-merge-requests.ts */
     abstract readonly MergeRequests: VcsClientMergeRequests;
-    /** @see {VcsClientMergeDiscussions} in ./vcs-client-merge-discussions.ts */
-    abstract readonly MergeDiscussions: VcsClientMergeDiscussions;
+    /** @see {VcsClientMergeDiscussions} in ./vcs-client-merge-discussions.ts | @deferred GitHub adapter does not implement this */
+    abstract readonly MergeDiscussions?: VcsClientMergeDiscussions;
+    /** @see {VcsClientRepositoryFiles} in ./vcs-client-repository-files.ts | @deferred GitLab-only in v1 */
+    abstract readonly RepositoryFiles?: VcsClientRepositoryFiles;
 }

package/dist/services/vcs-client/entities/vcs-file-content.type.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @purpose File content from repository: path, content (decoded), encoding.
+ * @consumer VcsClientRepositoryFiles.getFileContent
+ */
+export type VcsFileContent = {
+    /** @purpose Path to file in repository */
+    path: string;
+    /** @purpose File content (decoded by adapter: base64 → utf-8 for text, base64 for binary) */
+    content: string;
+    /** @purpose Content encoding: utf-8 (text) or base64 (binary) */
+    encoding: 'utf-8' | 'base64';
+};
+/**
+ * @purpose File content query parameters: repository, path, branch/commit.
+ * @consumer VcsClientRepositoryFiles.getFileContent
+ */
+export type VcsFileContentQuery = {
+    /** @purpose Repository identifier (group/project or owner/repo) */
+    repository: string;
+    /** @purpose Path to file in repository */
+    path: string;
+    /** @purpose Branch, tag, or commit SHA */
+    ref: string;
+};

package/dist/services/vcs-client/entities/vcs-merge-request-changes.type.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @purpose One changed file in MR/PR: path, status, branch, change metrics.
+ * @consumer VcsClientMergeRequests.getChanges
+ */
+export type VcsMergeRequestChanges = {
+    /** @purpose File path (new_path for GitLab, filename for GitHub) */
+    path: string;
+    /** @purpose Change status: added, modified, deleted, renamed */
+    status: 'added' | 'modified' | 'deleted' | 'renamed';
+    /** @purpose Previous path (only for renamed) */
+    previousPath?: string;
+    /** @purpose Branch (source_branch GitLab / head.ref GitHub) — for getFileContent */
+    ref: string;
+    /** @purpose Number of added lines */
+    additions?: number;
+    /** @purpose Number of deleted lines */
+    deletions?: number;
+};
+/**
+ * @purpose MR/PR changes query parameters: repository, number, pagination.
+ * @consumer VcsClientMergeRequests.getChanges
+ */
+export type VcsMergeRequestChangesQuery = {
+    /** @purpose Repository identifier (group/project or owner/repo) */
+    repository: string;
+    /** @purpose MR number (IID) or PR (number) */
+    iid: string | number;
+    /** @purpose Page number (starting from 1) */
+    page?: number;
+    /** @purpose Page size */
+    perPage?: number;
+};

package/dist/services/vcs-client/entities/vcs-url.type.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @purpose Parsed merge request / pull request URL result.
+ * @consumer parseVcsUrl
+ */
+export type VcsUrl = {
+    /** @purpose VCS provider: gitlab or github */
+    provider: 'gitlab' | 'github';
+    /** @purpose Host (with port if present): gitlab.com, github.internal.com:8443 */
+    host: string;
+    /** @purpose Repository identifier: group/project for GitLab, owner/repo for GitHub */
+    repository: string;
+    /** @purpose MR number (IID) or PR (number) */
+    iid: number;
+};

package/dist/services/vcs-client/entities/vcs-user.type.d.ts

@@ -1,4 +1,7 @@
+/** @purpose Authenticated VCS user identity surfaced to API consumers. */
 export type VcsUser = {
+    /** @purpose Display name of the VCS user */
     name: string;
+    /** @purpose Unique login identifier in the VCS system */
     login: string;
 };

package/dist/services/vcs-client/github/vcs-github-client.d.ts

@@ -0,0 +1,31 @@
+import { VcsGithubMergeRequests } from './vcs-github-merge-requests.js';
+import { VcsGithubRepositoryFiles } from './vcs-github-repository-files.js';
+import { VcsClient } from '../abstract/vcs-client.js';
+/**
+ * @purpose Options for creating a GitHub API client: base URL and access token.
+ * @consumer VcsGithubClient
+ */
+export type VcsGithubClientOptions = {
+    /** @purpose GitHub API base URL (e.g. https://api.github.com) */
+    baseUrl: string;
+    /** @purpose GitHub personal access token */
+    token: string;
+};
+/**
+ * @purpose GitHub client for working with REST API (minimal: without MergeDiscussions).
+ * @invariant Error Policy: Any non-2xx response is converted to an Error with status details.
+ * @consumer cli/cat
+ */
+export declare class VcsGithubClient extends VcsClient {
+    /** @see {VcsClient#MergeRequests} in services/vcs-client/abstract/vcs-client.ts */
+    readonly MergeRequests: VcsGithubMergeRequests;
+    /** @see {VcsClient#MergeDiscussions} in services/vcs-client/abstract/vcs-client.ts */
+    readonly MergeDiscussions: undefined;
+    /** @see {VcsClient#RepositoryFiles} in services/vcs-client/abstract/vcs-client.ts */
+    readonly RepositoryFiles: VcsGithubRepositoryFiles;
+    /**
+     * @purpose Create a GitHub API client bound to a base URL with access token.
+     * @param options Connection parameters: base URL and access token.
+     */
+    constructor(options: VcsGithubClientOptions);
+}

package/dist/services/vcs-client/github/vcs-github-merge-requests.d.ts

@@ -0,0 +1,40 @@
+import { VcsClientMergeRequests } from '../abstract/vcs-client-merge-requests.js';
+import type { VcsMergeRequestChanges, VcsMergeRequestChangesQuery } from '../entities/vcs-merge-request-changes.type.js';
+type RequestFn = (path: string, init?: RequestInit) => Promise<unknown>;
+/**
+ * @purpose Access to Pull Request files via GitHub API.
+ * @invariant Error Policy: Network/status errors are thrown outward from request().
+ * @consumer VcsGithubClient
+ */
+export declare class VcsGithubMergeRequests extends VcsClientMergeRequests {
+    /** @purpose Bound HTTP request function for GitHub API calls */
+    protected _request: RequestFn;
+    /**
+     * @purpose Wire the HTTP request adapter for GitHub PR endpoints.
+     * @param request Authenticated HTTP request function targeting GitHub API.
+     */
+    constructor(request: RequestFn);
+    /**
+     * @purpose GitHub getList not implemented — use getChanges for PR files.
+     * @returns Empty array — not implemented.
+     */
+    getList(): Promise<unknown[]>;
+    /**
+     * @purpose GitHub getOne not implemented.
+     * @returns Null — not implemented.
+     */
+    getOne(): Promise<unknown | null>;
+    /**
+     * @purpose GitHub getByIid not implemented.
+     * @returns Null — not implemented.
+     */
+    getByIid(): Promise<unknown | null>;
+    /**
+     * @param query Target repository and PR number, optional pagination.
+     * @returns List of changed files with metadata.
+     * @sideEffect Network: GET /repos/:owner/:repo/pulls/:number/files
+     * @see {VcsClientMergeRequests#getChanges} in services/vcs-client/abstract/vcs-client-merge-requests.ts
+     */
+    getChanges(query: VcsMergeRequestChangesQuery): Promise<VcsMergeRequestChanges[]>;
+}
+export {};

package/dist/services/vcs-client/github/vcs-github-repository-files.d.ts

@@ -0,0 +1,27 @@
+import { VcsClientRepositoryFiles } from '../abstract/vcs-client-repository-files.js';
+import type { VcsFileContent, VcsFileContentQuery } from '../entities/vcs-file-content.type.js';
+/**
+ * @purpose Access to repository file contents via GitHub Contents API.
+ * @invariant Error Policy: Network/status errors are thrown outward. 404 → null.
+ * @invariant Encoding Contract: GitHub returns base64 → adapter decodes to utf-8.
+ * @consumer VcsGithubClient
+ */
+export declare class VcsGithubRepositoryFiles extends VcsClientRepositoryFiles {
+    /** @purpose GitHub API base URL */
+    protected _baseUrl: string;
+    /** @purpose GitHub access token */
+    protected _token: string;
+    /**
+     * @purpose Wire the adapter with GitHub connection params for raw content fetches.
+     * @param baseUrl GitHub API base URL (e.g. https://api.github.com).
+     * @param token GitHub personal access token.
+     */
+    constructor(baseUrl: string, token: string);
+    /**
+     * @param query Target repository, file path, and ref.
+     * @returns File content or null if file not found.
+     * @sideEffect Network: GET /repos/:owner/:repo/contents/:path?ref=
+     * @see {VcsClientRepositoryFiles#getFileContent} in services/vcs-client/abstract/vcs-client-repository-files.ts
+     */
+    getFileContent(query: VcsFileContentQuery): Promise<VcsFileContent | null>;
+}

package/dist/services/vcs-client/gitlab/vcs-gitlab-client.d.ts

@@ -1,24 +1,33 @@
 import { VcsGitlabMergeRequests } from './vcs-gitlab-merge-requests.js';
 import { VcsGitlabMergeDiscussions } from './vcs-gitlab-merge-discussions.js';
+import { VcsGitlabRepositoryFiles } from './vcs-gitlab-repository-files.js';
 import { VcsClient } from '../abstract/vcs-client.js';
 /**
- * @purpose Опции для создания клиента GitLab API: базовый URL и токен доступа.
+ * @purpose Options for creating a GitLab API client: base URL and access token.
  * @consumer VcsGitlabClient
  */
 export type VcsGitlabClientOptions = {
+    /** @purpose GitLab instance base URL (e.g. https://gitlab.example.com) */
     baseUrl: string;
+    /** @purpose GitLab personal or project access token */
     token: string;
 };
 /**
- * @purpose Клиент GitLab для работы с REST API.
+ * @purpose GitLab client for working with REST API.
+ * @invariant Error Policy: Any non-2xx response is converted to an Error with status details.
+ * @invariant Retry Policy: No retries; retry responsibility lies with the caller.
  * @consumer cli/review-verify
- * @invariant Error Policy: Любой ответ !2xx преобразуется в Error с подробностями статуса.
- * @invariant Retry Policy: Повторов нет; ответственность за ретраи на вызывающей стороне.
  */
 export declare class VcsGitlabClient extends VcsClient {
     /** @see {VcsClient#MergeRequests} in services/vcs-client/abstract/vcs-client.ts */
     readonly MergeRequests: VcsGitlabMergeRequests;
     /** @see {VcsClient#MergeDiscussions} in services/vcs-client/abstract/vcs-client.ts */
     readonly MergeDiscussions: VcsGitlabMergeDiscussions;
+    /** @see {VcsClient#RepositoryFiles} in services/vcs-client/abstract/vcs-client.ts */
+    readonly RepositoryFiles: VcsGitlabRepositoryFiles;
+    /**
+     * @purpose Create a GitLab API client bound to a base URL with access token.
+     * @param options Connection parameters: base URL and access token.
+     */
     constructor(options: VcsGitlabClientOptions);
 }

package/dist/services/vcs-client/gitlab/vcs-gitlab-merge-discussions.d.ts

@@ -1,26 +1,37 @@
 import { VcsClientMergeDiscussions, type VcsAddNoteQuery, type VcsDiscussionsListQuery } from '../abstract/vcs-client-merge-discussions.js';
 type RequestFn = (path: string, init?: RequestInit) => Promise<unknown>;
 /**
- * @purpose Доступ к Discussions для Merge Request в GitLab.
+ * @purpose Access to Discussions for Merge Requests in GitLab.
+ * @invariant Error Policy: Network/status errors are thrown outward from request().
  * @consumer VcsGitlabClient
- * @invariant Error Policy: Ошибки сети/статуса пробрасываются наружу из request().
  */
 export declare class VcsGitlabMergeDiscussions extends VcsClientMergeDiscussions {
+    /** @purpose Bound HTTP request function injected for GitLab API calls */
     protected _request: RequestFn;
+    /**
+     * @purpose Wire the HTTP request adapter for GitLab merge discussion endpoints.
+     * @param request Authenticated HTTP request function targeting GitLab API.
+     */
     constructor(request: RequestFn);
     /**
-     * @see {VcsClientMergeDiscussions#addNote} in services/vcs-client/abstract/vcs-merge-discussions.ts
+     * @param query Target project, MR, discussion, and note body.
+     * @returns Created note object from GitLab API.
      * @sideEffect Network: POST /projects/:project/merge_requests/:iid/discussions/:discussion_id/notes
+     * @see {VcsClientMergeDiscussions#addNote} in services/vcs-client/abstract/vcs-merge-discussions.ts
      */
     addNote(query: VcsAddNoteQuery): Promise<unknown>;
     /**
-     * @see {VcsClientMergeDiscussions#getList} in services/vcs-client/abstract/vcs-merge-discussions.ts
+     * @param query Target project, MR, and optional pagination.
+     * @returns List of discussions for the requested page.
      * @sideEffect Network: GET /projects/:project/merge_requests/:iid/discussions
+     * @see {VcsClientMergeDiscussions#getList} in services/vcs-client/abstract/vcs-merge-discussions.ts
      */
     getList(query: VcsDiscussionsListQuery): Promise<unknown[]>;
     /**
+     * @param query Target project and MR.
+     * @returns Complete list of all discussions across all pages.
+     * @sideEffect Network: Multiple GET requests for paginated loading.
      * @see {VcsClientMergeDiscussions#getAll} in services/vcs-client/abstract/vcs-merge-discussions.ts
-     * @sideEffect Network: Многократные GET для постраничной загрузки.
      */
     getAll(query: {
         project: string;

package/dist/services/vcs-client/gitlab/vcs-gitlab-merge-requests.d.ts

@@ -1,27 +1,46 @@
 import { VcsClientMergeRequests, type VcsMergeRequestByIidQuery, type VcsMergeRequestsQuery } from '../abstract/vcs-client-merge-requests.js';
+import type { VcsMergeRequestChanges, VcsMergeRequestChangesQuery } from '../entities/vcs-merge-request-changes.type.js';
 type RequestFn = (path: string, init?: RequestInit) => Promise<unknown>;
 /**
- * @purpose Доступ к Merge Requests в GitLab.
+ * @purpose Access GitLab Merge Requests.
+ * @invariant Error Policy: Network/status errors propagated to caller.
  * @consumer VcsGitlabClient
- * @invariant Error Policy: Ошибки сети/статуса пробрасываются наружу из request().
  */
 export declare class VcsGitlabMergeRequests extends VcsClientMergeRequests {
+    /** @purpose Bound HTTP request function injected for GitLab API calls */
     protected _request: RequestFn;
+    /**
+     * @purpose Wire the HTTP request adapter for GitLab merge request endpoints.
+     * @param request Authenticated HTTP request function targeting GitLab API.
+     */
     constructor(request: RequestFn);
     /**
-     * @see {VcsClientMergeRequests#getList} in services/vcs-client/abstract/vcs-merge-requests.ts
+     * @param query Target project and optional filters.
+     * @returns List of merge requests matching the filters.
      * @sideEffect Network: GET /projects/:project/merge_requests
+     * @see {VcsClientMergeRequests#getList} in services/vcs-client/abstract/vcs-merge-requests.ts
      */
     getList(query: VcsMergeRequestsQuery): Promise<unknown[]>;
     /**
+     * @param query Target project and optional filters.
+     * @returns First matching merge request or null.
+     * @sideEffect Network: Delegates to getList() with per_page=1 limit.
      * @see {VcsClientMergeRequests#getList} in services/vcs-client/abstract/vcs-merge-requests.ts
-     * @sideEffect Network: Делегирует в getList() с ограничением per_page=1.
      */
     getOne(query: VcsMergeRequestsQuery): Promise<unknown | null>;
     /**
-     * @see {VcsClientMergeRequests#getList} in services/vcs-client/abstract/vcs-merge-requests.ts
+     * @param query Target project and MR IID.
+     * @returns Merge request object or null on 404.
      * @sideEffect Network: GET /projects/:project/merge_requests/:iid
+     * @see {VcsClientMergeRequests#getList} in services/vcs-client/abstract/vcs-merge-requests.ts
      */
     getByIid(query: VcsMergeRequestByIidQuery): Promise<unknown | null>;
+    /**
+     * @param query Target repository and MR IID, optional pagination.
+     * @returns List of changed files with metadata.
+     * @sideEffect Network: GET /projects/:project/merge_requests/:iid/changes
+     * @see {VcsClientMergeRequests#getChanges} in services/vcs-client/abstract/vcs-client-merge-requests.ts
+     */
+    getChanges(query: VcsMergeRequestChangesQuery): Promise<VcsMergeRequestChanges[]>;
 }
 export {};

package/dist/services/vcs-client/gitlab/vcs-gitlab-repository-files.d.ts

@@ -0,0 +1,27 @@
+import { VcsClientRepositoryFiles } from '../abstract/vcs-client-repository-files.js';
+import type { VcsFileContent, VcsFileContentQuery } from '../entities/vcs-file-content.type.js';
+/**
+ * @purpose Access repository files via GitLab API (/raw endpoint).
+ * @invariant Error Policy: Network/status errors propagated to caller. 404 → null.
+ * @invariant Encoding Contract: Text files → encoding: 'utf-8'; binary → encoding: 'base64'.
+ * @consumer VcsGitlabClient
+ */
+export declare class VcsGitlabRepositoryFiles extends VcsClientRepositoryFiles {
+    /** @purpose GitLab instance base URL */
+    protected _baseUrl: string;
+    /** @purpose GitLab access token */
+    protected _token: string;
+    /**
+     * @purpose Wire the adapter with GitLab connection params for raw file fetches.
+     * @param baseUrl GitLab instance base URL (e.g. https://gitlab.com/api/v4).
+     * @param token GitLab personal access token.
+     */
+    constructor(baseUrl: string, token: string);
+    /**
+     * @param query Target repository, file path, and ref.
+     * @returns File content or null if file not found.
+     * @sideEffect Network: GET /projects/:id/repository/files/:path/raw?ref=
+     * @see {VcsClientRepositoryFiles#getFileContent} in services/vcs-client/abstract/vcs-client-repository-files.ts
+     */
+    getFileContent(query: VcsFileContentQuery): Promise<VcsFileContent | null>;
+}

package/dist/services/vcs-client/parse-vcs-url.d.ts

@@ -0,0 +1,3 @@
+import type { VcsUrl } from './entities/vcs-url.type.js';
+/** @purpose Parse GitLab Merge Request or GitHub Pull Request URL. */
+export declare const parseVcsUrl: (url: string | null | undefined) => VcsUrl | null;

package/dist/shared/backend/git/git-core.d.ts

@@ -1,61 +1,63 @@
 import { type ParsedDiffFile } from './git-diff.js';
 /**
- * @purpose Описать данные удалённого репозитория origin (хост, проект, схема).
+ * @purpose Describe origin remote repository data (host, project, scheme).
  * @consumer git-core, vcs-client
  */
 export type GitRemoteInfo = {
+    /** @purpose Git host domain (e.g. github.com). */
     host: string;
+    /** @purpose Repository path on the host (e.g. owner/repo). */
     project: string;
+    /** @purpose URL scheme used for origin remote (http, https, ssh). */
     scheme: string;
 };
 /**
- * @purpose Агрегированная информация по diff: сырой текст, разобранные файлы, метрики токенов и коммитов.
+ * @purpose Aggregated diff information: raw text, parsed files, token and commit metrics.
  * @consumer commit-gen, review-gen, ai-legacy
  */
 export type GitDiffInfo = {
+    /** @purpose Raw git diff text output. */
     diff: string;
+    /** @purpose All parsed diff files sorted by token count ascending. */
     parsedDiff: ParsedDiffFile[];
+    /** @purpose Code/config files only, excluding tests, deleted and renamed. */
     parsedCodeDiff: ParsedDiffFile[];
+    /** @purpose Total token count across parsed code diff files. */
     parsedCodeTokens: number;
+    /** @purpose Token count of the largest code file chunk. */
     parsedCodeChunkMaxTokens: number;
+    /** @purpose Unique programming languages detected across code diff files. */
     programmingLanguages: (string | undefined)[];
+    /** @purpose Number of commits on top of base branch. */
     commitCount: number;
 };
 /**
- * @purpose Определить базовую ветку репозитория (main или master) для анализа diff.
- * @returns Имя базовой ветки для сравнений (main|master), либо 'master' по умолчанию.
- * @sideEffect Process: выполнение git branch.
+ * @purpose Determine the base branch (main or master) for diff analysis.
+ * @sideEffect Process: executes git branch.
  */
 export declare const detectGitBaseBranch: () => string;
 /**
- * @purpose Получить имя текущей ветки Git.
- * @returns Имя текущей ветки; 'HEAD' при отсоединённой голове или ошибке.
- * @sideEffect Process: выполнение git rev-parse.
+ * @purpose Get current Git branch name.
+ * @sideEffect Process: executes git rev-parse.
  */
 export declare const getGitCurrentBranch: () => string;
 /**
- * @purpose Получить сведения об удалённом репозитории origin.
- * @returns {host, project, scheme} или null, если origin не настроен/не распознан.
- * @sideEffect Process: выполнение git config / git remote.
+ * @purpose Get origin remote repository info.
+ * @sideEffect Process: executes git config / git remote.
  */
 export declare const getGitRemote: () => GitRemoteInfo | null;
 /**
- * @purpose Посчитать количество коммитов поверх базовой ветки.
- * @returns Ненулевое целое число коммитов поверх базовой ветки; 0 при ошибке/отсутствии данных.
- * @sideEffect Process: выполнение git rev-list.
+ * @purpose Count commits on top of the base branch.
+ * @sideEffect Process: executes git rev-list.
  */
 export declare const getGitCommitCount: () => number;
 /**
- * @purpose Получить текстовый diff текущего состояния относительно цели.
- * @param targetBranch Ветка или ревизия, относительно которой строится diff; если не указана — используется HEAD.
- * @returns Строка с текстовым представлением diff из git.
- * @sideEffect Process: выполнение git diff.
+ * @purpose Get textual diff of current state against target.
+ * @sideEffect Process: executes git diff.
  */
 export declare const getGitDiff: (targetBranch?: string) => string;
 /**
- * @purpose Построить агрегированную информацию по diff для дальнейшего анализа/ранжирования.
- * @param branch Целевая ветка/ревизия для сравнения; если не указана — сравнение с HEAD.
- * @returns Объект с исходным diff, разобранными файлами и метриками (языки, токены, коммиты).
- * @sideEffect Process: вызовы getGitDiff и getGitCommitCount (git команды).
+ * @purpose Build aggregated diff info for further analysis/ranking.
+ * @sideEffect Process: calls getGitDiff and getGitCommitCount (git commands).
  */
 export declare const getGitDiffInfo: (branch?: string) => GitDiffInfo;

package/dist/shared/backend/git/git-diff.d.ts

@@ -1,15 +1,23 @@
 /**
- * @purpose Описать один файл из разобранного git diff: флаги, имя, категория, язык, хунки и число токенов.
+ * @purpose Describe one file from parsed git diff: flags, name, category, language, hunks and token count.
  * @consumer git-core, commit-gen, review-gen
  */
 export type ParsedDiffFile = {
+    /** @purpose True if the file was created in this diff (new file mode). */
     isNew: boolean;
+    /** @purpose True if the file was deleted in this diff (deleted file mode). */
     isDeleted: boolean;
+    /** @purpose True if the file was renamed (rename from/to headers present). */
     isRenamed: boolean;
+    /** @purpose Current file path (post-rename if applicable). */
     filename: string;
+    /** @purpose Original file path before rename, or null. */
     oldFilename: string | null;
+    /** @purpose New file mode octet (e.g. 100644), or null. */
     newFileMode: string | null;
+    /** @purpose Deleted file mode octet, or null. */
     deletedFileMode: string | null;
+    /** @purpose Aggregated hunk data: token counts and change lines. */
     diff: {
         tokens: number;
         hunks: {
@@ -18,17 +26,20 @@ export type ParsedDiffFile = {
             tokens: number;
         }[];
     };
+    /** @purpose Total token count computed across all hunks. */
     tokens: number;
+    /** @purpose Raw metadata extracted from diff headers (index, modes, etc.). */
     metadata: Record<string, unknown>;
+    /** @purpose File extension in lowercase (e.g. 'ts'). */
     ext: string;
+    /** @purpose File category: code, config, doc, img, bin, lock, etc. */
     category: string;
+    /** @purpose Detected programming language from file extension, if any. */
     programmingLanguage?: string;
 };
 /**
- * @purpose Разобрать текстовый вывод git diff в нормализованный список файлов с метаданными и токенами.
+ * @purpose Parse raw git diff output into normalized file list with metadata and tokens.
+ * @pre Input string must match `git diff` format (unified diff).
  * @consumer git/git-core, commit-gen, review-gen
- * @pre Входная строка должна соответствовать формату `git diff` (unified diff).
- * @param diffText Полный текстовый diff для парсинга.
- * @returns Массив объектов файлов с признаками (isNew/isDeleted/isRenamed), категориями, языком, хунками и суммой токенов.
  */
 export declare const parseGitDiff: (diffText: string) => ParsedDiffFile[];