Merge pull request #108 from Araxeus/add-releaseRegex-config-option

Araxeus · web-flow · commit 88d0debf0818 · 2025-11-29T15:05:57.000+02:00
diff --git a/README.md b/README.md
@@ -24,6 +24,7 @@ Whether you're a web developer streamlining asset management or a power user aut
 - [Configuration](#configuration)
   - [Versioning Dependencies](#versioning-dependencies)
   - [GitHub Releases](#github-releases)
+  - [Filtering releases with releaseRegex](#filtering-releases-with-releaseregex)
 - [Default Configuration](#default-configuration)
 - [Commands](#commands)
   - [Sync](#sync)
@@ -216,6 +217,52 @@ To extract files from a compressed release archive, you can define an object tha
 }
 ```
 
+### Filtering releases with releaseRegex
+
+Vendorfiles can now filter release tags/titles when searching for the "latest" release using the `releaseRegex` option. This should be a JavaScript-style regular expression string (without surrounding `/` delimiters). The regex is tested against the release tag/name (and can be used to match release titles where appropriate) to restrict which releases are considered the “latest”.
+
+Use-cases:
+
+- Only consider semver tags: `"^v\\d+\\.\\d+\\.\\d+$"`
+- Ignore pre-releases with `-alpha`/`-beta`: `"^v(?!.*-(?:alpha|beta)).*"`
+- Prefer releases whose title contains `stable`: `"stable"`
+
+Examples:
+
+JSON example (per-dependency):
+
+```json
+{
+  "vendorDependencies": {
+    "fzf": {
+      "version": "0.38.0",
+      "repository": "https://github.com/junegunn/fzf",
+      "releaseRegex": "^v\\d+\\.\\d+\\.\\d+$",
+      "files": ["{release}/fzf-{version}-linux_amd64.tar.gz"]
+    }
+  }
+}
+```
+
+YAML example (global default and per-dep override):
+
+```yaml
+vendorConfig:
+  vendorFolder: .
+default:
+  releaseRegex: "^v\\d+\\.\\d+\\.\\d+$"
+vendorDependencies:
+  fzf:
+    repository: https://github.com/junegunn/fzf
+    files:
+      - "{release}/fzf-{version}-linux_amd64.tar.gz"
+```
+
+Notes:
+
+- If omitted, Vendorfiles considers all releases/tags when determining the latest release.
+- Use double escaping (e.g. `\\d`) in JSON strings.
+
 ## Default Configuration
 
 For shared options across dependencies, use a `default` object at the same level as `vendorConfig` and `vendorDependencies`. Here's an example:
diff --git a/lib/commands.ts b/lib/commands.ts
@@ -258,8 +258,6 @@ export async function install({
         typeof file === 'object' ? Object.entries(file) : file,
     );
 
-    const ref = newVersion; // TODO delete this after typescript bug is fixed (newVersion is not a string)
-
     type ReleaseFileOutput = string | { [input: string]: string };
 
     const releaseFiles: { input: string; output: ReleaseFileOutput }[] = [];
@@ -296,7 +294,7 @@ export async function install({
                 .getFile({
                     repo,
                     path: input,
-                    ref,
+                    ref: newVersion,
                 })
                 .catch(err => {
                     if (err?.status === 404) {
@@ -309,7 +307,7 @@ export async function install({
                                 typeof file === 'string' ? file : file[0]
                             }" from ${
                                 dependency.repository
-                            } with version ${ref}`,
+                            } with version ${newVersion}`,
                         );
                     }
                 });
@@ -323,7 +321,7 @@ export async function install({
     await Promise.all(
         // file.output is either a string that or an object which would mean that we want to extract the files from the downloaded archive
         releaseFiles.map(async file => {
-            const input = replaceVersion(file.input, ref).replace(
+            const input = replaceVersion(file.input, newVersion).replace(
                 '{release}/',
                 '',
             );
@@ -332,7 +330,8 @@ export async function install({
             const releaseFile = await github.downloadReleaseFile({
                 repo,
                 path: input,
-                version: ref,
+                version: newVersion,
+                releaseRegex: dependency.releaseRegex,
             });
 
             if (typeof output === 'object') {
@@ -372,7 +371,7 @@ export async function install({
                         inputPath = path.join(randomFolderName, inputPath);
                         outputPath = path.join(
                             depDirectory,
-                            replaceVersion(outputPath, ref),
+                            replaceVersion(outputPath, newVersion),
                         );
                         try {
                             await fs.access(inputPath);
@@ -397,7 +396,7 @@ export async function install({
             } else {
                 await readableToFile(
                     releaseFile,
-                    path.join(depDirectory, replaceVersion(output, ref)),
+                    path.join(depDirectory, replaceVersion(output, newVersion)),
                 );
             }
         }),
diff --git a/lib/github.ts b/lib/github.ts
@@ -1,5 +1,5 @@
 import { createOAuthDeviceAuth } from '@octokit/auth-oauth-device';
-import { Octokit } from '@octokit/rest';
+import { Octokit, type RestEndpointMethodTypes } from '@octokit/rest';
 import * as dotenv from 'dotenv';
 import getEnvPaths from 'env-paths';
 import _fetch, { type FetchOptions } from 'make-fetch-happen';
@@ -34,16 +34,23 @@ const octokit = () => {
     return _octokit;
 };
 
-const releases = new Map();
+const releases = new Map<
+    string,
+    RestEndpointMethodTypes['repos']['getReleaseByTag']['response']['data']
+>();
 async function getReleaseFromTag({
     owner,
     name,
     tag,
 }: Repository & { tag: string }) {
-    const key = `${owner}/${name}/${tag}`;
-    if (releases.has(key)) {
-        return releases.get(key);
+    const repo = `${owner}/${name}`;
+    const key = `${repo}/${tag}`;
+    for (const [k, release] of releases) {
+        if (k === key || (k.startsWith(repo) && release.tag_name === tag)) {
+            return release;
+        }
     }
+
     const res = await octokit().repos.getReleaseByTag({
         owner,
         repo: name,
@@ -54,11 +61,18 @@ async function getReleaseFromTag({
     return res.data;
 }
 
-export async function getLatestRelease({ owner, name: repo }: Repository) {
-    const key = `${owner}/${repo}/latest`;
-    if (releases.has(key)) {
-        return releases.get(key);
+export async function getLatestRelease(
+    { owner, name: repo }: Repository,
+    releaseRegex?: string,
+) {
+    if (releaseRegex) {
+        return getReleaseByRegex({ owner, name: repo }, releaseRegex);
     }
+    const key = `${owner}/${repo}/latest`;
+
+    const cached = releases.get(key);
+    if (cached !== undefined) return cached;
+
     const res = await octokit().repos.getLatestRelease({
         owner,
         repo,
@@ -68,6 +82,35 @@ export async function getLatestRelease({ owner, name: repo }: Repository) {
     return res.data;
 }
 
+export async function getReleaseByRegex(
+    { owner, name: repo }: Repository,
+    releaseRegex: string,
+) {
+    const key = `${owner}/${repo}/regex/${releaseRegex}`;
+
+    const cached = releases.get(key);
+    if (cached !== undefined) return cached;
+
+    const releasesList = await octokit().repos.listReleases({
+        owner,
+        repo,
+        per_page: 100,
+    });
+
+    const releaseRegexObj = new RegExp(releaseRegex);
+    const matchedRelease = releasesList.data.find(
+        release =>
+            releaseRegexObj.test(release.tag_name) ||
+            releaseRegexObj.test(release.name || ''),
+    );
+    if (matchedRelease) {
+        releases.set(key, matchedRelease);
+        return matchedRelease;
+    }
+
+    throw `No releases found matching ${releaseRegex.toString()} in ${owner}/${repo}`;
+}
+
 export async function getFileCommitSha({
     repo,
     path,
@@ -121,18 +164,23 @@ export async function downloadReleaseFile({
     repo,
     path,
     version,
+    releaseRegex,
 }: {
     repo: Repository;
     path: string;
     version: string;
+    releaseRegex?: string;
 }) {
     const release = await (version
         ? getReleaseFromTag({ ...repo, tag: version })
-        : getLatestRelease(repo));
+        : getLatestRelease(repo, releaseRegex));
 
-    assert(!!release, `Release "${version}" was not found in ${release.url}`);
+    assert(
+        !!release,
+        `Release "${version}" was not found in ${repo.owner}/${repo.name}`,
+    );
 
-    assert(release.assets, `Release assets were not found in ${release.url}`);
+    assert(!!release.assets, `Release assets were not found in ${release.url}`);
 
     const asset_id = release.assets.find(
         (asset: { name: string }) => asset.name === path,
diff --git a/lib/types.d.ts b/lib/types.d.ts
@@ -48,6 +48,7 @@ export type VendorDependency = {
     hashVersionFile?: string | boolean;
     name?: string;
     vendorFolder?: string;
+    releaseRegex?: string;
 };
 
 // LOCKFILE TYPES
diff --git a/lib/utils.ts b/lib/utils.ts
@@ -158,7 +158,10 @@ export async function getNewVersion(
         }
     } else {
         try {
-            const latestRelease = await github.getLatestRelease(repo);
+            const latestRelease = await github.getLatestRelease(
+                repo,
+                dependency.releaseRegex,
+            );
             newVersion = latestRelease.tag_name as string;
         } catch {
             if (showOutdatedOnly) {
@@ -323,6 +326,28 @@ export function validateVendorDependency(
         Array.isArray(dependency.files) && dependency.files.length > 0,
         `config key 'vendorDependencies.${name}.files' is not a valid array`,
     );
+    if (dependency.hashVersionFile) {
+        assert(
+            typeof dependency.hashVersionFile === 'string' ||
+                dependency.hashVersionFile === true,
+            `config key 'vendorDependencies.${name}.hashVersionFile' must be a string or true`,
+        );
+    }
+    if (dependency.releaseRegex) {
+        assert(
+            typeof dependency.releaseRegex === 'string' &&
+                dependency.releaseRegex.length > 0 &&
+                (() => {
+                    try {
+                        new RegExp(dependency.releaseRegex);
+                        return true;
+                    } catch {
+                        return false;
+                    }
+                })(),
+            `config key 'vendorDependencies.${name}.releaseRegex' must be a valid regex string`,
+        );
+    }
 }
 
 export function getDependencyFolder({
