Files

Allegro 35fed446c7 docs: add Syntax Guard demo documentation

Add demo scenarios showing the hook in action with:
- Syntax error detection example
- Critical file protection demo
- Expected output format
- Performance metrics

2026-04-05 06:13:01 +00:00

3.4 KiB

Raw Blame History

Syntax Guard Demo

This document demonstrates the Syntax Guard pre-receive hook in action.

Test Scenario: Syntax Error Detection

1. Create a Test File with Syntax Error

# test_broken.py
def broken_function(
    """Unclosed parentheses"""
    print("This will never run")

message = "Unclosed string

2. Attempt to Push

git add test_broken.py
git commit -m "Add broken file"
git push origin main

3. Hook Output (Push Rejected)

========================================
   Python Syntax Guard - Pre-receive
========================================

[INFO] Files checked: 1
[INFO] Critical files checked: 0

[ERROR] Syntax error in: test_broken.py

  File "test_broken.py", line 7
    message = "Unclosed string
              ^
SyntaxError: unterminated string literal

========================================
           SUMMARY
========================================
Files checked: 1
Critical files checked: 0
Errors found: 1

[ERROR] ╔════════════════════════════════════════════════════════════╗
[ERROR] ║  PUSH REJECTED: Syntax errors detected!                    ║
[ERROR] ║                                                             ║
[ERROR] ║  Please fix the syntax errors above before pushing again.  ║
[ERROR] ╚════════════════════════════════════════════════════════════╝

remote: error: hook declined to update refs/heads/main
To https://gitea.example.com/Timmy_Foundation/hermes-agent.git
 ! [remote rejected] main -> main (hook declined)
error: failed to push some refs to

4. Fix the Error

# test_broken.py (FIXED)
def broken_function():
    """Fixed parentheses"""
    print("This will now run")

message = "Closed string"

5. Push Again (Success)

git add test_broken.py
git commit -m "Fix syntax error"
git push origin main

========================================
   Python Syntax Guard - Pre-receive
========================================

========================================
           SUMMARY
========================================
Files checked: 1
Critical files checked: 0
Errors found: 0

[INFO] ✓ All Python files passed syntax check

remote: Resolving deltas: 100% (2/2)
remote: Done syncing
To https://gitea.example.com/Timmy_Foundation/hermes-agent.git
   a1b2c3d..e4f5g6h  main -> main

Critical File Protection

When a critical file has a syntax error:

[ERROR] Syntax error in: run_agent.py
  ^^^ CRITICAL FILE - This file is essential for system operation

  File "run_agent.py", line 150
    def run_agent(
                 ^
SyntaxError: unexpected EOF while parsing

Files Protected

The following critical files are specially marked:

run_agent.py - Main agent runner
model_tools.py - Tool orchestration layer
hermes-agent/tools/nexus_architect.py - Nexus architect tool
cli.py - Command-line interface
batch_runner.py - Batch processing runner
hermes_state.py - State management

Performance

Small push (1-10 files): < 1 second
Medium push (10-50 files): 1-3 seconds
Large push (50+ files): 3-10 seconds

All times include Git operations and Python syntax checking.

3.4 KiB Raw Blame History