# generated-file-warning

**Type:** PreToolUse hook recipe — review before use, not auto-applied.

## Purpose

Warn when an agent attempts to edit a file that was generated by a build tool, code generator, or script. Edits to generated files are usually overwritten on the next build run, wasting work or silently breaking regeneration.

## Trigger Suggestion

```
PreToolUse → tool in [Write, Edit]
  AND target file contains generated-file marker OR path matches known generated paths
```

## Detection Signals

Check for any of the following in the target file's first 5 lines, or in its path:

| Signal | Example |
|---|---|
| Header comment: `// @generated` | TypeScript/JavaScript |
| Header comment: `// Code generated` | Go protobuf/grpc |
| Header comment: `/* AUTO-GENERATED` | Various |
| Header comment: `# This file is auto-generated` | Python, YAML |
| Header comment: `// DO NOT EDIT` | Various |
| Path segment: `generated/`, `__generated__/`, `.generated/` | Any language |
| File extension: `.pb.go`, `_pb2.py`, `.generated.ts` | Protobuf, GraphQL |

## Behavior

When a generated file is detected:

1. Print: `[generated-file-warning] This file appears to be generated:`
2. Show the target path and the detected marker.
3. State: "Edits to generated files are typically overwritten on the next build. Edit the source instead."
4. Suggest the likely source file if derivable (e.g., for `.pb.go` → the `.proto` file).
5. Warn but do not block by default.

## Safe Default

Warn and ask for confirmation; allow if user explicitly proceeds. Generated-file edits are sometimes necessary (e.g., for vendored generated output), so hard-blocking would cause too many false positives.

## Blocking vs Warning Mode

- **Warning (recommended):** Inform and request confirmation.
- **Blocking:** Use when the repo enforces a strict "no-edit-generated" policy enforced by CI.

## False-Positive Risks

- Vendored generated files that are intentionally kept in source control and edited by hand (e.g., some migration files).
- Projects that generate files once and then maintain them manually.

## Example Implementation Sketch

```bash
#!/usr/bin/env bash
# Called with $TARGET_PATH set by the hook runner.

GENERATED_MARKERS=(
  "@generated"
  "Code generated"
  "AUTO-GENERATED"
  "auto-generated"
  "DO NOT EDIT"
)

if [ -f "$TARGET_PATH" ]; then
  HEADER=$(head -5 "$TARGET_PATH")
  for marker in "${GENERATED_MARKERS[@]}"; do
    if echo "$HEADER" | grep -q "$marker"; then
      echo "[generated-file-warning] This file appears to be generated: $TARGET_PATH"
      echo "  Marker found: $marker"
      echo "  Edits will likely be overwritten on the next build. Edit the source instead."
      exit 1  # Set to exit 0 for warning-only mode
    fi
  done
fi

# Also check path
if echo "$TARGET_PATH" | grep -qE "(^|/)(__generated__|generated|\.generated)/"; then
  echo "[generated-file-warning] Path suggests generated file: $TARGET_PATH"
  exit 1
fi

exit 0
```

## Sources / Inspiration

- Code generation conventions from protobuf, GraphQL codegen, and gRPC ecosystems.
- Similar checks in `golangci-lint` and TypeScript strict mode documentation.
