feat: enhance tag generation configuration with detailed descriptions and examples for directory separator and version prefix options

Author: virgofx

.github/workflows/ci.yml

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

README.md

@@ -199,6 +199,8 @@ configuring the following optional input parameters as needed.
 | `module-change-exclude-patterns` | Comma-separated list of file patterns (relative to each module) to exclude from triggering version changes. Lets you release a module but control which files inside it do not force a version bump.<br><sub>[Read more here](#understanding-the-filtering-options)</sub>          | `.gitignore,*.md,*.tftest.hcl,tests/**` |
 | `module-asset-exclude-patterns`  | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
 | `use-ssh-source-format`          | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://[email protected]/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`)                                                            | `false`                                 |
+| `tag-directory-separator`        | Character used to separate directory path components in Git tags. Supports `/`, `-`, `_`, or `.`                                                                                                                                                                                      | `/`                                     |
+| `use-version-prefix`             | Whether to include the 'v' prefix on version tags (e.g., v1.2.3 vs 1.2.3)                                                                                                                                                                                                            | `true`                                  |
 
 ### Understanding the filtering options
 

action.yml

@@ -110,11 +110,24 @@ inputs:
     required: true
     default: ${{ github.token }}
   tag-directory-separator:
-    description: The separator character to use between module directory parts in the git tag.
+    description: >
+      Character used to separate directory path components in Git tags. This separator is used to convert 
+      module directory paths into tag names (e.g., 'modules/aws/s3-bucket' becomes 'modules-aws-s3-bucket-v1.0.0' 
+      when using '-'). Must be a single character from: /, -, _, or .
+      
+      Examples with different separators:
+      - "/" (default): modules/aws/s3-bucket/v1.0.0
+      - "-": modules-aws-s3-bucket-v1.0.0  
+      - "_": modules_aws_s3_bucket_v1.0.0
+      - ".": modules.aws.s3.bucket.v1.0.0
     required: true
     default: /
   use-version-prefix:
-    description: Whether to include the 'v' prefix on version tags (e.g., v1.2.3).
+    description: >
+      Whether to include the 'v' prefix on version tags (e.g., v1.2.3 vs 1.2.3). When enabled, all new version 
+      tags will include the 'v' prefix. For initial releases, this setting takes precedence over any 'v' prefix 
+      specified in the default-first-tag - if use-version-prefix is false and default-first-tag contains 'v', 
+      the 'v' will be automatically removed to ensure consistency.
     required: true
     default: "true"
 

src/config.ts

@@ -66,14 +66,19 @@ function initializeConfig(): Config {
         }'`,
       );
     }
-
     // Validate default first tag format
     if (!VERSION_TAG_REGEX.test(configInstance.defaultFirstTag)) {
       throw new TypeError(
         `Default first tag must be in format v#.#.# or #.#.# (e.g., v1.0.0 or 1.0.0). Got: '${configInstance.defaultFirstTag}'`,
       );
     }
 
+    // If we aren't using "v" prefix but the default first tag was specified with a "v"
+    // prefix, then strip this to enforce.
+    if (!configInstance.useVersionPrefix && configInstance.defaultFirstTag.startsWith('v')) {
+      configInstance.defaultFirstTag = configInstance.defaultFirstTag.substring(1);
+    }
+
     info(`Major Keywords: ${configInstance.majorKeywords.join(', ')}`);
     info(`Minor Keywords: ${configInstance.minorKeywords.join(', ')}`);
     info(`Patch Keywords: ${configInstance.patchKeywords.join(', ')}`);

src/terraform-module.ts

@@ -9,7 +9,6 @@ import {
   VALID_TAG_DIRECTORY_SEPARATORS,
   VERSION_TAG_REGEX,
 } from '@/utils/constants';
