diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md new file mode 100644 index 0000000..d0d6726 --- /dev/null +++ b/.github/actions/analyze-hooks/README.md @@ -0,0 +1,133 @@ +# analyze-hooks + +Files the actions and filters a release adds, updates, deprecates or removes, and the views it +adds, changes or removes, as pending changelog entries, so the release notes name them. + +```yaml +- uses: actions/checkout@v6 + with: + ref: ${{ inputs.branch }} + persist-credentials: false + # The last release tag and the tree it points at are read from history. + fetch-depth: 0 + +- uses: stellarwp/plugin-toolbox/.github/actions/analyze-hooks@v1 + +# Write the changelog and commit here, e.g. with the release-prep action: this action only writes +# change files. +``` + +Run it before the changelog is written, so its entries are processed with the rest. It commits +nothing: the step that commits the release preparation carries the files. + +## What it writes + +The checkout is compared with the last release tag reachable from `HEAD`: the newest tag of three +or four numeric parts, with or without a leading `v` (`6.18.3`, `v5.3.0`, `4.19.1.1`). A tag such as +`6.18.3-rc1` or `ft-002` is not a release. + +| File in the changes directory | Entry | +|---|---| +| `analyze-hooks-added-filters.yaml` | ``Added filters: `a`, `b` `` | +| `analyze-hooks-updated-filters.yaml` | ``Updated filters: `a` `` | +| `analyze-hooks-deprecated-filters.yaml` | ``Deprecated filters: `a` `` | +| `analyze-hooks-removed-filters.yaml` | ``Removed filters: `a` `` | +| `analyze-hooks-added-actions.yaml` | ``Added actions: `a` `` | +| `analyze-hooks-updated-actions.yaml` | ``Updated actions: `a` `` | +| `analyze-hooks-deprecated-actions.yaml` | ``Deprecated actions: `a` `` | +| `analyze-hooks-removed-actions.yaml` | ``Removed actions: `a` `` | +| `analyze-hooks-added-views.yaml` | ``Added views: `src/views/v2/month.php` `` | +| `analyze-hooks-changed-views.yaml` | ``Changed views: `src/views/v2/list.php` `` | +| `analyze-hooks-removed-views.yaml` | ``Removed views: `src/views/v2/day.php` `` | + +Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes no file. + +- **Hooks** are the `apply_filters`, `apply_filters_ref_array`, `apply_filters_deprecated`, + `do_action`, `do_action_ref_array` and `do_action_deprecated` calls under `paths` whose name is a + complete string literal. A name built + from a variable, interpolation or concatenation is not listed, and neither is a call inside a + comment, inside a string, or in the HTML of a template outside ``. The name can be on any line after + the parenthesis. A hook is live while one of its calls is not a `_deprecated` one, deprecated when + every call is, and gone when it has none. A hook is added when it is live now and was not at the + tag, deprecated when it is deprecated now and was not, and removed when it is gone now and was + live or deprecated. A hook that moved, or that still has another call elsewhere, is not listed. +- **Updated hooks** are hooks in the same state in both trees whose docblocks have a `@since` line + now that they did not have at the tag: a change to a hook's signature is recorded as one more + line, such as `@since TBD Added the $type parameter.` The lines of every call's docblock are read + together. A docblock belongs to a call when no `;`, `{` or `}` comes between them. +- **Views** are the `.php` files matched by `views-paths` that were added, changed or removed since + the tag. A renamed view is changed, under its new path. Each is named by its path in the + checkout, `.php` included, so a reader with an override of the file finds it by that path. + +The files are rewritten on every run, so a second run changes nothing and an entry whose change was +reverted is removed. An entry is not written again when another pending change file holds it, or +when a changelog file already carries it above the heading of the last release, or of the newest +release before it when the changelog has no section for that one: the lines a run +after the changelog was written finds. An entry of an earlier release does not count, so a view +changed in two releases is listed in both. + +## What the repository needs + +- A checkout with full history and tags: `fetch-depth: 0`. A shallow checkout that shows no release + tag fails the step. A complete history with no release tag is a plugin before its first release: + the action writes nothing and warns. +- A changelogger. The changes directory (`changesDir`, `changelog` by default), the files the + changelog is written to and the label of each type are read from the `changelogger` section of + `package.json`. Without one, the entries go to `changelog/`. + +## A changelogger with its own types + +A repository whose changelogger has a type per kind of change passes them as `types`. An entry with +a type of its own holds the names only, since the type's label already says what they are: + +```yaml +- uses: stellarwp/plugin-toolbox/.github/actions/analyze-hooks@v1 + with: + # PHP files only: a markdown file can quote a hook call. + paths: | + *.php + :!vendor + :!vendor-prefixed + views-paths: | + themes/ld30/templates + themes/legacy/templates + src/views + includes/*/templates/* + types: >- + {"added-filters": "tweak: added filters", "updated-filters": "tweak: updated filters", + "deprecated-filters": "deprecated: deprecated filters", + "added-actions": "tweak: added actions", "updated-actions": "tweak: updated actions", + "deprecated-actions": "deprecated: deprecated actions", + "added-views": "tweak: added templates", "changed-views": "tweak: updated templates", + "removed-views": "deprecated: deprecated templates"} +``` + +With these types a changed template is written as +``Tweak - Updated templates: `themes/ld30/templates/course.php` ``. An entry left out of `types`, here +the removed hooks, stays a `tweak` reading `Removed filters: …`. + +## Inputs + +| Input | Default | | +|---|---|---| +| `paths` | `src` | Where to search for hooks, one git pathspec per line. `*.php` matches every PHP file, `:!vendor` excludes a directory. | +| `views-paths` | `src/views` | Where the templates a theme can override live, one git pathspec per line. A `*` matches across directories: `includes/*/templates/*`. Empty lists no view. | +| `types` | | The changelog type per entry, as a JSON object in a string. Keys: `added-filters`, `updated-filters`, `deprecated-filters`, `removed-filters`, `added-actions`, `updated-actions`, `deprecated-actions`, `removed-actions`, `added-views`, `changed-views`, `removed-views`. | +| `working-directory` | | Where the repository is checked out. Empty is the workspace. | + +## Outputs + +| Output | | +|---|---| +| `tag` | The last release tag the checkout was compared with. | +| `files` | The change files written, one per line. Empty when nothing changed. | + +## How it runs + +The logic is in [`analyze-hooks.js`](analyze-hooks.js), run by `actions/github-script`, so there is +no dependency to install and nothing to build. It only reads git and writes change files, so it is +safe to run on any checkout. + +Run its tests locally: `npm install` once in the toolbox, then +`node --test tests/actions/analyze-hooks/analyze-hooks.test.js`. They run the action against a real +git repository. diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml new file mode 100644 index 0000000..672e657 --- /dev/null +++ b/.github/actions/analyze-hooks/action.yml @@ -0,0 +1,73 @@ +# Files the actions and filters a release adds, updates, deprecates or removes, and the views it +# adds, changes or removes, as pending changelog entries, so the release notes name them. It +# compares the checkout with the last release tag and writes change files only: it commits +# nothing, so the step that commits the release preparation carries them. +# +# The logic lives in analyze-hooks.js, run by actions/github-script, so there is no dependency to +# install and nothing to build. +name: Analyze hooks +description: Files the hooks and views a release adds, changes or removes as pending changelog entries + +inputs: + paths: + description: >- + Where to search for `apply_filters`, `do_action` and their `_ref_array` and `_deprecated` + calls, one git pathspec per line, relative to the checkout. A pathspec can be a glob or an + exclusion: `*.php` then `:!vendor` searches every PHP file outside vendor. + required: false + default: 'src' + views-paths: + description: >- + Where the templates a theme can override live, one git pathspec per line, relative to the + checkout. Every `.php` file they match that was added, changed or removed since the last + release is listed by its path in the checkout, e.g. `src/views/v2/list.php`. A `*` matches + across directories, so `includes/*/templates/*` is the templates directory of every directory + under `includes`. Empty lists no view. + required: false + default: 'src/views' + types: + description: >- + The changelog type of each entry, as a JSON object in a string, for a changelogger that has a + type per kind of change, e.g. `'{"added-filters": "tweak: added filters"}'`. The keys are + `added-filters`, `updated-filters`, `deprecated-filters`, `removed-filters`, `added-actions`, + `updated-actions`, `deprecated-actions`, `removed-actions`, `added-views`, `changed-views` and + `removed-views`. An entry with a type here holds the names only, since the type's label says + what they are. An entry without one is a `tweak` reading `Added filters: …`. + required: false + default: '' + working-directory: + description: >- + Where the repository is checked out, relative to the workspace or absolute. Empty is the + workspace. A directory that is not there fails before anything runs. + required: false + default: '' + +outputs: + tag: + description: 'The last release tag the checkout was compared with, e.g. `6.18.3` or `v5.3.0`. Empty before the first release.' + value: ${{ steps.analyze.outputs.tag }} + files: + description: 'The change files written, one per line, relative to the checkout. Empty when nothing changed.' + value: ${{ steps.analyze.outputs.files }} + +runs: + using: 'composite' + steps: + - name: Add the hook and view changelog entries + id: analyze + uses: actions/github-script@v9 + env: + # github-script's require() resolves against the workspace of the repository being built, + # not this action's directory, so the path has to be passed in. github.action_path is the + # documented expression for it. + ACTION_PATH: ${{ github.action_path }} + # Read from process.env rather than interpolated into the script, so an input is data and + # never part of the program. + INPUT_PATHS: ${{ inputs.paths }} + INPUT_VIEWS_PATHS: ${{ inputs.views-paths }} + INPUT_TYPES: ${{ inputs.types }} + INPUT_WORKING_DIRECTORY: ${{ inputs.working-directory }} + with: + script: | + const { runAnalyzeHooks } = require(`${process.env.ACTION_PATH}/analyze-hooks.js`) + await runAnalyzeHooks({ core, exec, env: process.env }) diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js new file mode 100644 index 0000000..72cc04c --- /dev/null +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -0,0 +1,623 @@ +'use strict' + +/** + * Files the hooks and views a release changes as pending changelog entries, so the release notes + * name them. Run before the changelog is written, on a checkout with full history and tags. + * + * Compared with the last release tag: + * - the `apply_filters` / `do_action` calls under `paths` whose name is a complete string literal, + * outside comments and outside the HTML of a template. + * A hook is added when it is live now and was not at the tag, deprecated when every call became + * a `_deprecated` one, and removed when no call is left, so one that moved, or that still has + * another call elsewhere, is not listed. A hook in both trees whose docblocks gained a `@since` + * line is updated; + * - the `.php` files under `views-paths` that `git diff` reports as added, changed or renamed, or + * removed, by their path in the checkout. + * + * Each kind becomes one entry, `/analyze-hooks--.yaml`, so + * a second run rewrites the same files. An entry a changelog file already carries above the last + * release's heading, or another pending file holds, is not written again. + * + * runAnalyzeHooks reads the inputs and the checkout and runs git through `exec`. The functions it + * is built from are pure, so a test can call them with text. + */ + +const fs = require('node:fs') +const path = require('node:path') + +const { readChangeloggerSection } = require('../../lib/changelogger.js') +const { runOrFail } = require('../../lib/exec.js') +const { compareVersions } = require('../../lib/versions.js') +const { readWorkingDirectory, readCheckoutFile } = require('../../lib/workspace.js') + +/** What was not done, to close every error message. */ +const WHAT = 'No hook or view changelog entry was written.' + +/** The prefix of the files this action owns in the changes directory. */ +const FILE_PREFIX = 'analyze-hooks-' + +/** A release tag: three or four numeric parts, with or without a leading `v`. Not `6.18.3-rc1`, not `ft-002`. */ +const RELEASE_TAG = /^v?\d+\.\d+\.\d+(\.\d+)?$/ + +/** + * A hook call whose name is a plain string literal, closed by `,` or `)`. A name built from a + * variable, interpolation or concatenation (`'tec_' . $name`) is not a name. + */ +const HOOK_CALL = /\b(apply_filters|do_action)(_ref_array|_deprecated)?\s*\(\s*(?:'([^'$]+)'|"([^"$]+)")\s*[,)]/g + +/** Every entry the action can write, as `-`: the keys the `types` input takes. */ +const ENTRY_KEYS = [ + 'added-filters', + 'updated-filters', + 'deprecated-filters', + 'removed-filters', + 'added-actions', + 'updated-actions', + 'deprecated-actions', + 'removed-actions', + 'added-views', + 'changed-views', + 'removed-views', +] + +/** The type an entry has when `types` does not name one. */ +const DEFAULT_TYPE = 'tweak' + +/** + * The newest release tag, compared part by part as numbers. + * + * @param {string[]} tags The tags reachable from HEAD. + * + * @returns {string|undefined} The tag, or undefined when none is a release. + */ +function lastReleaseTag(tags) { + const version = (tag) => tag.replace(/^v/, '') + + return tags + .filter((tag) => RELEASE_TAG.test(tag)) + .sort((a, b) => compareVersions(version(a), version(b))) + .pop() +} + +/** Whitespace removed, so text rewrapped or respaced by hand still compares equal. */ +const squash = (text) => text.replace(/\s+/g, '') + +/** + * What `code` steps over in PHP: the closing tag, a block comment, a line comment (`#[` opens an + * attribute, not a comment), a quoted string and a heredoc or nowdoc. + */ +const TOKEN = + /\?>|\/\*[\s\S]*?\*\/|(?:\/\/|#(?!\[)).*?(?=\?>|$)|'(?:[^'\\]|\\[\s\S])*'|"(?:[^"\\]|\\[\s\S])*"|<<<[ \t]*(['"]?)(\w+)\1\r?\n[\s\S]*?^[ \t]*\2\b/gm + +/** + * The PHP code of a file, with its comments and the HTML outside `` turned to spaces and + * its strings kept, so a call in a comment or in a template's markup is not read as a call. + * + * @param {string} source A PHP file. + * + * @returns {{text: string, docblocks: {end: number, since: string[]}[], strings: number[][]}} The + * code, as long as the source; each `/**` comment, where it ends and its `@since` lines; + * and where each string and heredoc starts and ends. + */ +function code(source) { + const docblocks = [] + const strings = [] + const pieces = [] + let at = 0 + const blankTo = (end) => { + pieces.push(source.slice(at, end).replace(/[^\n]/g, ' ')) + at = end + } + // Up to and including the next ` { + const open = source.indexOf('') { + toPhp(at + 2) + } else if (/^(\/[/*]|#)/.test(match[0])) { + if (match[0].startsWith('/**')) { + const since = match[0].match(/@since\b.*$/gm) ?? [] + docblocks.push({ + end: at + match[0].length, + since: since.map((line) => squash(line.replace(/\*\/$/, ''))), + }) + } + blankTo(at + match[0].length) + } else { + strings.push([at, at + match[0].length]) + pieces.push(match[0]) + at += match[0].length + } + } + pieces.push(source.slice(at)) + + return { text: pieces.join(''), docblocks, strings } +} + +/** + * A hook in one tree: whether it is live, and its `@since` lines. + * + * @typedef {{live: boolean, since: Set}} Hook + */ + +/** + * The hooks a set of PHP files calls. A hook is live while one of its calls is not a `_deprecated` + * one, and deprecated when every call is. Its `@since` lines are those of the docblock above each + * call, when no `;`, `{` or `}` comes between the two. + * + * @param {string[]} sources The files. + * + * @returns {{filters: Map, actions: Map}} The hooks by name, per kind. + */ +function hooks(sources) { + const found = { filters: new Map(), actions: new Map() } + + for (const source of sources) { + const { text, docblocks, strings } = code(source) + + for (const match of text.matchAll(HOOK_CALL)) { + // Code quoted in a string is not a call. + if (strings.some(([start, end]) => start <= match.index && match.index < end)) { + continue + } + + const kind = found[match[1] === 'apply_filters' ? 'filters' : 'actions'] + const name = match[3] ?? match[4] + const hook = kind.get(name) ?? { live: false, since: new Set() } + const docblock = docblocks.findLast((doc) => doc.end <= match.index) + + hook.live ||= match[2] !== '_deprecated' + if (docblock && !/[;{}]/.test(text.slice(docblock.end, match.index))) { + docblock.since.forEach((line) => hook.since.add(line)) + } + kind.set(name, hook) + } + } + + return found +} + +/** + * Whether a hook's docblocks have a `@since` line they did not have at the tag. A line that came + * with a call deleted since does not hide a new one. + * + * @param {Hook} was The hook at the tag. + * @param {Hook} is The hook now. + * + * @returns {boolean} True when a line is new. + */ +function hasNewSince(was, is) { + return [...is.since].some((line) => !was.since.has(line)) +} + +/** + * The state of a hook in a tree. + * + * @param {Map} kind The tree's hooks of one kind. + * @param {string} name The hook. + * + * @returns {'live'|'deprecated'|'gone'} Whether it has a call that is not deprecated, only + * deprecated calls, or none. + */ +function state(kind, name) { + if (!kind.has(name)) { + return 'gone' + } + + return kind.get(name).live ? 'live' : 'deprecated' +} + +/** + * The entries between the tag's source and the current one. + * + * @param {string[]} before The files with a hook call at the last release. + * @param {string[]} after The files with a hook call now. + * @param {string} viewsDiff The views changed since the last release, as `git diff + * --name-status -z` prints them. + * + * @returns {{change: string, kind: string, names: string[]}[]} One entry per change and kind. + */ +function analyze(before, after, viewsDiff) { + const [old, now] = [hooks(before), hooks(after)] + const entries = [] + + // A hook that became live is added, one whose calls all became deprecated is deprecated, and one + // with no call left, live or deprecated before, is removed. One that stayed as it was is updated + // when its docblocks have a `@since` line they did not have at the tag. + for (const kind of ['filters', 'actions']) { + const names = { Added: [], Updated: [], Deprecated: [], Removed: [] } + + for (const name of new Set([...old[kind].keys(), ...now[kind].keys()])) { + const [was, is] = [state(old[kind], name), state(now[kind], name)] + + if (is !== was) { + names[{ live: 'Added', deprecated: 'Deprecated', gone: 'Removed' }[is]].push(name) + } else if (is !== 'gone' && hasNewSince(old[kind].get(name), now[kind].get(name))) { + names.Updated.push(name) + } + } + + for (const [change, list] of Object.entries(names)) { + if (list.length) { + entries.push({ change, kind, names: list.sort() }) + } + } + } + + // A status and a path, or for a rename the status and the old and the new path. A renamed view + // is changed, under its new path. + const views = { Added: [], Changed: [], Removed: [] } + const fields = viewsDiff.split('\0') + for (let at = 0; at < fields.length - 1; at += fields[at].startsWith('R') ? 3 : 2) { + const file = fields[at + (fields[at].startsWith('R') ? 2 : 1)] + + if (file.endsWith('.php')) { + views[{ A: 'Added', M: 'Changed', R: 'Changed', D: 'Removed' }[fields[at][0]]].push(file) + } + } + + for (const [change, list] of Object.entries(views)) { + if (list.length) { + entries.push({ change, kind: 'views', names: list.sort() }) + } + } + + return entries +} + +/** + * Reads an input of git pathspecs, one per line. + * + * @param {string} input The input value. + * + * @returns {string[]} The pathspecs, without blank lines. + */ +function readPathspecs(input) { + return String(input ?? '') + .split('\n') + .map((line) => line.trim()) + .filter(Boolean) +} + +/** + * Reads the `types` input: the changelog type of each entry, for a repository whose changelogger + * has a type per kind of hook change. + * + * @param {string} input A JSON object in a string, `-` to type. Empty is none. + * + * @throws {Error} When it is not a JSON object of known keys and non-empty strings. + * + * @returns {Object} The type per entry key. + */ +function readTypes(input) { + const trimmed = String(input ?? '').trim() + if (trimmed === '') { + return {} + } + + const shape = `Pass a JSON object in a string, with keys from ${ENTRY_KEYS.join(', ')}, e.g. '{"added-filters": "tweak: added filters"}'. ${WHAT}` + + let types + try { + types = JSON.parse(trimmed) + } catch { + throw new Error(`types is not valid JSON. ${shape}`) + } + + if (types === null || typeof types !== 'object' || Array.isArray(types)) { + throw new Error(`types is not a JSON object. ${shape}`) + } + + for (const [key, type] of Object.entries(types)) { + if (!ENTRY_KEYS.includes(key)) { + throw new Error(`types has the unknown key '${key}'. ${shape}`) + } + if (typeof type !== 'string' || type.trim() === '') { + throw new Error(`types.${key} is not a changelog type. ${shape}`) + } + } + + return types +} + +/** + * Reads what the repository's changelogger configures, from package.json. A file that is missing, + * not JSON, or without a `changelogger` section gives the changelogger's defaults, as it does for + * the changelogger itself. + * + * @param {string|null} packageJson The file's contents, or null when there is none. + * + * @returns {{changesDir: string, changelogFiles: string[], labels: Object}} Where + * the pending entries live, the files the changelog is written to, and the label each + * type is written with. + */ +function readChangelogger(packageJson) { + const config = readChangeloggerSection(packageJson) ?? {} + + const written = (Array.isArray(config.files) ? config.files : []).map((file) => file?.path) + + return { + changesDir: typeof config.changesDir === 'string' && config.changesDir !== '' ? config.changesDir : 'changelog', + // readme.txt and changelog.md as well as what is configured: a custom writing strategy names + // no file, and a file that is not there is skipped. + changelogFiles: [...new Set([config.changelogFile, ...written, 'changelog.md', 'readme.txt'])].filter( + (file) => typeof file === 'string' && file !== '' + ), + labels: config.types !== null && typeof config.types === 'object' ? config.types : {}, + } +} + +/** + * The type and text of an entry. + * + * Without a type of its own an entry is a `tweak` that says what it is, `Added filters: …`. A type + * from `types` already says it, in the label the changelogger writes, so the text is the names. + * + * @param {{change: string, kind: string, names: string[]}} entry The entry. + * @param {Object} types The `types` input. + * + * @returns {{key: string, type: string, text: string}} The entry's key, changelog type and text. + */ +function describe(entry, types) { + const key = `${entry.change.toLowerCase()}-${entry.kind}` + const names = entry.names.map((name) => `\`${name}\``).join(', ') + + return types[key] + ? { key, type: types[key], text: names } + : { key, type: DEFAULT_TYPE, text: `${entry.change} ${entry.kind}: ${names}` } +} + +/** A YAML scalar on one line: double quoted, single quoted or plain. */ +const SCALAR = '(?:"((?:[^"\\\\]|\\\\.)*)"|\'((?:[^\']|\'\')*)\'|(.+))' + +/** + * Reads a one-line scalar of a change file. + * + * @param {string} body The change file. + * @param {string} key The key to read. + * + * @returns {string|undefined} Its value, unquoted. + */ +function scalar(body, key) { + const match = new RegExp(`^${key}:\\s*${SCALAR}\\s*$`, 'm').exec(body) + if (!match) { + return undefined + } + if (match[1] !== undefined) { + return match[1].replace(/\\(.)/g, '$1') + } + + return match[2] !== undefined ? match[2].replace(/''/g, "'") : match[3].trim() +} + +/** + * Whether the plugin already carries an entry: in a changelog file, as a line that is the type's + * label and the text, or in a pending change file that is not this action's. + * + * @param {{type: string, text: string}} entry The entry. + * @param {object} known + * @param {string[]} known.lines The squashed `* ` lines of the changelog files. + * @param {Set} known.pending The pending entries, as squashed `type|text`. + * @param {Object} labels The label the changelogger writes each type with. + * + * @returns {boolean} True when it is already there. + */ +function isKnown(entry, known, labels) { + if (known.pending.has(squash(`${entry.type}|${entry.text}`))) { + return true + } + + const label = labels[entry.type] ?? `${entry.type[0].toUpperCase()}${entry.type.slice(1)}` + + // `Tweak - Added filters: …` from the stock strategies; a label that ends the sentence itself, + // `Tweak - Added actions:`, is followed by the names with no separator. + return [squash(`${label}-${entry.text}`), squash(`${label}${entry.text}`)].some((line) => known.lines.includes(line)) +} + +/** A heading of a changelog file that names a version: `= [6.18.2] 2026-01-01 =`, `= 3.9.0 =`, `### [6.18.2]`. */ +const VERSION_HEADING = /^[=#].*?(?}} What isKnown compares with. + */ +function readKnown(cwd, changesDir, changelogFiles, version) { + const lines = changelogFiles.flatMap((file) => + [...sinceLastRelease(readCheckoutFile(cwd, file) ?? '', version).matchAll(/^\* (.+)$/gm)].map((match) => + squash(match[1]) + ) + ) + + const pending = new Set() + const dir = path.join(cwd, changesDir) + + for (const file of fs.existsSync(dir) ? fs.readdirSync(dir) : []) { + if (!file.endsWith('.yaml') || file.startsWith(FILE_PREFIX)) { + continue + } + + const body = fs.readFileSync(path.join(dir, file), 'utf8') + const [type, text] = [scalar(body, 'type'), scalar(body, 'entry')] + + if (type !== undefined && text !== undefined) { + pending.add(squash(`${type}|${text}`)) + } + } + + return { lines, pending } +} + +/** + * Runs the action. + * + * @param {object} options + * @param {object} options.core The @actions/core toolkit, for the log, the outputs and the summary. + * @param {object} options.exec The @actions/exec toolkit, which runs git. + * @param {object} options.env The environment, holding the inputs as `INPUT_*`. + * @param {string} options.cwd The workspace, the process's working directory by default. + * + * @throws {Error} When an input is refused, or the checkout is shallow and shows no release tag. + * + * @returns {Promise} + */ +async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() }) { + const paths = readPathspecs(env.INPUT_PATHS) + if (paths.length === 0) { + throw new Error(`paths is empty. Pass the directories to search for hooks, one per line, e.g. src. ${WHAT}`) + } + const viewsPaths = readPathspecs(env.INPUT_VIEWS_PATHS) + const types = readTypes(env.INPUT_TYPES) + const cwd = readWorkingDirectory(env.INPUT_WORKING_DIRECTORY, { base: workspace, what: WHAT }) + const { changesDir, changelogFiles, labels } = readChangelogger(readCheckoutFile(cwd, 'package.json')) + + const git = (args, what) => runOrFail(exec, 'git', args, { cwd, silent: true }, what) + + const tag = lastReleaseTag((await git(['tag', '--merged', 'HEAD'], 'Listing the tags')).split('\n')) + if (!tag) { + // A shallow checkout hides the tags behind it, which is a mistake in the workflow. A complete + // history without a release tag is a plugin before its first release, with nothing to compare. + const shallow = (await git(['rev-parse', '--is-shallow-repository'], 'Reading the checkout')).trim() === 'true' + if (shallow) { + throw new Error( + 'No release tag is reachable from HEAD, and the checkout is shallow, so the last release cannot ' + + `be found. Check out with fetch-depth: 0. ${WHAT}` + ) + } + + core.setOutput('tag', '') + core.setOutput('files', '') + core.warning(`No release tag is reachable from HEAD: there is no last release to compare with. ${WHAT}`) + + return + } + + // git grep exits 1 when nothing matches, which is a tree without hooks, not a failure. + const grep = async (args) => { + const result = await exec.getExecOutput('git', ['grep', '-I', '-z', '--full-name', ...args], { + cwd, + silent: true, + ignoreReturnCode: true, + }) + if (result.exitCode > 1) { + throw new Error(`Searching for hooks failed (exit code ${result.exitCode}):\n${result.stderr.trim()}`) + } + + return result.stdout + } + + // Every file under `paths` with a hook call, whole, so a name on any line after the parenthesis + // and a call inside a comment are read right. `-e ''` matches every line, each printed after its + // file's name and a NUL. + // The file names are passed as arguments, which holds for a few thousand files. + const sources = async (...tree) => { + const prefix = tree.length ? `${tree[0]}:` : '' + const files = (await grep(['-l', '-E', '(apply_filters|do_action)', ...tree, '--', ...paths])) + .split('\0') + .filter(Boolean) + .map((file) => `:(top,literal)${file.slice(prefix.length)}`) + if (files.length === 0) { + return [] + } + + const lines = new Map() + for (const line of (await grep(['-e', '', ...tree, '--', ...files])).split('\n')) { + const nul = line.indexOf('\0') + if (nul !== -1) { + const file = line.slice(0, nul) + if (!lines.has(file)) { + lines.set(file, []) + } + lines.get(file).push(line.slice(nul + 1)) + } + } + + return [...lines.values()].map((file) => file.join('\n')) + } + + // --relative names a file by its path in the checkout, which git prints the same whatever the + // form of the pathspec, `./src/views` or `src/views/`. + const viewsDiff = + viewsPaths.length === 0 + ? '' + : await git( + ['diff', '--name-status', '-z', '-M', '--relative', '--diff-filter=ADMR', tag, '--', ...viewsPaths], + 'Listing the changed views' + ) + + const known = readKnown(cwd, changesDir, changelogFiles, tag.replace(/^v/, '')) + const dir = path.join(cwd, changesDir) + fs.mkdirSync(dir, { recursive: true }) + + // Rewritten from scratch: a file from an earlier run whose change was since reverted must go. + for (const file of fs.readdirSync(dir)) { + if (file.startsWith(FILE_PREFIX) && file.endsWith('.yaml')) { + fs.rmSync(path.join(dir, file)) + } + } + + const summary = [`## Hook and view changes since ${tag}`] + const files = [] + + for (const found of analyze(await sources(tag), await sources(), viewsDiff)) { + const entry = describe(found, types) + + if (isKnown(entry, known, labels)) { + summary.push(`- skipped \`${entry.key}\`, the plugin already has it`) + continue + } + + const file = `${changesDir}/${FILE_PREFIX}${entry.key}.yaml` + // JSON strings are valid YAML double-quoted scalars, so no name can break out of the entry. + fs.writeFileSync( + path.join(cwd, file), + `significance: patch\ntype: ${JSON.stringify(entry.type)}\nentry: ${JSON.stringify(entry.text)}\n` + ) + files.push(file) + summary.push(`- \`${file}\`: ${entry.text}`) + } + + core.setOutput('tag', tag) + core.setOutput('files', files.join('\n')) + core.info(`Wrote ${files.length} hook and view changelog entries (since ${tag}).`) + await core.summary.addRaw(summary.join('\n'), true).write() +} + +module.exports = { runAnalyzeHooks, lastReleaseTag, readTypes } diff --git a/README.md b/README.md index 93ac9b8..ed72fd7 100644 --- a/README.md +++ b/README.md @@ -166,6 +166,7 @@ Each phase ends with something people can actually use. - [ ] Port `setup-slic`, `prepare-matrix`, `setup-bun` from LearnDash. - [ ] Port `check-php-changes`, `smart-checkout`, `process-changelog`, `add-changelog`, `generate-pot` from TEC. +- [x] Port `analyze-hooks` from TEC: the actions and filters a release adds, updates, deprecates or removes and the views it adds, changes or removes, as pending changelog entries. The search paths, the views paths and the changelog types are inputs, and a `v` on the release tag is accepted. - [ ] Add `setup-node` for the npm crowd. - [x] Add `release-prep`: version bump, TBD replacement and changelog through pup and the changelogger action, committed to the release branch through the GitHub API. A caller to copy is in `templates/workflows/release-prep.yml`. - [x] Add `release-merge`: the release branch into the base branch, the base back into develop, each step safe to rerun and a conflict reported with a `MERGE_CONFLICT` line. diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js new file mode 100644 index 0000000..72c34d7 --- /dev/null +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -0,0 +1,413 @@ +'use strict' + +const { describe, it, beforeEach, afterEach } = require('node:test') +const assert = require('node:assert') +const { execFileSync } = require('node:child_process') +const fs = require('node:fs') +const os = require('node:os') +const path = require('node:path') + +const { + runAnalyzeHooks, + lastReleaseTag, + readTypes, +} = require('../../../.github/actions/analyze-hooks/analyze-hooks.js') +const { coreWithOutputs, recordedRealExec } = require('../../support/actions.js') + +/** A git that signs nothing, whatever the machine it runs on configures: a signed tag asks for a message. */ +const GIT_ENV = { + ...process.env, + GIT_AUTHOR_NAME: 't', + GIT_AUTHOR_EMAIL: 't@example.com', + GIT_COMMITTER_NAME: 't', + GIT_COMMITTER_EMAIL: 't@example.com', + GIT_CONFIG_COUNT: '2', + GIT_CONFIG_KEY_0: 'tag.gpgsign', + GIT_CONFIG_VALUE_0: 'false', + GIT_CONFIG_KEY_1: 'commit.gpgsign', + GIT_CONFIG_VALUE_1: 'false', +} + +const BEFORE = ` `significance: patch\ntype: ${JSON.stringify(type)}\nentry: ${JSON.stringify(text)}\n` + +describe('analyze-hooks', () => { + let repo + + const git = (...args) => execFileSync('git', args, { cwd: repo, env: GIT_ENV, encoding: 'utf8', stdio: 'pipe' }) + + const write = (name, body) => { + fs.mkdirSync(path.dirname(path.join(repo, name)), { recursive: true }) + fs.writeFileSync(path.join(repo, name), body) + } + + const commit = (message) => { + git('add', '--all') + git('commit', '-q', '--allow-empty', '-m', message) + } + + const entries = (dir = 'changelog') => + Object.fromEntries( + (fs.existsSync(path.join(repo, dir)) ? fs.readdirSync(path.join(repo, dir)) : []) + .filter((file) => file.endsWith('.yaml')) + .sort() + .map((file) => [file, fs.readFileSync(path.join(repo, dir, file), 'utf8')]) + ) + + const run = async (t, inputs = {}) => { + const { core, outputs, summary } = await coreWithOutputs(t) + const { exec } = await recordedRealExec() + + await runAnalyzeHooks({ + core, + exec, + cwd: repo, + env: { INPUT_PATHS: 'src', INPUT_VIEWS_PATHS: 'src/views', ...inputs }, + }) + + return { outputs: outputs(), summary: summary() } + } + + beforeEach(() => { + repo = fs.mkdtempSync(path.join(os.tmpdir(), 'toolbox-analyze-hooks-')) + git('init', '-q', '-b', 'main') + write('src/Tribe/Main.php', BEFORE) + write('src/views/v2/list.php', ' { + fs.rmSync(repo, { recursive: true, force: true }) + }) + + it('writes one entry per kind of added and removed hook and for the changed views', async (t) => { + const { outputs } = await run(t) + + assert.deepStrictEqual(entries(), { + 'analyze-hooks-added-actions.yaml': entry('Added actions: `tec_added_action`, `tec_added_ref`'), + 'analyze-hooks-added-filters.yaml': entry('Added filters: `tec_added_a`, `tec_added_b`'), + 'analyze-hooks-changed-views.yaml': entry('Changed views: `src/views/v2/list.php`'), + 'analyze-hooks-removed-actions.yaml': entry('Removed actions: `tec_removed_action`'), + 'analyze-hooks-removed-filters.yaml': entry('Removed filters: `tec_removed_filter`'), + }) + assert.strictEqual(outputs.tag, '6.18.2') + assert.strictEqual(outputs.files.split('\n').length, 5) + }) + + it('does not list a hook that only moved, or whose name is dynamic or concatenated', async (t) => { + write('src/Tribe/Concat.php', " { + write('src/Tribe/Twin.php', " { + write( + 'src/Tribe/Deprecated.php', + " { + const docblock = (...since) => `/**\n * A hook.\n *\n${since.map((line) => ` * @since ${line}\n`).join('')} */\n` + write( + 'src/Tribe/Updated.php', + ` { + const call = (since) => `/**\n * A hook.\n *\n * @since ${since}\n */\ndo_action( 'tec_swapped' );\n` + write('src/Tribe/Swapped.php', ` { + await run(t) + const first = entries() + await run(t) + assert.deepStrictEqual(entries(), first) + + write('src/Tribe/Main.php', BEFORE) + commit('revert') + await run(t) + assert.deepStrictEqual(Object.keys(entries()), ['analyze-hooks-changed-views.yaml']) + }) + + it('compares with the last release tag, with or without a leading v', async (t) => { + git('tag', 'v6.18.3') + const { outputs } = await run(t) + + assert.strictEqual(outputs.tag, 'v6.18.3') + assert.deepStrictEqual(entries(), {}) + }) + + it('does not write an entry a changelog file or another pending file already has', async (t) => { + write('changelog.md', '= [6.18.3] =\n\n* Tweak - Changed views: `src/views/v2/list.php`\n\n= [6.18.2] =\n\n* Fix - A fix.\n') + write('changelog/by-hand.yaml', 'significance: patch\ntype: tweak\nentry: "Removed actions: `tec_removed_action`"\n') + await run(t) + + const written = Object.keys(entries()) + assert.ok(!written.includes('analyze-hooks-changed-views.yaml')) + assert.ok(!written.includes('analyze-hooks-removed-actions.yaml')) + assert.ok(written.includes('analyze-hooks-added-actions.yaml')) + }) + + it('still lists a change an earlier release also made', async (t) => { + write('readme.txt', 'Stable tag: 6.18.2\n\n== Changelog ==\n\n= [6.18.2] 2026-01-01 =\n\n* Tweak - Changed views: `src/views/v2/list.php`\n') + await run(t) + + assert.ok('analyze-hooks-changed-views.yaml' in entries()) + }) + + it('still lists it when the changelog has no section for the last release', async (t) => { + write('changelog.md', '### [6.18.1] 2026-01-01\n\n* Tweak - Changed views: `src/views/v2/list.php`\n') + await run(t) + + assert.ok('analyze-hooks-changed-views.yaml' in entries()) + }) + + it('reads a hook whose name is on the line after the parenthesis', async (t) => { + write('src/Tribe/Wrapped.php', " { + write('src/Tribe/Three.php', " { + write('src/Tribe/Main.php', AFTER.replace("do_action( \"tec_added_action\", $x );", "// do_action( 'tec_removed_action' );")) + write( + 'src/Tribe/Comments.php', + [ + '

