Update dependencies, clean up version list, refactor build scripts and workflow

.github/workflows/build.yml

@@ -12,27 +12,26 @@ on:
     paths-ignore:
       - 'docs/**'
 
+concurrency:
+  group: documentation-build
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
 jobs:
   build:
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        language: ['js', 'php']
-
-    name: '${{ matrix.language }}'
-
     steps:
       - uses: actions/checkout@master
         with:
-          persist-credentials: false # otherwise, the token used is the GITHUB_TOKEN, instead of your personal token
-          fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+          fetch-depth: 0
 
       - name: Clone flarum/framework
         run: git clone https://github.com/flarum/framework.git flarum
 
       - name: PHP > Use PHP 8.3
-        if: ${{ matrix.language == 'php' }}
         uses: shivammathur/setup-php@v2
         with:
           php-version: '8.3'
@@ -44,29 +43,29 @@ jobs:
           key: ${{ runner.os }}-doctum
 
       - name: JS > Use Node.js 22.x
-        if: ${{ matrix.language == 'js' }}
         uses: actions/setup-node@v3
         with:
           node-version: 22.x
 
       - name: JS > Install dependencies
-        if: ${{ matrix.language == 'js' }}
         run: yarn install --frozen-lockfile
 
-      - name: Build
-        run: ./scripts/build-${{ matrix.language }}.sh
+      - name: Build documentation
+        run: |
+          python scripts/build-js.py
+          python scripts/build-php.py
 
-      - name: Commit
+      - name: Commit and push documentation
         run: |
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
           git add docs
-          if [ "$(git status --porcelain docs/${{ matrix.language }} | wc -l)" -lt "2" ]; then
+          if [ "$(git status --porcelain docs | wc -l)" -lt "2" ]; then
             echo "No changes to commit"
             git reset
             git checkout -- .
           else
-            git commit -m "${{ matrix.language }}: update (flarum/framework@${FLARUM_SHA})" docs
+            git commit -m "docs: update (flarum/framework@${FLARUM_SHA})" docs
           fi
 
       - name: Pull

.tool-versions

@@ -0,0 +1 @@
+php 8.3

package.json

@@ -6,15 +6,12 @@
   "repository": "https://github.com/flarum/framework",
   "license": "MIT",
   "dependencies": {
-    "cli": "^1.0.1",
-    "flarum-webpack-config": "^3.0.3",
-    "minimist": "^1.2.8",
-    "progressbar": "^1.3.0",
-    "typedoc": "^0.28.17",
-    "typedoc-plugin-dt-links": "^2.0.46",
+    "flarum-webpack-config": "^3.0.6",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-dt-links": "^2.0.75",
     "typedoc-plugin-extras": "^4.0.1",
     "typedoc-plugin-mdn-links": "^5.1.1",
-    "typedoc-plugin-missing-exports": "^4.1.2",
+    "typedoc-plugin-missing-exports": "^4.1.4",
     "typedoc-plugin-rename-defaults": "^0.7.3"
   }
 }

scripts/_vars.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+import os
+import shutil
+import subprocess
+
+
+SCRIPTS_PATH = Path(__file__).resolve().parent
+REPO_PATH = SCRIPTS_PATH.parent
+FLARUM_PATH = REPO_PATH / "flarum"
+FLARUM_CORE_PATH = FLARUM_PATH / "framework" / "core"
+_last_cwd = Path.cwd().resolve()
+
+
+def log(message: str) -> None:
+    print(f"##[command]{message}")
+
+
+def run(command: list[str], cwd: Path | None = None, **kwargs) -> None:
+    # Log the working directory if it's changed as a `cd` command for GitHub Actions log.
+    global _last_cwd
+    current_cwd = (cwd or Path.cwd()).resolve()
+    if current_cwd != _last_cwd:
+        log(f"cd {current_cwd}")
+        _last_cwd = current_cwd
+
+    log(" ".join(command))
+    executable = shutil.which(command[0])
+    if executable is None:
+        raise FileNotFoundError(f"Could not find command: {command[0]}")
+    subprocess.run([executable, *command[1:]], cwd=cwd, check=True, **kwargs)
+
+
+def git(*args: str, cwd: Path) -> str:
+    return subprocess.check_output(["git", *args], cwd=cwd, text=True).strip()
+
+
+def write_github_environment(name: str, value: str) -> None:
+    github_env = os.environ.get("GITHUB_ENV")
+    if github_env:
+        with open(github_env, "a", encoding="utf-8", newline="") as file:
+            file.write(f"{name}={value}{os.linesep}")
+
+
+def initialize() -> None:
+    os.environ["SCRIPTS_PATH"] = str(SCRIPTS_PATH)
+    os.environ["REPO_PATH"] = str(REPO_PATH)
+    os.environ["FLARUM_PATH"] = str(FLARUM_PATH)
+    os.environ["FLARUM_CORE_PATH"] = str(FLARUM_CORE_PATH)
+    print(f"Using flarum/framework @ {FLARUM_CORE_PATH}")
+    if not os.environ.get("GITHUB_ENV"):
+        print("Assuming local environment. GITHUB_ENV not set.")
+    else:
+        write_github_environment(
+            "FLARUM_SHA", git("rev-parse", "--verify", "HEAD", "--short", cwd=FLARUM_CORE_PATH)
+        )

