caddis-plugin: Instructions file for GitHub Copilot

Code Portability Standards

All code must be location-agnostic and portable. Projects should work when copied to any machine or directory.

Critical Rules

NEVER Use Absolute Paths

# ❌ NEVER DO THIS - Hardcoded paths break portability
config_path = "<PROJECT_ROOT>/config.json"
data_file = "C:\\Users\\john\\data\\complaints.csv"
log_path = "/home/user/app/logs/app.log"

# ✅ ALWAYS DO THIS - Relative to script location
from pathlib import Path

# Get project root relative to current file
PROJECT_ROOT = Path(__file__).parent.parent  # adjust .parent based on file depth
config_path = PROJECT_ROOT / "config.json"
data_file = PROJECT_ROOT / "data" / "complaints.csv"
log_path = PROJECT_ROOT / "logs" / "app.log"

Path Resolution Patterns

For Python Files

from pathlib import Path

# Current file's directory
CURRENT_DIR = Path(__file__).parent

# Project root (from src/package/module.py → project root)
PROJECT_ROOT = Path(__file__).parent.parent.parent

# Common paths
DATA_DIR = PROJECT_ROOT / "data"
CONFIG_DIR = PROJECT_ROOT / "config"
LOGS_DIR = PROJECT_ROOT / "logs"

# Ensure directories exist
DATA_DIR.mkdir(exist_ok=True)
LOGS_DIR.mkdir(exist_ok=True)

For Config Files (config.py)

"""
Configuration module with portable path resolution.
"""
from pathlib import Path
from dotenv import load_dotenv
import os

# Resolve paths relative to this file's location
CONFIG_DIR = Path(__file__).parent
PROJECT_ROOT = CONFIG_DIR.parent if CONFIG_DIR.name == "src" else CONFIG_DIR

# Load .env from project root
ENV_PATH = PROJECT_ROOT / ".env"
load_dotenv(ENV_PATH)

# All paths relative to project root
DATA_DIR = PROJECT_ROOT / "data"
LOGS_DIR = PROJECT_ROOT / "logs"
STATIC_DIR = PROJECT_ROOT / "static"

Environment-Specific Values

Use .env files for machine-specific configuration:

# ❌ NEVER hardcode machine-specific values
DB_HOST = "192.168.1.100"
LOG_PATH = "E:\\Logs\\app.log"

# ✅ ALWAYS use environment variables
import os
DB_HOST = os.getenv("DB_HOST", "localhost")
LOG_PATH = os.getenv("LOG_PATH", str(LOGS_DIR / "app.log"))