diff --git a/.github/workflows/integration-test.yml b/.github/workflows/integration-test.yml index 9d09e193..008bc034 100644 --- a/.github/workflows/integration-test.yml +++ b/.github/workflows/integration-test.yml @@ -470,3 +470,39 @@ jobs: pre-commit run github-action-readme-generator --all-files --verbose cmp ACTION.after-first-run.md docs/ACTION.md + + - name: Verify documented release hook + working-directory: consumer + run: | + cat > docs/ACTION.md <<'MARKDOWN' + # Consumer + + + stale published description + + MARKDOWN + + cat > .pre-commit-config.yaml <<'YAML' + repos: + - repo: https://github.com/bitflight-devops/github-action-readme-generator + rev: v2.1.0 + hooks: + - id: github-action-readme-generator + args: [--readme, docs/ACTION.md] + YAML + + git add docs/ACTION.md .pre-commit-config.yaml + pre-commit validate-config .pre-commit-config.yaml + + set +e + pre-commit run github-action-readme-generator --all-files --verbose + published_status=$? + set -e + + if [ "$published_status" -eq 0 ]; then + echo "::error::published hook should report the target README modification" + exit 1 + fi + + grep -F "Generated through the published pre-commit hook" docs/ACTION.md + grep -F "default README must stay stale" README.md diff --git a/AGENTS.md b/AGENTS.md index 550de38a..3c2108b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,7 @@ Load the narrow source that owns the task instead of relying on cached repositor - **Generation, README ownership, versioning, convergence, formatting, or bundles:** read `docs/tool-contract.md`. - **Build, test, lint, or package-script behavior:** read `package.json` and `vite.config.ts`. -- **Git-hook behavior:** read the matching file under `.husky/` and the script it invokes in `package.json`. +- **Git-hook behavior:** for this repository's local hooks, read `.husky/` and the invoked `package.json` script; for the published consumer hook, read `.pre-commit-hooks.yaml` and `scripts/pre-commit-hook.sh`. - **CI behavior:** read the relevant file under `.github/workflows/`; workflow display names are not the source of truth. - **Release behavior:** read the relevant workflow and the `release` configuration in `package.json`. - **Before declaring a fix, review finding, or your own diff settled:** read `.claude/skills/checker-principle/SKILL.md`. diff --git a/README.md b/README.md index 61c8e819..a097631f 100644 --- a/README.md +++ b/README.md @@ -154,33 +154,28 @@ You can modify the script below to include any extra variables you like or use n ### Using as a Pre-commit Hook -You can automate README generation on every commit by using this tool as a pre-commit hook. This ensures your documentation stays up-to-date automatically. +This repository publishes a pre-commit hook. Consumers need a supported Node.js/npm installation, but do not need to install this package separately. -1. **Install the tool locally** (if you haven't already): +Add the hook to `.pre-commit-config.yaml` using an immutable release tag: -```sh -npm install --save-dev github-action-readme-generator -# or -yarn add -D github-action-readme-generator +```yaml +repos: + - repo: https://github.com/bitflight-devops/github-action-readme-generator + rev: v2.1.0 + hooks: + - id: github-action-readme-generator ``` -2. **Configure pre-commit**: +Use `pre-commit autoupdate` to move to newer releases. Do not use the moving `v2` alias as `rev`: pre-commit caches repositories by repository and revision string, so moving that tag does not reliably update an existing hook environment. -Add the following to your `.pre-commit-config.yaml` file: +The hook runs on every commit because the action and README paths are configurable. Staged filenames are not passed to the generator. Pass CLI options through `args` when needed: ```yaml -repos: - - repo: local - hooks: - id: github-action-readme-generator - name: Generate README from action.yml - entry: npx github-action-readme-generator - language: system - files: ^(action\.yml|\.ghadocs\.json)$ - pass_filenames: false + args: [--readme, docs/ACTION.md] ``` -This configuration will automatically regenerate your README whenever `action.yml` or `.ghadocs.json` changes. +Configuration is still read from the consumer repository's `.ghadocs.json`; there is no separate configuration-file path option. ## Configuration diff --git a/docs/tool-contract.md b/docs/tool-contract.md index 73ab8213..fa0d6411 100644 --- a/docs/tool-contract.md +++ b/docs/tool-contract.md @@ -141,6 +141,14 @@ This is the case the tool exists for and the case least covered by unit tests; - Zero-input and zero-output actions are ordinary third-party shapes, not edge cases. +## Published pre-commit hook + +The pre-commit manifest is an adapter to the released CLI, not a second installation of this development repository. `.pre-commit-hooks.yaml` uses `unsupported_script`; `scripts/pre-commit-hook.sh` requires the consumer's Node/npm runtime, reads the selected repository revision's `package.json` version, and executes that exact npm release. + +Consumer `args` are forwarded to the CLI. Staged filenames are not: `pass_filenames: false` keeps arbitrary staged paths from becoming CLI arguments. Action and README paths may therefore be supplied through the generator's normal CLI/config inputs, while configuration itself remains the consumer repository's `.ghadocs.json`. + +A published pre-commit `rev` must be an immutable release tag whose npm package already exists. Do not document a moving major tag such as `v2`: pre-commit caches hook repositories by repository and revision string, so moving the same ref does not reliably refresh an existing consumer. Use exact release tags and let `pre-commit autoupdate` select newer ones. + ## Published bundles are self-contained A GitHub Actions runner gives this action no `node_modules` of its own. Every