@ethima/semantic-release-configuration 3.3.4 → 4.0.0

package/README.md

@@ -13,7 +13,7 @@ configuration supporting a range of languages and platforms supported by the
   Commits specification][conventionalcommits-url].
 - Generates release notes using
   [`@semantic-release/release-notes-generator`][semantic-release-notes-generator-plugin-url].
-- Updates templated content in a project's root-level `README.md` file
+- Updates templated content in files, e.g. a project's root-level `README.md`,
   with updated version information using
   [`@google/semantic-release-replace-plugin`][semantic-release-replace-plugin-url]
   and [`@semantic-release/git`][semantic-release-git-plugin-url].
@@ -106,39 +106,50 @@ The configuration is not able to automatically register releases with the
 General registry. Newly created releases should be registered using [JuliaHub's
 _Register Packages_ interface][juliahub-register-package-url].
 
-### Templated Content in `README.md` Files
+### Templated Content in Files
 
 The configuration will look for `__NEXT_SEMANTIC_RELEASE_VERSION__` tokens in
-templates in a project's root-level `README.md` and replace them with the
-version that is being released. This is, for instance, useful for automatically
-keeping installation instructions up-to-date.
+templates in files specified in the `files_with_versioned_templates`
+configuration and replace them with the version that is being released. This
+is, for instance, useful for automatically keeping installation instructions
+up-to-date. The configuration defaults to a project's root-level `README.md`.
 
-Templated content is created using HTML comments and has the following
-structure:
+Templated content has the following token-based structure:
 
-- A `<!-- START_VERSIONED_TEMPLATE` token,
+- A `BEGIN_VERSIONED_TEMPLATE` token,
 - the template itself with one or more
   `__NEXT_SEMANTIC_RELEASE_VERSION__` tokens,
-- a comment closing tag `-->`,
-- (optionally) content that was previously templated,
-- a comment closing the templated content `<!-- END_VERSIONED_TEMPLATE -->`.
-
-More concretely a section in a `README` that looks like
+- an `END_VERSIONED_TEMPLATE` token,
+- (optionally) content that was previously templated and which will be
+  discarded,
+- an `END_VERSIONED_TEMPLATE_REPLACEMENT` token.
+
+The `BEGIN_VERSIONED_TEMPLATE`, `END_VERSIONED_TEMPLATE` and
+`END_VERSIONED_TEMPLATE_REPLACEMENT` tokens must each be on their own line.
+These lines may be indented and contain other content that is exempt from
+replacements, e.g. comment markers to ensure the templates do not affect
+surrounding code or documentation. The exact tokens may differ per file-type,
+[see the source code for available
+configurations](./src/versioned-templates.js). For instance, Markdown files can
+use HTML block comments and may replace the literal `END_VERSIONED_TEMPLATE`
+token with an "end comment" token.
+
+More concretely a section in a `README.md` that looks like
 
 ```markdown
-<!-- START_VERSIONED_TEMPLATE
+<!-- BEGIN_VERSIONED_TEMPLATE
 
 The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!
 
 -->
-<!-- END_VERSIONED_TEMPLATE -->
+<!-- END_VERSIONED_TEMPLATE_REPLACEMENT -->
 ```
 
 would, after a v1.2.3 release using the configuration has been triggered,
 become
 
 ```markdown
-<!-- START_VERSIONED_TEMPLATE
+<!-- BEGIN_VERSIONED_TEMPLATE
 
 The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION__!
 
@@ -146,7 +157,7 @@ The next semantically released version will be v__NEXT_SEMANTIC_RELEASE_VERSION_
 
 The next semantically released version will be v1.2.3!
 
-<!-- END_VERSIONED_TEMPLATE -->
+<!-- END_VERSIONED_TEMPLATE_REPLACEMENT -->
 ```
 
 Note that the `v` is in the template! The version as derived by the semantic