-import { removeTrailingCharacters } from '@/utils/string';
 import { endGroup, info, startGroup } from '@actions/core';
 
 /**
@@ -224,7 +223,7 @@ export class TerraformModule {
       return null;
     }
 
-    const match = latestTag.match(MODULE_TAG_REGEX);
+    const match = MODULE_TAG_REGEX.exec(latestTag);
 
     return match ? match[3] : null;
   }
@@ -471,7 +470,7 @@ export class TerraformModule {
       return null;
     }
 
-    return `${this.name}/${releaseTagVersion}`;
+    return `${this.name}${config.tagDirectorySeparator}${releaseTagVersion}`;
   }
 
   //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
@@ -617,29 +616,23 @@ export class TerraformModule {
    *
    * The function transforms the directory path by:
    * - Trimming whitespace
-   * - Replacing invalid characters with hyphens
-   * - Normalizing slashes
-   * - Removing leading/trailing slashes
-   * - Handling consecutive dots and hyphens
-   * - Removing any remaining whitespace
    * - Converting to lowercase (for consistency)
-   * - Removing trailing dots, hyphens, and underscores
+   * - Normalizing path separators (both backslashes and forward slashes) to the configured tag directory separator
+   * - Replacing invalid characters with hyphens (preserving only alphanumeric, "/", ".", "-", "_")
+   * - Normalizing consecutive special characters ("/", ".", "-", "_") to single instances
+   * - Removing leading/trailing special characters ("/", ".", "-", "_")
    *
    * @param {string} terraformDirectory - The relative directory path from which to generate the module name.
    * @returns {string} A valid Terraform module name based on the provided directory path.
    */
   public static getTerraformModuleNameFromRelativePath(terraformDirectory: string): string {
-    const cleanedDirectory = terraformDirectory
+    return terraformDirectory
       .trim()
-      .replace(/[^a-zA-Z0-9/_-]+/g, '-')
-      .replace(/\/{2,}/g, '/')
-      .replace(/\/\.+/g, '/')
-      .replace(/(^\/|\/$)/g, '')
-      .replace(/\.\.+/g, '.')
-      .replace(/--+/g, '-')
-      .replace(/\s+/g, '')
-      .toLowerCase();
-    return removeTrailingCharacters(cleanedDirectory, ['.', '-', '_']);
+      .toLowerCase()
+      .replace(/[/\\]/g, config.tagDirectorySeparator) // Normalize backslashes and forward slashes to configured separator
+      .replace(/[^a-zA-Z0-9/._-]+/g, '-') // Replace invalid characters with hyphens (preserve alphanumeric, /, ., _, -)
+      .replace(/[/._-]{2,}/g, (match) => match[0]) // Normalize consecutive special characters to single instances
+      .replace(/(^[/._-]+|[/._-]+$)/g, ''); // Remove leading/trailing special characters
   }
 
   /**

src/types/config.types.ts

@@ -105,21 +105,38 @@ export interface Config {
   useSSHSourceFormat: boolean;
 
   /**
-   * The character used to separate the module name from the version in tags.
+   * The character used to separate directory path components when creating Git tags from module paths.
+   * This separator is applied throughout the entire directory structure conversion process, not just 
+   * between the module name and version.
+   * 
    * Must be a single character and one of: -, _, /, .
    *
-   * Examples:
-   * - "/" (default): module/aws-s3-bucket/v1.0.0
-   * - "-": module-aws-s3-bucket-v1.0.0
-   * - "_": module_aws-s3-bucket_v1.0.0
-   * - ".": module.aws-s3-bucket.v1.0.0
+   * When converting a module path like 'modules/aws/s3-bucket' to a Git tag, this separator determines
+   * how directory separators (/) are replaced in the tag name portion:
+   * 
+   * Examples with module path 'modules/aws/s3-bucket' and version 'v1.0.0':
+   * - "/" (default): modules/aws/s3-bucket/v1.0.0
+   * - "-": modules-aws-s3-bucket-v1.0.0
+   * - "_": modules_aws_s3_bucket_v1.0.0
+   * - ".": modules.aws.s3-bucket.v1.0.0
+   * 
+   * This setting affects tag creation, tag parsing, and tag association logic throughout the system.
    */
   tagDirectorySeparator: string;
 
   /**
    * Whether to include the "v" prefix in version tags.
-   * When true (default), tags will be formatted as: module/v1.2.3
-   * When false, tags will be formatted as: module/1.2.3
+   * 
+   * When true (default), version tags will include the "v" prefix:
+   * - Example: module/v1.2.3
+   * 
+   * When false, version tags will not include the "v" prefix:
+   * - Example: module/1.2.3
+   * 
+   * For initial releases, this setting takes precedence over any "v" prefix specified in the 
+   * defaultFirstTag configuration. If useVersionPrefix is false and defaultFirstTag contains 
+   * a "v" prefix (e.g., "v1.0.0"), the "v" will be automatically removed to ensure consistency 
+   * with the useVersionPrefix setting (resulting in "1.0.0").
    */
   useVersionPrefix: boolean;
 }

