fix: consistently use posix paths for links generated in docs markdown

fixes #259

Author: JohannesRudolph

src/commands/kit/apply.command.ts

@@ -71,15 +71,15 @@ export function registerApplyCmd(program: TopLevelCommand) {
         // by convention, the module id looks like $platform/...
         const platformConfig = foundationRepo.findPlatform(platform);
 
-        const { kitModulePath, targetPath } = await applyKitModule(
+        const { relativeKitModulePath, targetPath } = await applyKitModule(
           foundationRepo,
           platformConfig.id,
           logger,
           moduleId,
         );
 
         logger.progress(
-          `applied module ${kitModulePath} to ${
+          `applied module ${relativeKitModulePath} to ${
             collie.relativePath(
               targetPath,
             )
@@ -111,7 +111,7 @@ export async function applyKitModule(
 
   const factory = new CliApiFacadeFactory(logger);
   const tfdocs = factory.buildTerraformDocs(collie);
-  const kitModulePath = collie.relativePath(
+  const relativeKitModulePath = collie.relativePath(
     collie.resolvePath("kit", moduleId),
   );
 
@@ -138,15 +138,15 @@ export async function applyKitModule(
     entries: [
       {
         name: "terragrunt.hcl",
-        content: await generateTerragrunt(kitModulePath, tfdocs),
+        content: await generateTerragrunt(relativeKitModulePath, tfdocs),
       },
     ],
   };
 
   await dir.write(platformModuleDir);
 
   return {
-    kitModulePath,
+    relativeKitModulePath,
     targetPath,
   };
 }

src/commands/kit/kit-utilities.ts

@@ -1,4 +1,3 @@
-import { path } from "https://deno.land/x/[email protected]/deps.ts";
 import {
   Dir,
   DirectoryGenerator,
@@ -7,6 +6,8 @@ import {
 import { Logger } from "../../cli/Logger.ts";
 import { TerraformDocsCliFacade } from "../../api/terraform-docs/TerraformDocsCliFacade.ts";
 import { indent } from "../../cli/indent.ts";
+import { convertToPosixPath } from "../../path.ts";
+import * as path from "std/path";
 
 export async function newKitDirectoryCreation(
   modulePath: string,
@@ -97,7 +98,7 @@ export async function generateTerragrunt(
   const isBootstrap = kitModulePath.endsWith(`${path.SEP}bootstrap`);
 
   // terragrunt needs a posix style path
-  const posixKitModulePath = kitModulePath.replaceAll("\\", "/");
+  const posixKitModulePath = convertToPosixPath(kitModulePath);
 
   const platformIncludeBlock = `include "platform" {
   path = find_in_parent_folders("platform.hcl")

src/compliance/ComplianceControlParser.test.ts

@@ -1,5 +1,6 @@
 import { assertEquals } from "std/testing/assert";
 import { ComplianceControlParser } from "./ComplianceControlParser.ts";
+import { isWindows } from "../os.ts";
 
 Deno.test("parsing with POSIX paths", () => {
   const path = "compliance/cfmm/iam/identity-lifecycle-management.md";
@@ -8,9 +9,11 @@ Deno.test("parsing with POSIX paths", () => {
   assertEquals(result, "cfmm/iam/identity-lifecycle-management");
 });
 
-Deno.test("parsing with windows paths", () => {
-  const path = "compliance\\cfmm\\iam\\identity-lifecycle-management.md";
-  const result = ComplianceControlParser.toId(path);
+if (isWindows) {
+  Deno.test("parsing with windows paths", () => {
+    const path = "compliance\\cfmm\\iam\\identity-lifecycle-management.md";
+    const result = ComplianceControlParser.toId(path);
 
-  assertEquals(result, "cfmm/iam/identity-lifecycle-management");
-});
+    assertEquals(result, "cfmm/iam/identity-lifecycle-management");
+  });
+}

src/compliance/ComplianceControlParser.ts

@@ -9,6 +9,7 @@ import {
   ModelValidator,
 } from "../model/schemas/ModelValidator.ts";
 import { ComplianceControl } from "./ComplianceControl.ts";
+import { convertToPosixPath } from "../path.ts";
 
 // note: this is very much similar to KitModuleParser, maybe there's a common abstraction
 // behind that we should use - until then let's wait for rule of three
@@ -89,7 +90,7 @@ export class ComplianceControlParser {
   }
 
   static toId(relativeControlPath: string) {
-    const posixPath = relativeControlPath.replaceAll("\\", "/");
+    const posixPath = convertToPosixPath(relativeControlPath);
 
     const components = path.parse(posixPath);
 

src/docs/DocumentationRepository.ts

@@ -1,8 +1,9 @@
 import * as path from "std/path";
 import { FoundationRepository } from "../model/FoundationRepository.ts";
+import { convertToPosixPath } from "../path.ts";
 
-// TODO: refactor this to consistently use resolvePath, have no public members for proper encapsulation
 export class DocumentationRepository {
+  // DESIGN:
   // we use a "hidden" directory with a leading "." because terragrunt excludes hidden files and dirs
   // when building a terragrunt-cache folder, see  https://terragrunt.gruntwork.io/docs/reference/config-blocks-and-attributes/#terraform "include_in_copy"
   // >  By default, Terragrunt excludes hidden files and folders during the copy step.
@@ -15,10 +16,17 @@ export class DocumentationRepository {
     return this.foundation.resolvePath(this.docsRootDir, ...pathSegments);
   }
 
+  private makeLink(from: string, to: string) {
+    // note: in generated markdown we only use POSIX style paths
+    const relativeLink = path.relative(from, to);
+
+    return convertToPosixPath(relativeLink);
+  }
+
   kitModuleLink(from: string, moduleId: string) {
     const kitModulePath = this.resolveKitModulePath(moduleId);
 
-    return path.relative(from, kitModulePath);
+    return this.makeLink(from, kitModulePath);
   }
 
   resolveKitModulePath(moduleId: string) {
@@ -28,7 +36,7 @@ export class DocumentationRepository {
   controlLink(from: string, controlId: string) {
     const controlPath = this.resolveControlPath(controlId);
 
-    return path.relative(from, controlPath);
+    return this.makeLink(from, controlPath);
   }
 
   resolveCompliancePath(...pathSegments: string[]) {

src/foundation/FoundationDependenciesTreeBuilder.ts

@@ -8,6 +8,7 @@ import {
 } from "../kit/KitDependencyAnalyzer.ts";
 import { buildLabeledIdPath, insert } from "../model/tree.ts";
 import { CollieRepository } from "../model/CollieRepository.ts";
+import { convertToPosixPath } from "../path.ts";
 
 export interface FoundationsTree {
   [foundation: string]: FoundationTree;
@@ -68,9 +69,10 @@ export class FoundationDependenciesTreeBuilder {
         path.dirname(m.sourcePath),
       );
 
-      const id = resolvedPlatformModulePath
-        .substring(resolvedPlatformPath.length + "/".length)
-        .replaceAll("\\", "/"); // convert to posix style path if required
+      const relativePlatformModulePath = resolvedPlatformModulePath
+        .substring(resolvedPlatformPath.length + "/".length);
+
+      const id = convertToPosixPath(relativePlatformModulePath);
 
       const label = m.sourcePath;
       const labeledComponents = buildLabeledIdPath(id, label);

src/kit/KitModuleParser.ts

@@ -10,6 +10,7 @@ import {
 } from "../model/schemas/ModelValidator.ts";
 import { KitModule } from "./KitModule.ts";
 import { ParsedKitModule } from "./ParsedKitModule.ts";
+import { convertToPosixPath } from "../path.ts";
 
 export class KitModuleParser {
   constructor(
@@ -68,7 +69,7 @@ export class KitModuleParser {
       return;
     }
 
-    const posixRelativeModulePath = relativeModulePath.replaceAll("\\", "/");
+    const posixRelativeModulePath = convertToPosixPath(relativeModulePath);
 
     return {
       id: posixRelativeModulePath.substring("kit/".length),

src/path.ts

@@ -0,0 +1,11 @@
+import * as path from "std/path";
+
+/**
+ * Converts a relative path with windows or POSIX path separators to a relative path with POSIX separators
+ * https://stackoverflow.com/questions/53799385/how-can-i-convert-a-windows-path-to-posix-path-using-node-path
+ * @param relativePath a relative path (this is important!)
+ * @returns
+ */
+export function convertToPosixPath(relativePath: string) {
+  return relativePath.split(path.sep).join(path.posix.sep);
+}