dataJAR-recipes: Instructions file for GitHub Copilot

AutoPkg Recipe Linter Suite - AI Coding Agent Instructions

Project Overview

This is a suite of Python linters for validating and fixing AutoPkg recipes. AutoPkg recipes are XML plist or YAML files that automate software packaging for macOS. Each linter is a standalone script in its own directory that detects and fixes specific issues in recipe files.

Architecture: Unified CLI runner (autopkg-linter.py) + 17 independent linter modules (plus OverridePkgReceiptChecker, which runs standalone), each following the same pattern.

Critical Environment Requirement

⚠️ All scripts MUST run using AutoPkg's Python: /usr/local/autopkg/python

Every script includes verify_environment() that checks sys.executable.startswith('/usr/local/autopkg'). This is not optional - AutoPkg recipes require AutoPkg's Python environment with its specific dependencies (plistlib, etc.).

Linter Architecture Pattern

Each linter follows this structure:

LinterName/
├── LinterName.py          # Main script with main() function
├── README.md              # Detailed documentation
└── __pycache__/          # Python bytecode cache

Standard Linter Structure

Every linter script contains:

1. Shebang: #!/usr/local/autopkg/python
2. verify_environment(): Validates Python path (imported from linter_common)
3. clean_path(): Handles drag-and-drop paths with escaped spaces (imported from linter_common)
4. process_plist_recipe(): Logic for XML plist recipes
5. process_yaml_recipe(): Logic for YAML recipes (if applicable)
6. main(): Interactive prompt for recipe directory, then scans/processes files

Recipe Format Handling

• Plist recipes (.recipe): XML plist format using plistlib
• YAML recipes (.yaml): YAML format using yaml module
• Most linters support both formats with separate processing functions
• Some operations (e.g., XML escaping) only apply to plist format

Suite Runner Integration