feat: Add module reference mode configuration for Terraform module documentation (#283)

- Implemented `module-ref-mode` input to control how module versions are referenced in generated documentation (options: "tag" or "sha").
- Updated `configureGitAuthentication` function to handle GitHub token authentication for HTTPS operations.
- Enhanced tests for `configureGitAuthentication` to cover various scenarios including error handling and domain-specific configurations.
- Modified `generateWikiFiles` function to utilize the new `moduleRefMode` configuration, adjusting the reference format based on the selected mode.
- Refactored `TerraformModule` class to store tags as objects containing both name and commit SHA, allowing for better version management.
- Updated metadata and constants to include new module reference mode options and validation.
- Adjusted action YAML to include new input for `module-ref-mode` with appropriate descriptions.

Co-authored-by: Mark Johnson <739719+virgofx@users.noreply.github.com>

Author: Copilot

.github/workflows/ci.yml

@@ -57,7 +57,8 @@ jobs:
           module-asset-exclude-patterns: .gitignore,*.md,*.tftest.hcl,tests/**
           use-ssh-source-format: true
           tag-directory-separator: "-"
-          use-version-prefix: false
+          use-version-prefix: true
+          module-ref-mode: tag
 
       - name: Test Action Outputs
         id: test-outputs

README.md

@@ -226,6 +226,28 @@ describe('config', () => {
         new TypeError("Default first tag must be in format v#.#.# or #.#.# (e.g., v1.0.0 or 1.0.0). Got: 'v1.0'"),
       );
     });
+
+    it('should throw error for invalid module-ref-mode', () => {
+      setupTestInputs({ 'module-ref-mode': 'invalid' });
+      expect(() => getConfig()).toThrow(new TypeError("Invalid module_ref_mode 'invalid'. Must be one of: tag, sha"));
+
+      clearConfigForTesting();
+      vi.unstubAllEnvs();
+      setupTestInputs({ 'module-ref-mode': 'TAG' });
+      expect(() => getConfig()).toThrow(new TypeError("Invalid module_ref_mode 'TAG'. Must be one of: tag, sha"));
+    });
+
+    it('should allow valid module-ref-mode values', () => {
+      setupTestInputs({ 'module-ref-mode': 'tag' });
+      let config = getConfig();
+      expect(config.moduleRefMode).toBe('tag');
+
+      clearConfigForTesting();
+      vi.unstubAllEnvs();
+      setupTestInputs({ 'module-ref-mode': 'sha' });
+      config = getConfig();
+      expect(config.moduleRefMode).toBe('sha');
+    });
   });
 
   describe('initialization', () => {
@@ -256,6 +278,7 @@ describe('config', () => {
       expect(config.useSSHSourceFormat).toBe(false);
       expect(config.tagDirectorySeparator).toBe('/');
       expect(config.useVersionPrefix).toBe(true);
+      expect(config.moduleRefMode).toBe('tag');
 
       expect(startGroup).toHaveBeenCalledWith('Initializing Config');
       expect(startGroup).toHaveBeenCalledTimes(1);
@@ -275,6 +298,7 @@ describe('config', () => {
         ['Use SSH Source Format: false'],
         ['Tag Directory Separator: /'],
         ['Use Version Prefix: true'],
+        ['Module Ref Mode: tag'],
       ]);
     });
   });

__tests__/config.test.ts

@@ -1,5 +1,29 @@
 import { TerraformModule } from '@/terraform-module';
-import type { CommitDetails, GitHubRelease } from '@/types';
+import type { CommitDetails, GitHubRelease, GitHubTag } from '@/types';
+
+/**
+ * Helper function to create a GitHubTag from a tag name.
+ * Generates a fake commit SHA for testing purposes.
+ *
+ * @param name - The tag name
+ * @param commitSHA - Optional commit SHA (defaults to a hash of the tag name)
+ * @returns A GitHubTag object
+ */
+export function createMockTag(name: string, commitSHA?: string): GitHubTag {
+  // Generate a simple hash if no SHA provided
+  const defaultSHA = commitSHA ?? `sha${name.split('').reduce((acc, char) => acc + char.charCodeAt(0), 0)}`;
+  return { name, commitSHA: defaultSHA };
+}
+
+/**
+ * Helper function to create multiple GitHubTags from tag names.
+ *
+ * @param names - Array of tag names
+ * @returns Array of GitHubTag objects
+ */
+export function createMockTags(names: string[]): GitHubTag[] {
+  return names.map((name) => createMockTag(name));
+}
 
 /**
  * Helper function to create a TerraformModule instance for testing.
@@ -9,7 +33,7 @@ import type { CommitDetails, GitHubRelease } from '@/types';
  * @param options.latestTag - Optional latest tag for the module
  * @param options.commits - Optional array of commit details
  * @param options.commitMessages - Optional array of commit messages (will create commits)
- * @param options.tags - Optional array of tags
+ * @param options.tags - Optional array of tag names (will be converted to GitHubTag objects)
  * @param options.releases - Optional array of releases
  * @returns A configured TerraformModule instance for testing
  */
@@ -39,7 +63,8 @@ export function createMockTerraformModule(options: {
     module.addCommit(commit);
   }
 
-  module.setTags(tags);
+  // Convert string tags to GitHubTag objects
+  module.setTags(createMockTags(tags));
   module.setReleases(releases);
 
   return module;

__tests__/helpers/terraform-module.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { config } from '@/mocks/config';
 import { context } from '@/mocks/context';
 import { parseTerraformModules } from '@/parser';
+import { createMockTags } from '@/tests/helpers/terraform-module';
 import type { CommitDetails, GitHubRelease } from '@/types';
 import { endGroup, info, startGroup } from '@actions/core';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -271,11 +272,11 @@ describe('parseTerraformModules', () => {
       writeFileSync(join(moduleDir, 'main.tf'), 'resource "aws_vpc" "main" {}');
 
       const tags = ['modules/vpc/v1.0.0', 'modules/vpc/v1.1.0', 'modules/sg/v1.0.0'];
-      const result = parseTerraformModules([], tags, []);
+      const result = parseTerraformModules([], createMockTags(tags), []);
 
       expect(result).toHaveLength(1);
       // Tags are sorted in descending order (newest first) by setTags method
-      expect(result[0].tags).toEqual(['modules/vpc/v1.1.0', 'modules/vpc/v1.0.0']);
+      expect(result[0].tags.map((t) => t.name)).toEqual(['modules/vpc/v1.1.0', 'modules/vpc/v1.0.0']);
     });
 
     it('should set releases on all modules using static method', () => {
@@ -325,15 +326,15 @@ describe('parseTerraformModules', () => {
         { id: 1, title: 'modules/vpc/v1.0.0', tagName: 'modules/vpc/v1.0.0', body: 'VPC release' },
         { id: 2, title: 'other/v1.0.0', tagName: 'other/v1.0.0', body: 'Other release' },
       ];
-      const result = parseTerraformModules([], tags, releases);
+      const result = parseTerraformModules([], createMockTags(tags), releases);
 
       expect(result).toHaveLength(2);
       const rdsModule = result.find((m) => m.name === 'modules/rds');
       const vpcModule = result.find((m) => m.name === 'modules/vpc');
 
-      expect(rdsModule?.tags).toEqual(['modules/rds/v2.0.0']);
+      expect(rdsModule?.tags.map((t) => t.name)).toEqual(['modules/rds/v2.0.0']);
       expect(rdsModule?.releases).toEqual([]);
-      expect(vpcModule?.tags).toEqual(['modules/vpc/v1.1.0', 'modules/vpc/v1.0.0']); // Descending order
+      expect(vpcModule?.tags.map((t) => t.name)).toEqual(['modules/vpc/v1.1.0', 'modules/vpc/v1.0.0']); // Descending order
       expect(vpcModule?.releases).toEqual([releases[0]]);
     });
 
@@ -346,7 +347,7 @@ describe('parseTerraformModules', () => {
       const releases: GitHubRelease[] = [
         { id: 1, title: 'modules/vpc/v1.0.0', tagName: 'modules/vpc/v1.0.0', body: 'VPC release' },
       ];
-      const result = parseTerraformModules([], tags, releases);
+      const result = parseTerraformModules([], createMockTags(tags), releases);
 
       expect(result).toHaveLength(1);
       expect(result[0].name).toBe('modules/networking');

__tests__/parser.test.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { context } from '@/mocks/context';
@@ -23,6 +24,8 @@ vi.mock('node:fs', () => ({
   readdirSync: vi.fn().mockImplementation(() => []),
 }));
 
+const execFileSyncMock = vi.mocked(execFileSync);
+
 describe('releases', () => {
   const url = 'https://api.github.com/repos/techpivot/terraform-module-releaser/releases';
   const mockListReleasesResponse = {
@@ -294,6 +297,14 @@ describe('releases', () => {
       context.set({
         workspaceDir: '/workspace',
       });
+      execFileSyncMock.mockReset();
+      execFileSyncMock.mockImplementation((_file, args) => {
+        if (Array.isArray(args) && args.includes('rev-parse')) {
+          return Buffer.from('abc123def456');
+        }
+
+        return Buffer.from('');
+      });
       mockTerraformModule = createMockTerraformModule({
         directory: '/workspace/path/to/test-module',
         commits: [
@@ -327,6 +338,7 @@ describe('releases', () => {
           name: 'path/to/test-module/v1.1.0',
           body: 'Mock changelog content',
           tag_name: 'path/to/test-module/v1.1.0',
+          target_commitish: 'abc123def456',
           draft: false,
           prerelease: false,
         },
@@ -352,19 +364,33 @@ describe('releases', () => {
         },
         ...originalReleases,
       ]);
-      expect(mockTerraformModule.setTags).toHaveBeenCalledWith(['path/to/test-module/v1.1.0', ...originalTags]);
+      expect(mockTerraformModule.setTags).toHaveBeenCalledWith([
+        {
+          name: 'path/to/test-module/v1.1.0',
+          commitSHA: 'abc123def456',
+        },
+        ...originalTags,
+      ]);
       expect(mockTerraformModule.needsRelease()).toBe(false);
       expect(startGroup).toHaveBeenCalledWith('Creating releases & tags for modules');
       expect(endGroup).toHaveBeenCalled();
     });
 
     it('should handle null/undefined name and body from GitHub API response', async () => {
+      execFileSyncMock.mockImplementation((_file, args) => {
+        if (Array.isArray(args) && args.includes('rev-parse')) {
+          return Buffer.from('def456abc789');
+        }
+
+        return Buffer.from('');
+      });
       const mockRelease = {
         data: {
           id: 789012,
           name: null, // Simulate GitHub API returning null for name
           body: undefined, // Simulate GitHub API returning undefined for body
           tag_name: 'path/to/test-module/v1.1.0',
+          target_commitish: 'def456abc789',
           draft: false,
           prerelease: false,
         },
@@ -390,7 +416,13 @@ describe('releases', () => {
       expect(newRelease.body).toContain('v1.1.0'); // Should fall back to generated changelog since body is undefined
       expect(newRelease.body).toContain('feat: Add new feature'); // Should contain the commit message
 
-      expect(mockTerraformModule.setTags).toHaveBeenCalledWith(['path/to/test-module/v1.1.0', ...originalTags]);
+      expect(mockTerraformModule.setTags).toHaveBeenCalledWith([
+        {
+          name: 'path/to/test-module/v1.1.0',
+          commitSHA: 'def456abc789',
+        },
+        ...originalTags,
+      ]);
       expect(endGroup).toHaveBeenCalled();
     });
 

__tests__/releases.test.ts

@@ -29,11 +29,14 @@ describe('tags', () => {
 
       expect(Array.isArray(tags)).toBe(true);
 
-      // Known tags
+      // Extract tag names from the tag objects
+      const tagNames = tags.map((tag) => tag.name);
+
+      // Known tags that should exist in the repository
       const knownTags = ['v1.3.1', 'v1.3.0', 'v1.2.0', 'v1.1.1', 'v1.1.0', 'v1.0.1', 'v1.0.0', 'v1'];
       // Ensure all known tags are present in the fetched tags using a for...of loop
       for (const tag of knownTags) {
-        expect(tags).toContain(tag);
+        expect(tagNames).toContain(tag);
       }
 
       expect(startGroup).toHaveBeenCalledWith('Fetching repository tags');
@@ -74,8 +77,14 @@ describe('tags', () => {
     });
 
     it('should fetch all available tags when pagination is required', async () => {
-      const mockTagData = { data: [{ name: 'v2.0.0' }, { name: 'v2.0.1' }, { name: 'v2.0.2' }] };
-      const expectedTags = mockTagData.data.map((tag) => tag.name);
+      const mockTagData = {
+        data: [
+          { name: 'v2.0.0', commit: { sha: 'abc123' } },
+          { name: 'v2.0.1', commit: { sha: 'def456' } },
+          { name: 'v2.0.2', commit: { sha: 'ghi789' } },
+        ],
+      };
+      const expectedTags = mockTagData.data.map((tag) => ({ name: tag.name, commitSHA: tag.commit.sha }));
 
       stubOctokitReturnData('repos.listTags', mockTagData);
       const tags = await getAllTags({ per_page: 1 });
@@ -88,15 +97,16 @@ describe('tags', () => {
 
       // Additional assertions to verify pagination calls and debug info
       expect(info).toHaveBeenCalledWith('Found 3 tags.');
+      // Debug logs the tags array with {name, commitSHA} structure
       expect(vi.mocked(debug).mock.calls).toEqual([
         ['Total page requests: 3'],
         [JSON.stringify(expectedTags, null, 2)],
       ]);
     });
 
     it('should output singular "tag" when only one', async () => {
-      const mockTagData = { data: [{ name: 'v4.0.0' }] };
-      const expectedTags = mockTagData.data.map((tag) => tag.name);
+      const mockTagData = { data: [{ name: 'v4.0.0', commit: { sha: 'abc123' } }] };
+      const expectedTags = mockTagData.data.map((tag) => ({ name: tag.name, commitSHA: tag.commit.sha }));
 
       stubOctokitReturnData('repos.listTags', mockTagData);
       const tags = await getAllTags({ per_page: 1 });
@@ -116,7 +126,13 @@ describe('tags', () => {
     });
 
     it('should fetch all available tags when pagination is not required', async () => {
-      stubOctokitReturnData('repos.listTags', { data: [{ name: 'v2.0.0' }, { name: 'v2.0.1' }, { name: 'v2.0.2' }] });
+      stubOctokitReturnData('repos.listTags', {
+        data: [
+          { name: 'v2.0.0', commit: { sha: 'abc123' } },
+          { name: 'v2.0.1', commit: { sha: 'def456' } },
+          { name: 'v2.0.2', commit: { sha: 'ghi789' } },
+        ],
+      });
 
       const tags = await getAllTags({ per_page: 20 });
 
@@ -125,7 +141,7 @@ describe('tags', () => {
 
       // Exact match of known tags to ensure no unexpected tags are included
       const expectedTags = ['v2.0.0', 'v2.0.1', 'v2.0.2'];
-      expect(tags).toEqual(expectedTags);
+      expect(tags.map((t) => t.name)).toEqual(expectedTags);
 
       // Additional assertions to verify pagination calls and debug info
       expect(debug).toHaveBeenCalledWith(expect.stringMatching(/Total page requests: 1/));