@foss.global/codefeed 1.9.0 → 1.10.0

package/ts/classes.gitmanagerpublicclient.ts

@@ -0,0 +1,856 @@
+import * as plugins from './plugins.js';
+
+export interface IGitManagerPublicReadClientOptions {
+  gitManager: plugins.TGitManager;
+  publicBaseUrl?: string;
+  smartHttpBaseUrl?: string;
+  sshBaseUrl?: string;
+  allowAllRepositories?: boolean;
+  isRepositoryPublic?: (repositoryArg: plugins.TGitManagerRepositoryInfo) => Promise<boolean>;
+  organizationMetadata?: (
+    orgArg: string,
+  ) => Promise<Partial<plugins.fossInterfaces.IPublicOrg> | undefined>;
+  repositoryMetadata?: (
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+  ) => Promise<Partial<plugins.fossInterfaces.IPublicRepo> | undefined>;
+  newsProvider?: (limitArg: number) => Promise<plugins.fossInterfaces.IPublicNewsItem[]>;
+  maxCommits?: number;
+  maxReleases?: number;
+  maxLanguageFiles?: number;
+  maxConcurrency?: number;
+}
+
+export class GitManagerPublicReadClient {
+  private readonly gitManager: plugins.TGitManager;
+  private readonly publicBaseUrl: string;
+  private readonly smartHttpBaseUrl: string;
+  private readonly sshBaseUrl: string;
+  private readonly allowAllRepositories: boolean;
+  private readonly isRepositoryPublic?: (
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+  ) => Promise<boolean>;
+  private readonly organizationMetadata?: (
+    orgArg: string,
+  ) => Promise<Partial<plugins.fossInterfaces.IPublicOrg> | undefined>;
+  private readonly repositoryMetadata?: (
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+  ) => Promise<Partial<plugins.fossInterfaces.IPublicRepo> | undefined>;
+  private readonly newsProvider?: (
+    limitArg: number,
+  ) => Promise<plugins.fossInterfaces.IPublicNewsItem[]>;
+  private readonly maxCommits: number;
+  private readonly maxReleases: number;
+  private readonly maxLanguageFiles: number;
+  private readonly maxConcurrency: number;
+
+  constructor(optionsArg: IGitManagerPublicReadClientOptions) {
+    if (!optionsArg.allowAllRepositories && !optionsArg.isRepositoryPublic) {
+      throw new Error(
+        'GitManagerPublicReadClient requires allowAllRepositories or an authoritative isRepositoryPublic predicate',
+      );
+    }
+    this.gitManager = optionsArg.gitManager;
+    this.publicBaseUrl = this.normalizeBaseUrl(
+      optionsArg.publicBaseUrl ?? 'https://foss.global',
+      ['http:', 'https:'],
+    );
+    this.smartHttpBaseUrl = this.normalizeBaseUrl(
+      optionsArg.smartHttpBaseUrl ?? this.publicBaseUrl,
+      ['http:', 'https:'],
+    );
+    this.sshBaseUrl = this.normalizeBaseUrl(
+      optionsArg.sshBaseUrl ?? 'ssh://git@code.foss.global:29419',
+      ['ssh:'],
+    );
+    this.allowAllRepositories = optionsArg.allowAllRepositories ?? false;
+    this.isRepositoryPublic = optionsArg.isRepositoryPublic;
+    this.organizationMetadata = optionsArg.organizationMetadata;
+    this.repositoryMetadata = optionsArg.repositoryMetadata;
+    this.newsProvider = optionsArg.newsProvider;
+    this.maxCommits = this.validateLimit(optionsArg.maxCommits ?? 40, 'maxCommits', 1, 1000);
+    this.maxReleases = this.validateLimit(optionsArg.maxReleases ?? 50, 'maxReleases', 1, 1000);
+    this.maxLanguageFiles = this.validateLimit(
+      optionsArg.maxLanguageFiles ?? 1000,
+      'maxLanguageFiles',
+      1,
+      10_000,
+    );
+    this.maxConcurrency = this.validateLimit(
+      optionsArg.maxConcurrency ?? 8,
+      'maxConcurrency',
+      1,
+      32,
+    );
+  }
+
+  public async getOverview(
+    queryArg = '',
+  ): Promise<plugins.fossInterfaces.IReq_PublicOverview['response']> {
+    const query = queryArg.trim().toLowerCase();
+    if (query.length > 160) {
+      throw new Error('Query exceeds maximum length of 160');
+    }
+    const repositoryInfos = await this.listVisibleRepositories();
+    const filteredInfos = query
+      ? repositoryInfos.filter((repository) =>
+          `${repository.org}/${repository.repo}`.toLowerCase().includes(query),
+        )
+      : repositoryInfos;
+    const repos = await this.mapWithConcurrency(
+      filteredInfos.slice(0, query ? 100 : 36),
+      (repository) => this.mapRepository(repository),
+    );
+    const orgs = await this.mapOrganizations(repositoryInfos);
+    const commitFeed = await this.getCommitFeed(filteredInfos.slice(0, 12), 3);
+    const activity = commitFeed.slice(0, 24).map((commit) => this.mapActivity(commit));
+    const news = query ? [] : ((await this.newsProvider?.(6)) ?? []);
+    return {
+      orgs: query
+        ? orgs.filter((org) => org.name.toLowerCase().includes(query))
+        : orgs,
+      repos,
+      activity,
+      commitFeed,
+      news,
+      stats: this.getStats(orgs, repos),
+    };
+  }
+
+  public async getOrg(
+    orgArg: string,
+  ): Promise<plugins.fossInterfaces.IReq_PublicOrg['response']> {
+    const org = this.validateSlug(orgArg, 'organization', 120);
+    const repositoryInfos = (await this.listVisibleRepositories()).filter(
+      (repository) => repository.org === org,
+    );
+    if (repositoryInfos.length === 0) {
+      return {
+        org: null,
+        repos: [],
+        members: [],
+        activity: [],
+        commitFeed: [],
+        stats: {
+          orgCount: 0,
+          repoCount: 0,
+          releaseCount: 0,
+          openIssueCount: 0,
+        },
+      };
+    }
+    const repos = await this.mapWithConcurrency(repositoryInfos, (repository) =>
+      this.mapRepository(repository),
+    );
+    const [mappedOrg] = await this.mapOrganizations(repositoryInfos, [org]);
+    const commitFeed = await this.getCommitFeed(repositoryInfos.slice(0, 12), 3);
+    const activity = commitFeed.slice(0, 24).map((commit) => this.mapActivity(commit));
+    return {
+      org: mappedOrg ?? null,
+      repos,
+      members: [],
+      activity,
+      commitFeed,
+      stats: this.getStats(mappedOrg ? [mappedOrg] : [], repos),
+    };
+  }
+
+  public async getRepo(
+    orgArg: string,
+    repoArg: string,
+    pathArg = '',
+    _issueNumberArg = 0,
+  ): Promise<plugins.fossInterfaces.IReq_PublicRepo['response']> {
+    const repository = await this.findVisibleRepository(orgArg, repoArg);
+    if (!repository) {
+      return {
+        repo: null,
+        contents: [],
+        readme: '',
+        releases: [],
+        activity: [],
+        issues: [],
+        selectedIssue: null,
+        selectedIssueComments: [],
+        commits: [],
+        languages: {},
+      };
+    }
+    const path = this.validatePath(pathArg);
+    const [tree, readme, tags, commitSummaries, languages] = await Promise.all([
+      this.withFallback(
+        () => this.gitManager.listTree({
+          org: repository.org,
+          repo: repository.repo,
+          ref: repository.defaultBranch,
+          path: path || undefined,
+        }),
+        [],
+      ),
+      path ? Promise.resolve('') : this.readReadme(repository),
+      this.withFallback(
+        () => this.gitManager.listTags({
+          org: repository.org,
+          repo: repository.repo,
+          limit: this.maxReleases,
+        }),
+        [],
+      ),
+      this.withFallback(
+        () => this.gitManager.listCommits({
+          org: repository.org,
+          repo: repository.repo,
+          ref: repository.defaultBranch,
+          limit: Math.min(this.maxCommits, 12),
+        }),
+        [],
+      ),
+      this.scanLanguages(repository),
+    ]);
+    const commits = commitSummaries.map((commit) => this.mapCommit(commit));
+    const latestCommit = commits[0];
+    const releases = tags.map((tag) => this.mapRelease(repository, tag));
+    const repo = await this.mapRepository(repository);
+    repo.releaseCount = releases.length;
+    repo.language = this.getPrimaryLanguage(languages);
+    return {
+      repo,
+      contents: tree
+        .filter((entry) => entry.entryType !== 'other')
+        .map((entry) => this.mapContent(repository, entry, latestCommit)),
+      readme,
+      releases,
+      activity: commits.map((commit) => this.mapActivity(commit)),
+      issues: [],
+      selectedIssue: null,
+      selectedIssueComments: [],
+      commits,
+      languages,
+    };
+  }
+
+  public async getFile(
+    orgArg: string,
+    repoArg: string,
+    pathArg: string,
+  ): Promise<plugins.fossInterfaces.IReq_PublicFile['response']> {
+    const repository = await this.findVisibleRepository(orgArg, repoArg);
+    if (!repository) {
+      return { repo: null, file: null, activity: [], commits: [] };
+    }
+    const path = this.validatePath(pathArg, false);
+    const [file, commitSummaries, repo] = await Promise.all([
+      this.withFallback(
+        () => this.gitManager.readFile({
+          org: repository.org,
+          repo: repository.repo,
+          ref: repository.defaultBranch,
+          path,
+        }),
+        null,
+      ),
+      this.withFallback(
+        () => this.gitManager.listCommits({
+          org: repository.org,
+          repo: repository.repo,
+          ref: repository.defaultBranch,
+          limit: Math.min(this.maxCommits, 8),
+        }),
+        [],
+      ),
+      this.mapRepository(repository),
+    ]);
+    const commits = commitSummaries.map((commit) => this.mapCommit(commit));
+    return {
+      repo,
+      file: file
+        ? {
+            path: file.path,
+            name: file.path.split('/').pop() ?? file.path,
+            size: file.size,
+            htmlUrl: this.repoPathUrl(repository, `src/${repository.defaultBranch}/${file.path}`),
+            downloadUrl: '',
+            content: file.isBinary
+              ? ''
+              : Buffer.from(file.contentBase64, 'base64').toString('utf8'),
+            isBinary: file.isBinary,
+            truncated: false,
+          }
+        : null,
+      activity: commits.map((commit) => this.mapActivity(commit)),
+      commits,
+    };
+  }
+
+  public async getCommits(
+    orgArg: string,
+    repoArg: string,
+    shaArg = '',
+  ): Promise<plugins.fossInterfaces.IReq_PublicCommits['response']> {
+    const repository = await this.findVisibleRepository(orgArg, repoArg);
+    if (!repository) {
+      return { repo: null, commits: [], selectedCommit: null };
+    }
+    const sha = shaArg.trim();
+    if (sha && !/^[0-9a-fA-F]{40,64}$/.test(sha)) {
+      throw new Error('Invalid commit SHA');
+    }
+    const [repo, commitSummaries, selectedCommit] = await Promise.all([
+      this.mapRepository(repository),
+      this.withFallback(
+        () => this.gitManager.listCommits({
+          org: repository.org,
+          repo: repository.repo,
+          ref: repository.defaultBranch,
+          limit: this.maxCommits,
+        }),
+        [],
+      ),
+      sha
+        ? this.withFallback(() => this.getCommitDetail(repository, sha), null)
+        : Promise.resolve(null),
+    ]);
+    return {
+      repo,
+      commits: commitSummaries.map((commit) => this.mapCommit(commit)),
+      selectedCommit,
+    };
+  }
+
+  private async listVisibleRepositories(): Promise<plugins.TGitManagerRepositoryInfo[]> {
+    const repositories = await this.gitManager.listRepositories();
+    if (this.allowAllRepositories) {
+      return repositories;
+    }
+    const visibility = await this.mapWithConcurrency(repositories, async (repository) => ({
+      repository,
+      visible: await this.isRepositoryPublic!(repository),
+    }));
+    return visibility
+      .filter((entry) => entry.visible)
+      .map((entry) => entry.repository);
+  }
+
+  private async findVisibleRepository(
+    orgArg: string,
+    repoArg: string,
+  ): Promise<plugins.TGitManagerRepositoryInfo | undefined> {
+    const org = this.validateSlug(orgArg, 'organization', 120);
+    const repo = this.validateSlug(repoArg, 'repository', 160);
+    return (await this.listVisibleRepositories()).find(
+      (repository) => repository.org === org && repository.repo === repo,
+    );
+  }
+
+  private async mapOrganizations(
+    repositoriesArg: plugins.TGitManagerRepositoryInfo[],
+    explicitOrgsArg?: string[],
+  ): Promise<plugins.fossInterfaces.IPublicOrg[]> {
+    const orgNames = explicitOrgsArg
+      ?? [...new Set(repositoriesArg.map((repository) => repository.org))];
+    const orgs = await this.mapWithConcurrency(orgNames, async (name) => {
+      const repositories = repositoriesArg.filter((repository) => repository.org === name);
+      const metadata = await this.organizationMetadata?.(name);
+      const base: plugins.fossInterfaces.IPublicOrg = {
+        name,
+        fullName: name,
+        description: '',
+        website: '',
+        location: '',
+        avatarUrl: '',
+        htmlUrl: `${this.publicBaseUrl}/${name}`,
+        repoCount: repositories.length,
+        starsCount: 0,
+        memberCount: 0,
+        languages: {},
+      };
+      return {
+        ...base,
+        ...metadata,
+        name,
+        repoCount: repositories.length,
+      };
+    });
+    return orgs.sort((orgA, orgB) => orgA.name.localeCompare(orgB.name));
+  }
+
+  private async mapRepository(
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+  ): Promise<plugins.fossInterfaces.IPublicRepo> {
+    const [latestCommit] = await this.withFallback(
+      () => this.gitManager.listCommits({
+        org: repositoryArg.org,
+        repo: repositoryArg.repo,
+        ref: repositoryArg.defaultBranch,
+        limit: 1,
+      }),
+      [],
+    );
+    const metadata = await this.repositoryMetadata?.(repositoryArg);
+    const slug = `${repositoryArg.org}/${repositoryArg.repo}`;
+    const base: plugins.fossInterfaces.IPublicRepo = {
+      id: this.stableId(slug),
+      org: repositoryArg.org,
+      name: repositoryArg.repo,
+      slug,
+      orgAvatarUrl: '',
+      description: '',
+      language: '',
+      htmlUrl: `${this.publicBaseUrl}/${slug}`,
+      cloneUrl: `${this.smartHttpBaseUrl}/${slug}.git`,
+      sshUrl: `${this.sshBaseUrl}/${slug}.git`,
+      starsCount: 0,
+      forksCount: 0,
+      watchersCount: 0,
+      openIssuesCount: 0,
+      openPrCount: 0,
+      releaseCount: 0,
+      size: 0,
+      defaultBranch: repositoryArg.defaultBranch,
+      updatedAt: latestCommit?.createdAt ?? '',
+      createdAt: latestCommit?.createdAt ?? '',
+      archived: false,
+      topics: [],
+    };
+    return {
+      ...base,
+      ...metadata,
+      id: this.stableId(slug),
+      org: repositoryArg.org,
+      name: repositoryArg.repo,
+      slug,
+      defaultBranch: repositoryArg.defaultBranch,
+    };
+  }
+
+  private async getCommitFeed(
+    repositoriesArg: plugins.TGitManagerRepositoryInfo[],
+    perRepositoryLimitArg: number,
+  ): Promise<plugins.fossInterfaces.IPublicCommit[]> {
+    const groups = await this.mapWithConcurrency(repositoriesArg, async (repository) => {
+      const commits = await this.withFallback(
+        () => this.gitManager.listCommits({
+          org: repository.org,
+          repo: repository.repo,
+          ref: repository.defaultBranch,
+          limit: Math.min(this.maxCommits, perRepositoryLimitArg),
+        }),
+        [],
+      );
+      return commits.map((commit) => this.mapCommit(commit));
+    });
+    return groups
+      .flat()
+      .sort((commitA, commitB) => commitB.createdAt.localeCompare(commitA.createdAt))
+      .slice(0, this.maxCommits);
+  }
+
+  private mapCommit(
+    commitArg: plugins.TGitManagerCommitSummary,
+  ): plugins.fossInterfaces.IPublicCommit {
+    return {
+      sha: commitArg.sha,
+      shortSha: commitArg.shortSha,
+      message: commitArg.subject,
+      title: commitArg.subject,
+      body: '',
+      htmlUrl: this.repoPathUrl(
+        { org: commitArg.org, repo: commitArg.repo },
+        `commit/${commitArg.sha}`,
+      ),
+      createdAt: commitArg.createdAt,
+      authorName: commitArg.authorName,
+      authorLogin: '',
+      authorAvatarUrl: '',
+      repoSlug: `${commitArg.org}/${commitArg.repo}`,
+      files: [],
+      additions: 0,
+      deletions: 0,
+      verified: false,
+      kind: this.getActivityKind(commitArg.subject),
+    };
+  }
+
+  private async getCommitDetail(
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+    shaArg: string,
+  ): Promise<plugins.fossInterfaces.IPublicCommitDetail> {
+    const [commit, diff] = await Promise.all([
+      this.gitManager.getCommit({
+        org: repositoryArg.org,
+        repo: repositoryArg.repo,
+        ref: shaArg,
+      }),
+      this.gitManager.getDiff({
+        org: repositoryArg.org,
+        repo: repositoryArg.repo,
+        headRef: shaArg,
+      }),
+    ]);
+    return {
+      sha: commit.sha,
+      shortSha: commit.shortSha,
+      message: commit.message,
+      title: commit.subject,
+      body: commit.body,
+      htmlUrl: this.repoPathUrl(repositoryArg, `commit/${commit.sha}`),
+      createdAt: commit.createdAt,
+      authorName: commit.author.name,
+      authorLogin: '',
+      authorAvatarUrl: '',
+      verified: false,
+      parents: commit.parents.map((parent) => parent.sha),
+      additions: diff.additions,
+      deletions: diff.deletions,
+      files: diff.files.map((file) => ({
+        path: file.newPath || file.oldPath,
+        previousPath: file.oldPath,
+        status: this.mapDiffStatus(file.status),
+        language: this.languageForPath(file.newPath || file.oldPath),
+        additions: file.additions,
+        deletions: file.deletions,
+        isBinary: file.isBinary,
+        hunks: file.hunks.map((hunk) => ({
+          header: hunk.header,
+          lines: hunk.lines.map((line) => ({
+            kind: line.kind,
+            content: line.content,
+            oldNumber: line.oldNumber,
+            newNumber: line.newNumber,
+          })),
+        })),
+      })),
+      diffTruncated: diff.truncated,
+    };
+  }
+
+  private mapContent(
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+    entryArg: plugins.TGitManagerTreeEntry,
+    latestCommitArg?: plugins.fossInterfaces.IPublicCommit,
+  ): plugins.fossInterfaces.IPublicContentItem {
+    const type = entryArg.entryType === 'other' ? 'file' : entryArg.entryType;
+    return {
+      name: entryArg.name,
+      path: entryArg.path,
+      type,
+      size: entryArg.size ?? 0,
+      htmlUrl: this.repoPathUrl(
+        repositoryArg,
+        `src/${repositoryArg.defaultBranch}/${entryArg.path}`,
+      ),
+      downloadUrl: '',
+      lastCommitSha: latestCommitArg?.sha ?? '',
+      lastAuthorDate: latestCommitArg?.createdAt ?? '',
+      lastCommitMessage: latestCommitArg?.title ?? '',
+    };
+  }
+
+  private mapRelease(
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+    tagArg: plugins.TGitManagerTag,
+  ): plugins.fossInterfaces.IPublicRelease {
+    return {
+      tagName: tagArg.name,
+      name: tagArg.subject || tagArg.name,
+      body: tagArg.message,
+      htmlUrl: this.repoPathUrl(repositoryArg, `releases/tag/${tagArg.name}`),
+      publishedAt: tagArg.taggedAt,
+      prerelease: /(?:^|[-.])(alpha|beta|rc)(?:[-.]|$)/i.test(tagArg.name),
+      draft: false,
+      author: {
+        login: '',
+        fullName: tagArg.taggerName,
+        description: '',
+        website: '',
+        location: '',
+        avatarUrl: '',
+        htmlUrl: '',
+        createdAt: '',
+      },
+      assets: [],
+    };
+  }
+
+  private mapActivity(
+    commitArg: plugins.fossInterfaces.IPublicCommit,
+  ): plugins.fossInterfaces.IPublicActivityEntry {
+    return {
+      id: commitArg.sha,
+      org: commitArg.repoSlug.split('/')[0] ?? '',
+      repo: commitArg.repoSlug.split('/')[1] ?? '',
+      repoSlug: commitArg.repoSlug,
+      tagName: '',
+      version: '',
+      kind: commitArg.kind,
+      title: commitArg.title,
+      body: commitArg.body,
+      createdAt: commitArg.createdAt,
+    };
+  }
+
+  private async readReadme(repositoryArg: plugins.TGitManagerRepositoryInfo): Promise<string> {
+    for (const path of ['README.md', 'readme.md', 'Readme.md']) {
+      try {
+        const file = await this.gitManager.readFile({
+          org: repositoryArg.org,
+          repo: repositoryArg.repo,
+          ref: repositoryArg.defaultBranch,
+          path,
+        });
+        if (!file.isBinary) {
+          return Buffer.from(file.contentBase64, 'base64').toString('utf8');
+        }
+      } catch {
+        continue;
+      }
+    }
+    return '';
+  }
+
+  private async scanLanguages(
+    repositoryArg: plugins.TGitManagerRepositoryInfo,
+  ): Promise<Record<string, number>> {
+    const languages: Record<string, number> = {};
+    const pendingPaths = [''];
+    let fileCount = 0;
+    let scannedEntryCount = 0;
+    while (pendingPaths.length > 0 && scannedEntryCount < this.maxLanguageFiles) {
+      const path = pendingPaths.shift()!;
+      const entries = await this.withFallback(
+        () => this.gitManager.listTree({
+          org: repositoryArg.org,
+          repo: repositoryArg.repo,
+          ref: repositoryArg.defaultBranch,
+          path: path || undefined,
+        }),
+        [],
+      );
+      for (const entry of entries) {
+        if (scannedEntryCount >= this.maxLanguageFiles) {
+          break;
+        }
+        scannedEntryCount += 1;
+        if (entry.entryType === 'dir') {
+          if (entry.path.split('/').length <= 20) {
+            pendingPaths.push(entry.path);
+          }
+          continue;
+        }
+        if (entry.entryType !== 'file' || fileCount >= this.maxLanguageFiles) {
+          continue;
+        }
+        fileCount += 1;
+        const language = this.languageForPath(entry.path);
+        languages[language] = (languages[language] ?? 0) + (entry.size ?? 0);
+      }
+    }
+    return languages;
+  }
+
+  private getStats(
+    orgsArg: plugins.fossInterfaces.IPublicOrg[],
+    reposArg: plugins.fossInterfaces.IPublicRepo[],
+  ): plugins.fossInterfaces.IPublicStats {
+    return {
+      orgCount: orgsArg.length,
+      repoCount: reposArg.length,
+      releaseCount: reposArg.reduce((sum, repo) => sum + repo.releaseCount, 0),
+      openIssueCount: reposArg.reduce((sum, repo) => sum + repo.openIssuesCount, 0),
+    };
+  }
+
+  private getPrimaryLanguage(languagesArg: Record<string, number>): string {
+    return Object.entries(languagesArg)
+      .sort((entryA, entryB) => entryB[1] - entryA[1] || entryA[0].localeCompare(entryB[0]))[0]?.[0] ?? '';
+  }
+
+  private languageForPath(pathArg: string): string {
+    const extension = pathArg.toLowerCase().split('.').pop() ?? '';
+    const languages: Record<string, string> = {
+      ts: 'TypeScript',
+      tsx: 'TypeScript',
+      js: 'JavaScript',
+      jsx: 'JavaScript',
+      mjs: 'JavaScript',
+      cjs: 'JavaScript',
+      rs: 'Rust',
+      go: 'Go',
+      py: 'Python',
+      java: 'Java',
+      kt: 'Kotlin',
+      rb: 'Ruby',
+      php: 'PHP',
+      c: 'C',
+      h: 'C',
+      cc: 'C++',
+      cpp: 'C++',
+      hpp: 'C++',
+      cs: 'C#',
+      swift: 'Swift',
+      sh: 'Shell',
+      bash: 'Shell',
+      zsh: 'Shell',
+      html: 'HTML',
+      css: 'CSS',
+      scss: 'SCSS',
+      vue: 'Vue',
+      svelte: 'Svelte',
+    };
+    return languages[extension] ?? 'Other';
+  }
+
+  private getActivityKind(messageArg: string): plugins.fossInterfaces.TPublicActivityKind {
+    const prefix = messageArg.trim().toLowerCase().match(/^([a-z]+)(?:\([^)]*\))?[!:]/)?.[1];
+    switch (prefix) {
+      case 'feat':
+      case 'fix':
+      case 'perf':
+      case 'docs':
+      case 'test':
+      case 'refactor':
+      case 'build':
+      case 'ci':
+      case 'chore':
+        return prefix;
+      case 'release':
+      case 'rel':
+        return 'rel';
+      default:
+        return 'code';
+    }
+  }
+
+  private mapDiffStatus(
+    statusArg: plugins.TGitManagerDiff['files'][number]['status'],
+  ): plugins.fossInterfaces.TPublicDiffFileStatus {
+    switch (statusArg) {
+      case 'added':
+      case 'deleted':
+      case 'renamed':
+        return statusArg;
+      default:
+        return 'modified';
+    }
+  }
+
+  private repoPathUrl(
+    repositoryArg: Pick<plugins.TGitManagerRepositoryInfo, 'org' | 'repo'>,
+    suffixArg: string,
+  ): string {
+    const encodedSuffix = suffixArg
+      .split('/')
+      .map((segment) => encodeURIComponent(segment))
+      .join('/');
+    return `${this.publicBaseUrl}/${repositoryArg.org}/${repositoryArg.repo}/${encodedSuffix}`;
+  }
+
+  private stableId(valueArg: string): number {
+    let hash = 2166136261;
+    for (const char of valueArg) {
+      hash ^= char.charCodeAt(0);
+      hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+  }
+
+  private normalizeBaseUrl(valueArg: string, allowedProtocolsArg: string[]): string {
+    const value = valueArg.trim().replace(/\/+$/, '');
+    if (
+      !value
+      || value.length > 2048
+      || /[\u0000-\u0020\u007f]/.test(value)
+    ) {
+      throw new Error('Invalid base URL');
+    }
+    let parsed: URL;
+    try {
+      parsed = new URL(value);
+    } catch {
+      throw new Error('Invalid base URL');
+    }
+    if (
+      !allowedProtocolsArg.includes(parsed.protocol)
+      || parsed.password
+      || parsed.search
+      || parsed.hash
+    ) {
+      throw new Error('Invalid base URL');
+    }
+    return value;
+  }
+
+  private validateSlug(valueArg: string, labelArg: string, maxLengthArg: number): string {
+    const value = valueArg.trim();
+    if (
+      !value
+      || value.length > maxLengthArg
+      || value === '.'
+      || value === '..'
+      || !/^[A-Za-z0-9._-]+$/.test(value)
+    ) {
+      throw new Error(`Invalid ${labelArg}`);
+    }
+    return value;
+  }
+
+  private validatePath(valueArg: string, allowEmptyArg = true): string {
+    const path = valueArg.trim().replace(/^\/+|\/+$/g, '');
+    if (!path) {
+      if (allowEmptyArg) {
+        return '';
+      }
+      throw new Error('Path is required');
+    }
+    if (
+      path.length > 500
+      || path.includes('\\')
+      || path.split('/').some((segment) => !segment || segment === '.' || segment === '..')
+    ) {
+      throw new Error('Invalid path');
+    }
+    return path;
+  }
+
+  private validateLimit(
+    valueArg: number,
+    labelArg: string,
+    minimumArg: number,
+    maximumArg: number,
+  ): number {
+    if (!Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+      throw new Error(`${labelArg} must be an integer between ${minimumArg} and ${maximumArg}`);
+    }
+    return valueArg;
+  }
+
+  private async withFallback<TValue>(
+    operationArg: () => Promise<TValue>,
+    fallbackArg: TValue,
+  ): Promise<TValue> {
+    try {
+      return await operationArg();
+    } catch {
+      return fallbackArg;
+    }
+  }
+
+  private async mapWithConcurrency<TInput, TOutput>(
+    itemsArg: TInput[],
+    mapperArg: (itemArg: TInput) => Promise<TOutput>,
+  ): Promise<TOutput[]> {
+    const results = new Array<TOutput>(itemsArg.length);
+    let nextIndex = 0;
+    const workers = Array.from(
+      { length: Math.min(this.maxConcurrency, itemsArg.length) },
+      async () => {
+        while (nextIndex < itemsArg.length) {
+          const index = nextIndex;
+          nextIndex += 1;
+          results[index] = await mapperArg(itemsArg[index]);
+        }
+      },
+    );
+    await Promise.all(workers);
+    return results;
+  }
+}