Add all generated files to techdocs_metadata.json

Signed-off-by: Eric Peterson <ericpeterson@spotify.com>

packages/techdocs-common/src/stages/generate/helpers.test.ts

@@ -23,7 +23,7 @@ import os from 'os';
 import path, { resolve as resolvePath } from 'path';
 import { ParsedLocationAnnotation } from '../../helpers';
 import {
-  addBuildTimestampMetadata,
+  createOrUpdateMetadata,
   getGeneratorKey,
   getMkdocsYml,
   getRepoUrlFromLocationAnnotation,
@@ -369,13 +369,15 @@ describe('helpers', () => {
   });
 
   describe('addBuildTimestampMetadata', () => {
+    const mockFiles = {
+      'invalid_techdocs_metadata.json': 'dsds',
+      'techdocs_metadata.json': '{"site_name": "Tech Docs"}',
+    };
+
     beforeEach(() => {
       mockFs.restore();
       mockFs({
-        [rootDir]: {
-          'invalid_techdocs_metadata.json': 'dsds',
-          'techdocs_metadata.json': '{"site_name": "Tech Docs"}',
-        },
+        [rootDir]: mockFiles,
       });
     });
 
@@ -385,7 +387,7 @@ describe('helpers', () => {
 
     it('should create the file if it does not exist', async () => {
       const filePath = path.join(rootDir, 'wrong_techdocs_metadata.json');
-      await addBuildTimestampMetadata(filePath, mockLogger);
+      await createOrUpdateMetadata(filePath, mockLogger);
 
       // Check if the file exists
       await expect(
@@ -397,18 +399,28 @@ describe('helpers', () => {
       const filePath = path.join(rootDir, 'invalid_techdocs_metadata.json');
 
       await expect(
-        addBuildTimestampMetadata(filePath, mockLogger),
+        createOrUpdateMetadata(filePath, mockLogger),
       ).rejects.toThrowError('Unexpected token d in JSON at position 0');
     });
 
     it('should add build timestamp to the metadata json', async () => {
       const filePath = path.join(rootDir, 'techdocs_metadata.json');
 
-      await addBuildTimestampMetadata(filePath, mockLogger);
+      await createOrUpdateMetadata(filePath, mockLogger);
 
       const json = await fs.readJson(filePath);
       expect(json.build_timestamp).toBeLessThanOrEqual(Date.now());
     });
+
+    it('should add list of files to the metadata json', async () => {
+      const filePath = path.join(rootDir, 'techdocs_metadata.json');
+
+      await createOrUpdateMetadata(filePath, mockLogger);
+
+      const json = await fs.readJson(filePath);
+      expect(json.files[0]).toEqual(Object.keys(mockFiles)[0]);
+      expect(json.files[1]).toEqual(Object.keys(mockFiles)[1]);
+    });
   });
 
   describe('storeEtagMetadata', () => {

packages/techdocs-common/src/stages/generate/helpers.ts

@@ -27,6 +27,7 @@ import { PassThrough, Writable } from 'stream';
 import { Logger } from 'winston';
 import { ParsedLocationAnnotation } from '../../helpers';
 import { SupportedGeneratorKey } from './types';
+import { getFileTreeRecursively } from '../publish/helpers';
 
 // TODO: Implement proper support for more generators.
 export function getGeneratorKey(entity: Entity): SupportedGeneratorKey {
@@ -345,14 +346,20 @@ export const patchIndexPreBuild = async ({
 };
 
 /**
- * Update the techdocs_metadata.json to add a new build timestamp metadata. Create the .json file if it doesn't exist.
+ * Create or update the techdocs_metadata.json. Values initialized/updated are:
+ * - The build_timestamp (now)
+ * - The list of files generated
  *
  * @param {string} techdocsMetadataPath File path to techdocs_metadata.json
  */
-export const addBuildTimestampMetadata = async (
+export const createOrUpdateMetadata = async (
   techdocsMetadataPath: string,
   logger: Logger,
 ): Promise<void> => {
+  const techdocsMetadataDir = techdocsMetadataPath
+    .split(path.sep)
+    .slice(0, -1)
+    .join(path.sep);
   // check if file exists, create if it does not.
   try {
     await fs.access(techdocsMetadataPath, fs.constants.F_OK);
@@ -372,6 +379,19 @@ export const addBuildTimestampMetadata = async (
   }
 
   json.build_timestamp = Date.now();
+
+  // Get and write generated files to the metadata JSON. Each file string is in
+  // a form appropriate for invalidating the associated object from cache.
+  try {
+    json.files = (await getFileTreeRecursively(techdocsMetadataDir)).map(file =>
+      file.replace(`${techdocsMetadataDir}/`, ''),
+    );
+  } catch (err) {
+    assertError(err);
+    json.files = [];
+    logger.warn(`Unable to add files list to metadata: ${err.message}`);
+  }
+
   await fs.writeJson(techdocsMetadataPath, json);
   return;
 };

packages/techdocs-common/src/stages/generate/techdocs.ts

@@ -23,7 +23,7 @@ import {
   ScmIntegrations,
 } from '@backstage/integration';
 import {
-  addBuildTimestampMetadata,
+  createOrUpdateMetadata,
   getMkdocsYml,
   patchIndexPreBuild,
   patchMkdocsYmlPreBuild,
@@ -164,9 +164,9 @@ export class TechdocsGenerator implements GeneratorBase {
      * Post Generate steps
      */
 
-    // Add build timestamp to techdocs_metadata.json
+    // Add build timestamp and files to techdocs_metadata.json
     // Creates techdocs_metadata.json if file does not exist.
-    await addBuildTimestampMetadata(
+    await createOrUpdateMetadata(
       path.join(outputDir, 'techdocs_metadata.json'),
       childLogger,
     );

packages/techdocs-common/src/stages/publish/types.ts

@@ -65,6 +65,8 @@ export type TechDocsMetadata = {
   site_name: string;
   site_description: string;
   etag: string;
+  build_timestamp: number;
+  files?: string[];
 };
 
 export type MigrateRequest = {