Allow .pre-commit-hooks.yaml hooks to extend repo: builtin hooks

[pygarap]

Summary

Allow .pre-commit-hooks.yaml hooks to extend repo: builtin hooks through a prek-only extends field, for hook authors who publish a repository consumed by end users.

For each extended manifest hook, prek should load the referenced repo: builtin hook as the base implementation, apply the supported hook fields declared in .pre-commit-hooks.yaml, and execute that builtin hook with the resulting configuration.

The referenced hook must be a Rust-native hook available through the Explicit Builtin Repository. The manifest hook can customize its public identity, metadata, filters, arguments, and other supported hook options without requiring a wrapper executable, an external interpreter, or a separate hook environment.

Proposed syntax [.pre-commit-hooks.yaml]

- id: pytest-filename-conventions
  name: Enforce pytest filename conventions
  description: Ensures files under tests/ follow pytest naming conventions (test_*.py, __init__.py, or conftest.py).
  extends:
    repo: builtin
    id: require-filename-pattern
  files: '(^|/)tests/.+\.py$'
  args:
    - '^test_.*\.py$'
    - '^__init__\.py$'
    - '^conftest\.py$'

- id: text-unicode-replacement-char
  name: No Unicode replacement characters
  description: Forbids text files containing the Unicode replacement character U+FFFD.
  extends:
    repo: builtin
    id: deny-pattern
  args:
    - "\uFFFD"
  types: [text]

For pytest-filename-conventions, prek should execute the builtin require-filename-pattern implementation while applying the manifest hook's name, description, files, and args.

For text-unicode-replacement-char, prek should execute the builtin deny-pattern implementation while applying the manifest hook's name, description, args, and types.

Consumers could then use the published hooks as normal remote hooks:

.pre-commit-config.yaml

repos:
  - repo: https://github.com/example/prek-hooks
    rev: v1.0.0
    hooks:
      - id: pytest-filename-conventions
      - id: text-unicode-replacement-char

Equivalent builtin configuration[.pre-commit-config.yaml]

The manifest hooks above should behave exactly like this direct repo: builtin configuration:

repos:
  - repo: builtin
    hooks:
      - id: require-filename-pattern
        name: Enforce pytest filename conventions
        description: Ensures files under tests/ follow pytest naming conventions (test_*.py, __init__.py, or conftest.py).
        files: '(^|/)tests/.+\.py$'
        args:
          - '^test_.*\.py$'
          - '^__init__\.py$'
          - '^conftest\.py$'
      - id: deny-pattern
        name: No Unicode replacement characters
        description: Forbids text files containing the Unicode replacement character U+FFFD.
        args:
          - "\uFFFD"
        types: [text]

Required behavior

• Allow only repo: builtin for extends.repo.
• Require extends.id to identify an existing hook available through the Explicit Builtin Repository.
• Load the referenced builtin hook as the base implementation.
• Apply the supported hook fields from the .pre-commit-hooks.yaml hook to that base hook.
• Apply normal consumer configuration overrides after the manifest hook fields.
• Execute the referenced builtin Rust implementation using the final effective configuration.
• Use the manifest hook's top-level id for selection and output; use extends.id only to select the builtin implementation.
• Require id, name, and extends for an extended manifest hook.
• Do not require entry or language; reject entry, and allow language only when set to system.
• Execute the bundled Rust implementation without installing dependencies, creating a hook environment, or invoking an external interpreter.
• Apply the same argument support and compatibility checks as the equivalent direct repo: builtin configuration.
• Report clear validation errors for unknown builtin hook IDs and incompatible fields.
• Support extended hooks in prek validate-manifest and prek try-repo.
• Keep existing manifest hooks unchanged and document that extends is specific to prek.

References

• https://github.com/j178/prek/blob/master/docs/authoring-hooks.md
• https://github.com/j178/prek/blob/master/docs/builtin.md
• https://github.com/j178/prek/blob/master/docs/reference/configuration.md
• https://github.com/j178/prek/blob/master/docs/reference/cli.md
• Add repo: builtin #853

[j178]

I’d rather not introduce a new, dedicated config key/concept just for this niche use case. I think I prefer the approach proposed in #1238.

[pygarap]

@j178 My ticket is specifically about .pre-commit-hooks.yaml, for hook authors publishing a repository that end users consume.

#1238 is specifically about .pre-commit-config.yaml, which is configured by end users in their own repositories. So the two proposals address different use cases and serve different purposes.

My intention was also to add a follow-up ticket to #2504 by supporting also the ability to allow .pre-commit-hooks.yaml hooks to extend hooks from remote repositories.

Together, these would make hook extension a general, fully featured capability for hook authors, rather than a niche use case.

This would let hook authors publish reusable variants of existing hooks without duplicating their implementation or creating wrapper executables.