feat: revamp plugin system

[jescalada]

Changelog

• Added Phases for pull and push chains to make plugin system more flexible
• Extended plugins to take config options including
  • phase: Which phase in the chain to execute
  • displayName: User-facing string for sideband streaming and audits
  • isCollectible: Same as regular processors, non-critical errors allow chain to continue running, errors are collected in the end
  • chains: Which push chains to run the plugin for (ATM: tags, branches or both)
• Added a sample diff scanning plugin to show plugin configuration
  • Also shows TypeScript plugin support
• Fixed plugin descriptions on sideband streaming messages
• Updated plugin documentation to reflect new capabilities

Description

Note: This PR was human-written, and I would appreciate your human thoughts on it 😃

It revamps the plugin system to allow inserting plugins into specific phases in each chain. It also adds PluginOptions to configure the plugin displayName, isCollectible and chains properties.

Each chain is divided into Phases, which are considered ChainElements. Both plugins and chain elements are resolved into executable actions (ProcessorExec).

This allows plugins to access certain Action fields that get populated later on, such as the push diff in the AFTER_DIFF phase.

For example:

const branchPushChainElements: ChainElement[] = [
  proc.push.resolveUserFromToken,
  proc.push.checkEmptyBranch,
  proc.push.checkRepoInAuthorisedList,
  PushPhase.AFTER_PERMISSIONS,
  proc.push.checkMessages,
  proc.push.checkAuthorEmails,
  proc.push.checkUserPushPermission,
  proc.push.pullRemote, // cleanup is handled after chain execution if successful
  proc.push.writePack,
  PushPhase.AFTER_CHECKOUT,
  proc.push.checkHiddenCommits,
  proc.push.checkIfWaitingAuth,
  proc.push.preReceive,
  proc.push.getDiff,
  PushPhase.AFTER_DIFF,
  proc.push.gitleaks,
  proc.push.scanDiff,
  PushPhase.BEFORE_APPROVAL,
  proc.push.blockForAuth,
];

Each phase along with the guaranteed properties is described in the updated plugin documentation.

CustomSecretScanner plugin execution

This simple plugin demonstrates how to access the diff and scan it - previously not possible:

Related Issue

Resolves #

The idea of phases was already introduced by @dcoric in #1639. I expanded on it and focused on plugin revamp specifically.

I think safe, accurate pull scanning (supply chain scans) cannot actually be done via plugins at the moment: if we naively pull the diff using simpleGit within a plugin, we end up getting only the default branch (thus a user pulling a different, compromised branch wouldn't be detected), and on top of that the scan would complete first and then trigger a second "authorized" pull, thus if a vulnerability was introduced right after the scan finished, the user would be able to pull it anyways.

As a follow-up to this PR. I'd like to rewrite the pull chain logic to actually obtain the data requested by the user git pull <specific-branch>, store it in the action so it's extensible via plugins, and finally forward the git pull result to the user.

Checklist

General

• I have read the CONTRIBUTING.md guidelines
• Commit messages follow Conventional Commits format
• I have a FINOS CLA on file

Documentation

• Documentation has been added/updated for any new features

Tests

• Tests have been added/updated for new functionality
• Unit tests pass (npm test)
• Linting and formatting pass (npm run lint and npm run format:check)
• Type checks pass (npm run check-types)

[netlify]

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Name	Link
🔨 Latest commit	178f795
🔍 Latest deploy log	https://app.netlify.com/projects/endearing-brigadeiros-63f9d0/deploys/6a8913fe0236780008f4a16d

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov]

Codecov Report

❌ Patch coverage is 88.63636% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.13%. Comparing base (39fc66a) to head (178f795).
⚠️ Report is 45 commits behind head on main.

Files with missing lines	Patch %	Lines
src/proxy/chain.ts	90.00%	6 Missing ⚠️
src/plugin.ts	85.71%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1683      +/-   ##
==========================================
- Coverage   90.26%   87.13%   -3.14%     
==========================================
  Files          94      104      +10     
  Lines        9115     9799     +684     
  Branches     1705     1748      +43     
==========================================
+ Hits         8228     8538     +310     
- Misses        854     1226     +372     
- Partials       33       35       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.