Skip to content

Setup Guide: Component Placement Rules Enforcement

Status (2026-07): Placement-rule enforcement is currently manual. There is no pre-commit hook and no CI workflow wired for placement rules today — the automated pieces described in older revisions of this guide (scripts/pre-commit-placement-check.sh, .github/workflows/placement-rules-check.yml) do not exist in the repo. Run the validation script yourself before committing placement changes.

🚀 Validation

The real validation script is scripts/validation/validate-placement-rules.py, exposed as an npm alias:

# From repo root — validate placement rules across the codebase
npm run validate-placement-rules

# Or call the script directly
python scripts/validation/validate-placement-rules.py .

Related placement scripts (also npm aliases, see package.json):

npm run sync-placement-rules    # scripts/development/sync-placement-rules.py
npm run watch-placement-rules   # scripts/utilities/watch-placement-rules.py

📋 Manual Workflow

Placement rules are enforced by convention + manual validation, not by a hook:

  1. Make your placement-related change.
  2. Run npm run validate-placement-rules from the repo root.
  3. Fix any reported violations.
  4. Commit.

If you want commit-time enforcement, you can wire the validation script into your own local git hook — but note that is a personal setup, not something the repo installs for you.

🔧 Enforcement Levels

Level 1: Documentation + Manual Validation (current)

  • Rules documented in COMPONENT_PLACEMENT_LAYOUT_RULES.md
  • Compliance checked by running npm run validate-placement-rules

Level 2: Local Pre-commit (opt-in, not shipped)

  • A developer may add their own git hook that calls the validation script.
  • The repo does not install one.

Level 3: CI/CD Integration (not configured)

  • No placement-rules GitHub Actions workflow currently exists.
  • The active workflows are ast-grep-lint.yml, deploy-hostinger.yml, keep-alive.yml, and release.yml (.github/workflows/).

📊 What the Validator Checks

The validation script checks the placement constants, required functions, and package-size database referenced in COMPONENT_PLACEMENT_LAYOUT_RULES.md. See that document (and the script source) for the authoritative, current list — values below are indicative and may drift, so treat the code as the source of truth.

🛠️ Troubleshooting

Issue: "python: command not found"

# Use python3 instead
python3 scripts/validation/validate-placement-rules.py .

Issue: "Module not found"

# Ensure you're in the repo root
cd /path/to/pcb_stackup_generator
python scripts/validation/validate-placement-rules.py .

📞 Support

If you encounter issues: 1. Check the rules documentation: COMPONENT_PLACEMENT_LAYOUT_RULES.md 2. Run validation manually: npm run validate-placement-rules 3. Review the validation script: scripts/validation/validate-placement-rules.py