docgen.api.ts

import { FunctionDetail } from './git.api';
import httpApi from './http.api';

// Types for docstring style configuration
export enum PythonDocstringStyle {
  GOOGLE = "GOOGLE",
  EPYDOC = "EPYDOC",
  NUMPYDOC = "NUMPYDOC",
  REST = "REST"
}

export enum JavaScriptDocstringStyle {
  JSDOC = "JSDoc"
}

export enum JavaDocstringStyle {
  JAVADOC = "JavaDoc"
}

export enum CSharpDocstringStyle {
  XML = "XML"
}

export enum KotlinDocstringStyle {
  KDOC = "KDoc"
}

export enum CDocstringStyle {
  DOXYGEN = "Doxygen",
  JAVADOC_STYLE = "JavaDoc-Style"
}

export interface LanguageStyleGuide {
  docstringStyle: string;
  maxDocStringLength: number;
  fileExtension: string[];
  displayName: string;
  name: string;
  supportedStyles: string[];
}

export interface DocStyleGuide {
  language: Record<string, LanguageStyleGuide>;
}

export interface CommitOutput {
  commitToGit: boolean;
  branch?: string;  // Optional field
  path: string;
}

export interface ArchDocConfig {
  commitOutput?: CommitOutput;
  hostDocumentation: boolean;
  generatePdf: boolean;
  generateMd: boolean;
  generateHtml: boolean;
  generateRtf: boolean;
  generateXml: boolean;
}

export type DocGenStatusReponse = {
  messages: string[];
  percentage: number;
};

export type DocGenInitialResponse = {
  message: string;
  inProgress: boolean;
  lroJobId: string;
};

// Helper function to build data structure for docgen requests
/**
 * Generates data for document generation related to a GitHub repository.
 *
 * @param {string} orgName - The name of the organization on GitHub.
 * @param {string} repoName - The name of the repository.
 * @returns {Object} An object containing git_repo and vendor properties.
 * @example
 * const data = buildDocGenData('myOrg', 'myRepo');
 * console.log(data);
 * // Output:
 * // {
 * //   git_repo: {
 * //     repo_name: 'myRepo',
 * //     organization_name: 'myOrg'
 * //   },
 * //   vendor: 'GITHUB'
 * // }
 */
function buildDocGenData( orgName: string, repoName: string, vendor: string) {
  return {
    git_repo: {
      repo_name: repoName,
      organization_name: orgName,
    },
    vendor: vendor,
  };
}

export const triggerDocGen = (
  orgName: string,
  repoName: string,
  vendor: string,
  genType: string,
  styleGuide?: DocStyleGuide,
  archDocConfig?: ArchDocConfig,
): Promise<DocGenInitialResponse> => {
  const data = buildDocGenData(orgName, repoName, vendor);
  const url = `/v1/git/job/${genType}/start`;
  return httpApi.post<DocGenInitialResponse>(url, { ...data, style_guide: styleGuide, arch_doc_config: archDocConfig }).then(({ data }) => data);
};

export const getDocGenStatus = (
  orgName: string,
  repoName: string,
  vendor: string,
  genType: string,
  lroJobId: string,
): Promise<DocGenStatusReponse> => {
  const url = `/v1/git/job/${lroJobId}/status`;
  return httpApi.get<DocGenStatusReponse>(url).then(({ data }) => data);
};

export const terminateJob = (
  lroJobId: string,
): Promise<Record<string, string>> => {
  const url = `/v1/git/job/${lroJobId}/terminate`;
  return httpApi.post<Record<string, string>>(url).then(({ data }) => data);
};

export const triggerAnalysisRepo = (
  orgName: string,
  repoName: string,
  vendor: string,
  analysisType?: string,
): Promise<DocGenInitialResponse> => {
  const data = buildDocGenData(orgName, repoName, vendor);
  let url = `/v1/git/analyze/repo`;
  // Only append analysisType to URL if it's provided and not empty
  url = analysisType && analysisType.trim() !== '' ? `${url}/${analysisType}` : url;
  return httpApi.post<DocGenInitialResponse>(url, { ...data }).then(({ data }) => data);
};

export const getAnalysisRepoStatus = (
  orgName: string, 
  repoName: string, 
  vendor: string,
  analysisType: string,
  lroJobId: string,
): Promise<DocGenStatusReponse> => {
  const data = buildDocGenData(orgName, repoName, vendor);
  let url = `/v1/git/analyze/repo`;
  // Only append analysisType to URL if it's provided and not empty
  url = analysisType && analysisType.trim() !== '' ? `${url}/${analysisType}` : url;
  url = `${url}/status?jobId=${lroJobId}`;
  return httpApi.post<DocGenStatusReponse>(url, { ...data }).then(({ data }) => data);
};

// Function to fetch function details for a repository
export const getAdvancedRepoAnalysisDetails = (
  orgName: string, repoName: string, vendor: string,
  analysisType: string,
): Promise<FunctionDetail[] | Record<string, string>> => {
  const data = buildDocGenData(orgName, repoName, vendor);
  const url = `/v1/git/job/${analysisType}/details`;
  
  return httpApi.post<FunctionDetail[] | Record<string, string>>(url, { ...data }).then(({ data }) => data); // Extract the message 
};

/**
 * Fetches language details for a specified repository.
 *
 * @async
 * @function
 * @param {string} orgName - The name of the organization that owns the repository.
 * @param {string} repoName - The name of the repository to fetch language details for.
 * @returns {Promise<LanguageStyleGuide[]>} A promise that resolves with an array of `LanguageStyleGuide` objects containing details about the languages used in the specified repository.
 * @throws {Error} If there is a failure during the HTTP request or if the data structure does not match expectations.
 *
 * @example
 * getLanguage('myOrg', 'myRepo')
 *   .then(languages => {
 *     console.log(languages);
 *   })
 *   .catch(error => {
 *     console.error('Error fetching language details:', error);
 *   });
 */
export const getLanguage = (
  orgName: string,
  repoName: string,
  vendor: string,
): Promise<LanguageStyleGuide[]> => {
  // Function to fetch language details for a repository
  const data = buildDocGenData(orgName, repoName, vendor);
  const url = `/v1/git/repo/language`;
  return httpApi.post<LanguageStyleGuide[]>(url, { ...data }).then(({ data }) => data);
};