How ziad-maged/vcs-protection works
vcs-protection is a branch-protection tool with local Git-hook enforcement and a GitHub Actions guard. The main workflow configures protected branch rules, then checks attempted local ref changes and pushes; the remote guard checks GitHub push and pull-request events and can report or revert violations. The graph also includes rule-management, status/audit, installation, and workflow-generation capabilities. Relationships are based on the README and SOURCE INDEX references; sampled source excerpts provide additional evidence for hook and configuration behavior.
Main entry points: handlers.ts Hook enforcement · cli.ts CLI entry · shared.ts Command services · load.ts Effective config
Components 24
CLI and commands
- CLI entry
src/cli.ts - Rule commands
src/commands/rules.ts - Initialization
src/commands/init.ts - Status and doctor
src/commands/status.ts - GitHub and audit
src/commands/github.ts - Hook management
src/commands/install.ts - CI guard command
src/commands/ciGuard.ts
Local protection
- Git hook shims
src/hooks/shim.ts - Hook enforcement
src/hooks/handlers.ts - Rule evaluation
src/rules/evaluate.ts - Bypass audit log
src/audit/log.ts
GitHub enforcement
- Workflow generation
src/github/workflow.ts - Remote guard logic
src/github/guard.ts - GitHub API client
src/github/client.ts - GitHub remote parsing
src/github/remote.ts
Rules and repository
- Branch matching
src/rules/match.ts - Effective config
src/config/load.ts - Config schema
src/config/schema.ts - Git repository access
src/git/repo.ts - Git command runner
src/git/exec.ts
Setup and visibility
- Command services
src/commands/shared.ts
Other components
- Repository user
- GitHub
- Git repository
Connections 42
- Repository user → CLI entry: runs commands
README.md - CLI entry → Rule commands: dispatches to
src/cli.ts - CLI entry → Initialization: dispatches to
src/cli.ts - CLI entry → Status and doctor: dispatches to
src/cli.ts - CLI entry → GitHub and audit: dispatches to
src/cli.ts - CLI entry → Hook management: dispatches to
src/cli.ts - CLI entry → CI guard command: dispatches to
src/cli.ts - CLI entry → Hook enforcement: dispatches hooks
src/cli.ts - Rule commands → Command services: uses services
src/commands/rules.ts - Initialization → Command services: uses services
src/commands/init.ts - Status and doctor → Command services: uses services
src/commands/status.ts - GitHub and audit → Command services: uses services
src/commands/github.ts - Hook management → Git hook shims: installs shims
src/commands/install.ts - Initialization → Effective config: loads config
src/commands/init.ts - Initialization → Workflow generation: generates workflow
src/commands/init.ts - Rule commands → Workflow generation: updates workflow
src/commands/rules.ts - Command services → Effective config: loads effective rules
src/commands/shared.ts - Command services → GitHub API client: creates client
src/commands/shared.ts - Command services → GitHub remote parsing: parses remote
src/commands/shared.ts - Git hook shims → Hook enforcement: invokes
README.md - Hook enforcement → Effective config: loads rules
src/hooks/handlers.ts - Hook enforcement → Rule evaluation: evaluates updates
src/hooks/handlers.ts - Hook enforcement → Branch matching: matches branch
src/hooks/handlers.ts - Hook enforcement → Git repository access: inspects repository
src/hooks/handlers.ts - Hook enforcement → Git command runner: checks Git result
src/hooks/handlers.ts - Hook enforcement → Bypass audit log: records bypass
src/hooks/handlers.ts - Hook enforcement → Git hook shims: repairs hooks
src/hooks/handlers.ts - Effective config → Config schema: parses config
src/config/load.ts - Effective config → Git repository access: finds default ref
src/config/load.ts - Effective config → Git command runner: reads remote config
src/config/load.ts - Git repository access → Git command runner: runs Git queries
src/git/repo.ts - Rule evaluation → Config schema: uses rule types
src/rules/evaluate.ts - Rule evaluation → Branch matching: matches rules
src/rules/evaluate.ts - Git hook shims → Git repository: runs on Git events
README.md - Git repository access → Git repository: reads repository state
src/git/repo.ts - CI guard command → Remote guard logic: runs guard
src/commands/ciGuard.ts - Remote guard logic → GitHub API client: uses API
src/github/guard.ts - Remote guard logic → Branch matching: checks protected branches
src/github/guard.ts - GitHub API client → GitHub: requests REST API
src/github/client.ts - Workflow generation → GitHub: runs on GitHub Actions
README.md - Remote guard logic → GitHub: checks and reverts pushes
README.md - GitHub and audit → Bypass audit log: reads bypass log
src/commands/github.ts