scripts/build-js.py

@@ -0,0 +1,92 @@
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+from _vars import FLARUM_PATH, FLARUM_CORE_PATH, REPO_PATH, SCRIPTS_PATH, git, initialize, run
+
+
+def generate(ref: str, skip_existing: bool = False) -> None:
+    path = REPO_PATH / "docs" / "js" / ref
+    if skip_existing and path.is_dir():
+        print(f" - {ref} -> tag already exists, skipping")
+        return
+
+    try:
+        short_sha = git("rev-parse", "--verify", "--short", f"{ref}^{{commit}}", cwd=FLARUM_CORE_PATH)
+        ref_sha = git("rev-parse", "--verify", f"{ref}^{{commit}}", cwd=FLARUM_CORE_PATH)
+    except subprocess.CalledProcessError:
+        short_sha = "unknown"
+        ref_sha = ""
+
+    stamp_file = path / ".source-ref-sha"
+    if ref_sha and stamp_file.is_file() and stamp_file.read_text(encoding="utf-8").strip() == ref_sha:
+        print(f" - {ref} ({short_sha}) cached")
+        return
+
+    print(f" - {ref} ({short_sha})")
+    shutil.rmtree(path, ignore_errors=True)
+    path.mkdir(parents=True)
+
+    run(["git", "checkout", "-q", "--", "."], cwd=FLARUM_PATH)
+    run(["git", "clean", "-f", "-d"], cwd=FLARUM_PATH)
+    run(["git", "checkout", "-q", ref], cwd=FLARUM_PATH)
+    run(["yarn", "install", "--immutable"], cwd=FLARUM_PATH)
+
+    package_file = FLARUM_CORE_PATH / "js" / "package.json"
+    if package_file.is_file():
+        package = json.loads(package_file.read_text(encoding="utf-8"))
+        if package.get("name") == "@flarum/core":
+            package["name"] = "flarum"
+            package_file.write_text(json.dumps(package, indent=2) + "\n", encoding="utf-8")
+
+    typedoc_package = REPO_PATH / "typedoc.package.json"
+    core_typedoc = FLARUM_CORE_PATH / "js" / "typedoc.json"
+    shutil.copy(typedoc_package, core_typedoc)
+    typedoc_lines = core_typedoc.read_text(encoding="utf-8").splitlines(keepends=True)
+    del typedoc_lines[10]
+    core_typedoc.write_text("".join(typedoc_lines), encoding="utf-8")
+
+    extensions_path = FLARUM_PATH / "extensions"
+    for extension in extensions_path.iterdir():
+        extension_js = extension / "js"
+        if not extension_js.is_dir():
+            continue
+        shutil.copy(typedoc_package, extension_js / "typedoc.json")
+        tsconfig = extension_js / "tsconfig.json"
+        if not tsconfig.is_file():
+            shutil.copy(extensions_path / "flags" / "js" / "tsconfig.json", tsconfig)
+
+    env = os.environ.copy()
+    env["NODE_OPTIONS"] = "--max-old-space-size=16384"
+    run(
+        ["npx", "typedoc", "--gitRevision", ref, "--out", str(path),
+         "--name", f"Flarum ({ref})", "--readme", str(REPO_PATH / "src" / "readme-js.md")],
+        cwd=REPO_PATH,
+        env=env,
+    )
+    stamp_file.write_text(f"{ref_sha}\n", encoding="utf-8")
+
+
+initialize()
+generate("2.x")
+generate("1.x")
+
+latest_tags: dict[str, str] = {}
+tags = git("tag", "--sort=-v:refname", cwd=FLARUM_CORE_PATH).splitlines()
+for tag in tags:
+    match = re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)", tag)
+    if not match:
+        continue
+    key = f"{match.group(1)}.{match.group(2)}"
+    if key in {"1.0", "1.1", "1.2"} or key in latest_tags:
+        continue
+    latest_tags[key] = tag
+
+for key in sorted(latest_tags, key=lambda value: tuple(int(part) for part in value.split("."))):
+    generate(latest_tags[key], True)
+
+run([sys.executable, str(SCRIPTS_PATH / "set-redirects.py"), "js"], cwd=REPO_PATH)
+run([sys.executable, str(SCRIPTS_PATH / "set-index-file.py"), "js"], cwd=REPO_PATH)

scripts/build-php.py

@@ -0,0 +1,17 @@
+import sys
+
+from _vars import FLARUM_PATH, REPO_PATH, SCRIPTS_PATH, initialize, run
+
+
+initialize()
+run(["git", "checkout", "-q", "--", "."], cwd=FLARUM_PATH)
+run(["git", "clean", "-f", "-d"], cwd=FLARUM_PATH)
+print("Generating")
+
+run(
+    ["php", str(REPO_PATH / "doctum.phar"), "update", "doctum-config.php",
+     "--force", "--no-progress", "--ignore-parse-errors"],
+    cwd=REPO_PATH,
+)
+run([sys.executable, str(SCRIPTS_PATH / "set-redirects.py"), "php"], cwd=REPO_PATH)
+run([sys.executable, str(SCRIPTS_PATH / "set-index-file.py"), "php"], cwd=REPO_PATH)