@@ -182,7 +193,7 @@ including a non-visible whitespace character, e.g. [a _Zero Width Non-Joiner
 (ZWNJ)_ character](https://unicode-table.com/en/200C/). A sufficient approach
 is to modify the starting token, so that the template is no longer recognized
 as one. Using the suggested ZWNJ character the starting token becomes
-`<!--‌ START_VERSIONED_TEMPLATE`.
+`<!--‌ BEGIN_VERSIONED_TEMPLATE`.
 
 Note that when using this approach, although the templates/tokens _visually_
 look like versions that should be replaced, they cannot be copied and pasted as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethima/semantic-release-configuration",
-  "version": "3.3.4",
+  "version": "4.0.0",
   "description": "A shareable semantic release configuration supporting a range of languages and platforms supported by the Ethima organization.",
   "main": "./src/index.js",
   "repository": {
@@ -24,6 +24,6 @@
     "@semantic-release/github": "8.0.7",
     "@semantic-release/gitlab": "12.0.1",
     "conventional-changelog-conventionalcommits": "5.0.0",
-    "cosmiconfig": "8.1.0"
+    "cosmiconfig": "8.1.3"
   }
 }

package/src/versioned-templates.js

@@ -1,42 +1,229 @@
-const BLOCK_COMMENT_END_PATTERN = "-->";
-const BLOCK_COMMENT_START_PATTERN = "<!--";
-const TEMPLATE_VERSION_PLACEHOLDER = "__NEXT_SEMANTIC_RELEASE_VERSION__";
-
-const templateMatcher = new RegExp(
-  [
-    `(${BLOCK_COMMENT_START_PATTERN}\\s*START_VERSIONED_TEMPLATE\\s*)`,
-    "(.*?)", // The template to insert the version into
-    `(\\s*${BLOCK_COMMENT_END_PATTERN})`,
-    ".*?", // The templated content, will be discarded
-    `(${BLOCK_COMMENT_START_PATTERN}\\s*END_VERSIONED_TEMPLATE\\s*${BLOCK_COMMENT_END_PATTERN})`,
-  ].join(""),
-  "gms"
-);
-
-function templateReplacer(
-  _,
-  templateStartMarker,
+const { extname } = require("node:path");
+
+/**
+ * The default configuration for tokens used by the {@link buildReplacement}
+ * and {@link buildTemplateMatcher} functions to parse templates and perform
+ * replacements.
+ *
+ * The tokens serve the following purposes:
+ * - `next_version_placeholder_token` represents locations in a template that
+ *   need to be replaced by the version of the next semantic release.
+ * - `replacement_end_token` represents the end of content that was previously
+ *   filled in. Should be on a separate line. This line may contain additional
+ *   content which will be maintained along with the token in the replaced
+ *   content, e.g. indentation, comment markers, etc..
+ * - `template_begin_token` indicates the start of the template in which
+ *   `next_version_placeholder_token`s should be replaced. Should be on a
+ *   separate line. This line may contain additional content which will be
+ *   maintained along with the token in the replaced content, e.g. indentation,
+ *   comment markers, etc..
+ * - `template_continuation_token` represents indented markers that are
+ *   necessary to indicate continuation of the template, but which should not
+ *   be present in the replaced content, e.g. comment indicators for line-based
+ *   comments, etc. Indented whitespace does not have to be configured in the
+ *   token.
+ * - `template_end_token` indicates the end of the template. Should be on a
+ *   separate line. This line may contain additional content which will be
+ *   maintained along with the token in the replaced content, e.g. indentation,
+ *   comment markers, etc..
+ */
+const DEFAULT_TEMPLATE_TOKEN_CONFIGURATION = {
+  next_version_placeholder_token: "__NEXT_SEMANTIC_RELEASE_VERSION__",
+  replacement_end_token: "END_VERSIONED_TEMPLATE_REPLACEMENT",
+  template_begin_token: "BEGIN_VERSIONED_TEMPLATE",
+  template_continuation_token: "",
+  template_end_token: "END_VERSIONED_TEMPLATE",
+};
+
+/**
+ * Template token configuration for files that can be commented using "C-style
+ * comments", e.g. C, CSS, JavaScript, TypeScript, etc.
+ */
+const C_BLOCK_TEMPLATE_TOKEN_CONFIGURATION = {
+  template_continuation_token: "\\s\\*+",
+  template_end_token: "\\*+/",
+};
+
+/**
+ * Template token configuration for files that can be commented using "hash
+ * signs", e.g. Python, TOML, YAML, etc.
+ */
+const HASH_TEMPLATE_TOKEN_CONFIGURATION = {
+  template_continuation_token: "#",
+};
+
+/**
+ * Template token configuration for files that can be commented using XML
+ * comments, e.g. HTML, Markdown, etc.
+ */
+const XML_TEMPLATE_TOKEN_CONFIGURATION = {
+  template_end_token: "-->",
+};
+
+/**
+ * Maps file extensions to token configurations for templates that can be
+ * included in the specified file formats.
+ */
+const FILE_EXTENSION_TO_TEMPLATE_CONFIGURATION = {
+  c: C_BLOCK_TEMPLATE_TOKEN_CONFIGURATION,
+  css: C_BLOCK_TEMPLATE_TOKEN_CONFIGURATION,
+  html: XML_TEMPLATE_TOKEN_CONFIGURATION,
+  jl: HASH_TEMPLATE_TOKEN_CONFIGURATION,
+  js: C_BLOCK_TEMPLATE_TOKEN_CONFIGURATION,
+  md: XML_TEMPLATE_TOKEN_CONFIGURATION,
+  py: HASH_TEMPLATE_TOKEN_CONFIGURATION,
+  toml: HASH_TEMPLATE_TOKEN_CONFIGURATION,
+  ts: C_BLOCK_TEMPLATE_TOKEN_CONFIGURATION,
+  xml: XML_TEMPLATE_TOKEN_CONFIGURATION,
+  yaml: HASH_TEMPLATE_TOKEN_CONFIGURATION,
+  yml: HASH_TEMPLATE_TOKEN_CONFIGURATION,
+};
+
+/**
+ * Builds a replacement string from the components matched by a matcher created
+ * by {@link buildTemplateMatcher}. Any `next_version_placeholder_token`s, as
+ * identified by the {@link DEFAULT_TEMPLATE_TOKEN_CONFIGURATION}, are replaced
+ * by the next semantic release version. Any "template continuation tokens" are
+ * removed from the template using {@link stripTemplateContinuationTokens}.
+ */
+function buildReplacement(
+  // Only grab the tokens of interest that should be included in the
+  // replacement string. These are obtained from the match instead of the
+  // configuration to ensure additional information in the templated area is
+  // preserved, e.g. whitespace, etc.
+  _, // Full match
+  template_begin,
   template,
-  templateEndMarker,
-  templateCloseMarker,
-  ...args
+  template_end,
+  replacement_end,
+  _, // Index of match start
+  _, // Searched text
+  filename,
+  context
 ) {
-  const context = args.pop();
+  const { next_version_placeholder_token, template_continuation_token } =
+    getTemplateTokenConfiguration(filename);
+
+  const normalized_template = stripTemplateContinuationTokens(
+    template_continuation_token,
+    template
+  );
 
   return [
-    templateStartMarker,
+    template_begin,
     template,
-    templateEndMarker,
-    `\n\n`,
-    template.replaceAll(
-      TEMPLATE_VERSION_PLACEHOLDER,
+    template_end,
+    normalized_template.replaceAll(
+      next_version_placeholder_token,
       context.nextRelease.version
     ),
-    `\n\n`,
-    templateCloseMarker,
+    replacement_end,
   ].join("");
 }
 
+/**
+ * Builds a regular expression to find templated regions in a file. Templated
+ * regions are defined by a token configuration based on the {@param filename}'s
+ * extension.
+ *
+ * The resulting regular expression is set up to capture:
+ * - The line starting the template,
+ * - One or more lines defining the template in which
+ *   `next_version_placeholder_token` should be replaced by the next semantic
+ *   release version,
+ * - The line indicating the end of the template.
+ * - The line indicating the end of the replacement.
+ *
+ * Any content between the end of the template and the end of the replacement
+ * is dropped.
+ */
+function buildTemplateMatcher(filename) {
+  const { replacement_end_token, template_begin_token, template_end_token } =
+    getTemplateTokenConfiguration(filename);
+
+  return new RegExp(
+    [
+      `(\n[^\n]*${template_begin_token}[^\n]*)`,
+      // The template to insert the version into. Needs to lazily match to
+      // ensure only content up until the first `template_end_token` is matched
+      // to prevent issues when multiple templates are present in a single file
+      "((?:\n[^\n]*?)+?)",
+      `(\n[^\n]*${template_end_token}[^\n]*)`,
+      // The templated content, will be discarded. Needs to lazily match to
+      // ensure only content up until the first `replacement_end_token` is
+      // grabbed
+      ".*?",
+      `(\n[^\n]*${replacement_end_token}[^\n]*?)`,
+    ].join(""),
+    "gs"
+  );
+}
+
+/**
+ * Returns the template token configuration corresponding to the specified
+ * {@param filename} based on its extension. Extension specific configuration
+ * is merged with the {@link DEFAULT_TEMPLATE_TOKEN_CONFIGURATION}
+ */
+function getTemplateTokenConfiguration(filename) {
+  // `extname` returns the extension with a dot-prefix
+  return {
+    ...DEFAULT_TEMPLATE_TOKEN_CONFIGURATION,
+    ...FILE_EXTENSION_TO_TEMPLATE_CONFIGURATION[extname(filename).slice(1)],
+  };
+}
+
+/**
+ * Strips the {@param template_continuation_token} and the largest common
+ * length of whitespace after those tokens from the {@param template}.
+ *
+ * For instance, assuming the {@param template_continuation_token} is `#`, this
+ * will turn
+ * ```
+ *   #   Foo bar
+ *   #      Quuz Quux
+ * ```
+ * into
+ * ```
+ *   Foo bar
+ *      Quuz Quux
+ * ```
+ */
+function stripTemplateContinuationTokens(
+  template_continuation_token,
+  template
+) {
+  // The capture group is only necessary when using this matcher in the context
+  // of replacement, i.e. where all the matched content should be replaced by
+  // the indentation. It is used in that context and for determining the
+  // largest common whitespace prefix for each line in the template
+  const indented_continuation_token_matcher = `^(\\s*)${template_continuation_token}`;
+  const continuation_prefix_matcher = new RegExp(
+    `${indented_continuation_token_matcher}(?<prefix>\\s*)`
+  );
+
+  const prefix_lengths = template
+    .split("\n")
+    // The first line in the template will be empty when splitting on newlines,
+    // due to the way the matchers are set up to match on starting newlines
+    .slice(1)
+    .map((template_line) => {
+      const match = template_line.match(continuation_prefix_matcher);
+      return match?.groups?.prefix?.length ?? 0;
+    });
+
+  const largest_common_prefix_matcher = new RegExp(
+    `${indented_continuation_token_matcher}\\s{${Math.min(...prefix_lengths)}}`,
+    "gm"
+  );
+
+  return template.replaceAll(largest_common_prefix_matcher, "$1");
+}
+
+/**
+ * Returns the semantic release configuration for the
+ * `@google/semantic-release-replace-plugin` set up to replace specific tokens
+ * with the next semantic release version in the provided {@param files}.
+ */
 function VersionedTemplatesConfiguration(files) {
   return [
     "@google/semantic-release-replace-plugin",
@@ -45,8 +232,8 @@ function VersionedTemplatesConfiguration(files) {
         {
           countMatches: true,
           files,
-          from: templateMatcher,
-          to: templateReplacer,
+          from: buildTemplateMatcher,
+          to: buildReplacement,
         },
       ],
     },