Proyectos de Subversion Moodle

#!/usr/bin/env node
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

import chalk from 'chalk';
import { getAllComponents } from './components.mjs';
import { getCombinedNotesByComponent, deleteAllNotes } from './note.mjs';
import { getNoteName } from './noteTypes.mjs';
import { writeFile, readFile, unlink } from 'fs/promises';
import { join as joinPath } from 'path';
import logger from './logger.mjs';
import { getCurrentVersion } from './helpers.mjs';

/**
 * Helper to fetch the current notes from a file.
 *
 * @param {string} file
 * @returns {Promise<string>}
 */
const getCurrentNotes = async (file) => {
    try {
        return await readFile(file, 'utf8');
    } catch (error) {
        return null;
    }
}

/**
 * Update the UPGRADING.md file.
 *
 * @param {string} upgradeNotes
 * @param {Object} options
 * @param {boolean} options.deleteNotes
 * @returns {Promise<void>}
 */
const updateUpgradeNotes = async (upgradeNotes, options) => {
    const fileName = 'UPGRADING.md';
    // Write the notes to a file.
    logger.info(`Writing notes to ${chalk.underline(chalk.bold(fileName))}`);
    // Prepend to the existing file.
    const existingContent = await getCurrentNotes(fileName);
    if (existingContent) {
        await writeFile(fileName, getUpdatedNotes(existingContent, upgradeNotes));
    } else {
        // This should not normally happen.
        await writeFile(fileName, upgradeNotes);
    }

    if (options.deleteNotes) {
        logger.warn(`>>> Deleting all notes <<<`)
        // Delete the notes.
        deleteAllNotes();
    }
};

/**
 * Create the current summary notes.
 *
 * @param {string} upgradeNotes
 * @returns {Promise<void>}
 */
const createCurrentSummary = async (upgradeNotes) => {
    const fileName = 'UPGRADING-CURRENT.md';
    const notes = `# Moodle upgrade notes\n\n${upgradeNotes}`;
    await writeFile(fileName, notes);

    logger.info(`Running upgrade notes written to ${chalk.underline(chalk.bold(fileName))}`);
};

/**
 * Get the indexes of the lines that contain the version headings.
 *
 * @param {array<string>} lines
 * @returns {array<object>}
 */
