@williamthorsen/release-kit 14.2.2 → 14.2.3

package/dist/esm/changelogOverrides.js

@@ -1,307 +1,52 @@
-import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { describeError } from '@williamthorsen/toolbelt.errors';
-import { extractMigration } from "./extractMigration.js";
-import { isRecord } from "./typeGuards.js";
+import { applyChangelogOverrides, formatStaleOverrideKeyWarning } from "./applyChangelogOverrides.js";
+import { loadChangelogOverrides } from "./loadChangelogOverrides.js";
 const OVERRIDES_FILENAME = '.meta/changelog-overrides.json';
-const VALID_AUDIENCE_VALUES = new Set(['all', 'dev', 'skip']);
-const V1_SUPPORTED_AUDIENCE_VALUES = new Set(['skip']);
-export const KNOWN_OVERRIDE_FIELDS = new Set(['audience', 'description', 'body', 'breaking']);
-export const OVERRIDE_KEY_PATTERN = /^[0-9a-f]+(:[1-9][0-9]*)?$/;
-const SCHEMA_KEY = '$schema';
-export function loadChangelogOverrides(path) {
-    if (!existsSync(path)) {
-        return { overrides: new Map() };
-    }
-    let content;
-    try {
-        content = readFileSync(path, 'utf8');
-    }
-    catch (error) {
-        return {
-            errors: [`Failed to read override file ${path}: ${describeError(error)}`],
-        };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(content);
-    }
-    catch (error) {
-        return {
-            errors: [`Failed to parse override file ${path}: ${describeError(error)}`],
-        };
-    }
-    const result = validateChangelogOverrides(parsed);
-    if (result.errors.length > 0) {
-        return { errors: result.errors };
-    }
-    return { overrides: result.overrides };
-}
-export function validateChangelogOverrides(raw) {
-    const overrides = new Map();
-    const errors = [];
-    if (!isRecord(raw)) {
-        errors.push('Override file: top-level value must be an object keyed by commit hash');
-        return { overrides, errors };
-    }
-    for (const [key, rawEntry] of Object.entries(raw)) {
-        if (key === SCHEMA_KEY) {
-            if (typeof rawEntry !== 'string') {
-                errors.push(`Override file: '${SCHEMA_KEY}' must be a string`);
-            }
-            continue;
-        }
-        if (!OVERRIDE_KEY_PATTERN.test(key)) {
-            errors.push(`overrides['${key}']: key must be a lowercase hex commit hash or prefix, optionally followed by ':<n>'`);
-            continue;
-        }
-        const validated = validateSingleOverride(key, rawEntry, errors);
-        if (validated !== undefined) {
-            overrides.set(key, validated);
-        }
-    }
-    return { overrides, errors };
-}
-export function parseOverrideKey(key) {
-    const separatorIndex = key.indexOf(':');
-    if (separatorIndex === -1) {
-        return { hashPrefix: key };
-    }
-    return { hashPrefix: key.slice(0, separatorIndex), entry: Number(key.slice(separatorIndex + 1)) };
-}
-function validateSingleOverride(key, rawEntry, errors) {
-    if (!isRecord(rawEntry)) {
-        errors.push(`overrides['${key}']: must be an object`);
-        return undefined;
-    }
-    let entryValid = true;
-    for (const fieldName of Object.keys(rawEntry)) {
-        if (KNOWN_OVERRIDE_FIELDS.has(fieldName)) {
-            continue;
-        }
-        errors.push(`overrides['${key}']: unknown field '${fieldName}'`);
-        entryValid = false;
-    }
-    const result = {};
-    if (rawEntry['audience'] !== undefined) {
-        const audienceResult = validateAudience(key, rawEntry['audience'], errors);
-        if (audienceResult === undefined) {
-            entryValid = false;
-        }
-        else {
-            result.audience = audienceResult;
-        }
-    }
-    if (rawEntry['description'] !== undefined) {
-        if (typeof rawEntry['description'] !== 'string') {
-            errors.push(`overrides['${key}']: 'description' must be a string`);
-            entryValid = false;
-        }
-        else {
-            result.description = rawEntry['description'];
-        }
-    }
-    if (rawEntry['body'] !== undefined) {
-        if (typeof rawEntry['body'] !== 'string') {
-            errors.push(`overrides['${key}']: 'body' must be a string`);
-            entryValid = false;
-        }
-        else {
-            result.body = rawEntry['body'];
-        }
-    }
-    if (rawEntry['breaking'] !== undefined) {
-        if (typeof rawEntry['breaking'] !== 'boolean') {
-            errors.push(`overrides['${key}']: 'breaking' must be a boolean`);
-            entryValid = false;
-        }
-        else {
-            result.breaking = rawEntry['breaking'];
-        }
-    }
-    if (Object.keys(result).length === 0 && entryValid) {
-        errors.push(`overrides['${key}']: at least one override field must be set`);
-        return undefined;
-    }
-    if (!entryValid) {
-        return undefined;
-    }
-    return result;
-}
-function validateAudience(key, value, errors) {
-    if (typeof value !== 'string' || !VALID_AUDIENCE_VALUES.has(value)) {
-        errors.push(`overrides['${key}']: 'audience' must be one of 'all' | 'dev' | 'skip'`);
-        return undefined;
-    }
-    if (!V1_SUPPORTED_AUDIENCE_VALUES.has(value)) {
-        errors.push(`overrides['${key}']: audience '${value}' is not yet supported; only 'skip' is currently accepted`);
-        return undefined;
-    }
-    return 'skip';
-}
-export function formatStaleOverrideKeyWarning(key) {
-    return `Override key '${key}' did not match any item in the changelog (likely a stale reference)`;
-}
-export function applyChangelogOverrides(entries, overrides) {
-    const warnings = [];
-    if (overrides.size === 0) {
-        return { entries: entries.map(cloneEntry), warnings, errors: [], matchedKeys: [] };
-    }
-    const { errors, itemIdToKey } = resolveOverrideKeys(indexEntryPositions(entries), overrides);
-    const itemIdToOverride = new Map();
-    for (const [itemId, overrideKey] of itemIdToKey) {
-        const override = overrides.get(overrideKey);
-        if (override !== undefined) {
-            itemIdToOverride.set(itemId, override);
-        }
-    }
-    const matchedKeys = [...new Set(itemIdToKey.values())];
-    const transformedEntries = [];
-    for (const entry of entries) {
-        const transformedSections = [];
-        for (const section of entry.sections) {
-            const transformedItems = applyOverridesToItems(section.items, itemIdToOverride);
-            if (transformedItems.length === 0) {
-                continue;
-            }
-            transformedSections.push({ ...section, items: transformedItems });
-        }
-        transformedEntries.push({ ...entry, sections: transformedSections });
+export function applyWorkspaceOverrides(newEntries, workspacePath, overrideContext) {
+    const { project, perWorkspace, overrideWarnings, globalMatchedRootKeys } = overrideContext;
+    const workspaceOverrides = workspacePath === undefined ? undefined : perWorkspace.get(workspacePath);
+    const composed = composeOverrides(project, workspaceOverrides);
+    const applied = applyChangelogOverrides(newEntries, composed);
+    if (applied.errors.length > 0) {
+        throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
     }
-    return { entries: transformedEntries, warnings, errors, matchedKeys };
-}
-function resolveOverrideKeys(positionsByHash, overrides) {
-    const errors = [];
-    const failedKeys = new Set();
-    const itemIdToKey = new Map();
-    for (const [overrideKey, override] of overrides) {
-        const resolution = resolveOverrideKey(overrideKey, positionsByHash);
-        if (resolution.kind === 'ambiguous') {
-            errors.push(`Override key '${overrideKey}' is ambiguous: matches multiple commits (${resolution.hashes.join(', ')}). ` +
-                'Use a longer prefix or the full commit hash.');
-            continue;
-        }
-        if (resolution.kind === 'none') {
-            continue;
-        }
-        const { hash, positions } = resolution;
-        if (parseOverrideKey(overrideKey).entry === undefined && positions.length > 1) {
-            const fieldsSet = ['description', 'body'].filter((field) => override[field] !== undefined);
-            if (fieldsSet.length > 0) {
-                const ordinalKeys = positions.map((position) => `${overrideKey}:${position}`).join(', ');
-                errors.push(`Override key '${overrideKey}' sets ${fieldsSet.join(' and ')} on a commit with several items; use ${ordinalKeys}`);
-                continue;
-            }
-        }
-        for (const position of positions) {
-            const itemId = formatItemId(hash, position);
-            const claimingKey = itemIdToKey.get(itemId);
-            if (claimingKey === undefined) {
-                itemIdToKey.set(itemId, overrideKey);
-                continue;
+    overrideWarnings.push(...applied.warnings);
+    const matchedSet = new Set(applied.matchedKeys);
+    if (workspaceOverrides !== undefined) {
+        for (const key of workspaceOverrides.keys()) {
+            if (!matchedSet.has(key)) {
+                overrideWarnings.push(formatStaleOverrideKeyWarning(key));
             }
-            const target = position === undefined ? `commit ${hash}` : `the item at ${hash}:${position}`;
-            errors.push(`Override keys '${claimingKey}' and '${overrideKey}' both match ${target}; keep one`);
-            failedKeys.add(claimingKey);
-            failedKeys.add(overrideKey);
         }
     }
-    for (const [itemId, overrideKey] of itemIdToKey) {
-        if (failedKeys.has(overrideKey)) {
-            itemIdToKey.delete(itemId);
-        }
-    }
-    return { errors, itemIdToKey };
-}
-function resolveOverrideKey(overrideKey, positionsByHash) {
-    const { hashPrefix, entry } = parseOverrideKey(overrideKey);
-    const hashes = positionsByHash
-        .keys()
-        .filter((hash) => hash.startsWith(hashPrefix))
-        .toArray();
-    const [hash] = hashes;
-    if (hash === undefined) {
-        return { kind: 'none' };
-    }
-    if (hashes.length > 1) {
-        return { kind: 'ambiguous', hashes };
-    }
-    const available = [...(positionsByHash.get(hash) ?? [])];
-    const positions = entry === undefined
-        ? available.toSorted((left, right) => (left ?? 0) - (right ?? 0))
-        : available.filter((position) => position === entry);
-    return positions.length === 0 ? { kind: 'none' } : { kind: 'items', hash, positions };
-}
-function indexEntryPositions(entries) {
-    return indexItemPositions(entries.flatMap((entry) => entry.sections.flatMap((section) => section.items)));
-}
-function indexItemPositions(items) {
-    const positionsByHash = new Map();
-    for (const item of items) {
-        if (item.hash === undefined)
+    for (const key of applied.matchedKeys) {
+        if (workspaceOverrides?.has(key))
             continue;
-        const positions = positionsByHash.get(item.hash) ?? new Set();
-        positions.add(item.entry);
-        positionsByHash.set(item.hash, positions);
+        globalMatchedRootKeys.add(key);
     }
-    return positionsByHash;
-}
-function formatItemId(hash, entry) {
-    return entry === undefined ? hash : `${hash}:${entry}`;
+    return applied;
 }
-function applyOverridesToItems(items, itemIdToOverride) {
-    const result = [];
-    for (const item of items) {
-        if (item.hash === undefined) {
-            result.push(cloneItem(item));
-            continue;
-        }
-        const override = itemIdToOverride.get(formatItemId(item.hash, item.entry));
-        if (override === undefined) {
-            result.push(cloneItem(item));
-            continue;
-        }
-        if (override.audience === 'skip') {
-            continue;
+export function composeOverrides(rootEntries, workspaceEntries) {
+    const composed = new Map(rootEntries);
+    if (workspaceEntries !== undefined) {
+        for (const [key, value] of workspaceEntries) {
+            composed.set(key, value);
         }
-        result.push(applyOverrideToItem(item, override));
     }
-    return result;
+    return composed;
 }
-function applyOverrideToItem(item, override) {
-    const result = { ...item };
-    if (override.description !== undefined) {
-        result.description = override.description;
-    }
-    if (override.body !== undefined) {
-        result.body = override.body;
-    }
-    if (override.body !== undefined && item.entry === undefined) {
-        const migration = extractMigration(override.body);
-        if (migration === undefined) {
-            delete result.migration;
-        }
-        else {
-            result.migration = migration;
-        }
-    }
-    if (override.breaking !== undefined) {
-        result.breaking = override.breaking;
+export function createOverrideContext(workspacePaths) {
+    const result = loadOverridesForScopes({ project: '.', workspaces: [...workspacePaths] });
+    if (result.errors.length > 0) {
+        throw new Error(`Failed to load changelog overrides:\n  - ${result.errors.join('\n  - ')}`);
     }
-    return result;
-}
-function cloneItem(item) {
-    return { ...item };
-}
-function cloneEntry(entry) {
     return {
-        ...entry,
-        sections: entry.sections.map((section) => ({ ...section, items: section.items.map(cloneItem) })),
+        project: result.project,
+        perWorkspace: result.perWorkspace,
+        overrideWarnings: [],
+        globalMatchedRootKeys: new Set(),
     };
 }
-export function resolveOverridePath(scopeRoot) {
-    return path.posix.join(scopeRoot, OVERRIDES_FILENAME);
-}
 export function loadOverridesForScopes(scopes) {
     const errors = [];
     let project = new Map();
@@ -327,183 +72,6 @@ export function loadOverridesForScopes(scopes) {
     }
     return { project, perWorkspace, errors };
 }
-export function composeOverrides(rootEntries, workspaceEntries) {
-    const composed = new Map(rootEntries);
-    if (workspaceEntries !== undefined) {
-        for (const [key, value] of workspaceEntries) {
-            composed.set(key, value);
-        }
-    }
-    return composed;
-}
-export function createOverrideContext(workspacePaths) {
-    const result = loadOverridesForScopes({ project: '.', workspaces: [...workspacePaths] });
-    if (result.errors.length > 0) {
-        throw new Error(`Failed to load changelog overrides:\n  - ${result.errors.join('\n  - ')}`);
-    }
-    return {
-        project: result.project,
-        perWorkspace: result.perWorkspace,
-        overrideWarnings: [],
-        globalMatchedRootKeys: new Set(),
-    };
-}
-export function validateAllChangelogOverrides(inputs) {
-    const errors = [];
-    const warnings = [];
-    const projectFilePath = inputs.project?.filePath;
-    const projectMap = loadScopeMap(projectFilePath, errors);
-    const workspaceMaps = (inputs.workspaces ?? []).map((scope) => ({
-        filePath: scope.filePath,
-        items: scope.items,
-        map: loadScopeMap(scope.filePath, errors),
-    }));
-    const globalMatchedRootKeys = new Set();
-    for (const workspace of workspaceMaps) {
-        processWorkspaceScope({
-            workspace,
-            projectFilePath,
-            projectMap,
-            errors,
-            warnings,
-            globalMatchedRootKeys,
-        });
-    }
-    const projectItems = inputs.project?.items;
-    if (projectFilePath !== undefined && projectItems !== undefined) {
-        processProjectScope({ projectFilePath, projectMap, projectItems, errors, globalMatchedRootKeys });
-    }
-    if (projectFilePath !== undefined) {
-        collectRootStaleWarnings(projectFilePath, projectMap, globalMatchedRootKeys, warnings);
-    }
-    return { errors, warnings };
-}
-function processWorkspaceScope(args) {
-    const { workspace, projectFilePath, projectMap, errors, warnings, globalMatchedRootKeys } = args;
-    const { filePath, items, map } = workspace;
-    const validationEntries = makeValidationEntries(items);
-    const positionsByHash = indexItemPositions(items);
-    const workspaceApplied = applyChangelogOverrides(validationEntries, map);
-    for (const message of workspaceApplied.errors) {
-        errors.push(prefixWithFilePath(filePath, message));
-    }
-    if (projectFilePath !== undefined && projectMap.size > 0) {
-        const projectMinusShadowed = filterShadowedKeys(projectMap, map);
-        const projectApplied = applyChangelogOverrides(validationEntries, projectMinusShadowed);
-        for (const message of projectApplied.errors) {
-            errors.push(prefixWithFilePath(projectFilePath, message));
-        }
-        const perFileErrors = new Set([...workspaceApplied.errors, ...projectApplied.errors]);
-        const composedApplied = applyChangelogOverrides(validationEntries, composeOverrides(projectMap, map));
-        for (const message of composedApplied.errors) {
-            if (!perFileErrors.has(message)) {
-                errors.push(prefixWithFilePath(filePath, message));
-            }
-        }
-    }
-    for (const key of map.keys()) {
-        if (!hasAnyMatch(key, positionsByHash)) {
-            warnings.push(formatWorkspaceStaleWarning(filePath, key));
-        }
-    }
-    for (const key of projectMap.keys()) {
-        if (map.has(key))
-            continue;
-        if (hasAnyMatch(key, positionsByHash)) {
-            globalMatchedRootKeys.add(key);
-        }
-    }
-}
-function processProjectScope(args) {
-    const { projectFilePath, projectMap, projectItems, errors, globalMatchedRootKeys } = args;
-    const applied = applyChangelogOverrides(makeValidationEntries(projectItems), projectMap);
-    for (const message of applied.errors) {
-        errors.push(prefixWithFilePath(projectFilePath, message));
-    }
-    const positionsByHash = indexItemPositions(projectItems);
-    for (const key of projectMap.keys()) {
-        if (hasAnyMatch(key, positionsByHash)) {
-            globalMatchedRootKeys.add(key);
-        }
-    }
-}
-function collectRootStaleWarnings(projectFilePath, projectMap, globalMatchedRootKeys, warnings) {
-    for (const key of projectMap.keys()) {
-        if (!globalMatchedRootKeys.has(key)) {
-            warnings.push(formatRootStaleWarning(projectFilePath, key));
-        }
-    }
-}
-function hasAnyMatch(key, positionsByHash) {
-    return resolveOverrideKey(key, positionsByHash).kind !== 'none';
-}
-function filterShadowedKeys(projectMap, workspaceMap) {
-    const result = new Map();
-    for (const [key, value] of projectMap) {
-        if (workspaceMap.has(key))
-            continue;
-        result.set(key, value);
-    }
-    return result;
-}
-function loadScopeMap(filePath, errors) {
-    if (filePath === undefined) {
-        return new Map();
-    }
-    const result = loadChangelogOverrides(filePath);
-    if ('errors' in result) {
-        for (const message of result.errors) {
-            errors.push(prefixWithFilePath(filePath, message));
-        }
-        return new Map();
-    }
-    return result.overrides;
-}
-function makeValidationEntries(items) {
-    return [
-        {
-            version: '0.0.0',
-            date: '0000-00-00',
-            sections: [
-                {
-                    title: 'Validation',
-                    audience: 'all',
-                    items: items.map((item) => ({ ...item, description: '' })),
-                },
-            ],
-        },
-    ];
-}
-function prefixWithFilePath(filePath, message) {
-    return `${filePath}: ${message}`;
-}
-function formatWorkspaceStaleWarning(filePath, key) {
-    return `${filePath}: Override key '${key}' did not match any item in this workspace's history (likely a stale reference)`;
-}
-function formatRootStaleWarning(filePath, key) {
-    return `${filePath}: Override key '${key}' did not match any item in any scope (likely a stale reference)`;
-}
-export function applyWorkspaceOverrides(newEntries, workspacePath, overrideContext) {
-    const { project, perWorkspace, overrideWarnings, globalMatchedRootKeys } = overrideContext;
-    const workspaceOverrides = workspacePath === undefined ? undefined : perWorkspace.get(workspacePath);
-    const composed = composeOverrides(project, workspaceOverrides);
-    const applied = applyChangelogOverrides(newEntries, composed);
-    if (applied.errors.length > 0) {
-        throw new Error(`Changelog override application failed:\n  - ${applied.errors.join('\n  - ')}`);
-    }
-    overrideWarnings.push(...applied.warnings);
-    const matchedSet = new Set(applied.matchedKeys);
-    if (workspaceOverrides !== undefined) {
-        for (const key of workspaceOverrides.keys()) {
-            if (!matchedSet.has(key)) {
-                overrideWarnings.push(formatStaleOverrideKeyWarning(key));
-            }
-        }
-    }
-    for (const key of applied.matchedKeys) {
-        if (workspaceOverrides?.has(key))
-            continue;
-        globalMatchedRootKeys.add(key);
-    }
-    return applied;
+export function resolveOverridePath(scopeRoot) {
+    return path.posix.join(scopeRoot, OVERRIDES_FILENAME);
 }