Don't do_action( 'tec_html' );

", + '', + ].join('\n') + ) + commit('comments') + await run(t) + + const written = entries() + assert.strictEqual( + written['analyze-hooks-added-actions.yaml'], + entry('Added actions: `tec_added_ref`, `tec_after_string`, `tec_in_template`') + ) + assert.strictEqual(written['analyze-hooks-removed-actions.yaml'], entry('Removed actions: `tec_removed_action`')) + assert.ok(!written['analyze-hooks-added-filters.yaml'].includes('tec_block')) + assert.ok(!written['analyze-hooks-added-filters.yaml'].includes('tec_quoted')) + }) + + it('writes nothing, with a warning, before the first release', async (t) => { + git('tag', '-d', '6.18.2') + const { outputs } = await run(t) + + assert.deepStrictEqual(entries(), {}) + assert.strictEqual(outputs.tag, '') + }) + + it('fails when a shallow checkout shows no release tag', async (t) => { + const full = repo + repo = fs.mkdtempSync(path.join(os.tmpdir(), 'toolbox-analyze-hooks-shallow-')) + execFileSync('git', ['clone', '-q', '--depth', '1', '--no-tags', `file://${full}`, repo], { env: GIT_ENV, stdio: 'pipe' }) + fs.rmSync(full, { recursive: true, force: true }) + + await assert.rejects(run(t), /the checkout is shallow/) + }) + + it('searches every path it is given, a glob included, and honours an exclusion', async (t) => { + write('includes/legacy.php', " { + write('themes/ld30/templates/course.php', ' { + write('src/views/v2/week.php', ' { + write('includes/courses/templates/course.php', ' { + await run(t, { INPUT_VIEWS_PATHS: './src/views' }) + + assert.strictEqual(entries()['analyze-hooks-changed-views.yaml'], entry('Changed views: `src/views/v2/list.php`')) + }) + + it('writes the names only under a type of its own, where the changelogger keeps its change files', async (t) => { + write( + 'package.json', + JSON.stringify({ + changelogger: { + changesDir: 'changes', + changelogFile: 'changelog.txt', + types: { 'tweak: added actions': 'Tweak - Added actions:' }, + }, + }) + ) + // The label ends the sentence itself, so the names follow it with no separator. + write('changelog.txt', '* Tweak - Added actions: `tec_added_action`, `tec_added_ref`\n') + await run(t, { + INPUT_TYPES: '{"added-actions": "tweak: added actions", "added-filters": "tweak: added filters"}', + }) + + const written = entries('changes') + assert.strictEqual( + written['analyze-hooks-added-filters.yaml'], + entry('`tec_added_a`, `tec_added_b`', 'tweak: added filters') + ) + assert.ok(!('analyze-hooks-added-actions.yaml' in written), 'changelog.txt already has it') + assert.strictEqual(written['analyze-hooks-removed-filters.yaml'], entry('Removed filters: `tec_removed_filter`')) + }) + + it('writes to the changelogger defaults when package.json is not JSON', async (t) => { + write('package.json', '{ not json') + await run(t) + + assert.ok('analyze-hooks-added-actions.yaml' in entries('changelog')) + }) + + it('refuses an empty paths input', async (t) => { + await assert.rejects(run(t, { INPUT_PATHS: '\n \n' }), /paths is empty/) + }) + + it('refuses a types input that is not an object of known keys', () => { + assert.throws(() => readTypes('[]'), /not a JSON object/) + assert.throws(() => readTypes('{nope'), /not valid JSON/) + assert.throws(() => readTypes('{"added-hooks": "tweak"}'), /unknown key 'added-hooks'/) + assert.throws(() => readTypes('{"added-filters": ""}'), /not a changelog type/) + assert.deepStrictEqual(readTypes('{"deprecated-actions": "deprecated: deprecated actions", "removed-views": "deprecated: deprecated templates"}'), { + 'deprecated-actions': 'deprecated: deprecated actions', + 'removed-views': 'deprecated: deprecated templates', + }) + }) + + it('orders release tags by their numeric parts', () => { + assert.strictEqual(lastReleaseTag(['6.9.0', '6.10.0', '6.10.0.1', 'v6.2.0', '6.11.0-rc1', 'ft-002', '']), '6.10.0.1') + assert.strictEqual(lastReleaseTag(['ft-002']), undefined) + }) +})