diff --git a/src/docs/PlatformDocumentationGenerator.ts b/src/docs/PlatformDocumentationGenerator.ts index 20b364f..4c49c0d 100644 --- a/src/docs/PlatformDocumentationGenerator.ts +++ b/src/docs/PlatformDocumentationGenerator.ts @@ -26,7 +26,7 @@ export class PlatformDocumentationGenerator { private readonly kitDependencyAnalyzer: KitDependencyAnalyzer, private readonly controls: ComplianceControlRepository, private readonly terragrunt: TerragruntCliFacade, - private readonly logger: Logger + private readonly logger: Logger, ) {} async generate(docsRepo: DocumentationRepository) { @@ -39,24 +39,24 @@ export class PlatformDocumentationGenerator { const dest = docsRepo.resolvePlatformsPath("README.md"); this.logger.verbose( - (fmt) => `Copying ${fmt.kitPath(source)} to ${fmt.kitPath(dest)}` + (fmt) => `Copying ${fmt.kitPath(source)} to ${fmt.kitPath(dest)}`, ); await fs.ensureDir(path.dirname(dest)); await fs.copy(source, dest, { overwrite: true }); } private async generatePlatformsDocumentation( - docsRepo: DocumentationRepository + docsRepo: DocumentationRepository, ) { const foundationProgress = new ProgressReporter( "generate documentation", this.repo.relativePath(this.foundation.resolvePath()), - this.logger + this.logger, ); - const foundationDependencies = - await this.kitDependencyAnalyzer.findKitModuleDependencies( - this.foundation + const foundationDependencies = await this.kitDependencyAnalyzer + .findKitModuleDependencies( + this.foundation, ); for (const p of foundationDependencies.platforms) { @@ -68,22 +68,22 @@ export class PlatformDocumentationGenerator { private async generatePlatforDocumentation( dependencies: PlatformDependencies, - docsRepo: DocumentationRepository + docsRepo: DocumentationRepository, ) { const platformPath = this.foundation.resolvePlatformPath( - dependencies.platform + dependencies.platform, ); const platformProgress = new ProgressReporter( "generate documentation", this.repo.relativePath(platformPath), - this.logger + this.logger, ); const platformModuleDocumentation = new RunIndividualPlatformModuleOutputCollector( this.repo, this.terragrunt, - this.logger + this.logger, ); // as a fallback process modules serially, unfortunately this is the only "safe" way to collect output @@ -95,7 +95,7 @@ export class PlatformDocumentationGenerator { dep, documentationMd, docsRepo, - dependencies.platform + dependencies.platform, ); } @@ -106,11 +106,11 @@ export class PlatformDocumentationGenerator { dep: KitModuleDependency, documentationMd: string, docsRepo: DocumentationRepository, - platform: PlatformConfig + platform: PlatformConfig, ) { const destPath = docsRepo.resolvePlatformModulePath( platform.id, - dep.kitModuleId + dep.kitModuleId, ); await fs.ensureDir(path.dirname(destPath)); // todo: should we do nesting in the docs output or "flatten" module prefixes? @@ -120,14 +120,14 @@ export class PlatformDocumentationGenerator { const complianceStatementsBlock = this.generateComplianceStatementSection( dep, docsRepo, - destPath + destPath, ); mdSections.push(complianceStatementsBlock); const kitModuleSection = this.generateKitModuleSection( dep, docsRepo, - destPath + destPath, ); mdSections.push(kitModuleSection); @@ -135,28 +135,30 @@ export class PlatformDocumentationGenerator { this.logger.verbose( (fmt) => - `Wrote output "documentation_md" from platform module ${fmt.kitPath( - dep.sourcePath - )} to ${fmt.kitPath(destPath)}` + `Wrote output "documentation_md" from platform module ${ + fmt.kitPath( + dep.sourcePath, + ) + } to ${fmt.kitPath(destPath)}`, ); } private generateKitModuleSection( dep: KitModuleDependency, docsRepo: DocumentationRepository, - destPath: string + destPath: string, ) { if (!dep.kitModule) { return MarkdownUtils.container( "warning", "Invalid Kit Module Dependency", - "Could not find kit module at " + MarkdownUtils.code(dep.kitModulePath) + "Could not find kit module at " + MarkdownUtils.code(dep.kitModulePath), ); } const kitModuleLink = MarkdownUtils.link( dep.kitModule.name + " kit module", - docsRepo.kitModuleLink(destPath, dep.kitModuleId) + docsRepo.kitModuleLink(destPath, dep.kitModuleId), ); const kitModuleSection = `::: tip Kit module @@ -168,23 +170,25 @@ This platform module is a deployment of kit module ${kitModuleLink}. private generateComplianceStatementSection( dep: KitModuleDependency, docsRepo: DocumentationRepository, - destPath: string + destPath: string, ) { const complianceStatements = dep?.kitModule?.compliance ?.map((x) => { const control = this.controls.tryFindById(x.control); if (!control) { this.logger.warn( - `could not find compliance control ${x.control} referenced in a compliance statement in ${dep.kitModulePath}` + `could not find compliance control ${x.control} referenced in a compliance statement in ${dep.kitModulePath}`, ); return; } - return `- [${control.name}](${docsRepo.controlLink( - destPath, - x.control - )}): ${x.statement}`; + return `- [${control.name}](${ + docsRepo.controlLink( + destPath, + x.control, + ) + }): ${x.statement}`; }) .filter((x): x is string => !!x); diff --git a/src/docs/PlatformModuleOutputCollector.ts b/src/docs/PlatformModuleOutputCollector.ts index d782e40..c46b41a 100644 --- a/src/docs/PlatformModuleOutputCollector.ts +++ b/src/docs/PlatformModuleOutputCollector.ts @@ -5,17 +5,16 @@ import { CollieRepository } from "../model/CollieRepository.ts"; import { Logger } from "../cli/Logger.ts"; import { MeshError } from "../errors.ts"; - /** - * Note: + * Note: * For a great UX/DX it's important that running "collie foundation docs" is fast. - * + * * We have therefore tried speeding it up by collecting output from platform modules in parallel. * Unfortunately, it appears that terragrunt does not offer us a good way to reliably get all the outputs from all * platform modules, see https://github.com/meshcloud/collie-cli/issues/267 - * + * * This "fast mode" detection also caused other bugs like https://github.com/meshcloud/collie-cli/issues/269 - * + * * In the future, we should maybe investigate cachingas an alternative to parallelization, because usually an engineer * would re-run "collie foundation docs" only after changing a specific platform module */