feat: implement an option to always provide vcsPath in metadata for…

… md->md transformations (sans tests)
diplodoc-platform · Jul 11, 2024 · ad1b879 · ad1b879
1 parent b0f9c29
commit ad1b879
Show file tree

Hide file tree

Showing 6 changed files with 185 additions and 143 deletions.
diff --git a/src/models.ts b/src/models.ts
@@ -27,6 +27,31 @@ export type UserByLoginFunction = (login: string) => Promise<Contributor | null>
 export type CollectionOfPluginsFunction = (output: string, options: PluginOptions) => string;
 export type GetModifiedTimeByPathFunction = (filepath: string) => number | undefined;
 
+/**
+ * VCS integration configuration object.
+ * Future VCS futures should be configured with this one, not with
+ * `VCSConnectorConfig`.
+ */
+interface VCSConfiguration {
+    /**
+     * Externally accessible base URI for a resource where a particular documentation
+     * source is hosted.
+     *
+     * This configuration parameter is used to directly control the Edit button behaviour
+     * in the Diplodoc documentation viewer(s).
+     *
+     * For example, if the following applies:
+     * - Repo with doc source is hosted on GitHub (say, https://github.com/foo-org/bar),
+     * - Within that particular repo, the directory that is being passed as an `--input`
+     *   parameter to the CLI is located at `docs/`,
+     * - Whenever the Edit button is pressed, you wish to direct your readers to the
+     *   respective document's source on `main` branch
+     *
+     * you should pass `https://github.com/foo-org/bar/tree/main/docs` as a value for this parameter.
+     */
+    remoteBase: string;
+}
+
 interface YfmConfig {
     varsPreset: VarsPreset;
     ignore: string[];
@@ -41,6 +66,7 @@ interface YfmConfig {
     ignoreStage: string;
     singlePage: boolean;
     removeHiddenTocItems: boolean;
+    vcs?: VCSConfiguration;
     connector?: VCSConnectorConfig;
     lang?: Lang;
     langs?: Lang[];
@@ -199,20 +225,14 @@ export interface Contributors {
     [email: string]: Contributor;
 }
 
-export interface FileData {
-    tmpInputFilePath: string;
-    inputFolderPathLength: number;
-    fileContent: string;
-    sourcePath?: string;
-}
-
 export interface MetaDataOptions {
-    fileData: FileData;
+    pathData: PathData;
     isContributorsEnabled?: boolean;
     vcsConnector?: VCSConnector;
     addSystemMeta?: boolean;
     addSourcePath?: boolean;
     resources?: Resources;
+    shouldAlwaysAddVCSPath?: boolean;
 }
 
 export interface PluginOptions {
@@ -236,7 +256,7 @@ export interface Plugin {
 export interface ResolveMd2MdOptions {
     inputPath: string;
     outputPath: string;
-    metadata?: MetaDataOptions;
+    metadata: MetaDataOptions;
 }
 
 export interface ResolverOptions {

diff --git a/src/resolvers/md2md.ts b/src/resolvers/md2md.ts
@@ -12,16 +12,17 @@ import {getContentWithUpdatedMetadata} from '../services/metadata';
 import {ChangelogItem} from '@diplodoc/transform/lib/plugins/changelog/types';
 
 export async function resolveMd2Md(options: ResolveMd2MdOptions): Promise<void> {
-    const {inputPath, outputPath, metadata} = options;
+    const {inputPath, outputPath, metadata: metadataOptions} = options;
     const {input, output, changelogs: changelogsSetting} = ArgvService.getConfig();
     const resolvedInputPath = resolve(input, inputPath);
-    const vars = getVarsPerFile(inputPath);
+
+    const varsPreset = getVarsPerFile(inputPath);
 
     const content = await getContentWithUpdatedMetadata(
         readFileSync(resolvedInputPath, 'utf8'),
-        metadata,
-        vars.__system,
-        vars.__metadata,
+        metadataOptions,
+        varsPreset.__system as unknown,
+        varsPreset.__metadata,
     );
 
     const {result, changelogs} = transformMd2Md(content, {
@@ -30,7 +31,7 @@ export async function resolveMd2Md(options: ResolveMd2MdOptions): Promise<void>
         root: resolve(input),
         destRoot: resolve(output),
         collectOfPlugins: PluginService.getCollectOfPlugins(),
-        vars,
+        vars: varsPreset,
         log,
         copyFile,
     });

diff --git a/src/services/contributors.ts b/src/services/contributors.ts
@@ -3,11 +3,17 @@ import {dirname, join} from 'path';
 
 import {replaceDoubleToSingleQuotes} from '../utils';
 import {REGEXP_INCLUDE_CONTENTS, REGEXP_INCLUDE_FILE_PATH} from '../constants';
-import {Contributor, Contributors, FileData} from '../models';
+import {Contributor, Contributors} from '../models';
 import {FileContributors, VCSConnector} from '../vcs-connector/connector-models';
 
+export interface ContributorsServiceFileData {
+    resolvedFilePath: string;
+    inputFolderPathLength: number;
+    fileContent: string;
+}
+
 async function getFileContributorsMetadata(
-    fileData: FileData,
+    fileData: ContributorsServiceFileData,
     vcsConnector: VCSConnector,
 ): Promise<string> {
     const contributors = await getFileContributorsString(fileData, vcsConnector);
@@ -16,12 +22,12 @@ async function getFileContributorsMetadata(
 }
 
 async function getFileContributorsString(
-    fileData: FileData,
+    fileData: ContributorsServiceFileData,
     vcsConnector: VCSConnector,
 ): Promise<string> {
-    const {tmpInputFilePath, inputFolderPathLength} = fileData;
+    const {resolvedFilePath, inputFolderPathLength} = fileData;
 
-    const relativeFilePath = tmpInputFilePath.substring(inputFolderPathLength);
+    const relativeFilePath = resolvedFilePath.substring(inputFolderPathLength);
     const fileContributors: FileContributors =
         await vcsConnector.getContributorsByPath(relativeFilePath);
     let nestedContributors: Contributors = {};
@@ -44,7 +50,7 @@ async function getFileContributorsString(
 }
 
 async function getContributorsForNestedFiles(
-    fileData: FileData,
+    fileData: ContributorsServiceFileData,
     vcsConnector: VCSConnector,
 ): Promise<Contributors> {
     const {fileContent, inputFolderPathLength} = fileData;
@@ -77,10 +83,10 @@ async function getContributorsForNestedFiles(
                 throw err;
             }
 
-            const newFileData: FileData = {
+            const newFileData: ContributorsServiceFileData = {
                 ...fileData,
                 fileContent: contentIncludeFile,
-                tmpInputFilePath: relativeIncludeFilePath,
+                resolvedFilePath: relativeIncludeFilePath,
             };
 
             nestedContributors = await getContributorsForNestedFiles(newFileData, vcsConnector);
@@ -95,10 +101,9 @@ async function getContributorsForNestedFiles(
 }
 
 function getRelativeIncludeFilePaths(
-    fileData: Pick<FileData, 'tmpInputFilePath'>,
+    {resolvedFilePath: tmpInputFilePath}: ContributorsServiceFileData,
     includeContents: string[],
 ): Set<string> {
-    const {tmpInputFilePath} = fileData;
     const relativeIncludeFilePaths: Set<string> = new Set();
 
     includeContents.forEach((includeContent: string) => {
@@ -118,10 +123,8 @@ function getRelativeIncludeFilePaths(
     return relativeIncludeFilePaths;
 }
 
-async function getFileIncludes(
-    fileData: Pick<FileData, 'fileContent' | 'tmpInputFilePath' | 'inputFolderPathLength'>,
-) {
-    const {fileContent, tmpInputFilePath, inputFolderPathLength} = fileData;
+async function getFileIncludes(fileData: ContributorsServiceFileData) {
+    const {fileContent, inputFolderPathLength} = fileData;
 
     const results = new Set<string>();
 
@@ -130,7 +133,7 @@ async function getFileIncludes(
         return [];
     }
     const relativeIncludeFilePaths: Set<string> = getRelativeIncludeFilePaths(
-        {tmpInputFilePath},
+        fileData,
         includeContents,
     );
     for (const relativeIncludeFilePath of relativeIncludeFilePaths.values()) {
@@ -151,7 +154,7 @@ async function getFileIncludes(
         const includedPaths = await getFileIncludes({
             inputFolderPathLength,
             fileContent: contentIncludeFile,
-            tmpInputFilePath: relativeIncludeFilePath,
+            resolvedFilePath: relativeIncludeFilePath,
         });
         includedPaths.forEach((path) => results.add(path));
     }