3 files changed, 424 insertions, 0 deletions
diff --git a/docs/NOTES.org b/docs/NOTES.org
new file mode 100644
index 0000000..7040321
--- /dev/null
+++ b/docs/NOTES.org
@@ -0,0 +1,131 @@
+
+* Claude Code Session Notes
+This file contains important information for Claude to remember between sessions.
+** User Information
+*** Calendar Location
+Craig's calendar is available at: =/home/cjennings/sync/org/gcal.org=
+
+Use this to:
+- Check meeting times and schedules
+- Verify when events occurred
+- See what's upcoming
+
+*** Todo List Location
+Craig's todo list is at: =/home/cjennings/code/wttrin/todo.org=
+
+*IMPORTANT*: When Craig refers to "my todo list" or "task list", he means this file.
+- Use the Edit tool to update tasks in this file
+- Do NOT confuse this with Claude Code's TodoWrite tool (which is for tracking Claude's internal task progress)
+- This is an org-mode file with TODO/DOING/DONE states
+
+*** Quality Engineering Guidelines
+Craig's quality engineering and testing practices are documented at:
+=/home/cjennings/.emacs.d/ai-prompts/quality-engineer.org=
+
+*Key principles for wttrin testing project:*
+- Follow ERT (Emacs Lisp Regression Testing) framework
+- Separate interactive UI from logic (Interactive vs Non-Interactive Pattern)
+  - Internal functions prefixed with =--= contain pure logic
+  - Interactive wrappers handle user prompts
+  - Test the internal functions with direct parameters
+- Test file organization:
+  - Unit tests: =test-wttrin-<methodname>.el= (one file per method)
+  - Integration tests: =test-integration-<area-or-workflow>.el=
+  - Test utilities: =testutil-<category>.el=
+- Test naming: =test-<module>-<function>-<category>-<scenario>-<expected-result>=
+  - Categories: normal, boundary, error
+- NEVER hardcode dates in tests - use dynamic timestamp generation
+- DON'T MOCK WHAT YOU'RE TESTING - only mock external dependencies
+- Each test must be independent and deterministic
+
+*Current testing project:*
+- Adding comprehensive ERT tests to wttrin package
+- Multi-session project - track progress in session notes
+- Refactor functions to be testable (separate UI from logic)
+- Goal: Full test coverage for all core functionality
+
+*Session 1 Progress (2025-11-03):*
+- Created comprehensive testing plan in =docs/testing-plan.org=
+- Refactored wttrin.el to separate UI from logic
+  - Extracted =wttrin--build-url= (pure function for URL building)
+  - Fixed multiple bugs in =wttrin-fetch-raw-string=:
+    - Removed incorrect callback parameter to url-retrieve-synchronously
+    - Added nil buffer check for network failures
+    - Strip HTTP headers before decoding
+    - Kill buffer after use to prevent leaks
+    - URL encoding now handled properly
+  - Fixed double concatenation bug in =wttrin--get-cached-or-fetch=
+  - Fixed nil handling in =wttrin-additional-url-params=
+- Created test infrastructure:
+  - =tests/testutil-wttrin.el= with test utilities and helpers
+  - 4 unit test files with 33 comprehensive tests
+- Test Results: *33 tests, 33 passing, 0 failures*
+
+*Files with test coverage:*
+1. =wttrin-additional-url-params= - 7 tests (normal, boundary, error cases)
+2. =wttrin--make-cache-key= - 9 tests (includes Unicode, special chars)
+3. =wttrin--build-url= - 10 tests (URL encoding, parameters)
+4. =wttrin--cleanup-cache-if-needed= - 7 tests (cache eviction logic)
+
+*Next session priorities:*
+1. Write tests for =wttrin--get-cached-or-fetch= (cache workflow)
+2. Extract parsing logic from =wttrin-query= and test it
+3. Write integration tests for fetch → parse → display workflow
+4. Test error handling paths
+5. Consider adding tests for interactive functions (if needed)
+
+*** Working Style
+- Craig uses Emacs as primary tool
+** Session Protocols / Vocabulary
+*** "Add to our vocabulary"
+When Craig says "let's add this to our vocabulary" or a similar phrase, you should execute this sequence:
+
+1. Add a row at this level to the parent org heading named "Session Protocols / Vocabulary"
+2. Ask Craig for any similar names he might use.
+3. If he already hasn't provided this information or it isn't clear, ask him for the steps you should take when you see this phrase. Make sure the phrase under discussion is clear.
+4. Write the definition in steps just like any of the other org-headers and their content in this list.
+5. Then remember the instructions, because he's likely to ask you to do that vocabulary word. 
+*** "Let's wrap it up" / "That's a wrap" - End of Session Routine
+When Craig says "let's wrap it up" or "that's a wrap", execute this sequence:
+
+1. *Update notes*: Add anything important to remember for next session to this file (CLAUDE-NOTES.org)
+   - Session summary if significant work was done
+   - Critical reminders for tomorrow
+   - Any new conventions or preferences learned
+
+2. *Git commit and push*: Commit all changes in the repository and push to remote
+   - Use descriptive commit message
+   - Ensure working tree is clean
+   - Confirm push succeeded
+
+3. *Final exchange*: Brief valediction/good wishes before Craig closes laptop
+   - Keep it warm but concise
+   - Acknowledge the day's work if appropriate
+   - "Good night" / "Talk tomorrow" / similar
+
+This ensures clean handoff between sessions and nothing gets lost.
+
+** File Naming Conventions
+*** Update todo.org Links When Renaming Files
+Many documents in this project are linked in =todo.org= using org-mode =file:= links.
+
+*When renaming ANY file*, always search =todo.org= for references to that file and update all links to the new filename.
+
+Example workflow:
+1. Rename file (e.g., add =TOOLARGE-= prefix)
+2. Search =todo.org= for old filename
+3. Update all =file:= links to new filename
+
+This prevents broken links and maintains the integrity of the project documentation.
+
+** File Format Preferences
+*** ALWAYS Use Org-Mode Format
+The user uses Emacs as their primary tool. *ALWAYS* create new documentation files in =.org= format, not =.md= (markdown).
+
+*Rationale*:
+- Org-mode files are well-supported in Emacs
+- Can be easily exported to any other format (HTML, PDF, Markdown, etc.)
+- Better integration with user's workflow
+
+*Exception*: Only use .md if specifically requested or if the file is intended for GitHub/web display where markdown is expected.
+
diff --git a/docs/session-1-summary.org b/docs/session-1-summary.org
new file mode 100644
index 0000000..ebb0f4c
--- /dev/null
+++ b/docs/session-1-summary.org
@@ -0,0 +1,141 @@
+* WTTRIN Testing Project - Session 1 Summary
+Date: 2025-11-03
+Status: ✅ Complete
+
+** What Was Accomplished
+
+*** Bug Fixes in wttrin.el (5 bugs fixed)
+1. ✅ Fixed =wttrin-additional-url-params= to handle nil properly
+2. ✅ Removed incorrect callback parameter in =wttrin-fetch-raw-string=
+3. ✅ Added nil buffer check for network failures
+4. ✅ Strip HTTP headers before decoding (was causing display issues)
+5. ✅ Kill buffer after fetch to prevent memory leaks
+6. ✅ Fixed double concatenation of URL params in cache function
+7. ✅ Added proper URL encoding via new =wttrin--build-url= function
+
+*** Code Refactoring
+- Extracted =wttrin--build-url= as pure function (testable)
+- Separated URL building logic from network I/O
+- All refactoring maintains backward compatibility
+
+*** Test Infrastructure Created
+- =tests/testutil-wttrin.el= - Shared test utilities
+  - Cache helpers (add, clear, size)
+  - Custom variable management macros
+  - Setup/teardown functions
+
+*** Test Coverage Added
+*Total: 33 tests, 100% passing*
+
+1. *test-wttrin-additional-url-params.el* (7 tests)
+   - Normal: metric, USCS, wind speed units
+   - Boundary: nil, empty string, single char
+   - Error: invalid type handling
+
+2. *test-wttrin--make-cache-key.el* (9 tests)
+   - Normal: location with different unit systems
+   - Boundary: empty string, spaces, commas, Unicode, special chars
+   - Error: nil location
+
+3. *test-wttrin--build-url.el* (10 tests)
+   - Normal: simple locations, different unit systems
+   - Boundary: spaces, commas, special chars, Unicode, GPS coords
+   - Error: nil location signals error
+
+4. *test-wttrin--cleanup-cache-if-needed.el* (7 tests)
+   - Normal: cache cleanup when exceeding max size
+   - Boundary: empty cache, exactly at max, edge cases
+   - Validates oldest entries are removed correctly
+
+** Test Execution
+All tests pass successfully:
+
+#+begin_src shell
+emacs --batch -L . -L tests \
+  --eval "(setq package-user-dir \"~/.emacs.d/elpa\")" \
+  --eval "(package-initialize)" \
+  -l wttrin.el -l testutil-wttrin.el \
+  -l test-wttrin-additional-url-params.el \
+  -l test-wttrin--make-cache-key.el \
+  -l test-wttrin--build-url.el \
+  -l test-wttrin--cleanup-cache-if-needed.el \
+  -f ert-run-tests-batch-and-exit
+#+end_src
+
+*Result:* Running 33 tests ... Ran 33 tests, 33 results as expected, 0 unexpected
+
+** Documentation Created
+- =docs/testing-plan.org= - Comprehensive testing roadmap
+  - Identifies all functions needing tests
+  - Categorizes by refactoring needs
+  - Phases for implementation
+  - Estimated 95 total tests when complete
+
+- =docs/NOTES.org= - Updated with:
+  - Quality engineering guidelines reference
+  - Session 1 progress summary
+  - Next session priorities
+
+- =docs/session-1-summary.org= - This file!
+
+** Files Modified
+- =wttrin.el= - Bug fixes and refactoring
+- =docs/NOTES.org= - Testing project notes added
+- =~/.claude/settings.json= - Added wttrin project permissions
+
+** Files Created
+- =docs/testing-plan.org=
+- =docs/bugs.org=
+- =tests/testutil-wttrin.el=
+- =tests/test-wttrin-additional-url-params.el=
+- =tests/test-wttrin--make-cache-key.el=
+- =tests/test-wttrin--build-url.el=
+- =tests/test-wttrin--cleanup-cache-if-needed.el=
+- =docs/session-1-summary.org=
+
+** Next Session Priorities
+1. Write tests for =wttrin--get-cached-or-fetch= (cache workflow with TTL)
+2. Extract and test parsing logic from =wttrin-query=
+3. Write integration tests for fetch → parse → display workflow
+4. Test error handling paths throughout
+5. Consider async loading tests (if needed)
+
+** Progress Metrics
+- Functions tested: 4 of ~10 planned
+- Test coverage: ~40% of core functions
+- Bugs fixed: 7 (from original audit)
+- Bugs remaining: ~9 (see =docs/bugs.org= and =todo.org=)
+- Tests written: 33
+- Tests passing: 33 (100%)
+- Tests failing: 0
+
+** Notes for Next Session
+- Test utilities are working well - easy to add new tests
+- Refactoring pattern (extract pure functions) is effective
+- Cache logic is more complex - needs careful testing
+- Consider mocking url-retrieve-synchronously for fetch tests
+- Buffer manipulation in wttrin-query needs extraction for testing
+
+** How to Run Tests
+Individual test file:
+#+begin_src shell
+emacs --batch -L . -L tests \
+  --eval "(setq package-user-dir \"~/.emacs.d/elpa\")" \
+  --eval "(package-initialize)" \
+  -l wttrin.el -l testutil-wttrin.el \
+  -l test-wttrin-<function-name>.el \
+  -f ert-run-tests-batch-and-exit
+#+end_src
+
+All tests:
+#+begin_src shell
+emacs --batch -L . -L tests \
+  --eval "(setq package-user-dir \"~/.emacs.d/elpa\")" \
+  --eval "(package-initialize)" \
+  -l wttrin.el -l testutil-wttrin.el \
+  -l test-wttrin-additional-url-params.el \
+  -l test-wttrin--make-cache-key.el \
+  -l test-wttrin--build-url.el \
+  -l test-wttrin--cleanup-cache-if-needed.el \
+  -f ert-run-tests-batch-and-exit
+#+end_src
diff --git a/docs/testing-plan.org b/docs/testing-plan.org
new file mode 100644
index 0000000..e2fae9a
--- /dev/null
+++ b/docs/testing-plan.org
@@ -0,0 +1,152 @@
+* WTTRIN Testing Plan
+
+** Methods Analysis
+
+*** Pure Logic Functions (Easy to Test - No Refactoring Needed)
+These functions have no side effects and can be tested directly:
+
+**** =wttrin-additional-url-params= (Line 103)
+- *Purpose*: Concatenates unit system into URL parameter
+- *Current issues*: Has a bug (returns "?" when wttrin-unit-system is nil)
+- *Test categories*:
+  - Normal: wttrin-unit-system = "m", should return "?m"
+  - Normal: wttrin-unit-system = "u", should return "?u"
+  - Boundary: wttrin-unit-system = nil, currently returns "?" (bug!)
+  - Boundary: wttrin-unit-system = "", should return "?"
+  - Error: wttrin-unit-system is number/list (type error)
+
+**** =wttrin--make-cache-key= (Line 183)
+- *Purpose*: Creates cache key from location and settings
+- *Test categories*:
+  - Normal: location + unit system, returns "location|m"
+  - Normal: location with no unit system, returns "location|default"
+  - Boundary: Empty location string
+  - Boundary: Location with special characters (spaces, commas, Unicode)
+  - Error: nil location
+
+**** =wttrin--cleanup-cache-if-needed= (Line 217)
+- *Purpose*: Removes oldest 20% of cache entries when cache exceeds max size
+- *Test categories*:
+  - Normal: Cache at max, removes correct number of oldest entries
+  - Normal: Cache under max, does nothing
+  - Boundary: Cache exactly at max limit
+  - Boundary: Empty cache
+  - Boundary: Cache with 1 entry at max=1
+
+*** Functions Needing Refactoring (Mixed Logic + Side Effects)
+
+**** =wttrin-fetch-raw-string= (Line 107)
+*Current state*: Mixes URL building, network I/O, and decoding
+
+*Refactoring plan*:
+- Create =wttrin--build-url= (pure): Takes query, returns URL string
+- Create =wttrin--fetch-url= (I/O): Takes URL, returns raw response
+- Keep =wttrin-fetch-raw-string= as thin wrapper calling both
+
+*Tests for =wttrin--build-url=*:
+- Normal: query "Paris" → "https://wttr.in/Paris?A"
+- Normal: query with unit system "m" → "https://wttr.in/Paris?mA"
+- Boundary: query with spaces "New York" → properly encoded URL
+- Boundary: query with special chars ",./~" → properly encoded
+- Boundary: Empty query → "https://wttr.in/?A"
+- Error: nil query → error
+
+*Tests for =wttrin--fetch-url=*:
+- Mock url-retrieve-synchronously
+- Normal: successful fetch returns buffer content
+- Error: nil buffer (network failure) → error
+- Error: HTTP error codes (404, 500) → error
+
+**** =wttrin-query= (Line 133)
+*Current state*: Mixes data fetching, parsing, buffer creation, display, keymaps
+
+*Refactoring plan*:
+- Create =wttrin--parse-weather-data= (pure): Takes raw string, returns structured data
+- Create =wttrin--format-weather-buffer= (pure): Takes structured data, returns formatted string
+- Keep =wttrin-query= for buffer/display/keymap setup
+
+*Tests for =wttrin--parse-weather-data=*:
+- Normal: Valid weather data → parsed location, timestamp, body
+- Boundary: Minimal valid data
+- Error: "ERROR" in response → returns nil or signals error
+- Error: Malformed data → handles gracefully
+
+*Tests for =wttrin--format-weather-buffer=*:
+- Normal: Formatted data with location, timestamp, weather
+- Boundary: Empty weather body
+- Boundary: Very long weather data
+
+*** Cache Functions (Testable with Mocking)
+
+**** =wttrin--get-cached-or-fetch= (Line 187)
+*Test categories*:
+- Normal: Cache hit with fresh data → returns cached data
+- Normal: Cache miss → fetches new data and caches it
+- Normal: Cache hit with stale data → fetches new data
+- Boundary: Force refresh bypasses cache
+- Error: Fetch fails, cached data available → returns stale cache
+- Error: Fetch fails, no cached data → propagates error
+
+*** Interactive Functions (Minimal Testing Needed)
+These are thin wrappers around logic - test the logic, not the UI:
+
+- =wttrin= (Line 251) - Just calls wttrin-query with completing-read result
+- =wttrin-exit= (Line 117) - Just calls quit-window
+- =wttrin-requery= (Line 122) - Just prompts and calls wttrin-query
+- =wttrin-requery-force= (Line 240) - Sets flag and calls wttrin-query
+- =wttrin-clear-cache= (Line 231) - Just calls clrhash
+
+** Test File Structure
+
+Following the quality-engineer.org guidelines:
+
+*** Unit Test Files (tests/ directory)
+- =test-wttrin-additional-url-params.el=
+- =test-wttrin--make-cache-key.el=
+- =test-wttrin--cleanup-cache-if-needed.el=
+- =test-wttrin--build-url.el= (after refactoring)
+- =test-wttrin--parse-weather-data.el= (after refactoring)
+- =test-wttrin--format-weather-buffer.el= (after refactoring)
+- =test-wttrin--get-cached-or-fetch.el=
+
+*** Integration Test Files
+- =test-integration-wttrin-cache-workflow.el= (cache hit/miss/refresh)
+- =test-integration-wttrin-fetch-display.el= (fetch → parse → display)
+
+*** Test Utilities
+- =testutil-wttrin.el= (shared test helpers)
+
+** Refactoring Priority
+
+*** Phase 1: Test Pure Functions (No Refactoring Needed)
+1. =wttrin-additional-url-params=
+2. =wttrin--make-cache-key=
+3. =wttrin--cleanup-cache-if-needed=
+
+*** Phase 2: Refactor and Test URL Building
+1. Extract =wttrin--build-url= from =wttrin-fetch-raw-string=
+2. Write tests for =wttrin--build-url=
+3. Extract =wttrin--fetch-url= (I/O portion)
+4. Write tests for =wttrin--fetch-url= (mocked)
+
+*** Phase 3: Refactor and Test Query Logic
+1. Extract =wttrin--parse-weather-data=
+2. Write tests for parsing
+3. Extract =wttrin--format-weather-buffer=
+4. Write tests for formatting
+
+*** Phase 4: Integration Tests
+1. Cache workflow tests
+2. Fetch-to-display workflow tests
+
+** Estimated Test Count
+- Pure functions: ~30 tests
+- Refactored functions: ~40 tests
+- Cache logic: ~15 tests
+- Integration: ~10 tests
+*Total*: ~95 tests
+
+** Session Progress Tracking
+- Session 1 (2025-11-03): Created testing plan, identified functions
+- Session 2: TBD - Start with Phase 1
+- Session 3+: Continue through phases