check-one-function-per-file.yml

Enforce the one-function-definition-per-file rule across repository code files (.R, .py, .sh, .js, .ts, .jl). The check scans code files to verify that each file defines at most one top-level function, keeping code modular, searchable, and cleanly diffable.

Files that genuinely require multiple function definitions can opt out by adding a comment directive near the top of the file:

# check-one-function-per-file: allow-multiple

Inputs

Input	Type	Default	Description
`path`	string	`'.'`	Target directory or file path to scan.
`paths-ignore`	string	`'.git, .github, tests, test, vendor, scratch, _site, node_modules, .pytest_cache, .venv, venv'`	Comma- or newline-separated paths or glob patterns to ignore.
`extensions`	string	`'.R, .r, .py, .sh, .bash, .js, .ts, .mjs, .cjs, .jl'`	Comma- or space-separated list of file extensions to check.
`opt-out-comment`	string	`''`	Optional custom comment string to treat as an opt-out directive.
`base-ref`	string	`''`	Git ref to diff against for diff-scoped checking (e.g. `origin/main`). On pull requests and pushes, defaults to `HEAD^1` (the base tip GitHub built the merge ref on) or the previous commit automatically for diff-scoping.
`fail`	boolean	`true`	Whether to fail the workflow if multiple function definitions are detected.
`python-version`	string	`'3.x'`	Python version to set up.
`runs-on`	string	empty (`CI_RUNNER` variable, else `ubuntu-latest`)	Runner label for the job. Use a self-hosted label only for a private repository; never for a public one, whose pull requests can run arbitrary code on it (#1167).

Permissions

Only contents: read (the default), so no permissions: block is needed.

Example

name: Check one function per file
on:
  push: { branches: [main] }
  pull_request:
  workflow_dispatch:
jobs:
  check:
    uses: Morrison-Lab/gha/.github/workflows/check-one-function-per-file.yml@v2
    # with:
    #   runs-on: private-runner  # self-hosted runner label (private repositories only)

See the examples/ directory for caller stubs (e.g. examples/check-one-function-per-file.yml).