From 55c961217dad600792fe3a1c4e28201af6a72b09 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Tue, 10 Nov 2026 21:43:12 -0300 Subject: [PATCH 01/14] Add analyze-hooks: the hooks a release adds or removes and the views it changes, as changelog entries --- .github/actions/analyze-hooks/README.md | 103 +++++ .github/actions/analyze-hooks/action.yml | 69 +++ .../actions/analyze-hooks/analyze-hooks.js | 425 ++++++++++++++++++ README.md | 1 + .../analyze-hooks/analyze-hooks.test.js | 239 ++++++++++ 5 files changed, 837 insertions(+) create mode 100644 .github/actions/analyze-hooks/README.md create mode 100644 .github/actions/analyze-hooks/action.yml create mode 100644 .github/actions/analyze-hooks/analyze-hooks.js create mode 100644 tests/actions/analyze-hooks/analyze-hooks.test.js diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md new file mode 100644 index 00000000..147284db --- /dev/null +++ b/.github/actions/analyze-hooks/README.md @@ -0,0 +1,103 @@ +# analyze-hooks + +Files the actions and filters a release adds or removes, and the views it changes, 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-removed-filters.yaml` | ``Removed filters: `a` `` | +| `analyze-hooks-added-actions.yaml` | ``Added actions: `a` `` | +| `analyze-hooks-removed-actions.yaml` | ``Removed actions: `a` `` | +| `analyze-hooks-changed-views.yaml` | ``Changed views: `v2/list` `` | + +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`, `do_action` and + `do_action_ref_array` calls under `paths` whose name is a complete string literal. A name built + from a variable, interpolation or concatenation is not listed. A hook is added when the current + tree has it and the tag's tree does not, and removed the other way round, so a hook that moved, + or that still has another call elsewhere, is not listed. +- **Views** are the `.php` files under `views-path` that changed since the tag, named by their path + under that directory without `.php`. + +The files are rewritten on every run, so a second run changes nothing and an entry whose change was +reverted is removed. An entry a changelog file already carries, or another pending change file +holds, is not written again. + +## What the repository needs + +- A checkout with full history and tags: `fetch-depth: 0`. Without a release tag reachable from + `HEAD` the action fails. +- 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: + paths: | + . + :!vendor + :!vendor-prefixed + views-path: themes/ld30/templates + types: >- + {"added-filters": "tweak: added filters", "added-actions": "tweak: added actions", + "changed-views": "tweak: updated templates"} +``` + +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. `:!vendor` excludes a directory. | +| `views-path` | `src/views` | The directory of the templates a theme can override. Empty lists no view. | +| `types` | | The changelog type per entry, as a JSON object in a string. Keys: `added-filters`, `removed-filters`, `added-actions`, `removed-actions`, `changed-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 00000000..a95f76c7 --- /dev/null +++ b/.github/actions/analyze-hooks/action.yml @@ -0,0 +1,69 @@ +# Files the actions and filters a release adds or removes, and the views it changes, 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 a release adds or removes and the views it changes as pending changelog entries + +inputs: + paths: + description: >- + Where to search for `apply_filters` and `do_action` calls, one git pathspec per line, relative + to the checkout. A pathspec can exclude: `:!vendor` after `.` searches everything but vendor. + required: false + default: 'src' + views-path: + description: >- + The directory of the templates a theme can override. Every `.php` file under it that changed + since the last release is listed, by its path under the directory without `.php`. 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`, `removed-filters`, `added-actions`, `removed-actions` and `changed-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`.' + 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_PATH: ${{ inputs.views-path }} + 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 00000000..bb2f6c1d --- /dev/null +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -0,0 +1,425 @@ +'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. + * A hook is added when the current tree has it and the tag's tree does not, removed the other + * way round, so one that moved, or that still has another call elsewhere, is not listed; + * - the `.php` files under `views-path` that `git diff` reports as changed. + * + * Each kind becomes one entry, `/analyze-hooks--.yaml`, so + * a second run rewrites the same files. An entry a changelog file already carries, 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 { runOrFail } = require('../../lib/exec.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+)?$/ + +/** The kind each WordPress function files its hook under. */ +const FUNCTIONS = { + apply_filters: 'filters', + apply_filters_ref_array: 'filters', + do_action: 'actions', + do_action_ref_array: 'actions', +} + +/** + * 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(?:_ref_array)?|do_action(?:_ref_array)?)\(\s*(?:'([^'$]+)'|"([^"$]+)")\s*[,)]/g + +/** Every entry the action can write, as `-`: the keys the `types` input takes. */ +const ENTRY_KEYS = ['added-filters', 'removed-filters', 'added-actions', 'removed-actions', 'changed-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 parts = (tag) => tag.replace(/^v/, '').split('.').map(Number) + + return tags + .filter((tag) => RELEASE_TAG.test(tag)) + .sort((a, b) => { + const [x, y] = [parts(a), parts(b)] + for (let i = 0; i < Math.max(x.length, y.length); i++) { + if ((x[i] ?? 0) !== (y[i] ?? 0)) { + return (x[i] ?? 0) - (y[i] ?? 0) + } + } + + return 0 + }) + .pop() +} + +/** + * The hook names a source text calls. + * + * @param {string} source PHP source, or the matching lines of it. + * + * @returns {{filters: Set, actions: Set}} The names, per kind. + */ +function hooks(source) { + const found = { filters: new Set(), actions: new Set() } + + for (const match of source.matchAll(HOOK_CALL)) { + found[FUNCTIONS[match[1]]].add(match[2] ?? match[3]) + } + + return found +} + +/** + * The entries between the tag's source and the current one. + * + * @param {string} before The hook calls at the last release. + * @param {string} after The hook calls now. + * @param {string[]} changedFiles The files changed since the last release. + * @param {string} viewsPath The directory views live in. Empty lists no view. + * + * @returns {{change: string, kind: string, names: string[]}[]} One entry per change and kind. + */ +function analyze(before, after, changedFiles, viewsPath) { + const [old, now] = [hooks(before), hooks(after)] + const entries = [] + + for (const kind of ['filters', 'actions']) { + const came = [...now[kind]].filter((name) => !old[kind].has(name)) + const gone = [...old[kind]].filter((name) => !now[kind].has(name)) + + if (came.length) { + entries.push({ change: 'Added', kind, names: came.sort() }) + } + if (gone.length) { + entries.push({ change: 'Removed', kind, names: gone.sort() }) + } + } + + if (viewsPath !== '') { + const views = changedFiles + .filter((file) => file.startsWith(`${viewsPath}/`) && file.endsWith('.php')) + .map((file) => file.slice(viewsPath.length + 1, -'.php'.length)) + + if (views.length) { + entries.push({ change: 'Changed', kind: 'views', names: [...new Set(views)].sort() }) + } + } + + return entries +} + +/** + * Reads the `paths` input: one git pathspec per line. + * + * @param {string} input The input value. + * + * @throws {Error} When it lists nothing. + * + * @returns {string[]} The pathspecs. + */ +function readPaths(input) { + const paths = String(input ?? '') + .split('\n') + .map((line) => line.trim()) + .filter(Boolean) + + if (paths.length === 0) { + throw new Error(`paths is empty. Pass the directories to search for hooks, one per line, e.g. src. ${WHAT}`) + } + + return paths +} + +/** + * 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. + * + * @param {string|null} packageJson The file's contents, or null when there is none. + * + * @throws {Error} When the file is not JSON. + * + * @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) { + let config = {} + + if (packageJson !== null) { + try { + config = JSON.parse(packageJson)?.changelogger ?? {} + } catch { + throw new Error(`package.json is not valid JSON, so the changelogger's configuration cannot be read. ${WHAT}`) + } + } + + 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}` } +} + +/** Whitespace removed, so an entry rewrapped or respaced by hand still compares equal. */ +const squash = (text) => text.replace(/\s+/g, '') + +/** 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)) +} + +/** + * Reads the entries the plugin already carries. + * + * @param {string} cwd The checkout. + * @param {string} changesDir The directory of pending change files. + * @param {string[]} changelogFiles The files the changelog is written to. + * + * @returns {{lines: string[], pending: Set}} What isKnown compares with. + */ +function readKnown(cwd, changesDir, changelogFiles) { + const lines = changelogFiles.flatMap((file) => + [...(readCheckoutFile(cwd, file) ?? '').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 no release tag is reachable from HEAD. + * + * @returns {Promise} + */ +async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() }) { + const paths = readPaths(env.INPUT_PATHS) + const viewsPath = String(env.INPUT_VIEWS_PATH ?? '').trim().replace(/\/+$/, '') + 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) { + throw new Error( + 'No release tag is reachable from HEAD, so there is no last release to compare with. ' + + `Check out with fetch-depth: 0. ${WHAT}` + ) + } + + // git grep exits 1 when nothing matches, which is a tree without hooks, not a failure. + const calls = async (...tree) => { + const result = await exec.getExecOutput( + 'git', + ['grep', '-I', '-h', '-E', '(apply_filters|do_action)', ...tree, '--', ...paths], + { 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 + } + + const changed = + viewsPath === '' + ? [] + : (await git(['diff', '--name-only', tag, '--', viewsPath], 'Listing the changed views')).split('\n') + + const known = readKnown(cwd, changesDir, changelogFiles) + 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 calls(tag), await calls(), changed, viewsPath)) { + 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, hooks, analyze, readPaths, readTypes, readChangelogger, describe, isKnown } diff --git a/README.md b/README.md index 93ac9b87..e22e02f1 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 or removes and the views it changes, as pending changelog entries. The search paths, the views directory 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 00000000..c5a99435 --- /dev/null +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -0,0 +1,239 @@ +'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_PATH: '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: `v2/list`'), + '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', " { + 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.2] =\n\n* Tweak - Changed views: `v2/list`\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('fails when no release tag is reachable', async (t) => { + git('tag', '-d', '6.18.2') + + await assert.rejects(run(t), /No release tag is reachable from HEAD/) + }) + + it('searches every path it is given and honours an exclusion', async (t) => { + write('includes/legacy.php', " { + write('themes/ld30/templates/course.php', ' { + 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('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/) + }) + + 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) + }) +}) From c20de68dccadb4d71067d972a6de3840f77016d1 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Tue, 10 Nov 2026 22:12:20 -0300 Subject: [PATCH 02/14] analyze-hooks reads only the changelog above the last release, and a hook name on the line after the call --- .github/actions/analyze-hooks/README.md | 9 ++-- .../actions/analyze-hooks/analyze-hooks.js | 49 ++++++++++++------- .../analyze-hooks/analyze-hooks.test.js | 17 ++++++- 3 files changed, 54 insertions(+), 21 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 147284db..b0c27afd 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -38,15 +38,18 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes - **Hooks** are the `apply_filters`, `apply_filters_ref_array`, `do_action` and `do_action_ref_array` calls under `paths` whose name is a complete string literal. A name built - from a variable, interpolation or concatenation is not listed. A hook is added when the current + from a variable, interpolation or concatenation is not listed. The name has to be on the line + of the call or on the next one. A hook is added when the current tree has it and the tag's tree does not, and removed the other way round, so a hook that moved, or that still has another call elsewhere, is not listed. - **Views** are the `.php` files under `views-path` that changed since the tag, named by their path under that directory without `.php`. The files are rewritten on every run, so a second run changes nothing and an entry whose change was -reverted is removed. An entry a changelog file already carries, or another pending change file -holds, is not written again. +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: 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 diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index bb2f6c1d..6e836c76 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -11,8 +11,8 @@ * - the `.php` files under `views-path` that `git diff` reports as changed. * * Each kind becomes one entry, `/analyze-hooks--.yaml`, so - * a second run rewrites the same files. An entry a changelog file already carries, or another - * pending file holds, is not written again. + * 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. @@ -22,6 +22,7 @@ const fs = require('node:fs') const path = require('node:path') 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. */ @@ -61,20 +62,11 @@ const DEFAULT_TYPE = 'tweak' * @returns {string|undefined} The tag, or undefined when none is a release. */ function lastReleaseTag(tags) { - const parts = (tag) => tag.replace(/^v/, '').split('.').map(Number) + const version = (tag) => tag.replace(/^v/, '') return tags .filter((tag) => RELEASE_TAG.test(tag)) - .sort((a, b) => { - const [x, y] = [parts(a), parts(b)] - for (let i = 0; i < Math.max(x.length, y.length); i++) { - if ((x[i] ?? 0) !== (y[i] ?? 0)) { - return (x[i] ?? 0) - (y[i] ?? 0) - } - } - - return 0 - }) + .sort((a, b) => compareVersions(version(a), version(b))) .pop() } @@ -302,18 +294,40 @@ function isKnown(entry, known, labels) { return [squash(`${label}-${entry.text}`), squash(`${label}${entry.text}`)].some((line) => known.lines.includes(line)) } +/** + * The part of a changelog file written since the last release: everything above the heading that + * names it. An entry of an earlier release is not this release's, so a view changed in both is + * still listed. + * + * @param {string} text The changelog file. + * @param {string} version The last release, without a leading `v`. + * + * @returns {string} The text above the last release's heading, or all of it when no heading names + * the release. + */ +function sinceLastRelease(text, version) { + const escaped = version.replace(/\./g, '\\.') + // A heading line, `= [6.18.2] 2026-01-01 =` or `## 6.18.2`, holding the version as a whole. + const heading = new RegExp(`^[=#].*(?}} What isKnown compares with. */ -function readKnown(cwd, changesDir, changelogFiles) { +function readKnown(cwd, changesDir, changelogFiles, version) { const lines = changelogFiles.flatMap((file) => - [...(readCheckoutFile(cwd, file) ?? '').matchAll(/^\* (.+)$/gm)].map((match) => squash(match[1])) + [...sinceLastRelease(readCheckoutFile(cwd, file) ?? '', version).matchAll(/^\* (.+)$/gm)].map((match) => + squash(match[1]) + ) ) const pending = new Set() @@ -365,11 +379,12 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() ) } + // One line after each match, for a call whose name is on the line after the parenthesis. // git grep exits 1 when nothing matches, which is a tree without hooks, not a failure. const calls = async (...tree) => { const result = await exec.getExecOutput( 'git', - ['grep', '-I', '-h', '-E', '(apply_filters|do_action)', ...tree, '--', ...paths], + ['grep', '-I', '-h', '-A1', '-E', '(apply_filters|do_action)', ...tree, '--', ...paths], { cwd, silent: true, ignoreReturnCode: true } ) if (result.exitCode > 1) { @@ -384,7 +399,7 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() ? [] : (await git(['diff', '--name-only', tag, '--', viewsPath], 'Listing the changed views')).split('\n') - const known = readKnown(cwd, changesDir, changelogFiles) + const known = readKnown(cwd, changesDir, changelogFiles, tag.replace(/^v/, '')) const dir = path.join(cwd, changesDir) fs.mkdirSync(dir, { recursive: true }) diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index c5a99435..b7e2097c 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -161,7 +161,7 @@ describe('analyze-hooks', () => { }) it('does not write an entry a changelog file or another pending file already has', async (t) => { - write('changelog.md', '= [6.18.2] =\n\n* Tweak - Changed views: `v2/list`\n') + write('changelog.md', '= [6.18.3] =\n\n* Tweak - Changed views: `v2/list`\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) @@ -171,6 +171,21 @@ describe('analyze-hooks', () => { 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: `v2/list`\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', " { git('tag', '-d', '6.18.2') From 418f24878b08d08acc6ce33df30a30acca578ae4 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Tue, 10 Nov 2026 22:27:40 -0300 Subject: [PATCH 03/14] analyze-hooks cuts the changelog at the last release or the newest one before it --- .github/actions/analyze-hooks/README.md | 3 ++- .../actions/analyze-hooks/analyze-hooks.js | 24 ++++++++++++------- .../analyze-hooks/analyze-hooks.test.js | 7 ++++++ 3 files changed, 24 insertions(+), 10 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index b0c27afd..8f0a4a5e 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -47,7 +47,8 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes 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: the lines a run +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. diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 6e836c76..fed57ea2 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -294,23 +294,29 @@ function isKnown(entry, known, labels) { 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 = /^[=#].*?(? { 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: `v2/list`\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', " Date: Tue, 10 Nov 2026 22:35:56 -0300 Subject: [PATCH 04/14] analyze-hooks warns before a first release, and fails only when the checkout is shallow --- .github/actions/analyze-hooks/README.md | 5 +++-- .github/actions/analyze-hooks/action.yml | 2 +- .../actions/analyze-hooks/analyze-hooks.js | 21 ++++++++++++++----- .../analyze-hooks/analyze-hooks.test.js | 15 +++++++++++-- 4 files changed, 33 insertions(+), 10 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 8f0a4a5e..8a85f1f8 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -54,8 +54,9 @@ changed in two releases is listed in both. ## What the repository needs -- A checkout with full history and tags: `fetch-depth: 0`. Without a release tag reachable from - `HEAD` the action fails. +- 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/`. diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index a95f76c7..103e3aa1 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -40,7 +40,7 @@ inputs: outputs: tag: - description: 'The last release tag the checkout was compared with, e.g. `6.18.3` or `v5.3.0`.' + 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.' diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index fed57ea2..09d2768d 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -364,7 +364,7 @@ function readKnown(cwd, changesDir, changelogFiles, version) { * @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 no release tag is reachable from HEAD. + * @throws {Error} When an input is refused, or the checkout is shallow and shows no release tag. * * @returns {Promise} */ @@ -379,10 +379,21 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() const tag = lastReleaseTag((await git(['tag', '--merged', 'HEAD'], 'Listing the tags')).split('\n')) if (!tag) { - throw new Error( - 'No release tag is reachable from HEAD, so there is no last release to compare with. ' + - `Check out with fetch-depth: 0. ${WHAT}` - ) + // 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 } // One line after each match, for a call whose name is on the line after the parenthesis. diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index fa5a3b73..ea9b50c0 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -193,10 +193,21 @@ describe('analyze-hooks', () => { assert.match(entries()['analyze-hooks-added-filters.yaml'], /`tec_wrapped`/) }) - it('fails when no release tag is reachable', async (t) => { + 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), /No release tag is reachable from HEAD/) + await assert.rejects(run(t), /the checkout is shallow/) }) it('searches every path it is given and honours an exclusion', async (t) => { From 41c5bc1fe1064db598eb8e974b64499fc574f826 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:21:05 -0300 Subject: [PATCH 05/14] analyze-hooks reads package.json through the shared changelogger reader, so a file that is not JSON gives the defaults --- .github/actions/analyze-hooks/analyze-hooks.js | 17 +++++------------ .../actions/analyze-hooks/analyze-hooks.test.js | 7 +++++++ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 09d2768d..1a186ca4 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -21,6 +21,7 @@ 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') @@ -190,26 +191,18 @@ function readTypes(input) { } /** - * Reads what the repository's changelogger configures, from package.json. + * 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. * - * @throws {Error} When the file is not JSON. - * * @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) { - let config = {} - - if (packageJson !== null) { - try { - config = JSON.parse(packageJson)?.changelogger ?? {} - } catch { - throw new Error(`package.json is not valid JSON, so the changelogger's configuration cannot be read. ${WHAT}`) - } - } + const config = readChangeloggerSection(packageJson) ?? {} const written = (Array.isArray(config.files) ? config.files : []).map((file) => file?.path) diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index ea9b50c0..2325c1f4 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -258,6 +258,13 @@ describe('analyze-hooks', () => { 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 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/) From de927a80a259817b52ba64f9f385574a054abfff Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:22:11 -0300 Subject: [PATCH 06/14] analyze-hooks reads every file with a hook call whole, so a call in a comment is skipped and a name on any later line is read --- .github/actions/analyze-hooks/README.md | 5 +- .../actions/analyze-hooks/analyze-hooks.js | 115 +++++++++++++++--- .../analyze-hooks/analyze-hooks.test.js | 33 +++++ 3 files changed, 134 insertions(+), 19 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 8a85f1f8..3dc62bd3 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -38,8 +38,9 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes - **Hooks** are the `apply_filters`, `apply_filters_ref_array`, `do_action` and `do_action_ref_array` calls under `paths` whose name is a complete string literal. A name built - from a variable, interpolation or concatenation is not listed. The name has to be on the line - of the call or on the next one. A hook is added when the current + from a variable, interpolation or concatenation is not listed, and neither is a call inside a + comment or in the HTML of a template outside ``. The name can be on any line after + the parenthesis. A hook is added when the current tree has it and the tag's tree does not, and removed the other way round, so a hook that moved, or that still has another call elsewhere, is not listed. - **Views** are the `.php` files under `views-path` that changed since the tag, named by their path diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 1a186ca4..206e8922 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -5,7 +5,8 @@ * 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. + * - 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 the current tree has it and the tag's tree does not, removed the other * way round, so one that moved, or that still has another call elsewhere, is not listed; * - the `.php` files under `views-path` that `git diff` reports as changed. @@ -47,7 +48,7 @@ const FUNCTIONS = { * 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(?:_ref_array)?|do_action(?:_ref_array)?)\(\s*(?:'([^'$]+)'|"([^"$]+)")\s*[,)]/g +const HOOK_CALL = /\b(apply_filters(?:_ref_array)?|do_action(?:_ref_array)?)\s*\(\s*(?:'([^'$]+)'|"([^"$]+)")\s*[,)]/g /** Every entry the action can write, as `-`: the keys the `types` input takes. */ const ENTRY_KEYS = ['added-filters', 'removed-filters', 'added-actions', 'removed-actions', 'changed-views'] @@ -72,17 +73,69 @@ function lastReleaseTag(tags) { } /** - * The hook names a source text calls. + * 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 PHP source, or the matching lines of it. + * @param {string} source A PHP file. + * + * @returns {string} The code, as long as the source. + */ +function code(source) { + 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])) { + blankTo(at + match[0].length) + } else { + pieces.push(match[0]) + at += match[0].length + } + } + pieces.push(source.slice(at)) + + return pieces.join('') +} + +/** + * The hook names a set of PHP files calls. + * + * @param {string[]} sources The files. * * @returns {{filters: Set, actions: Set}} The names, per kind. */ -function hooks(source) { +function hooks(sources) { const found = { filters: new Set(), actions: new Set() } - for (const match of source.matchAll(HOOK_CALL)) { - found[FUNCTIONS[match[1]]].add(match[2] ?? match[3]) + for (const source of sources) { + for (const match of code(source).matchAll(HOOK_CALL)) { + found[FUNCTIONS[match[1]]].add(match[2] ?? match[3]) + } } return found @@ -91,8 +144,8 @@ function hooks(source) { /** * The entries between the tag's source and the current one. * - * @param {string} before The hook calls at the last release. - * @param {string} after The hook calls now. + * @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[]} changedFiles The files changed since the last release. * @param {string} viewsPath The directory views live in. Empty lists no view. * @@ -389,14 +442,13 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() return } - // One line after each match, for a call whose name is on the line after the parenthesis. // git grep exits 1 when nothing matches, which is a tree without hooks, not a failure. - const calls = async (...tree) => { - const result = await exec.getExecOutput( - 'git', - ['grep', '-I', '-h', '-A1', '-E', '(apply_filters|do_action)', ...tree, '--', ...paths], - { cwd, silent: true, ignoreReturnCode: true } - ) + 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()}`) } @@ -404,6 +456,35 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() 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. + // ponytail: 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')) + } + const changed = viewsPath === '' ? [] @@ -423,7 +504,7 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() const summary = [`## Hook and view changes since ${tag}`] const files = [] - for (const found of analyze(await calls(tag), await calls(), changed, viewsPath)) { + for (const found of analyze(await sources(tag), await sources(), changed, viewsPath)) { const entry = describe(found, types) if (isKnown(entry, known, labels)) { diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index 2325c1f4..d8c67012 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -193,6 +193,39 @@ describe('analyze-hooks', () => { assert.match(entries()['analyze-hooks-added-filters.yaml'], /`tec_wrapped`/) }) + it('reads a hook whose name is two lines below the parenthesis', async (t) => { + 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')) + }) + it('writes nothing, with a warning, before the first release', async (t) => { git('tag', '-d', '6.18.2') const { outputs } = await run(t) From 9c0f93315d039ffd63b99aca98728a6ff0f0dc89 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:23:21 -0300 Subject: [PATCH 07/14] analyze-hooks lists a hook whose calls all became _deprecated as deprecated, and a deprecated one deleted later as removed --- .github/actions/analyze-hooks/README.md | 18 +++-- .github/actions/analyze-hooks/action.yml | 10 ++- .../actions/analyze-hooks/analyze-hooks.js | 79 +++++++++++++------ .../analyze-hooks/analyze-hooks.test.js | 20 +++++ 4 files changed, 93 insertions(+), 34 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 3dc62bd3..d3e87690 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -1,6 +1,6 @@ # analyze-hooks -Files the actions and filters a release adds or removes, and the views it changes, as pending +Files the actions and filters a release adds, deprecates or removes, and the views it changes, as pending changelog entries, so the release notes name them. ```yaml @@ -29,20 +29,24 @@ or four numeric parts, with or without a leading `v` (`6.18.3`, `v5.3.0`, `4.19. | File in the changes directory | Entry | |---|---| | `analyze-hooks-added-filters.yaml` | ``Added filters: `a`, `b` `` | +| `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-deprecated-actions.yaml` | ``Deprecated actions: `a` `` | | `analyze-hooks-removed-actions.yaml` | ``Removed actions: `a` `` | | `analyze-hooks-changed-views.yaml` | ``Changed views: `v2/list` `` | 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`, `do_action` and - `do_action_ref_array` calls under `paths` whose name is a complete string literal. A name built +- **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 or in the HTML of a template outside ``. The name can be on any line after - the parenthesis. A hook is added when the current - tree has it and the tag's tree does not, and removed the other way round, so a hook that moved, - or that still has another call elsewhere, is not listed. + 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. - **Views** are the `.php` files under `views-path` that changed since the tag, named by their path under that directory without `.php`. @@ -88,7 +92,7 @@ An entry left out of `types`, here the removed hooks, stays a `tweak` reading `R |---|---|---| | `paths` | `src` | Where to search for hooks, one git pathspec per line. `:!vendor` excludes a directory. | | `views-path` | `src/views` | The directory of the templates a theme can override. Empty lists no view. | -| `types` | | The changelog type per entry, as a JSON object in a string. Keys: `added-filters`, `removed-filters`, `added-actions`, `removed-actions`, `changed-views`. | +| `types` | | The changelog type per entry, as a JSON object in a string. Keys: `added-filters`, `deprecated-filters`, `removed-filters`, `added-actions`, `deprecated-actions`, `removed-actions`, `changed-views`. | | `working-directory` | | Where the repository is checked out. Empty is the workspace. | ## Outputs diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index 103e3aa1..665f8ae6 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -1,4 +1,4 @@ -# Files the actions and filters a release adds or removes, and the views it changes, as pending +# Files the actions and filters a release adds, deprecates or removes, and the views it changes, 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. @@ -6,12 +6,13 @@ # 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 a release adds or removes and the views it changes as pending changelog entries +description: Files the hooks a release adds, deprecates or removes and the views it changes as pending changelog entries inputs: paths: description: >- - Where to search for `apply_filters` and `do_action` calls, one git pathspec per line, relative + 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 exclude: `:!vendor` after `.` searches everything but vendor. required: false default: 'src' @@ -26,7 +27,8 @@ inputs: 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`, `removed-filters`, `added-actions`, `removed-actions` and `changed-views`. + `added-filters`, `deprecated-filters`, `removed-filters`, `added-actions`, `deprecated-actions`, + `removed-actions` and `changed-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 diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 206e8922..153c5fd1 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -7,11 +7,12 @@ * 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 the current tree has it and the tag's tree does not, removed the other - * way round, so one that moved, or that still has another call elsewhere, is not listed; + * 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; * - the `.php` files under `views-path` that `git diff` reports as changed. * - * Each kind becomes one entry, `/analyze-hooks--.yaml`, so + * 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. * @@ -36,22 +37,22 @@ 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+)?$/ -/** The kind each WordPress function files its hook under. */ -const FUNCTIONS = { - apply_filters: 'filters', - apply_filters_ref_array: 'filters', - do_action: 'actions', - do_action_ref_array: 'actions', -} - /** * 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(?:_ref_array)?|do_action(?:_ref_array)?)\s*\(\s*(?:'([^'$]+)'|"([^"$]+)")\s*[,)]/g +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', 'removed-filters', 'added-actions', 'removed-actions', 'changed-views'] +const ENTRY_KEYS = [ + 'added-filters', + 'deprecated-filters', + 'removed-filters', + 'added-actions', + 'deprecated-actions', + 'removed-actions', + 'changed-views', +] /** The type an entry has when `types` does not name one. */ const DEFAULT_TYPE = 'tweak' @@ -123,24 +124,48 @@ function code(source) { } /** - * The hook names a set of PHP files calls. + * 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. * * @param {string[]} sources The files. * - * @returns {{filters: Set, actions: Set}} The names, per kind. + * @returns {{filters: Map, actions: Map}} The + * hooks by name, per kind. */ function hooks(sources) { - const found = { filters: new Set(), actions: new Set() } + const found = { filters: new Map(), actions: new Map() } for (const source of sources) { for (const match of code(source).matchAll(HOOK_CALL)) { - found[FUNCTIONS[match[1]]].add(match[2] ?? match[3]) + const kind = found[match[1] === 'apply_filters' ? 'filters' : 'actions'] + const name = match[3] ?? match[4] + const hook = kind.get(name) ?? { live: false } + + hook.live ||= match[2] !== '_deprecated' + kind.set(name, hook) } } return found } +/** + * 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. * @@ -155,15 +180,23 @@ function analyze(before, after, changedFiles, viewsPath) { 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. for (const kind of ['filters', 'actions']) { - const came = [...now[kind]].filter((name) => !old[kind].has(name)) - const gone = [...old[kind]].filter((name) => !now[kind].has(name)) + const names = { Added: [], 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 (came.length) { - entries.push({ change: 'Added', kind, names: came.sort() }) + if (is !== was) { + names[{ live: 'Added', deprecated: 'Deprecated', gone: 'Removed' }[is]].push(name) + } } - if (gone.length) { - entries.push({ change: 'Removed', kind, names: gone.sort() }) + + for (const [change, list] of Object.entries(names)) { + if (list.length) { + entries.push({ change, kind, names: list.sort() }) + } } } diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index d8c67012..9a84fce8 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -140,6 +140,23 @@ describe('analyze-hooks', () => { assert.ok(!Object.values(entries()).join('').includes('tec_twin')) }) + it('lists a hook that became deprecated as deprecated, and one deleted after it was deprecated as removed', async (t) => { + write( + 'src/Tribe/Deprecated.php', + " { await run(t) const first = entries() @@ -303,6 +320,9 @@ describe('analyze-hooks', () => { 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"}'), { + 'deprecated-actions': 'deprecated: deprecated actions', + }) }) it('orders release tags by their numeric parts', () => { From dac7d39e4fd1fda33fdaaf095098f9fc1b6a3d73 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:24:21 -0300 Subject: [PATCH 08/14] analyze-hooks lists a hook whose docblocks gained a @since line as updated --- .github/actions/analyze-hooks/README.md | 10 +++- .github/actions/analyze-hooks/action.yml | 8 +-- .../actions/analyze-hooks/analyze-hooks.js | 52 +++++++++++++------ .../analyze-hooks/analyze-hooks.test.js | 26 ++++++++++ 4 files changed, 74 insertions(+), 22 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index d3e87690..9ef531bb 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -1,6 +1,6 @@ # analyze-hooks -Files the actions and filters a release adds, deprecates or removes, and the views it changes, as pending +Files the actions and filters a release adds, updates, deprecates or removes, and the views it changes, as pending changelog entries, so the release notes name them. ```yaml @@ -29,9 +29,11 @@ or four numeric parts, with or without a leading `v` (`6.18.3`, `v5.3.0`, `4.19. | 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-changed-views.yaml` | ``Changed views: `v2/list` `` | @@ -47,6 +49,10 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes 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 more `@since` + lines now than 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 count once each. A + docblock belongs to a call when no `;`, `{` or `}` comes between them. - **Views** are the `.php` files under `views-path` that changed since the tag, named by their path under that directory without `.php`. @@ -92,7 +98,7 @@ An entry left out of `types`, here the removed hooks, stays a `tweak` reading `R |---|---|---| | `paths` | `src` | Where to search for hooks, one git pathspec per line. `:!vendor` excludes a directory. | | `views-path` | `src/views` | The directory of the templates a theme can override. Empty lists no view. | -| `types` | | The changelog type per entry, as a JSON object in a string. Keys: `added-filters`, `deprecated-filters`, `removed-filters`, `added-actions`, `deprecated-actions`, `removed-actions`, `changed-views`. | +| `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`, `changed-views`. | | `working-directory` | | Where the repository is checked out. Empty is the workspace. | ## Outputs diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index 665f8ae6..2c5b7305 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -1,4 +1,4 @@ -# Files the actions and filters a release adds, deprecates or removes, and the views it changes, as pending +# Files the actions and filters a release adds, updates, deprecates or removes, and the views it changes, 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. @@ -6,7 +6,7 @@ # 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 a release adds, deprecates or removes and the views it changes as pending changelog entries +description: Files the hooks a release adds, updates, deprecates or removes and the views it changes as pending changelog entries inputs: paths: @@ -27,8 +27,8 @@ inputs: 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`, `deprecated-filters`, `removed-filters`, `added-actions`, `deprecated-actions`, - `removed-actions` and `changed-views`. + `added-filters`, `updated-filters`, `deprecated-filters`, `removed-filters`, `added-actions`, + `updated-actions`, `deprecated-actions`, `removed-actions` and `changed-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 diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 153c5fd1..37953562 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -9,7 +9,8 @@ * 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; + * another call elsewhere, is not listed. A hook in both trees whose docblocks gained a `@since` + * line is updated; * - the `.php` files under `views-path` that `git diff` reports as changed. * * Each kind becomes one entry, `/analyze-hooks--.yaml`, so @@ -46,9 +47,11 @@ const HOOK_CALL = /\b(apply_filters|do_action)(_ref_array|_deprecated)?\s*\(\s*( /** 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', 'changed-views', @@ -73,6 +76,9 @@ function lastReleaseTag(tags) { .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. @@ -86,9 +92,11 @@ const TOKEN = * * @param {string} source A PHP file. * - * @returns {string} The code, as long as the source. + * @returns {{text: string, docblocks: {end: number, since: string[]}[]}} The code, as long as the + * source, and each `/**` comment: where it ends and its `@since` lines. */ function code(source) { + const docblocks = [] const pieces = [] let at = 0 const blankTo = (end) => { @@ -112,6 +120,10 @@ function code(source) { if (match[0] === '?>') { 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 { pieces.push(match[0]) @@ -120,28 +132,36 @@ function code(source) { } pieces.push(source.slice(at)) - return pieces.join('') + return { text: pieces.join(''), docblocks } } +/** @typedef {{live: boolean, since: Set}} Hook A hook in one tree: whether it is live, and its `@since` lines. */ + /** * 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. + * 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. - */ + * @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) { - for (const match of code(source).matchAll(HOOK_CALL)) { + const { text, docblocks } = code(source) + + for (const match of text.matchAll(HOOK_CALL)) { const kind = found[match[1] === 'apply_filters' ? 'filters' : 'actions'] const name = match[3] ?? match[4] - const hook = kind.get(name) ?? { live: false } + 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) } } @@ -152,8 +172,8 @@ function hooks(sources) { /** * The state of a hook in a tree. * - * @param {Map} kind The tree's hooks of one kind. - * @param {string} name The hook. + * @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. @@ -181,15 +201,18 @@ function analyze(before, after, changedFiles, viewsPath) { 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. + // with no call left, live or deprecated before, is removed. One that stayed as it was is updated + // when its docblocks have more `@since` lines than at the tag. for (const kind of ['filters', 'actions']) { - const names = { Added: [], Deprecated: [], Removed: [] } + 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' && now[kind].get(name).since.size > old[kind].get(name).since.size) { + names.Updated.push(name) } } @@ -323,9 +346,6 @@ function describe(entry, types) { : { key, type: DEFAULT_TYPE, text: `${entry.change} ${entry.kind}: ${names}` } } -/** Whitespace removed, so an entry rewrapped or respaced by hand still compares equal. */ -const squash = (text) => text.replace(/\s+/g, '') - /** A YAML scalar on one line: double quoted, single quoted or plain. */ const SCALAR = '(?:"((?:[^"\\\\]|\\\\.)*)"|\'((?:[^\']|\'\')*)\'|(.+))' diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index 9a84fce8..c5998642 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -157,6 +157,32 @@ describe('analyze-hooks', () => { assert.strictEqual(written['analyze-hooks-removed-actions.yaml'], entry('Removed actions: `tec_was_deprecated`')) }) + it('lists a hook whose docblocks gained a @since line as updated', async (t) => { + const docblock = (...since) => `/**\n * A hook.\n *\n${since.map((line) => ` * @since ${line}\n`).join('')} */\n` + write( + 'src/Tribe/Updated.php', + ` { await run(t) const first = entries() From 8bce46c5eba9f9c8c183af9c6cb777ec17fca47e Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:25:06 -0300 Subject: [PATCH 09/14] analyze-hooks names a view by its path in the checkout, .php included, whatever the form of views-path --- .github/actions/analyze-hooks/README.md | 5 ++-- .github/actions/analyze-hooks/action.yml | 4 +-- .../actions/analyze-hooks/analyze-hooks.js | 28 +++++++++---------- .../analyze-hooks/analyze-hooks.test.js | 19 +++++++++---- 4 files changed, 32 insertions(+), 24 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 9ef531bb..440d4c28 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -36,7 +36,7 @@ or four numeric parts, with or without a leading `v` (`6.18.3`, `v5.3.0`, `4.19. | `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-changed-views.yaml` | ``Changed views: `v2/list` `` | +| `analyze-hooks-changed-views.yaml` | ``Changed views: `src/views/v2/list.php` `` | Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes no file. @@ -54,7 +54,8 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes `@since TBD Added the $type parameter.` The lines of every call's docblock count once each. A docblock belongs to a call when no `;`, `{` or `}` comes between them. - **Views** are the `.php` files under `views-path` that changed since the tag, named by their path - under that directory without `.php`. + 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 diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index 2c5b7305..14d04d97 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -19,8 +19,8 @@ inputs: views-path: description: >- The directory of the templates a theme can override. Every `.php` file under it that changed - since the last release is listed, by its path under the directory without `.php`. Empty lists - no view. + since the last release is listed by its path in the checkout, e.g. `src/views/v2/list.php`. + Empty lists no view. required: false default: 'src/views' types: diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 37953562..7c20eb21 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -11,7 +11,8 @@ * 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-path` that `git diff` reports as changed. + * - the `.php` files under `views-path` that `git diff` reports as changed, 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 @@ -191,12 +192,12 @@ function state(kind, name) { * * @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[]} changedFiles The files changed since the last release. - * @param {string} viewsPath The directory views live in. Empty lists no view. + * @param {string[]} changedFiles The views changed since the last release, by their path in the + * repository. * * @returns {{change: string, kind: string, names: string[]}[]} One entry per change and kind. */ -function analyze(before, after, changedFiles, viewsPath) { +function analyze(before, after, changedFiles) { const [old, now] = [hooks(before), hooks(after)] const entries = [] @@ -223,14 +224,9 @@ function analyze(before, after, changedFiles, viewsPath) { } } - if (viewsPath !== '') { - const views = changedFiles - .filter((file) => file.startsWith(`${viewsPath}/`) && file.endsWith('.php')) - .map((file) => file.slice(viewsPath.length + 1, -'.php'.length)) - - if (views.length) { - entries.push({ change: 'Changed', kind: 'views', names: [...new Set(views)].sort() }) - } + const views = changedFiles.filter((file) => file.endsWith('.php')) + if (views.length) { + entries.push({ change: 'Changed', kind: 'views', names: [...new Set(views)].sort() }) } return entries @@ -469,7 +465,7 @@ function readKnown(cwd, changesDir, changelogFiles, version) { */ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() }) { const paths = readPaths(env.INPUT_PATHS) - const viewsPath = String(env.INPUT_VIEWS_PATH ?? '').trim().replace(/\/+$/, '') + const viewsPath = String(env.INPUT_VIEWS_PATH ?? '').trim() 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')) @@ -541,7 +537,9 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() const changed = viewsPath === '' ? [] - : (await git(['diff', '--name-only', tag, '--', viewsPath], 'Listing the changed views')).split('\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/`. + (await git(['diff', '--name-only', '--relative', tag, '--', viewsPath], 'Listing the changed views')).split('\n') const known = readKnown(cwd, changesDir, changelogFiles, tag.replace(/^v/, '')) const dir = path.join(cwd, changesDir) @@ -557,7 +555,7 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() const summary = [`## Hook and view changes since ${tag}`] const files = [] - for (const found of analyze(await sources(tag), await sources(), changed, viewsPath)) { + for (const found of analyze(await sources(tag), await sources(), changed)) { const entry = describe(found, types) if (isKnown(entry, known, labels)) { diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index c5998642..60386180 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -109,7 +109,7 @@ describe('analyze-hooks', () => { 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: `v2/list`'), + '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`'), }) @@ -204,7 +204,7 @@ describe('analyze-hooks', () => { }) 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: `v2/list`\n\n= [6.18.2] =\n\n* Fix - A fix.\n') + 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) @@ -215,14 +215,14 @@ describe('analyze-hooks', () => { }) 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: `v2/list`\n') + 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: `v2/list`\n') + 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()) @@ -305,7 +305,16 @@ describe('analyze-hooks', () => { commit('a template') await run(t, { INPUT_VIEWS_PATH: 'themes/ld30/templates/' }) - assert.strictEqual(entries()['analyze-hooks-changed-views.yaml'], entry('Changed views: `course`')) + assert.strictEqual( + entries()['analyze-hooks-changed-views.yaml'], + entry('Changed views: `themes/ld30/templates/course.php`') + ) + }) + + it('reads a views path that starts with ./', async (t) => { + await run(t, { INPUT_VIEWS_PATH: './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) => { From 4f10a2bdf85c845bc456eb974e8c9c74035f60f2 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:25:56 -0300 Subject: [PATCH 10/14] analyze-hooks takes views-paths, one git pathspec per line, so a glob or several template directories are read --- .github/actions/analyze-hooks/README.md | 6 ++-- .github/actions/analyze-hooks/action.yml | 10 +++--- .../actions/analyze-hooks/analyze-hooks.js | 31 ++++++++----------- .../analyze-hooks/analyze-hooks.test.js | 24 +++++++++++--- 4 files changed, 42 insertions(+), 29 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 440d4c28..cbb28af5 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -53,7 +53,7 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes lines now than 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 count once each. A docblock belongs to a call when no `;`, `{` or `}` comes between them. -- **Views** are the `.php` files under `views-path` that changed since the tag, named by their path +- **Views** are the `.php` files matched by `views-paths` that changed since the tag, named by their path in the checkout, `.php` included, so a reader with an override of the file finds it by that path. @@ -85,7 +85,7 @@ a type of its own holds the names only, since the type's label already says what . :!vendor :!vendor-prefixed - views-path: themes/ld30/templates + views-paths: themes/ld30/templates types: >- {"added-filters": "tweak: added filters", "added-actions": "tweak: added actions", "changed-views": "tweak: updated templates"} @@ -98,7 +98,7 @@ An entry left out of `types`, here the removed hooks, stays a `tweak` reading `R | Input | Default | | |---|---|---| | `paths` | `src` | Where to search for hooks, one git pathspec per line. `:!vendor` excludes a directory. | -| `views-path` | `src/views` | The directory of the templates a theme can override. Empty lists no view. | +| `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`, `changed-views`. | | `working-directory` | | Where the repository is checked out. Empty is the workspace. | diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index 14d04d97..450eeb76 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -16,10 +16,12 @@ inputs: to the checkout. A pathspec can exclude: `:!vendor` after `.` searches everything but vendor. required: false default: 'src' - views-path: + views-paths: description: >- - The directory of the templates a theme can override. Every `.php` file under it that changed - since the last release is listed by its path in the checkout, e.g. `src/views/v2/list.php`. + Where the templates a theme can override live, one git pathspec per line, relative to the + checkout. Every `.php` file they match that changed 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' @@ -62,7 +64,7 @@ runs: # 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_PATH: ${{ inputs.views-path }} + INPUT_VIEWS_PATHS: ${{ inputs.views-paths }} INPUT_TYPES: ${{ inputs.types }} INPUT_WORKING_DIRECTORY: ${{ inputs.working-directory }} with: diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 7c20eb21..fdbe3079 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -11,7 +11,7 @@ * 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-path` that `git diff` reports as changed, by their path in the + * - the `.php` files under `views-paths` that `git diff` reports as changed, by their path in the * checkout. * * Each kind becomes one entry, `/analyze-hooks--.yaml`, so @@ -233,25 +233,17 @@ function analyze(before, after, changedFiles) { } /** - * Reads the `paths` input: one git pathspec per line. + * Reads an input of git pathspecs, one per line. * * @param {string} input The input value. * - * @throws {Error} When it lists nothing. - * - * @returns {string[]} The pathspecs. + * @returns {string[]} The pathspecs, without blank lines. */ -function readPaths(input) { - const paths = String(input ?? '') +function readPathspecs(input) { + return String(input ?? '') .split('\n') .map((line) => line.trim()) .filter(Boolean) - - if (paths.length === 0) { - throw new Error(`paths is empty. Pass the directories to search for hooks, one per line, e.g. src. ${WHAT}`) - } - - return paths } /** @@ -464,8 +456,11 @@ function readKnown(cwd, changesDir, changelogFiles, version) { * @returns {Promise} */ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() }) { - const paths = readPaths(env.INPUT_PATHS) - const viewsPath = String(env.INPUT_VIEWS_PATH ?? '').trim() + 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')) @@ -535,11 +530,11 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() } const changed = - viewsPath === '' + viewsPaths.length === 0 ? [] : // --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/`. - (await git(['diff', '--name-only', '--relative', tag, '--', viewsPath], 'Listing the changed views')).split('\n') + (await git(['diff', '--name-only', '--relative', tag, '--', ...viewsPaths], 'Listing the changed views')).split('\n') const known = readKnown(cwd, changesDir, changelogFiles, tag.replace(/^v/, '')) const dir = path.join(cwd, changesDir) @@ -579,4 +574,4 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() await core.summary.addRaw(summary.join('\n'), true).write() } -module.exports = { runAnalyzeHooks, lastReleaseTag, hooks, analyze, readPaths, readTypes, readChangelogger, describe, isKnown } +module.exports = { runAnalyzeHooks, lastReleaseTag, readTypes } diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index 60386180..814a10d0 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -79,7 +79,7 @@ describe('analyze-hooks', () => { core, exec, cwd: repo, - env: { INPUT_PATHS: 'src', INPUT_VIEWS_PATH: 'src/views', ...inputs }, + env: { INPUT_PATHS: 'src', INPUT_VIEWS_PATHS: 'src/views', ...inputs }, }) return { outputs: outputs(), summary: summary() } @@ -290,7 +290,7 @@ describe('analyze-hooks', () => { write('includes/legacy.php', " { it('lists the views of another directory', async (t) => { write('themes/ld30/templates/course.php', ' { ) }) + it('lists the views of every path it is given, a glob included', async (t) => { + write('includes/courses/templates/course.php', ' { - await run(t, { INPUT_VIEWS_PATH: './src/views' }) + await run(t, { INPUT_VIEWS_PATHS: './src/views' }) assert.strictEqual(entries()['analyze-hooks-changed-views.yaml'], entry('Changed views: `src/views/v2/list.php`')) }) @@ -350,6 +362,10 @@ describe('analyze-hooks', () => { 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/) From bc4b75e9a62fe95f5a0c29adf5c56a830768d5fc Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:27:20 -0300 Subject: [PATCH 11/14] analyze-hooks lists added, changed and removed views apart, a renamed view as changed --- .github/actions/analyze-hooks/README.md | 14 +++--- .github/actions/analyze-hooks/action.yml | 13 +++--- .../actions/analyze-hooks/analyze-hooks.js | 46 +++++++++++++------ .../analyze-hooks/analyze-hooks.test.js | 33 +++++++++---- 4 files changed, 71 insertions(+), 35 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index cbb28af5..707e376c 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -1,7 +1,7 @@ # analyze-hooks -Files the actions and filters a release adds, updates, deprecates or removes, and the views it changes, as pending -changelog entries, so the release notes name them. +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 @@ -36,7 +36,9 @@ or four numeric parts, with or without a leading `v` (`6.18.3`, `v5.3.0`, `4.19. | `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. @@ -53,9 +55,9 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes lines now than 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 count once each. A docblock belongs to a call when no `;`, `{` or `}` comes between them. -- **Views** are the `.php` files matched by `views-paths` that changed since the tag, named by their path - in the checkout, `.php` included, so a reader with an override of the file finds it by that - path. +- **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 @@ -99,7 +101,7 @@ An entry left out of `types`, here the removed hooks, stays a `tweak` reading `R |---|---|---| | `paths` | `src` | Where to search for hooks, one git pathspec per line. `:!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`, `changed-views`. | +| `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 diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index 450eeb76..c3a21679 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -1,12 +1,12 @@ -# Files the actions and filters a release adds, updates, deprecates or removes, and the views it changes, as pending -# changelog entries, so the release notes name them. It compares the checkout with the last release +# 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 a release adds, updates, deprecates or removes and the views it changes as pending changelog entries +description: Files the hooks and views a release adds, changes or removes as pending changelog entries inputs: paths: @@ -19,8 +19,8 @@ inputs: 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 changed since the last release is listed by its - path in the checkout, e.g. `src/views/v2/list.php`. A `*` matches across directories, so + 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 @@ -30,7 +30,8 @@ inputs: 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` and `changed-views`. + `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 diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index fdbe3079..10987833 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -11,8 +11,8 @@ * 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 changed, by their path in the - * checkout. + * - 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 @@ -55,7 +55,9 @@ const ENTRY_KEYS = [ 'updated-actions', 'deprecated-actions', 'removed-actions', + 'added-views', 'changed-views', + 'removed-views', ] /** The type an entry has when `types` does not name one. */ @@ -192,12 +194,12 @@ function state(kind, name) { * * @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[]} changedFiles The views changed since the last release, by their path in the - * repository. + * @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, changedFiles) { +function analyze(before, after, viewsDiff) { const [old, now] = [hooks(before), hooks(after)] const entries = [] @@ -224,9 +226,22 @@ function analyze(before, after, changedFiles) { } } - const views = changedFiles.filter((file) => file.endsWith('.php')) - if (views.length) { - entries.push({ change: 'Changed', kind: 'views', names: [...new Set(views)].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 @@ -529,12 +544,15 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() return [...lines.values()].map((file) => file.join('\n')) } - const changed = + // --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 - ? [] - : // --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/`. - (await git(['diff', '--name-only', '--relative', tag, '--', ...viewsPaths], 'Listing the changed views')).split('\n') + ? '' + : 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) @@ -550,7 +568,7 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() const summary = [`## Hook and view changes since ${tag}`] const files = [] - for (const found of analyze(await sources(tag), await sources(), changed)) { + for (const found of analyze(await sources(tag), await sources(), viewsDiff)) { const entry = describe(found, types) if (isKnown(entry, known, labels)) { diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index 814a10d0..f103d4bd 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -305,10 +305,25 @@ describe('analyze-hooks', () => { commit('a template') await run(t, { INPUT_VIEWS_PATHS: 'themes/ld30/templates/' }) - assert.strictEqual( - entries()['analyze-hooks-changed-views.yaml'], - entry('Changed views: `themes/ld30/templates/course.php`') - ) + assert.deepStrictEqual(entries()['analyze-hooks-added-views.yaml'], entry('Added views: `themes/ld30/templates/course.php`')) + }) + + it('lists added, changed and removed views apart, a renamed view as changed', async (t) => { + write('src/views/v2/week.php', ' { @@ -317,10 +332,9 @@ describe('analyze-hooks', () => { commit('templates') await run(t, { INPUT_VIEWS_PATHS: 'src/views\n\nincludes/*/templates/*\n' }) - assert.strictEqual( - entries()['analyze-hooks-changed-views.yaml'], - entry('Changed views: `includes/courses/templates/course.php`, `src/views/v2/list.php`') - ) + const written = entries() + assert.strictEqual(written['analyze-hooks-added-views.yaml'], entry('Added views: `includes/courses/templates/course.php`')) + assert.strictEqual(written['analyze-hooks-changed-views.yaml'], entry('Changed views: `src/views/v2/list.php`')) }) it('reads a views path that starts with ./', async (t) => { @@ -371,8 +385,9 @@ describe('analyze-hooks', () => { 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"}'), { + assert.deepStrictEqual(readTypes('{"deprecated-actions": "deprecated: deprecated actions", "removed-views": "deprecated: deprecated templates"}'), { 'deprecated-actions': 'deprecated: deprecated actions', + 'removed-views': 'deprecated: deprecated templates', }) }) From 9c186ae22df7457bc73a9809131f3ac00ffa5d4c Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 14:28:17 -0300 Subject: [PATCH 12/14] The analyze-hooks example reads every LearnDash template directory, PHP files only, with a type per kind of change --- .github/actions/analyze-hooks/README.md | 23 ++++++++++++++----- .github/actions/analyze-hooks/action.yml | 3 ++- README.md | 2 +- .../analyze-hooks/analyze-hooks.test.js | 5 ++-- 4 files changed, 23 insertions(+), 10 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 707e376c..9765460d 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -83,23 +83,34 @@ a type of its own holds the names only, since the type's label already says what ```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 + views-paths: | + themes/ld30/templates + themes/legacy/templates + src/views + includes/*/templates/* types: >- - {"added-filters": "tweak: added filters", "added-actions": "tweak: added actions", - "changed-views": "tweak: updated templates"} + {"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"} ``` -An entry left out of `types`, here the removed hooks, stays a `tweak` reading `Removed filters: …`. +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. `:!vendor` excludes a directory. | +| `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. | diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index c3a21679..3190b315 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -13,7 +13,8 @@ inputs: 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 exclude: `:!vendor` after `.` searches everything but vendor. + 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: diff --git a/README.md b/README.md index e22e02f1..ed72fd7e 100644 --- a/README.md +++ b/README.md @@ -166,7 +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 or removes and the views it changes, as pending changelog entries. The search paths, the views directory and the changelog types are inputs, and a `v` on the release tag is accepted. +- [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 index f103d4bd..dcd295e3 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -286,11 +286,12 @@ describe('analyze-hooks', () => { await assert.rejects(run(t), /the checkout is shallow/) }) - it('searches every path it is given and honours an exclusion', async (t) => { + it('searches every path it is given, a glob included, and honours an exclusion', async (t) => { write('includes/legacy.php', " Date: Mon, 16 Nov 2026 14:28:56 -0300 Subject: [PATCH 13/14] analyze-hooks wraps its descriptions and docblocks at 100 columns --- .github/actions/analyze-hooks/action.yml | 26 +++++++++---------- .../actions/analyze-hooks/analyze-hooks.js | 15 ++++++++--- 2 files changed, 23 insertions(+), 18 deletions(-) diff --git a/.github/actions/analyze-hooks/action.yml b/.github/actions/analyze-hooks/action.yml index 3190b315..672e6571 100644 --- a/.github/actions/analyze-hooks/action.yml +++ b/.github/actions/analyze-hooks/action.yml @@ -1,7 +1,7 @@ -# 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. +# 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. @@ -12,18 +12,17 @@ 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. + 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. + 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: @@ -32,9 +31,8 @@ inputs: 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: …`. + `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: diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index 10987833..f4bdf544 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -125,7 +125,10 @@ function code(source) { } 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(/\*\/$/, ''))) }) + docblocks.push({ + end: at + match[0].length, + since: since.map((line) => squash(line.replace(/\*\/$/, ''))), + }) } blankTo(at + match[0].length) } else { @@ -138,7 +141,11 @@ function code(source) { return { text: pieces.join(''), docblocks } } -/** @typedef {{live: boolean, since: Set}} Hook A hook in one tree: whether it is live, and its `@since` lines. */ +/** + * 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` @@ -148,7 +155,7 @@ function code(source) { * @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() } @@ -518,7 +525,7 @@ async function runAnalyzeHooks({ core, exec, env, cwd: workspace = process.cwd() // 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. - // ponytail: the file names are passed as arguments, which holds for a few thousand files. + // 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])) From 50fc91d94a381cf5dcc18ba755f62fe943137dd1 Mon Sep 17 00:00:00 2001 From: Victor Larodiel Date: Mon, 16 Nov 2026 21:27:46 -0300 Subject: [PATCH 14/14] analyze-hooks skips a call quoted in a string, and lists a hook as updated when any of its @since lines is new --- .github/actions/analyze-hooks/README.md | 10 +++--- .../actions/analyze-hooks/analyze-hooks.js | 33 +++++++++++++++---- .../analyze-hooks/analyze-hooks.test.js | 14 ++++++++ 3 files changed, 46 insertions(+), 11 deletions(-) diff --git a/.github/actions/analyze-hooks/README.md b/.github/actions/analyze-hooks/README.md index 9765460d..d0d67264 100644 --- a/.github/actions/analyze-hooks/README.md +++ b/.github/actions/analyze-hooks/README.md @@ -46,15 +46,15 @@ Each is a `patch` entry of type `tweak`, and a kind with nothing to list writes `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 or in the HTML of a template outside ``. The name can be on any line after + 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 more `@since` - lines now than 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 count once each. A - docblock belongs to a call when no `;`, `{` or `}` comes between them. +- **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. diff --git a/.github/actions/analyze-hooks/analyze-hooks.js b/.github/actions/analyze-hooks/analyze-hooks.js index f4bdf544..72cc04cd 100644 --- a/.github/actions/analyze-hooks/analyze-hooks.js +++ b/.github/actions/analyze-hooks/analyze-hooks.js @@ -95,11 +95,13 @@ const TOKEN = * * @param {string} source A PHP file. * - * @returns {{text: string, docblocks: {end: number, since: string[]}[]}} The code, as long as the - * source, and each `/**` comment: where it ends and its `@since` lines. + * @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) => { @@ -132,13 +134,14 @@ function code(source) { } 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 } + return { text: pieces.join(''), docblocks, strings } } /** @@ -160,9 +163,14 @@ function hooks(sources) { const found = { filters: new Map(), actions: new Map() } for (const source of sources) { - const { text, docblocks } = code(source) + 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() } @@ -179,6 +187,19 @@ function hooks(sources) { 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. * @@ -212,7 +233,7 @@ function analyze(before, after, viewsDiff) { // 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 more `@since` lines than at the tag. + // 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: [] } @@ -221,7 +242,7 @@ function analyze(before, after, viewsDiff) { if (is !== was) { names[{ live: 'Added', deprecated: 'Deprecated', gone: 'Removed' }[is]].push(name) - } else if (is !== 'gone' && now[kind].get(name).since.size > old[kind].get(name).since.size) { + } else if (is !== 'gone' && hasNewSince(old[kind].get(name), now[kind].get(name))) { names.Updated.push(name) } } diff --git a/tests/actions/analyze-hooks/analyze-hooks.test.js b/tests/actions/analyze-hooks/analyze-hooks.test.js index dcd295e3..72c34d71 100644 --- a/tests/actions/analyze-hooks/analyze-hooks.test.js +++ b/tests/actions/analyze-hooks/analyze-hooks.test.js @@ -183,6 +183,18 @@ describe('analyze-hooks', () => { assert.deepStrictEqual(entries(), { 'analyze-hooks-updated-filters.yaml': entry('Updated filters: `tec_updated`') }) }) + it('lists a hook as updated when a new @since line replaces one that went with a deleted call', async (t) => { + 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() @@ -253,6 +265,7 @@ describe('analyze-hooks', () => { "# do_action( 'tec_hash' );", "/* apply_filters( 'tec_block', $a ); */", "$s = '// not a comment'; do_action( 'tec_after_string' );", + "$sample = \"do_action( 'tec_in_string' );\"; $code = 'apply_filters( \\'tec_quoted\\', $a );';", "?>

Don't do_action( 'tec_html' );

", '', ].join('\n') @@ -267,6 +280,7 @@ describe('analyze-hooks', () => { ) 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) => {