fix terraform docs common metadata (#438)

* Assign a placeholder version for unversioned docs

* Move all TFC versions to 'v0.0.x'

* Give version less docs a version

* Use PRODUCT_CONFIG when we can

* fix sitemaps for terraform-docs-common

* Check PRODUCT_CONFIG in more places

* fix file path

* remove console.log

* fix docs route tests

* change back to null

* fix more tests

* fix gather-version tests

* fix test

* put aloglia check back

* fix tests

* remove extra console.log

---------

Co-authored-by: Leah Bush <leah.bush@hashicorp.com>

Author: RubenSandwich

__fixtures__/versionMetadata.json

@@ -382,7 +382,13 @@
 			"isLatest": false
 		}
 	],
-	"terraform-docs-common": [],
+	"terraform-docs-common": [
+		{
+			"version": "v0.0.x",
+			"releaseStage": "stable",
+			"isLatest": true
+		}
+	],
 	"terraform-plugin-framework": [
 		{
 			"version": "v1.5.x",

app/api/content/[productSlug]/doc/[version]/[...docsPath]/route.test.ts

@@ -56,8 +56,8 @@ vi.mock('@api/docsPathsAllVersions.json', () => {
 vi.mock('@utils/productConfig.mjs', () => {
 	return {
 		PRODUCT_CONFIG: {
-			'terraform-enterprise': { contentDir: 'docs' },
-			'terraform-plugin-framework': { contentDir: 'docs' },
+			'terraform-enterprise': { contentDir: 'docs', versionedDocs: true },
+			'terraform-plugin-framework': { contentDir: 'docs', versionedDocs: true },
 		},
 	}
 })

app/api/content/[productSlug]/doc/[version]/[...docsPath]/route.ts

@@ -140,7 +140,9 @@ export async function GET(request: Request, { params }: { params: GetParams }) {
 		result: {
 			fullPath: parsedDocsPath,
 			product: productSlug,
-			version: parsedVersion,
+			version: PRODUCT_CONFIG[productSlug].versionedDocs
+				? parsedVersion
+				: 'v0.0.x',
 			metadata,
 			subpath: 'docs', // TODO: I guess we could grab the first part of the rawDocsPath? Is there something I am missing here?
 			markdownSource,

app/utils/allDocsPaths.ts

@@ -6,6 +6,7 @@
 import { Ok, Err, errorResultToString } from '@utils/result'
 import docsPathsAllVersions from '@api/docsPathsAllVersions.json'
 import { getProductVersion } from './contentVersions'
+import { PRODUCT_CONFIG } from './productConfig.mjs'
 
 export const getDocsPaths = async (
 	productSlugs: string[],
@@ -21,6 +22,9 @@ export const getDocsPaths = async (
 			}
 
 			if (docsPathsData[productSlug]) {
+				if (!PRODUCT_CONFIG[productSlug].versionedDocs) {
+					return docsPathsData[productSlug]['v0.0.x']
+				}
 				return docsPathsData[productSlug][latestProductVersion.value]
 			}
 			console.error(`Product, ${productSlug}, not found in docs paths`)

app/utils/contentVersions.ts

@@ -6,6 +6,8 @@
 import versionMetadata from '@api/versionMetadata.json'
 import { Ok, Err } from '@utils/result'
 
+import { PRODUCT_CONFIG } from '@utils/productConfig.mjs'
+
 type ProductVersionMetadata = {
 	version: string
 	isLatest: boolean
@@ -34,7 +36,7 @@ export const getProductVersion = (
 			},
 		)
 
-		if (!foundVersion) {
+		if (!PRODUCT_CONFIG[productSlug].versionedDocs) {
 			parsedVersion = '' // Set to an empty string if no latest version is found, as in the case for versionless docs such as terraform-docs-common
 		} else {
 			parsedVersion = foundVersion.version

app/utils/utils.test.ts

@@ -29,6 +29,14 @@ vi.mock('@api/docsPathsAllVersions.json', () => {
 	}
 })
 
+vi.mock('@utils/productConfig.mjs', () => {
+	return {
+		PRODUCT_CONFIG: {
+			terraform: { contentDir: 'docs', versionedDocs: true },
+		},
+	}
+})
+
 test('getProductVersion should return error for non-existent product', () => {
 	const expected = {
 		ok: false,

scripts/add-version-to-nav-data.mjs

@@ -5,7 +5,6 @@
 
 import fs from 'node:fs/promises'
 import { PRODUCT_CONFIG } from '../app/utils/productConfig.mjs'
-import semver from 'semver'
 
 /**
  * Adds version information to navigation data in a JSON file.
@@ -36,7 +35,7 @@ export async function addVersionToNavData(filePath, versionMetadata) {
 		const [product, version] = relativePath.split('/')
 
 		// We are looking at a versionless doc
-		if (!semver.valid(semver.coerce(version))) {
+		if (PRODUCT_CONFIG[product].versionedDocs === false) {
 			return
 		}
 

scripts/algolia/convert-mdx-to-json/index.mjs

@@ -31,9 +31,10 @@ export async function getLatestProductVersionDirectories(dir, versionMetadata) {
 				directoryPath,
 				versionMetadata,
 			)
+
 			// getLatestVersion will return null for versionless products
 			// if directory is for versionless docs, return null
-			return latestProductVersion == null
+			return latestProductVersion == 'v0.0.x'
 				? directoryPath
 				: path.join(directoryPath, latestProductVersion)
 		}),

scripts/gather-all-versions-docs-paths.mjs

@@ -38,7 +38,7 @@ export async function gatherAllVersionsDocsPaths(versionMetadata) {
 			const contentPath = path.join(
 				'./content',
 				product,
-				version?.version ?? '',
+				PRODUCT_CONFIG[product].versionedDocs ? (version?.version ?? '') : '',
 				PRODUCT_CONFIG[product].contentDir,
 			)
 

scripts/gather-version-metadata.mjs

@@ -8,6 +8,8 @@ import path from 'path'
 // Third-party
 import semver from 'semver'
 
+import { PRODUCT_CONFIG } from '../app/utils/productConfig.mjs'
+
 /**
  * Given a content directory, and a JSON output file, build version metadata
  * based on the content directory structure, and return it.
@@ -31,6 +33,21 @@ export async function gatherVersionMetadata(contentDir) {
 	for (const product of products) {
 		// Initialize the product array
 		versionMetadata[product] = []
+
+		/**
+		 * If the product is not versioned, we add a single entry for the
+		 * "v0.0.x" version, which is a placeholder for non-versioned products.
+		 * This is useful for products that do not have versioned documentation,
+		 * such as the HashiCorp Cloud Platform.
+		 */
+		if (PRODUCT_CONFIG[product].versionedDocs === false) {
+			versionMetadata[product].push({
+				version: 'v0.0.x',
+				releaseStage: 'stable',
+				isLatest: true,
+			})
+		}
+
 		/**
 		 * We expect the product directory to contain a directory for each version.
 		 * We expect that either:

scripts/gather-version-metadata.test.ts

@@ -7,6 +7,15 @@ import { beforeEach, expect, it, vi } from 'vitest'
 import { vol } from 'memfs'
 import { gatherVersionMetadata } from './gather-version-metadata.mjs'
 
+vi.mock('../app/utils/productConfig.mjs', () => {
+	return {
+		PRODUCT_CONFIG: {
+			'terraform-enterprise': { contentDir: 'docs', versionedDocs: true },
+			terraform: { contentDir: 'docs', versionedDocs: true },
+		},
+	}
+})
+
 // tell vitest to use fs mock from __mocks__ folder
 // this can be done in a setup file if fs should always be mocked
 vi.mock('fs')

scripts/mdx-transforms/add-version-to-internal-links/add-version-to-internal-links.mjs

@@ -6,7 +6,6 @@
 import remark from 'remark'
 import remarkMdx from 'remark-mdx'
 import flatMap from 'unist-util-flatmap'
-import semver from 'semver'
 
 import { PRODUCT_CONFIG } from '../../../app/utils/productConfig.mjs'
 
@@ -28,8 +27,7 @@ export const rewriteInternalLinksPlugin = ({ entry, versionMetadata }) => {
 	 */
 	const [product, version] = relativePath.split('/')
 
-	// We are looking at a versionless doc
-	if (semver.valid(semver.coerce(version)) === null) {
+	if (PRODUCT_CONFIG[product].versionedDocs === false) {
 		return
 	}
 

scripts/mdx-transforms/add-version-to-internal-links/add-version-to-internal-links.test.mjs

@@ -13,30 +13,43 @@ vi.mock('../../../app/utils/productConfig.mjs', () => {
 		PRODUCT_CONFIG: {
 			terraform: {
 				basePaths: ['cli', 'internals', 'intro', 'language'],
+				versionedDocs: true,
 			},
 			'terraform-enterprise': {
 				basePaths: ['enterprise'],
+				versionedDocs: true,
 			},
 			'terraform-cdk': {
 				basePaths: ['cdktf'],
+				versionedDocs: true,
 			},
 			'terraform-docs-agents': {
 				basePaths: ['cloud-docs/agents'],
+				versionedDocs: true,
 			},
 			'terraform-plugin-framework': {
 				basePaths: ['plugin/framework'],
+				versionedDocs: true,
 			},
 			'terraform-plugin-log': {
 				basePaths: ['plugin/log'],
+				versionedDocs: true,
 			},
 			'terraform-plugin-mux': {
 				basePaths: ['plugin/mux'],
+				versionedDocs: true,
 			},
 			'terraform-plugin-sdk': {
 				basePaths: ['plugin/sdkv2'],
+				versionedDocs: true,
 			},
 			'terraform-plugin-testing': {
 				basePaths: ['plugin/testing'],
+				versionedDocs: true,
+			},
+			'terraform-docs-common': {
+				basePaths: [],
+				versionedDocs: false,
 			},
 		},
 	}

scripts/mdx-transforms/build-mdx-transforms.mjs

@@ -25,6 +25,8 @@ import {
 } from './rewrite-internal-redirects/rewrite-internal-redirects.mjs'
 import { transformExcludeTerraformContent } from './exclude-terraform-content/index.mjs'
 
+import { PRODUCT_CONFIG } from '../../app/utils/productConfig.mjs'
+
 /**
  * Given a target directory,
  * Apply MDX transforms to all `.mdx` files found in the directory and its
@@ -61,7 +63,9 @@ export async function buildMdxTransforms(
 		 * if versionless, version becomes the content dir
 		 * which will cause an error when trying resolve partials
 		 */
-		const verifiedVersion = semver.valid(semver.coerce(version)) ? version : ''
+		const verifiedVersion = PRODUCT_CONFIG[repoSlug].versionedDocs
+			? version
+			: ''
 		const verifiedContentDir = semver.valid(semver.coerce(version))
 			? contentDir
 			: version

scripts/utils/file-path/latest-version/index.mjs

@@ -6,6 +6,8 @@
 import { getProductDirectoryFromFilePath } from '../product-directory/index.mjs'
 import { getVersionFromFilePath } from '../version/index.mjs'
 
+import { PRODUCT_CONFIG } from '../../../../app/utils/productConfig.mjs'
+
 /**
  * Checks if the given file path corresponds to the latest version of the document.
  *
@@ -29,7 +31,7 @@ export function isLatestVersion(filePath, versionMetadata) {
 	const productVersions = versionMetadata[productDir]
 
 	// if repo dir exists, and is an empty array (aka versionless docs)
-	if (Array.isArray(productVersions) && productVersions.length === 0) {
+	if (PRODUCT_CONFIG[productDir].versionedDocs === false) {
 		return true
 	}
 	// check that the file path version exists in the version metadata and is the latest version

scripts/utils/file-path/latest-version/index.test.mjs

@@ -118,11 +118,11 @@ describe('getLatestVersion', () => {
 		expect(latestVersion).toBe('v0.14.x')
 	})
 
-	test('should return null if product does not have versions', () => {
+	test('should return v0.0.x for versionless docs', () => {
 		getProductDirectoryFromFilePath.mockReturnValue('terraform-docs-common')
 		const filePath =
 			'content/terraform-docs-common/docs/cloud-docs/cost-estimation/gcp.mdx'
 		const latestVersion = getLatestVersion(filePath, versionMetadata)
-		expect(latestVersion).toBeNull()
+		expect(latestVersion).toBe('v0.0.x')
 	})
 })

scripts/utils/file-path/version/index.mjs

@@ -3,7 +3,6 @@
  * SPDX-License-Identifier: BUSL-1.1
  */
 
-import semver from 'semver'
 /**
  * Extracts the version from a given file path.
  *
@@ -40,6 +39,6 @@ export function getVersionFromFilePath(filePath) {
 		 * e.g. terraform-docs-common
 		 */
 
-		return semver.valid(semver.coerce(version))
+		return version === 'v0.0.x'
 	}
 }

scripts/utils/file-path/version/index.test.mjs

@@ -34,10 +34,10 @@ describe('getVersionFromFilePath', () => {
 		expect(version).toBe('v202410-1')
 	})
 
-	test('should return null if the file path is for versionless docs', () => {
+	test('should return false if the file path is for versionless docs', () => {
 		const filePath =
 			'content/terraform-docs-common/docs/cloud-docs/cost-estimation/gcp.mdx'
 		const version = getVersionFromFilePath(filePath)
-		expect(version).toBeNull()
+		expect(version).toBe(false)
 	})
 })