feat: add pre-commit hook

[petemounce]

Description

... for shifting-left apm audit runs to developers who use pre-commit or prek.

Please note prose in the description attribute. My choices with the files multiline regex may need extension to every target apm supports.

Users can use the hook by pasting:

repos:
...
  - repo: https://github.com/microsoft/apm
    rev: {some tag or sha}
    hooks:
      id: apm_audit

... into their .pre-commit-config.yaml. They can override any attribute in -hooks within their user-side config, which is how come I'm not overly concerned by the files regex being incomplete w.r.t. each supported target.

I turned pass_filenames off because the command does not receive filenames as positional args (pre-commit will, as standard, pass a list of files to every hook; that list may be filtered to only contain the files changed in a given diff, to optimise runtime).

Background docs: https://pre-commit.com/#new-hooks

(I also noticed that apm audit --help suggests the command is just for finding hidden Unicode characters; that sounds stale given what else the command seems to do)

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally

`prek run apm_audit --all-files` - entry fires correctly and hook failed where my tree's apm deps was unclean

(.venv)$ prek run apm_audit --all-files
warning: The following repos have mutable `rev` fields (moving tag / branch):
https://github.com/petemounce/apm: pete/pre-commit-hook
Mutable references are never updated after first install and are not supported.
See https://pre-commit.com/#using-the-latest-version-for-a-repository for more details.
hint: `prek auto-update` often fixes this",

apm_audit................................................................Failed
- hook id: apm_audit
- exit code: 1

                             [>] APM Policy Compliance
  ┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
  ┃ Status   ┃ Check                  ┃ Message                                  ┃
  ┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
  │ [+]      │ lockfile-exists        │ Lockfile present                         │
  │ [+]      │ ref-consistency        │ All dependency refs match lockfile       │
  │          │ deployed-files-present │ 45 deployed file(s) missing -- run 'apm  │
  │          │                        │ install' to restore                      │
  └──────────┴────────────────────────┴──────────────────────────────────────────┘

    deployed-files-present details:
      - .claude/skills/br
      - .github/skills/br
      - .opencode/skills/br
      - .claude/skills/caveman

hook fires when a change to `apm.yml` (`files` regex match) is staged

(.venv)$ prek run apm_audit
warning: The following repos have mutable `rev` fields (moving tag / branch):
https://github.com/petemounce/apm: pete/pre-commit-hook
Mutable references are never updated after first install and are not supported.
See https://pre-commit.com/#using-the-latest-version-for-a-repository for more details.
hint: `prek auto-update` often fixes this",

Unstaged changes detected, stashing unstaged changes to `/Users/pmounce/.cache/prek/patches/1776939861127-2938.patch`
apm_audit................................................................Passed

• All existing tests pass

  n/a - no code changes

• Added tests for new functionality (if applicable)

  n/a - no code changes

[Copilot]

Pull request overview

Adds a pre-commit hook definition to let developers run apm audit --ci locally via pre-commit/prek, shifting audit failures earlier in the workflow.

Changes:

• Introduces a new .pre-commit-hooks.yaml hook (apm_audit) that runs apm audit --ci.
• Configures hook triggering via a files regex and disables filename passing (pass_filenames: false).

[Copilot]

The default files list omits some APM-managed locations that are part of supported targets (notably .github/skills/ and .codex/). With the current regex, edits in those directories will not trigger apm audit --ci, which reduces the value of the hook for detecting drift in deployed assets. Consider adding those prefixes (or narrowing the description above so it matches the actual default behavior).

Suggested change

	.claude/.*|
	.cursor/.*|
	.github/agents/.*|
	.github/instructions/.*|
	.github/hooks/.*|
	.claude/.*|
	.codex/.*|
	.cursor/.*|
	.github/agents/.*|
	.github/instructions/.*|
	.github/hooks/.*|
	.github/skills/.*|

[petemounce]

@microsoft-github-policy-service agree

[petemounce]

It occurs to me that this might be done more slickly. For example, one error that can occur is deployed-files-present - this can be fixed via apm install. Perhaps apm audit --ci --mode=check|fix; default is just check, but where it's trivial to fix, fix can do that? (pre-commit's contract is to fail if any git diff exists after all applicable hooks have run)