@williamthorsen/release-kit 14.0.0 → 14.2.0

package/dist/esm/resolveReleaseDeclaration.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+export function getTargetName(workspace) {
+    return workspace.targetName ?? workspace.dir;
+}
+export function normalizeWorkspacePath(configuredPath) {
+    const normalized = path.posix.normalize(configuredPath.replaceAll('\\', '/'));
+    return normalized.replace(/^\.\//, '').replace(/\/+$/, '');
+}
+export function resolveReleaseDeclaration(workspaces, userConfig) {
+    if (userConfig?.releases !== undefined) {
+        return resolveReleasesBlock(workspaces, userConfig.releases);
+    }
+    return resolveLegacyBlocks(workspaces, userConfig?.workspaces ?? [], userConfig?.project);
+}
+function applyLegacyIdentities(workspace, legacyIdentities) {
+    if (legacyIdentities === undefined) {
+        return workspace;
+    }
+    return { ...workspace, legacyIdentities: legacyIdentities.map((identity) => ({ ...identity })) };
+}
+function claimPath(entryByPath, name, claimedPath, kind) {
+    const claimedBy = entryByPath.get(claimedPath);
+    if (claimedBy !== undefined) {
+        throw new Error(`releases.${name}: ${kind} '${claimedPath}' is already declared by releases.${claimedBy}; declare each ${kind} once`);
+    }
+    entryByPath.set(claimedPath, name);
+}
+function declareDirectory(name, entry, normalizedPath) {
+    if (path.posix.isAbsolute(normalizedPath) || normalizedPath === '..' || normalizedPath.startsWith('../')) {
+        throw new Error(`releases.${name}: path '${entry.path}' is outside the repo; declare a repo-relative directory`);
+    }
+    const isRoot = normalizedPath === '.' || normalizedPath === '';
+    return {
+        name,
+        path: isRoot ? '.' : normalizedPath,
+        ...(!isRoot && { paths: [`${normalizedPath}/**`] }),
+        ...(entry.tagPrefix !== undefined && { tagPrefix: entry.tagPrefix }),
+        ...(entry.legacyIdentities !== undefined && {
+            legacyIdentities: entry.legacyIdentities.map((identity) => ({ ...identity })),
+        }),
+    };
+}
+function resolveCompositeMembers(composite, retained, excluded, directories) {
+    const membersByName = new Map([
+        ...retained.map((workspace) => [getTargetName(workspace), { name: getTargetName(workspace), paths: workspace.paths }]),
+        ...directories.map((directory) => [directory.name, { name: directory.name, paths: directory.paths }]),
+    ]);
+    return composite.includes.map((memberName) => {
+        const member = membersByName.get(memberName);
+        if (member !== undefined) {
+            return member;
+        }
+        const label = `releases.${composite.name}.includes: '${memberName}'`;
+        if (memberName === composite.name) {
+            throw new Error(`${label} is the composite itself; a composite includes package and directory targets only`);
+        }
+        if (excluded.some((workspace) => workspace.dir === memberName)) {
+            throw new Error(`${label} is excluded, so the composite cannot include it`);
+        }
+        throw new Error(`${label} is not a release target. Known targets: ${membersByName.keys().toArray().join(', ')}`);
+    });
+}
+function resolveLegacyBlocks(workspaces, overrides, project) {
+    const overridesByDir = new Map(overrides.map((override) => [override.dir, override]));
+    const retained = [];
+    const excluded = [];
+    for (const workspace of workspaces) {
+        const override = overridesByDir.get(workspace.dir);
+        if (override?.shouldExclude === true) {
+            excluded.push(workspace);
+        }
+        else {
+            retained.push(applyLegacyIdentities(workspace, override?.legacyIdentities));
+        }
+    }
+    const declaration = { retained, excluded, directories: [] };
+    if (project !== undefined) {
+        declaration.composite = {
+            ...(project.paths !== undefined && { paths: [...project.paths] }),
+            ...(project.tagPrefix !== undefined && { tagPrefix: project.tagPrefix }),
+        };
+    }
+    return declaration;
+}
+function resolveReleasesBlock(workspaces, releases) {
+    const workspaceByPath = new Map(workspaces.map((workspace) => [workspace.workspacePath, workspace]));
+    const workspaceByDir = new Map(workspaces.map((workspace) => [workspace.dir, workspace]));
+    const entryByPath = new Map();
+    const excludedPaths = new Set();
+    const renamed = new Map();
+    const directories = [];
+    let composite;
+    for (const [name, entry] of Object.entries(releases)) {
+        if (entry !== false && 'includes' in entry) {
+            if (composite !== undefined) {
+                throw new Error(`releases declares more than one composite ('${composite.name}', '${name}'); ` +
+                    'a composite is versioned by the root package.json, which only one composite can own');
+            }
+            composite = {
+                name,
+                includes: entry.includes,
+                ...(entry.tagPrefix !== undefined && { tagPrefix: entry.tagPrefix }),
+            };
+            continue;
+        }
+        if (entry === false) {
+            const workspace = workspaceByDir.get(name);
+            if (workspace === undefined) {
+                throw new Error(`releases.${name}: false excludes a discovered workspace by its directory name, and no workspace is named '${name}'. ` +
+                    `Known workspaces: ${workspaceByDir.keys().toArray().join(', ')}`);
+            }
+            claimPath(entryByPath, name, workspace.workspacePath, 'workspace');
+            excludedPaths.add(workspace.workspacePath);
+            continue;
+        }
+        const normalizedPath = normalizeWorkspacePath(entry.path);
+        const workspace = workspaceByPath.get(normalizedPath);
+        if (workspace === undefined) {
+            const directory = declareDirectory(name, entry, normalizedPath);
+            claimPath(entryByPath, name, directory.path, 'directory');
+            directories.push(directory);
+            continue;
+        }
+        if (entry.tagPrefix !== undefined) {
+            throw new Error(`releases.${name}: tagPrefix applies only to a directory target, and '${workspace.workspacePath}' is a workspace, ` +
+                "whose tag prefix derives from its package name; declare the workspace's earlier prefixes in legacyIdentities");
+        }
+        claimPath(entryByPath, name, workspace.workspacePath, 'workspace');
+        const named = applyLegacyIdentities(workspace, entry.legacyIdentities);
+        renamed.set(workspace.workspacePath, name === workspace.dir ? named : { ...named, targetName: name });
+    }
+    const retained = [];
+    const excluded = [];
+    for (const workspace of workspaces) {
+        if (excludedPaths.has(workspace.workspacePath)) {
+            excluded.push(workspace);
+        }
+        else {
+            retained.push(renamed.get(workspace.workspacePath) ?? workspace);
+        }
+    }
+    const declaration = { retained, excluded, directories };
+    if (composite !== undefined) {
+        const members = resolveCompositeMembers(composite, retained, excluded, directories);
+        declaration.composite = {
+            name: composite.name,
+            members: members.map((member) => member.name),
+            paths: members.flatMap((member) => member.paths ?? []),
+            ...(composite.tagPrefix !== undefined && { tagPrefix: composite.tagPrefix }),
+        };
+    }
+    return declaration;
+}

package/dist/esm/resolveReleaseTags.d.ts

@@ -1,17 +1,26 @@
-import type { WorkspaceConfig } from './types.js';
+import type { DirectoryConfig, ResolvedProjectConfig, WorkspaceConfig } from './types.js';
 export interface ResolvedTag {
     tag: string;
+    /**
+     * Whether the tag belongs to a workspace package, to a directory target, or to the composite. A directory or project
+     * tag is never published to a registry but always qualifies for a GitHub Release.
+     */
+    kind: 'package' | 'directory' | 'project';
+    /** Name of the release target that owns the tag; `PROJECT_TARGET_ID` for the composite of a `project` block. */
     dir: string;
+    /** Repo-relative path of the target's package or directory; `.` for the composite. */
     workspacePath: string;
     /**
      * Whether the workspace to which this tag belongs can be published to a registry, copied from the matched
-     * workspace's `WorkspaceConfig.isPublishable`.
+     * workspace's `WorkspaceConfig.isPublishable`. Always false for a project tag.
      */
     isPublishable: boolean;
 }
 /** Discriminated argument to `resolveReleaseTags`: exactly one of the two keys is meaningful. */
 type ResolveReleaseTagsArgs = {
     workspaces: readonly WorkspaceConfig[];
+    directories?: readonly DirectoryConfig[];
+    project?: Pick<ResolvedProjectConfig, 'tagPrefix' | 'name'>;
 } | {
     singleWorkspace: WorkspaceConfig;
 };
@@ -20,7 +29,9 @@ type ResolveReleaseTagsArgs = {
  *
  * Pass `{ workspaces }` for monorepo mode: Each tag is matched against the workspace
  * whose `tagPrefix` it starts with, and that workspace's `isPublishable` propagates onto
- * the `ResolvedTag`. Because `tagPrefix` is derived from `deriveWorkspaceConfig()` (the
+ * the `ResolvedTag`. Add `directories` to also match each directory target's tag, which resolves at
+ * the directory with `kind: 'directory'`, and `project` to match the project tag, which resolves at the
+ * repo root with `kind: 'project'`. Because `tagPrefix` is derived from `deriveWorkspaceConfig()` (the
  * same source that produced the tag), encoding and decoding stay colocated.
  *
  * Pass `{ singleWorkspace }` for single-package mode: Tags like `v1.2.3` are matched and

package/dist/esm/resolveReleaseTags.js

@@ -1,5 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+import { getTargetName } from "./resolveReleaseDeclaration.js";
+import { PROJECT_TARGET_ID } from "./resolveReleaseTargets.js";
 const VERSION_PATTERN = /^v\d+\.\d+\.\d+/;
 const SEMVER_SUFFIX_PATTERN = /^\d+\.\d+\.\d+/;
 export function resolveReleaseTags(args) {
@@ -15,7 +17,7 @@ export function resolveReleaseTags(args) {
         return resolveSinglePackageTags(tags);
     }
     if ('workspaces' in args) {
-        return resolveMonorepoTags(tags, args.workspaces);
+        return resolveMonorepoTags(tags, args.workspaces, args.directories ?? [], args.project);
     }
     return resolveSinglePackageTags(tags, args.singleWorkspace);
 }
@@ -25,30 +27,49 @@ function resolveSinglePackageTags(tags, singleWorkspace) {
     if (matched.length > 1) {
         console.warn(`Warning: Multiple version tags found on HEAD: ${matched.join(', ')}. ` +
             `Publishing the same package multiple times is almost certainly unintended. Using only the first tag.`);
-        return matched.slice(0, 1).map((tag) => ({ tag, dir: '.', workspacePath: '.', isPublishable }));
+        return matched.slice(0, 1).map((tag) => ({ tag, kind: 'package', dir: '.', workspacePath: '.', isPublishable }));
     }
-    return matched.map((tag) => ({ tag, dir: '.', workspacePath: '.', isPublishable }));
+    return matched.map((tag) => ({ tag, kind: 'package', dir: '.', workspacePath: '.', isPublishable }));
 }
-function resolveMonorepoTags(tags, workspaces) {
+function resolveMonorepoTags(tags, workspaces, directories, project) {
     const sortedWorkspaces = workspaces.toSorted((a, b) => b.tagPrefix.length - a.tagPrefix.length);
     const resolved = [];
     for (const tag of tags) {
         const match = findMatchingWorkspace(tag, sortedWorkspaces);
+        const directory = directories.find((candidate) => hasVersionAfterPrefix(tag, candidate.tagPrefix));
         if (match !== undefined) {
-            resolved.push({ tag, dir: match.dir, workspacePath: match.workspacePath, isPublishable: match.isPublishable });
+            resolved.push({
+                tag,
+                kind: 'package',
+                dir: getTargetName(match),
+                workspacePath: match.workspacePath,
+                isPublishable: match.isPublishable,
+            });
+        }
+        else if (directory !== undefined) {
+            resolved.push({
+                tag,
+                kind: 'directory',
+                dir: directory.name,
+                workspacePath: directory.path,
+                isPublishable: false,
+            });
+        }
+        else if (project !== undefined && hasVersionAfterPrefix(tag, project.tagPrefix)) {
+            resolved.push({
+                tag,
+                kind: 'project',
+                dir: project.name ?? PROJECT_TARGET_ID,
+                workspacePath: '.',
+                isPublishable: false,
+            });
         }
     }
     return resolved;
 }
 function findMatchingWorkspace(tag, sortedWorkspaces) {
-    for (const workspace of sortedWorkspaces) {
-        if (!tag.startsWith(workspace.tagPrefix)) {
-            continue;
-        }
-        const versionSuffix = tag.slice(workspace.tagPrefix.length);
-        if (SEMVER_SUFFIX_PATTERN.test(versionSuffix)) {
-            return workspace;
-        }
-    }
-    return undefined;
+    return sortedWorkspaces.find((workspace) => hasVersionAfterPrefix(tag, workspace.tagPrefix));
+}
+function hasVersionAfterPrefix(tag, tagPrefix) {
+    return tag.startsWith(tagPrefix) && SEMVER_SUFFIX_PATTERN.test(tag.slice(tagPrefix.length));
 }

package/dist/esm/resolveReleaseTargets.d.ts

@@ -0,0 +1,29 @@
+import type { WorkspaceDiscovery } from './discoverWorkspaces.js';
+import type { MonorepoReleaseConfig, ReleaseKitConfig, ReleaseSettings, ReleaseTarget } from './types.js';
+/** Id of the composite target that a `project` block declares. A target name is never empty, so ids cannot clash. */
+export declare const PROJECT_TARGET_ID = "";
+/** Id of the package target at the root of a single-package repo. */
+export declare const SINGLE_PACKAGE_TARGET_ID = ".";
+/** The targets of a release run, in the order in which `prepare` reports them, and the settings that they share. */
+export interface ResolvedReleaseTargets {
+    targets: ReleaseTarget[];
+    settings: ReleaseSettings;
+}
+/**
+ * Projects the user config onto the release targets of the discovered repo shape.
+ *
+ * A single-package repo yields one package target at the root. A monorepo yields one package target per retained
+ * workspace, in discovery order, then one directory target per declared directory, in config order, then a composite
+ * target when the config declares one.
+ * Throws the config-merge errors of the shape, and when two targets share an id.
+ */
+export declare function resolveReleaseTargets(userConfig: ReleaseKitConfig | undefined, discovery: Exclude<WorkspaceDiscovery, {
+    kind: 'empty';
+}>): ResolvedReleaseTargets;
+/** Reports whether the targets are those of a single-package repo: its root package target and nothing else. */
+export declare function isSinglePackageTargets(targets: readonly ReleaseTarget[]): boolean;
+/**
+ * Projects a merged monorepo config onto its targets: one package target per workspace, in config order, then one
+ * directory target per directory, then a composite when the config has one. Throws when two targets share an id.
+ */
+export declare function projectMonorepoConfig(config: MonorepoReleaseConfig): ResolvedReleaseTargets;

package/dist/esm/resolveReleaseTargets.js

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs';
+import { isPublishableManifest } from "./isPublishableManifest.js";
+import { mergeMonorepoConfig, mergeSinglePackageConfig, readRootPackageVersion } from "./loadConfig.js";
+import { getTargetName } from "./resolveReleaseDeclaration.js";
+export const PROJECT_TARGET_ID = '';
+export const SINGLE_PACKAGE_TARGET_ID = '.';
+export function resolveReleaseTargets(userConfig, discovery) {
+    if (discovery.kind === 'single-package') {
+        const settings = mergeSinglePackageConfig(userConfig);
+        return { targets: [buildSinglePackageTarget()], settings: pickSettings(settings) };
+    }
+    return projectMonorepoConfig(mergeMonorepoConfig(discovery.packageDirs, userConfig, readRootPackageVersion()));
+}
+export function isSinglePackageTargets(targets) {
+    const [only] = targets;
+    return targets.length === 1 && only?.kind === 'package' && !only.isWorkspace;
+}
+export function projectMonorepoConfig(config) {
+    const targets = [
+        ...config.workspaces.map(buildWorkspaceTarget),
+        ...(config.directories ?? []).map(buildDirectoryTarget),
+    ];
+    if (config.project !== undefined) {
+        targets.push(buildProjectTarget(config.project, config.workspaces));
+    }
+    assertUniqueTargetIds(targets);
+    return { targets, settings: pickSettings(config) };
+}
+function assertUniqueTargetIds(targets) {
+    const pathsById = new Map();
+    for (const target of targets) {
+        const path = describeTargetPath(target);
+        pathsById.set(target.id, [...(pathsById.get(target.id) ?? []), path]);
+    }
+    for (const [id, paths] of pathsById) {
+        if (paths.length > 1) {
+            throw new Error(`Duplicate release target id '${id}' for workspaces: ${paths.join(', ')}`);
+        }
+    }
+}
+function buildDirectoryTarget(directory) {
+    const target = {
+        id: directory.name,
+        kind: 'directory',
+        tagPrefix: directory.tagPrefix,
+        versionFiles: [directory.versionFile],
+        changelogDir: directory.path,
+        isPublishable: false,
+        directoryPath: directory.path,
+    };
+    if (directory.paths !== undefined) {
+        target.paths = [...directory.paths];
+    }
+    if (directory.legacyIdentities !== undefined) {
+        target.legacyIdentities = directory.legacyIdentities;
+    }
+    return target;
+}
+function buildProjectTarget(project, workspaces) {
+    return {
+        id: project.name ?? PROJECT_TARGET_ID,
+        kind: 'composite',
+        members: project.members ?? workspaces.map(getTargetName),
+        tagPrefix: project.tagPrefix,
+        versionFiles: ['./package.json'],
+        changelogDir: '.',
+        paths: [...project.paths],
+        isPublishable: false,
+    };
+}
+function buildSinglePackageTarget() {
+    return {
+        id: SINGLE_PACKAGE_TARGET_ID,
+        kind: 'package',
+        tagPrefix: 'v',
+        versionFiles: ['package.json'],
+        changelogDir: '.',
+        packagePath: '.',
+        isPublishable: readRootPublishability(),
+        isWorkspace: false,
+    };
+}
+function buildWorkspaceTarget(workspace) {
+    const target = {
+        id: getTargetName(workspace),
+        kind: 'package',
+        packageName: workspace.name,
+        tagPrefix: workspace.tagPrefix,
+        versionFiles: [...workspace.packageFiles],
+        changelogDir: workspace.workspacePath,
+        paths: [...workspace.paths],
+        isPublishable: workspace.isPublishable,
+        packagePath: workspace.workspacePath,
+        isWorkspace: true,
+    };
+    if (workspace.legacyIdentities !== undefined) {
+        target.legacyIdentities = workspace.legacyIdentities;
+    }
+    return target;
+}
+function describeTargetPath(target) {
+    switch (target.kind) {
+        case 'package':
+            return target.packagePath;
+        case 'directory':
+            return target.directoryPath;
+        case 'composite':
+            return target.changelogDir;
+    }
+}
+function pickSettings(config) {
+    const { breakingPolicies, changelogJson, changelogMarkdown, formatCommand, releaseNotes, scopeAliases, versionPatterns, workTypes, } = config;
+    return {
+        changelogJson,
+        releaseNotes,
+        ...(breakingPolicies !== undefined && { breakingPolicies }),
+        ...(changelogMarkdown !== undefined && { changelogMarkdown }),
+        ...(formatCommand !== undefined && { formatCommand }),
+        ...(scopeAliases !== undefined && { scopeAliases }),
+        ...(versionPatterns !== undefined && { versionPatterns }),
+        ...(workTypes !== undefined && { workTypes }),
+    };
+}
+function readRootPublishability() {
+    try {
+        return isPublishableManifest(JSON.parse(readFileSync('package.json', 'utf8')));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/esm/sync-labels/generateCommand.js

@@ -15,10 +15,11 @@ export function formatLabelsYaml(labels, presetHashes, configFilePath = CONFIG_F
     for (const [name, hash] of sortedPresetHashes) {
         headerLines.push(`# ${name} preset hash: ${hash}`);
     }
-    const declared = labels.map(({ archived, color, description, name }) => ({
+    const declared = labels.map(({ aliases, archived, color, description, name }) => ({
         name,
         color,
         description: description ?? '',
+        ...(aliases !== undefined && { aliases }),
         ...(archived !== undefined && { archived }),
     }));
     const yamlBody = stringify(declared, { singleQuote: true, lineWidth: 0 });

package/dist/esm/sync-labels/resolveLabels.d.ts

@@ -8,8 +8,9 @@ import type { LabelDefinition } from './types.js';
  * one that an earlier layer defined, or removes it (`null`). Names match case-insensitively, as GitHub matches them,
  * and the replacing layer's spelling becomes the label's name. Replacement is wholesale, so an entry omitting
  * `description` drops the one that an earlier layer supplied rather than inheriting it.
- * Throws on two misstatements that the output diff would otherwise not show: keys in the `labels` record that differ
- * only in case, all but one of which the fold would discard, and a dangling `null`, a removal naming a label that the
- * `extends` presets did not define.
+ * Throws on three misstatements that the output diff would otherwise not show: keys in the `labels` record that differ
+ * only in case, all but one of which the fold would discard; a dangling `null`, a removal naming a label that the
+ * `extends` presets did not define; and an alias that names a resolved label or repeats another alias, which makes
+ * `github-label-sync` merge one label into another and delete it.
  */
 export declare function resolveLabels(config: RepoLabelsConfig): LabelDefinition[];

package/dist/esm/sync-labels/resolveLabels.js

@@ -26,11 +26,40 @@ export function resolveLabels(config) {
                 name,
                 color: spec.color,
                 ...(spec.description !== undefined && { description: spec.description }),
+                ...(spec.aliases !== undefined && { aliases: spec.aliases }),
                 ...(spec.archived !== undefined && { archived: spec.archived }),
             });
         }
     }
-    return sortLabels(resolved.values().toArray());
+    const labels = sortLabels(resolved.values().toArray());
+    const aliasCollisions = findAliasCollisions(labels);
+    if (aliasCollisions.length > 0) {
+        throw new Error(`Aliases must name labels that are not declared and must not repeat, or the sync merges one label into another and deletes it: ${aliasCollisions.join('; ')}.`);
+    }
+    return labels;
+}
+function findAliasCollisions(labels) {
+    const labelNamesByKey = new Map(labels.map((label) => [toLabelKey(label.name), label.name]));
+    const aliasOwnersByKey = new Map();
+    const collisions = [];
+    for (const label of labels) {
+        const aliases = label.aliases ?? [];
+        for (const alias of aliases) {
+            const key = toLabelKey(alias);
+            const namedLabel = labelNamesByKey.get(key);
+            const earlierOwner = aliasOwnersByKey.get(key);
+            if (namedLabel !== undefined) {
+                collisions.push(`'${label.name}' declares alias '${alias}', which names the label '${namedLabel}'`);
+            }
+            else if (earlierOwner !== undefined) {
+                collisions.push(`'${label.name}' declares alias '${alias}', which '${earlierOwner}' also declares`);
+            }
+            else {
+                aliasOwnersByKey.set(key, label.name);
+            }
+        }
+    }
+    return collisions;
 }
 function findCaseVariantGroups(names) {
     return Map.groupBy(names, toLabelKey)

package/dist/esm/sync-labels/templates.js

@@ -11,7 +11,7 @@ on:
     paths:
       - .github/labels.yaml
 
-  # Preview on review: The check's log has a full computed diff, including deletions of labels not declared by the file.
+  # Preview on review: The check's log has the computed diff, and the check warns about each label not declared by the file.
   pull_request:
     paths:
       - .github/labels.yaml

package/dist/esm/sync-labels/types.d.ts

@@ -6,6 +6,8 @@ export interface LabelDefinition {
     color: string;
     /** Short description shown in the GitHub UI. Absent when the label has none. */
     description?: string;
+    /** Names of existing labels that the sync renames to this one. Absent when the label has none. */
+    aliases?: string[];
     /** Marks the label for the sync to archive rather than keep active. Absent for an active label. */
     archived?: true;
 }