Beta to 6.91

.github/actions/make-constants-doc/action.yml

@@ -0,0 +1,27 @@
+name: Make constants documentation
+description: Regenerate and commit the beta constants reference
+
+inputs:
+  source_file:
+    description: PHP class containing documented configuration constants
+    required: false
+    default: lib/Cleantalk/ApbctWP/Constant.php
+  output_file:
+    description: Generated Markdown reference
+    required: false
+    default: docs/CONSTANT.MD
+  target_branch:
+    description: Branch to push the documentation commit to
+    required: false
+    default: beta
+
+runs:
+  using: composite
+  steps:
+    - name: Rebuild constants reference
+      shell: bash
+      run: bash "${{ github.action_path }}/entrypoint.sh"
+      env:
+        INPUT_SOURCE_FILE: ${{ inputs.source_file }}
+        INPUT_OUTPUT_FILE: ${{ inputs.output_file }}
+        INPUT_TARGET_BRANCH: ${{ inputs.target_branch }}

.github/actions/make-constants-doc/entrypoint.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+trap 'echo "::error::Command failed on line ${LINENO}: ${BASH_COMMAND}"' ERR
+
+SOURCE_FILE="${INPUT_SOURCE_FILE:-lib/Cleantalk/ApbctWP/Constant.php}"
+OUTPUT_FILE="${INPUT_OUTPUT_FILE:-docs/CONSTANT.MD}"
+TARGET_BRANCH="${INPUT_TARGET_BRANCH:-beta}"
+SCRIPT_DIR="${GITHUB_ACTION_PATH:-$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)}"
+
+generate_document() {
+  python3 "$SCRIPT_DIR/generate.py" --source "$SOURCE_FILE" --output "$OUTPUT_FILE"
+}
+
+# Returns 1 when the generated reference has no changes.
+# Errors must exit explicitly: errexit is suspended when called from an `if` condition.
+commit_document() {
+  generate_document || exit 1
+  git add -- "$OUTPUT_FILE" || exit 1
+  if git diff --cached --quiet -- "$OUTPUT_FILE"; then
+    return 1
+  fi
+  git commit --only -m 'docs: update constants reference [skip ci]' -- "$OUTPUT_FILE" || exit 1
+}
+
+git config user.name 'github-actions[bot]'
+git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+if ! commit_document; then
+  echo "Constants reference is up to date."
+  exit 0
+fi
+
+for attempt in 1 2 3; do
+  if git push origin "HEAD:${TARGET_BRANCH}"; then
+    exit 0
+  fi
+  if [ "$attempt" -eq 3 ]; then
+    echo "::error::Could not push constants reference to ${TARGET_BRANCH}."
+    exit 1
+  fi
+  git fetch origin "$TARGET_BRANCH"
+  # Rebuild on top of the fresh branch instead of rebasing a stale generated commit.
+  git reset --hard "origin/${TARGET_BRANCH}"
+  if ! commit_document; then
+    echo "Constants reference is up to date."
+    exit 0
+  fi
+done

.github/actions/make-constants-doc/generate.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+DECLARATION_RE = re.compile(
+    r'^\s*(?:(?:public|protected|private|final)\s+)*const\s+(\w+)\s*=',
+    re.MULTILINE,
+)
+DOCUMENTED_CONSTANT_RE = re.compile(
+    r'/\*\*(?P<doc>(?:(?!\*/).)*)\*/\s*'
+    r'(?:(?:public|protected|private|final)\s+)*'
+    r"const\s+(?P<name>\w+)\s*=\s*['\"](?P<value>\w+)['\"]\s*;",
+    re.DOTALL,
+)
+
+
+@dataclass
+class Constant:
+    name: str
+    value: str
+    description: str
+    type_name: str
+    deprecated: str | None
+    line: int
+
+
+def parse_constants(source: str) -> list[Constant]:
+    constants: list[Constant] = []
+    for match in DOCUMENTED_CONSTANT_RE.finditer(source):
+        description: list[str] = []
+        tags: dict[str, str] = {}
+        in_tags = False
+        for raw_line in match['doc'].splitlines():
+            line = re.sub(r'^\s*\* ?', '', raw_line).strip()
+            if line.startswith('@'):
+                tag, _, value = line.partition(' ')
+                tags[tag] = value.strip()
+                in_tags = True
+            elif not in_tags:
+                description.append(line)
+
+        constants.append(Constant(
+            name=match['name'],
+            value=match['value'],
+            description='\n'.join(description).strip(),
+            type_name=tags.get('@var', ''),
+            deprecated=tags.get('@deprecated'),
+            line=source.count('\n', 0, match.start('name')) + 1,
+        ))
+
+    declarations = DECLARATION_RE.findall(source)
+    names = [constant.name for constant in constants]
+    if not declarations:
+        raise ValueError('No class constants found')
+    if len(names) != len(set(names)):
+        raise ValueError('Duplicate constant declarations')
+    missing = set(declarations) - set(names)
+    if missing:
+        raise ValueError('Missing docblock or unsupported declaration: ' + ', '.join(sorted(missing)))
+
+    canonical = {constant.name for constant in constants if constant.deprecated is None}
+    for constant in constants:
+        if constant.deprecated is not None:
+            if (
+                constant.value not in canonical
+                or constant.deprecated != 'Use self::' + constant.value
+            ):
+                raise ValueError('Invalid deprecated alias: ' + constant.name)
+        elif (
+            constant.value != constant.name
+            or not constant.description
+            or not constant.type_name
+        ):
+            raise ValueError('Canonical constant needs a description and @var type: ' + constant.name)
+    return constants
+
+
+def render_document(constants: list[Constant], source_link: str) -> str:
+    lines = [
+        '# CleanTalk Anti-Spam configuration constants',
+        '',
+        '<!-- Generated from Constant.php docblocks. Do not edit this file manually. -->',
+        '',
+        'Define configuration constants in `wp-config.php` before WordPress loads the plugin. '
+        'Use the global names below, not the class constants.',
+        '',
+        'Values must match the documented PHP types. The registry ignores values of the wrong type. '
+        'When both a current name and a deprecated alias are defined, the registry prefers the current name. '
+        'Direct legacy reads are noted in the descriptions.',
+        '',
+    ]
+    for constant in constants:
+        if constant.deprecated is not None:
+            continue
+        aliases = [alias.name for alias in constants if alias.deprecated is not None and alias.value == constant.name]
+        lines.extend([
+            '## `' + constant.name + '`',
+            '',
+            constant.description,
+            '',
+            '- **Type:** `' + constant.type_name + '`.',
+            f'- **Declaration:** [Constant.php:{constant.line}]({source_link}#L{constant.line}).',
+            '- **Deprecated names:** ' + (', '.join('`' + alias + '`' for alias in aliases) if aliases else 'none') + '.',
+            '',
+        ])
+    return '\n'.join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description='Build the constants reference from PHP docblocks.')
+    parser.add_argument('--source', required=True, type=Path)
+    parser.add_argument('--output', required=True, type=Path)
+    args = parser.parse_args()
+
+    try:
+        constants = parse_constants(args.source.read_text(encoding='utf-8'))
+        source_link = Path(os.path.relpath(args.source.resolve(), args.output.parent.resolve())).as_posix()
+        document = render_document(constants, source_link)
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        with args.output.open('w', encoding='utf-8', newline='\n') as output:
+            output.write(document)
+    except (OSError, ValueError) as error:
+        parser.error(str(error))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())