src/types/metadata.types.ts

@@ -1,18 +1,41 @@
 import type { Config } from '@/types/config.types';
 
 /**
- * Metadata about GitHub Action inputs, including their types, defaults, and mapping to config properties.
- * This serves as the single source of truth for action configuration.
+ * Metadata definition for GitHub Action inputs that enables dynamic configuration mapping.
  *
- * @todo update doc - defaults at runtime come from action.yml, testing see helpers/inputs.ts
+ * This interface serves as the translation layer between GitHub Action inputs defined in
+ * action.yml and our internal Config type. It provides the necessary metadata to:
+ * - Parse input values according to their expected types
+ * - Map action inputs to the corresponding config property names
+ * - Enforce required/optional input validation
+ * - Support dynamic config creation in createConfigFromInputs()
+ *
+ * The metadata is used by the ACTION_INPUTS constant in metadata.ts to create a
+ * comprehensive mapping of all action inputs, which then drives the automatic
+ * config generation process.
+ *
+ * @see {@link /workspaces/terraform-module-releaser/src/utils/metadata.ts} for usage
+ * @see {@link https://docs.github.com/en/actions/reference/metadata-syntax-for-github-actions#inputs} GitHub Actions input reference
  */
 export interface ActionInputMetadata {
-  /** The config property name this input maps to */
+  /**
+   * The config property name this input maps to.
+   * Must be a valid key from the Config interface.
+   */
   configKey: keyof Config;
 
-  /** Whether this input is required */
+  /**
+   * Whether this input is required by the GitHub Action.
+   * When true, the action will fail if the input is not provided.
+   */
   required: boolean;
 
-  /** The input type for proper parsing */
+  /**
+   * The expected data type of the input for proper parsing and validation.
+   * - 'string': Direct string value
+   * - 'boolean': Parsed using getBooleanInput for proper true/false handling
+   * - 'number': Parsed using parseInt for integer conversion
+   * - 'array': Comma-separated string parsed into array with deduplication
+   */
   type: 'string' | 'boolean' | 'number' | 'array';
-}
+}

src/utils/constants.ts

@@ -44,8 +44,12 @@ export const VERSION_TAG_REGEX = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
  * - "module-v1.0.0" → ["module-v1.0.0", "module", "-", "v1.0.0", "1", "0", "0"]
  * - "feature_2.3.4" → ["feature_2.3.4", "feature", "_", "2.3.4", "2", "3", "4"]
  * - "service/v0.1.0" → ["service/v0.1.0", "service", "/", "v0.1.0", "0", "1", "0"]
+ *
+ * Note: In the character class [-_/.], only the dot (.) requires escaping to match literal periods.
+ * The hyphen (-) doesn't need escaping when at the start/end of the character class.
+ * The forward slash (/) doesn't need escaping in JavaScript regex character classes.
  */
-export const MODULE_TAG_REGEX = /^(.+)([-_\/\.])(v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*))$/;
+export const MODULE_TAG_REGEX = /^(.+)([-_/.])(v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*))$/;
 
 /**
  * Release type constants for semantic versioning