U/sgriffin/rules2

.github/copilot-instructions.md

@@ -0,0 +1,110 @@
+## Project Context
+
+Message Header Analyzer (MHA) - Outlook add-in for analyzing email headers. See README.md for full feature list and usage.
+
+**Development Workflow:**
+- User runs `npm run dev-server` for local development - don't ask to build unless there are errors
+- Webpack handles compilation and hot reload automatically
+- Test in Outlook Desktop with Debug tasks when needed
+
+## Development Principles
+
+- **Zero tolerance for errors AND warnings**: ALL errors and warnings from ANY source (build, TypeScript, ESLint, tests) must be fixed - warnings are errors, don't introduce problems
+- **Stop on unexpected errors**: Present options instead of chasing fixes wildly
+- **Check in frequently**: Commit often for incremental testing
+- **Minimal dependencies**: Discuss before adding new packages
+- **No legacy code**: Remove old code completely when updating
+- **No process comments**: Don't add "Phase 1", "TODO", or development process comments
+- **Keep README current**: When adding features/commands/options, update README.md in the same change
+- **Don't create markdown files**: Never create new .md files (README, TODO, etc.) without being asked
+- **Let user commit**: Don't auto-commit changes - present what's done and let user commit when ready
+- **Complete all planned work**: When outlining a multi-step plan, implement ALL parts - don't stop partway and declare "good enough". Only the user decides when work is complete.
+- **Don't duplicate functionality**: Reuse existing code when possible - if unsure about options, ask first
+- **Fix everything you find**: When user says "fix X", fix ALL instances of X everywhere. If you find related issues while fixing, fix those too. Don't say "this is for later" - either fix it now or explicitly offer to add it to TODO.md. The user will tell you if something should be deferred.
+- **No deferring without permission**: Never skip fixing something because it seems hard or time-consuming. If you think something should be deferred, explicitly ask: "Should I add this to TODO.md or fix it now?"
+
+## Code Standards
+
+### TypeScript
+- **Pure TypeScript**: No JavaScript files - everything must be .ts
+- **Pure ES Modules**: `"type": "module"` in package.json, no CommonJS
+- Strict mode with all safety flags enabled
+- No implicit `any`
+- **Never use `unknown` type** - use proper types or type assertions
+- No unsafe operations
+- Explicit return types required
+- Use type assertions (`as Type`) when unavoidable
+
+### HTML/CSS
+- **No inline code or styles**: Keep JavaScript and CSS in separate files
+- Use external TypeScript modules compiled to ES modules
+- Use external CSS files linked in HTML
+
+### ESLint
+- Max complexity: 15 (only ignore for legitimately complex functions)
+- Explicit function return types required
+- No `any` types
+- K&R brace style
+- **No trailing whitespace**: ESLint will fail on any trailing spaces or extra blank lines - never add them
+- Fix issues properly - **never disable rules to bypass problems**
+
+### Error Handling
+- Let errors propagate naturally with typed errors
+- Use try/catch only when required by dependencies
+- Provide meaningful error messages
+
+## Common Patterns
+
+### Type Assertions (when unavoidable)
+```typescript
+const data = JSON.parse(jsonString) as SomeType[];
+const element = document.getElementById('id') as HTMLElement;
+```
+
+### Complexity Exceptions (use sparingly)
+```typescript
+// eslint-disable-next-line complexity
+async function legitimatelyComplexFunction() { }
+```
+
+## Anti-Patterns to Avoid
+
+❌ Disabling ESLint rules to bypass problems
+❌ Using `any` or `unknown` without type assertions
+❌ Adding TODO/Phase comments in code
+❌ Keeping deprecated/legacy code
+❌ Guessing at fixes - stop and ask instead
+
+## Testing Requirements
+
+- All tests must pass before committing
+- Test failures are NEVER expected - if tests fail, fix the code or fix the tests
+- Run `npm test` after any code changes
+- Run `npm run lint` to verify no ESLint errors
+
+### TDD Approach for Bug Fixes
+
+When fixing bugs identified in code reviews or reported issues:
+
+1. **Write failing test first**: Create a test that demonstrates the bug - it MUST FAIL with the current buggy code
+2. **Apply the fix**: Implement the code changes to address the bug
+3. **Verify test passes**: Run the test again - it should now PASS with the fixed code
+4. **If test still fails**: Reconsider whether the fix is incorrect OR the test is incorrect
+5. **If test was incorrect**: Fix the test, then retest with OLD buggy code to verify it fails there, then retest with NEW fixed code to verify it passes
+
+This approach ensures:
+- The bug actually exists and is reproducible
+- The fix actually solves the problem
+- We have regression protection going forward
+
+## Workflow for Changes
+
+**Development:**
+- User runs `npm run dev-server` - don't ask to start it
+- Webpack dev server handles compilation and hot reload
+- Make code changes and test in browser/Outlook
+
+**Testing:**
+- `npm test` - Run tests
+- `npm run lint` - ESLint check
+- `npm run lint:fix` - Auto-fix ESLint issues