const getVersionLineIndexes = (lines) => {
    const h2Indexes = [];
    lines.forEach((line, index) => {
        const matches = line.match(/^##\s(?<version>.*)$/);
        if (matches) {
            h2Indexes.push({
                index,
                line,
                version: matches.groups.version,
            });
        }
    });

    return h2Indexes;
};

/**
 * Find the index of the Unreleased heading.
 *
 * @param {array<object>} versionHeadings
 * @returns {number}
 */
const findUnreleasedHeadingIndex = (versionHeadings) => versionHeadings.findIndex((heading) => {
    if (heading.version === 'Unreleased') {
        // Used if version cannot be guessed.
        return true;
    }

    if (heading.version.endsWith('+')) {
        // Weekly release for a stable branch.
        return true;
    }

    if (heading.version.match(/beta|rc\d/)) {
        // Beta and RC rolls are treated as weeklies.
        return true;
    }

    if (heading.version.endsWith('dev')) {
        // Development version.
        return true;
    }

    return false;
});

/**
 * Get the before and after content, to facilitate replacing any existing Unreleased notes.
 *
 * @param {array<string>} lines
 * @returns {Object} {beforeContent: string, afterContent: string}
 */
const getBeforeAndAfterContent = (lines) => {
    const existingLines = lines.split('\n');
    const versionHeadings = getVersionLineIndexes(existingLines);

    if (versionHeadings.length > 0) {
        const unreleasedHeadingIndex = findUnreleasedHeadingIndex(versionHeadings);
        if (unreleasedHeadingIndex !== -1) {
            const beforeContent = existingLines.slice(0, versionHeadings[unreleasedHeadingIndex].index).join('\n');
            if (versionHeadings.length > unreleasedHeadingIndex + 1) {
                const afterContent = existingLines.slice(versionHeadings[unreleasedHeadingIndex + 1].index).join('\n');
                return {
                    beforeContent,
                    afterContent,
                };
            }
            return {
                beforeContent,
                afterContent: '',
            };
        }

        return {
            beforeContent: existingLines.slice(0, versionHeadings[0].index).join('\n'),
            afterContent: existingLines.slice(versionHeadings[0].index).join('\n'),
        };
    }

    return {
        beforeContent: existingLines.join('\n'),
        afterContent: '',
    }
};

/**
 * Get the notes for the component.
 *
 * @param {string} types
 * @param {Number} headingLevel
 * @returns {string}
 */
const getNotesForComponent = (types, headingLevel) => {
    let upgradeNotes = '';
    Object.entries(types).forEach(([type, notes]) => {
        upgradeNotes += '#'.repeat(headingLevel);
        upgradeNotes += ` ${getNoteName(type)}\n\n`;
        notes.forEach(({ message, issueNumber }) => {
            // Split the message into lines, removing empty lines.
            const messageLines = message
                .split('\n')
                // Remove empty lines between tables, and list entries, but not after lists.
                .filter((line, index, lines) => {
                    if (line.trim().length === 0) {
                        // This line is empty.

                        // If it's the first line in the file, remove it.
                        if (index === 0) {
                            return false;
                        }

                        // This is the last line in the file, remove it.
                        if (index === lines.length - 1) {
                            return false;
                        }

                        // If the previous line relates to a table, remove this line.
                        if (lines[index - 1].match(/^\s*\|/)) {
                            return false;
                        }

                        // If the next line is also empty, do not remove this line.
                        if (lines[index + 1].trim().length === 0) {
                            return true;
                        }

                        // Do not remove the line if the previous line was a list item.
                        if (lines[index - 1].match(/^\s*[-*]\s/)) {
                            return true;
                        }

                        if (lines[index - 1].match(/^\s*\d+\.\s/)) {
                            return true;
                        }

                        // Preserve all other empty lines by default.
                        return true;
                    }

                    // Keep any line which has content.
                    return true;
                });


            const firstLine = messageLines.shift().trim();
            upgradeNotes += `- ${firstLine}\n`;

            messageLines
                .forEach((line) => {
                    upgradeNotes += `  ${line}`.trimEnd() + `\n`;
                });
            upgradeNotes += `\n  For more information see [${issueNumber}](https://tracker.moodle.org/browse/${issueNumber})\n`;
        });
        upgradeNotes += '\n';
    });

    return upgradeNotes;
};

/**
 * Get the updated notes mixed with existing content.
 *
 * @param {string} existingContent
 * @param {string} upgradeNotes
 */
const getUpdatedNotes = (existingContent, upgradeNotes) => {
    const { beforeContent, afterContent } = getBeforeAndAfterContent(existingContent);
    const newContent = `${beforeContent}\n${upgradeNotes}\n${afterContent}`
        .split('\n')
        .filter((line, index, lines) => {
            if (line === '' && lines[index - 1] === '') {
                // Remove multiple consecutive empty lines.
                return false;
            }
            return true;
        })
        .join('\n');

    return newContent;
};

/**
 * Update the notes for each component.
 */
const updateComponentNotes = (
    notes,
    version,
    notesFileName = 'UPGRADING.md',
    removeEmpty = false,
) => {
    return getAllComponents().map(async (component) => {
        logger.verbose(`Updating notes for ${component.name} into ${component.path}`);
        const fileName = joinPath(component.path, notesFileName);

        const existingContent = await getCurrentNotes(fileName);

        if (!existingContent) {
            if (!notes[component.value]) {
                // No existing notes, and no new notes to add.
                return;
            }
        } else {
            if (!notes[component.value]) {
                // There is existing content, but nothing to add.
                if (removeEmpty) {
                    logger.verbose(`Removing empty notes file ${fileName}`);
                    await unlink(fileName);
                }
                return;
            }
        }

        const componentNotes = notes[component.value];
        let upgradeNotes = `## ${version}\n\n`;
        upgradeNotes += getNotesForComponent(componentNotes, 3);

        if (existingContent) {
            await writeFile(fileName, getUpdatedNotes(existingContent, upgradeNotes));
        } else {
            await writeFile(
                fileName,
                `# ${component.name} Upgrade notes\n\n${upgradeNotes}`,
            );
        }
    });
}

/**
 * Generate the upgrade notes for a new release.
 *
 * @param {string|undefined} version
 * @param {Object} options
 * @param {boolean} options.generateUpgradeNotes
 * @param {boolean} options.deleteNotes
 * @returns {Promise<void>}
 */
export default async (version, options = {}) => {
    const notes = await getCombinedNotesByComponent();

    if (Object.keys(notes).length === 0) {
        logger.warn('No notes to generate');
        return;
    }

    if (!version) {
        version = await getCurrentVersion();
    }

    // Generate the upgrade notes for this release.
    // We have
    // - a title with the release name
    // - the change types
    // - which contain the components
    // - which document each change
    let upgradeNotes = `## ${version}\n\n`;

    Object.entries(notes).forEach(([component, types]) => {
        upgradeNotes += `### ${component}\n\n`;
        upgradeNotes += getNotesForComponent(types, 4);
    });

    await Promise.all([
        createCurrentSummary(upgradeNotes),
        ...updateComponentNotes(notes, version, 'UPGRADING-CURRENT.md', true),
    ]);
    if (options.generateUpgradeNotes) {
        await Promise.all(updateComponentNotes(notes, version));
        await updateUpgradeNotes(upgradeNotes, options);
    }
};