@juancr11/sibu 0.6.0 → 0.8.0

package/bin/modules/maintainer-release-support/generate-changelog/changelog-writer.js

@@ -0,0 +1,91 @@
+import { renderChangelogSection } from './changelog-format.js';
+export const STANDARD_CHANGELOG_HEADER = `# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+`;
+export function planChangelogUpdate(existingContent, proposal) {
+    const nextSection = renderChangelogSection(proposal).trimEnd();
+    if (!existingContent || existingContent.trim().length === 0) {
+        return {
+            status: 'ok',
+            content: `${STANDARD_CHANGELOG_HEADER}\n${nextSection}\n`,
+            replacingExistingSection: false,
+        };
+    }
+    const parsedChangelog = parseChangelogSections(existingContent);
+    if (parsedChangelog.status === 'blocked') {
+        return parsedChangelog;
+    }
+    const targetSectionIndex = findTargetSectionIndex(parsedChangelog.sections, proposal);
+    if (targetSectionIndex >= 0) {
+        const sections = [...parsedChangelog.sections];
+        sections[targetSectionIndex] = nextSection;
+        return {
+            status: 'ok',
+            content: joinChangelog(parsedChangelog.header, sections),
+            replacingExistingSection: true,
+        };
+    }
+    return {
+        status: 'ok',
+        content: joinChangelog(parsedChangelog.header, [nextSection, ...parsedChangelog.sections]),
+        replacingExistingSection: false,
+    };
+}
+function parseChangelogSections(content) {
+    if (!content.trimStart().startsWith('# Changelog')) {
+        return unsafeParsedChangelog('Existing CHANGELOG.md does not start with a # Changelog heading.');
+    }
+    const sectionMatches = [...content.matchAll(/^## .+$/gm)];
+    if (sectionMatches.length === 0) {
+        return unsafeParsedChangelog('Existing CHANGELOG.md has no parseable release sections.');
+    }
+    const firstSectionIndex = sectionMatches[0]?.index;
+    if (firstSectionIndex === undefined) {
+        return unsafeParsedChangelog('Existing CHANGELOG.md has no parseable release sections.');
+    }
+    const header = content.slice(0, firstSectionIndex).trimEnd();
+    const sections = sectionMatches.map((match, index) => {
+        const start = match.index ?? 0;
+        const end = sectionMatches[index + 1]?.index ?? content.length;
+        return content.slice(start, end).trim();
+    });
+    return {
+        status: 'ok',
+        header,
+        sections,
+    };
+}
+function findTargetSectionIndex(sections, proposal) {
+    const expectedHeading = proposal.targetSection.type === 'unreleased' ? '## Unreleased' : `## ${proposal.targetSection.version} - ${proposal.targetSection.date}`;
+    return sections.findIndex((section) => section.split('\n')[0] === expectedHeading);
+}
+function joinChangelog(header, sections) {
+    return `${header.trimEnd()}\n\n${sections.map((section) => section.trim()).join('\n\n')}\n`;
+}
+function unsafeChangelog(message) {
+    return {
+        status: 'blocked',
+        message,
+        warnings: [
+            {
+                code: 'unsafe-changelog',
+                message,
+            },
+        ],
+    };
+}
+function unsafeParsedChangelog(message) {
+    return {
+        status: 'blocked',
+        message,
+        warnings: [
+            {
+                code: 'unsafe-changelog',
+                message,
+            },
+        ],
+    };
+}

package/bin/modules/maintainer-release-support/generate-changelog/git-history.js

@@ -0,0 +1,93 @@
+import { execFileSync } from 'node:child_process';
+export function readGitHistory(command, cwd = process.cwd()) {
+    if (!isInsideGitRepository(cwd)) {
+        return blocked('not-git-repository', 'Run the changelog workflow inside a git repository.');
+    }
+    const toRef = command.toRef ?? 'HEAD';
+    if (!isValidCommitRef(toRef, cwd)) {
+        return blocked('invalid-git-ref', `Could not resolve git ref \`${toRef}\`.`);
+    }
+    if (command.fromRef && !isValidCommitRef(command.fromRef, cwd)) {
+        return blocked('invalid-git-ref', `Could not resolve git ref \`${command.fromRef}\`.`);
+    }
+    const latestTag = command.fromRef ? undefined : getLatestReachableTag(toRef, cwd);
+    const fromRef = command.fromRef ?? latestTag;
+    const missingTag = !command.fromRef && !latestTag;
+    const range = fromRef ? `${fromRef}..${toRef}` : toRef;
+    const commits = readCommits(range, cwd);
+    const warnings = missingTag
+        ? [
+            {
+                code: 'missing-tag',
+                message: 'No previous tag found. Using all reachable commits.',
+            },
+        ]
+        : [];
+    return {
+        status: 'ok',
+        commits,
+        sourceRange: {
+            fromRef,
+            toRef,
+            usedLatestTag: !command.fromRef && Boolean(latestTag),
+            missingTag,
+        },
+        warnings,
+    };
+}
+function isInsideGitRepository(cwd) {
+    try {
+        return runGit(['rev-parse', '--is-inside-work-tree'], cwd).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+function isValidCommitRef(ref, cwd) {
+    try {
+        runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getLatestReachableTag(toRef, cwd) {
+    try {
+        const tag = runGit(['describe', '--tags', '--abbrev=0', toRef], cwd).trim();
+        return tag || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readCommits(range, cwd) {
+    const output = runGit(['log', '--format=%H%x1f%s%x1f%b%x1e', range], cwd);
+    return output
+        .split('\x1e')
+        .map((record) => record.trim())
+        .filter((record) => record.length > 0)
+        .map(parseCommitRecord);
+}
+function parseCommitRecord(record) {
+    const [hash = '', subject = '', body = ''] = record.split('\x1f');
+    return {
+        hash,
+        subject,
+        body,
+    };
+}
+function blocked(code, message) {
+    return {
+        status: 'blocked',
+        message,
+        warnings: [{ code, message }],
+    };
+}
+function runGit(args, cwd) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}

package/bin/modules/maintainer-release-support/generate-changelog/handler.js

@@ -0,0 +1,167 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildChangelogProposal, renderChangelogPreview } from './changelog-format.js';
+import { planChangelogUpdate } from './changelog-writer.js';
+import { readGitHistory } from './git-history.js';
+import { determineSemverBump, parseSemverVersion } from './semver.js';
+export function handleGenerateChangelogProposal(command, cwd = process.cwd()) {
+    const targetSection = getTargetSection(command);
+    if (targetSection.status === 'blocked') {
+        return targetSection.result;
+    }
+    const gitHistory = readGitHistory(command, cwd);
+    if (gitHistory.status === 'blocked') {
+        return {
+            status: 'blocked',
+            message: gitHistory.message,
+            warnings: gitHistory.warnings,
+        };
+    }
+    const proposal = buildChangelogProposal({
+        commits: gitHistory.commits,
+        sourceRange: gitHistory.sourceRange,
+        targetSection: targetSection.value,
+        warnings: gitHistory.warnings,
+    });
+    return {
+        status: 'proposed',
+        proposal: addSemverMismatchWarning(proposal),
+    };
+}
+export async function handleGenerateChangelogWrite(command, ports = createNodeChangelogWritePorts(), cwd = process.cwd()) {
+    const proposalResult = handleGenerateChangelogProposal(command, cwd);
+    if (proposalResult.status === 'blocked') {
+        return proposalResult;
+    }
+    const changelogPath = path.join(cwd, 'CHANGELOG.md');
+    const preview = renderChangelogPreview(proposalResult.proposal, 'CHANGELOG.md');
+    ports.showPreview(preview);
+    const updatePlan = planChangelogUpdate(ports.readFile(changelogPath), proposalResult.proposal);
+    if (updatePlan.status === 'blocked') {
+        return {
+            status: 'blocked',
+            message: updatePlan.message,
+            warnings: updatePlan.warnings,
+            preview,
+        };
+    }
+    if (!command.assumeYes) {
+        const confirmed = await ports.confirmWrite();
+        if (!confirmed) {
+            return {
+                status: 'declined',
+                changelogPath,
+                preview,
+                proposal: proposalResult.proposal,
+            };
+        }
+    }
+    ports.writeFile(changelogPath, updatePlan.content);
+    return {
+        status: 'written',
+        changelogPath,
+        preview,
+        content: updatePlan.content,
+        proposal: proposalResult.proposal,
+    };
+}
+function getTargetSection(command) {
+    if (!command.version) {
+        return {
+            status: 'ok',
+            value: { type: 'unreleased' },
+        };
+    }
+    const version = parseSemverVersion(command.version);
+    if (version.status === 'invalid') {
+        return {
+            status: 'blocked',
+            result: {
+                status: 'blocked',
+                message: version.message,
+                warnings: [
+                    {
+                        code: 'invalid-version',
+                        message: version.message,
+                    },
+                ],
+            },
+        };
+    }
+    const date = command.date ?? new Date().toISOString().slice(0, 10);
+    if (!isIsoDate(date)) {
+        const message = `Release date \`${date}\` must use ISO format YYYY-MM-DD.`;
+        return {
+            status: 'blocked',
+            result: {
+                status: 'blocked',
+                message,
+                warnings: [
+                    {
+                        code: 'invalid-date',
+                        message,
+                    },
+                ],
+            },
+        };
+    }
+    return {
+        status: 'ok',
+        value: {
+            type: 'version',
+            version: version.version.version,
+            date,
+        },
+    };
+}
+function addSemverMismatchWarning(proposal) {
+    if (proposal.targetSection.type !== 'version' || !proposal.sourceRange.fromRef) {
+        return proposal;
+    }
+    const previousVersion = parseSemverVersion(proposal.sourceRange.fromRef);
+    if (previousVersion.status !== 'ok') {
+        return proposal;
+    }
+    const targetVersion = parseSemverVersion(proposal.targetSection.version);
+    if (targetVersion.status !== 'ok') {
+        return proposal;
+    }
+    const actualBump = determineSemverBump(previousVersion.version, targetVersion.version);
+    if (actualBump.status !== 'ok' || actualBump.bump === proposal.semverGuidance.suggestedBump) {
+        return proposal;
+    }
+    const warning = {
+        code: 'semver-bump-mismatch',
+        message: `Provided version ${proposal.targetSection.version} is a ${actualBump.bump} bump from ${previousVersion.version.version}, but commit history suggests a ${proposal.semverGuidance.suggestedBump} bump.`,
+    };
+    return {
+        ...proposal,
+        warnings: [...proposal.warnings, warning],
+    };
+}
+function isIsoDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return false;
+    }
+    const date = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+function createNodeChangelogWritePorts() {
+    return {
+        readFile(filePath) {
+            if (!fs.existsSync(filePath)) {
+                return undefined;
+            }
+            return fs.readFileSync(filePath, 'utf8');
+        },
+        writeFile(filePath, content) {
+            fs.writeFileSync(filePath, content, 'utf8');
+        },
+        confirmWrite() {
+            return false;
+        },
+        showPreview(preview) {
+            process.stdout.write(preview);
+        },
+    };
+}

package/bin/modules/maintainer-release-support/generate-changelog/semver.js

@@ -0,0 +1,40 @@
+export function parseSemverVersion(input) {
+    const trimmedInput = input.trim();
+    const match = /^v?(?<major>0|[1-9]\d*)\.(?<minor>0|[1-9]\d*)\.(?<patch>0|[1-9]\d*)$/.exec(trimmedInput);
+    if (!match?.groups) {
+        return {
+            status: 'invalid',
+            message: `Release version \`${input}\` must use SemVer format MAJOR.MINOR.PATCH, with an optional leading v.`,
+        };
+    }
+    const major = Number(match.groups.major);
+    const minor = Number(match.groups.minor);
+    const patch = Number(match.groups.patch);
+    return {
+        status: 'ok',
+        version: {
+            version: `${major}.${minor}.${patch}`,
+            major,
+            minor,
+            patch,
+        },
+    };
+}
+export function determineSemverBump(previousVersion, nextVersion) {
+    if (nextVersion.major > previousVersion.major) {
+        return { status: 'ok', bump: 'major' };
+    }
+    if (nextVersion.major !== previousVersion.major) {
+        return { status: 'not-comparable' };
+    }
+    if (nextVersion.minor > previousVersion.minor) {
+        return { status: 'ok', bump: 'minor' };
+    }
+    if (nextVersion.minor !== previousVersion.minor) {
+        return { status: 'not-comparable' };
+    }
+    if (nextVersion.patch > previousVersion.patch) {
+        return { status: 'ok', bump: 'patch' };
+    }
+    return { status: 'not-comparable' };
+}

package/bin/modules/maintainer-release-support/index.js

@@ -0,0 +1,2 @@
+export { handleGenerateChangelogProposal, handleGenerateChangelogWrite } from './generate-changelog/handler.js';
+export { previewAndConfirmMaintainerRelease, planMaintainerRelease, executeConfirmedRelease } from './release-workflow/handler.js';

package/bin/modules/maintainer-release-support/release-workflow/git-release.js

@@ -0,0 +1,114 @@
+import { execFileSync } from 'node:child_process';
+import { parseSemverVersion } from '../generate-changelog/semver.js';
+export function resolveReleaseRange(command, cwd = process.cwd()) {
+    if (!isInsideGitRepository(cwd)) {
+        return blocked('not-git-repository', 'Run the release workflow inside a git repository.');
+    }
+    if (!isWorkingTreeClean(cwd)) {
+        return blocked('dirty-working-tree', 'Working tree must be clean before planning a release.');
+    }
+    const toRef = command.toRef ?? 'HEAD';
+    if (!isValidCommitRef(toRef, cwd)) {
+        return blocked('invalid-git-ref', `Could not resolve git ref \`${toRef}\`.`);
+    }
+    if (command.fromRef) {
+        if (!isValidCommitRef(command.fromRef, cwd)) {
+            return blocked('invalid-git-ref', `Could not resolve git ref \`${command.fromRef}\`.`);
+        }
+        return {
+            status: 'ok',
+            range: {
+                fromRef: command.fromRef,
+                toRef,
+            },
+            usedLatestSemverTag: false,
+        };
+    }
+    const latestSemverTag = getLatestReachableSemverTag(toRef, cwd);
+    if (!latestSemverTag) {
+        return blocked('missing-semver-tag', 'No previous SemVer-like release tag found. Provide --from and --version to release from an explicit baseline.');
+    }
+    return {
+        status: 'ok',
+        range: {
+            fromRef: latestSemverTag,
+            toRef,
+        },
+        usedLatestSemverTag: true,
+    };
+}
+export function checkReleaseTagAvailable(tagName, cwd = process.cwd()) {
+    const tagCommit = resolveRef(`refs/tags/${tagName}`, cwd);
+    if (!tagCommit) {
+        return { status: 'ok', existingTagAtHead: false };
+    }
+    const headCommit = resolveRef('HEAD', cwd);
+    if (tagCommit === headCommit) {
+        return { status: 'ok', existingTagAtHead: true };
+    }
+    return blockedTag('existing-target-tag', `Release tag \`${tagName}\` already exists and does not point at HEAD.`);
+}
+function isInsideGitRepository(cwd) {
+    try {
+        return runGit(['rev-parse', '--is-inside-work-tree'], cwd).trim() === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+function isWorkingTreeClean(cwd) {
+    return runGit(['status', '--porcelain'], cwd).trim().length === 0;
+}
+function isValidCommitRef(ref, cwd) {
+    try {
+        runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getLatestReachableSemverTag(toRef, cwd) {
+    const tags = readReachableTags(toRef, cwd);
+    return tags.find((tag) => parseSemverVersion(tag).status === 'ok');
+}
+function readReachableTags(toRef, cwd) {
+    try {
+        return runGit(['tag', '--merged', toRef, '--sort=-version:refname'], cwd)
+            .split('\n')
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function resolveRef(ref, cwd) {
+    try {
+        return runGit(['rev-parse', '--verify', '--quiet', ref], cwd).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function blocked(code, message) {
+    return {
+        status: 'blocked',
+        message,
+        warnings: [{ code, message }],
+    };
+}
+function blockedTag(code, message) {
+    return {
+        status: 'blocked',
+        message,
+        warnings: [{ code, message }],
+    };
+}
+function runGit(args, cwd) {
+    return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}