docs: remove outdated coverage implementation plans
- Removed 3 deprecated implementation plan documents from docs/plans directory: - 2025-01-20-tools-coverage-implementation.md - 2025-01-20-utils-coverage-completion.md - 2025-01-20-utils-coverage-implementation.md - These plans are no longer needed since the coverage work has been completed and merged
This commit is contained in:
@@ -1,263 +0,0 @@
|
||||
# Implementation Plan: 100% Tool Coverage
|
||||
|
||||
**Date:** 2025-01-20
|
||||
**Goal:** Achieve 100% test coverage on note-tools.ts and vault-tools.ts
|
||||
**Approach:** Add targeted test cases to existing test files
|
||||
|
||||
## Overview
|
||||
|
||||
This plan addresses the remaining coverage gaps in the tool modules to achieve 100% statement coverage as part of pre-release validation.
|
||||
|
||||
## Current Coverage Status
|
||||
|
||||
- **note-tools.ts:** 96.01% → Target: 100% (9 uncovered lines)
|
||||
- **vault-tools.ts:** 94.22% → Target: 100% (14 uncovered lines)
|
||||
|
||||
## Gap Analysis
|
||||
|
||||
### Note-Tools Uncovered Lines (9 lines)
|
||||
|
||||
1. **Lines 238-239:** Conflict resolution loop (when creating files with duplicate names)
|
||||
2. **Lines 377, 408, 590, 710, 836:** Folder-not-file errors (5 occurrences across different methods)
|
||||
3. **Line 647:** Include compressed data flag in Excalidraw read
|
||||
4. **Line 771:** Add frontmatter to file that has no existing frontmatter
|
||||
|
||||
### Vault-Tools Uncovered Lines (14 lines)
|
||||
|
||||
1. **Line 76:** Invalid path validation error
|
||||
2. **Line 200:** Folder assignment (possibly unreachable)
|
||||
3. **Line 267:** Skip root folder in iteration
|
||||
4. **Line 272:** Glob filtering skip
|
||||
5. **Line 325:** Alias as string (non-array) normalization
|
||||
6. **Line 374:** Folder mtime extraction error catch
|
||||
7. **Lines 452-456, 524-528:** Defensive "path doesn't exist" returns
|
||||
8. **Lines 596-597:** Glob filtering in search
|
||||
9. **Lines 608, 620:** MaxResults early termination
|
||||
10. **Line 650:** Snippet end-of-line adjustment
|
||||
11. **Line 777:** Search error catch block
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Task 1: Add Note-Tools Conflict Resolution Tests
|
||||
|
||||
**Objective:** Cover lines 238-239 (conflict resolution loop)
|
||||
|
||||
**Steps:**
|
||||
1. Add test: "creates file with incremented counter when conflicts exist"
|
||||
2. Mock PathUtils.fileExists to return true for "file.md" and "file 2.md"
|
||||
3. Verify creates "file 3.md"
|
||||
4. Run coverage to confirm lines 238-239 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/note-tools.test.ts`
|
||||
|
||||
**Expected outcome:** Lines 238-239 covered
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Add Note-Tools Folder-Not-File Error Tests
|
||||
|
||||
**Objective:** Cover lines 377, 408, 590, 710, 836 (folder instead of file errors)
|
||||
|
||||
**Steps:**
|
||||
1. Add test for read_note: "returns error when path is a folder"
|
||||
- Mock PathUtils.folderExists to return true
|
||||
- Verify error message uses ErrorMessages.notAFile()
|
||||
|
||||
2. Add test for rename_file: "returns error when path is a folder"
|
||||
3. Add test for update_note: "returns error when path is a folder"
|
||||
4. Add test for delete_note: "returns error when path is a folder"
|
||||
5. Add test for update_sections: "returns error when path is a folder"
|
||||
6. Run coverage to confirm all 5 lines covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/note-tools.test.ts`
|
||||
|
||||
**Expected outcome:** Lines 377, 408, 590, 710, 836 covered
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Add Note-Tools Excalidraw and Frontmatter Tests
|
||||
|
||||
**Objective:** Cover lines 647, 771
|
||||
|
||||
**Steps:**
|
||||
1. Add test for read_excalidraw: "includes compressed data when flag is true"
|
||||
- Call with includeCompressed=true
|
||||
- Verify result.compressedData is included
|
||||
|
||||
2. Add test for update_frontmatter: "adds frontmatter to file without existing frontmatter"
|
||||
- Mock file content without frontmatter
|
||||
- Update frontmatter
|
||||
- Verify frontmatter added at beginning with newline separator
|
||||
|
||||
3. Run coverage to confirm lines 647, 771 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/note-tools.test.ts`
|
||||
|
||||
**Expected outcome:** Lines 647, 771 covered, note-tools.ts at 100%
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Add Vault-Tools Invalid Path and Glob Tests
|
||||
|
||||
**Objective:** Cover lines 76, 272, 596-597
|
||||
|
||||
**Steps:**
|
||||
1. Add test for list(): "returns error for invalid vault path"
|
||||
- Mock PathUtils.isValidVaultPath to return false
|
||||
- Verify error message
|
||||
|
||||
2. Add test for list(): "filters items using glob excludes"
|
||||
- Mock GlobUtils.shouldInclude to return false for some items
|
||||
- Verify filtered items not in results
|
||||
|
||||
3. Add test for search(): "applies glob filtering to search results"
|
||||
- Provide includes/excludes patterns
|
||||
- Verify filtered files not searched
|
||||
|
||||
4. Run coverage to confirm lines 76, 272, 596-597 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/vault-tools.test.ts`
|
||||
|
||||
**Expected outcome:** Lines 76, 272, 596-597 covered
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Add Vault-Tools Edge Case Tests
|
||||
|
||||
**Objective:** Cover lines 267, 325, 374, 608, 620, 650
|
||||
|
||||
**Steps:**
|
||||
1. Add test for list(): "skips root folder in iteration"
|
||||
- Mock folder structure with root folder (path='', isRoot()=true)
|
||||
- Verify root not in results
|
||||
|
||||
2. Add test for list(): "normalizes aliases from string to array"
|
||||
- Mock cache.frontmatter.aliases as string instead of array
|
||||
- Verify result has aliases as array
|
||||
|
||||
3. Add test for getFolderMetadata(): "handles folder without mtime stat"
|
||||
- Mock folder without stat or with invalid stat
|
||||
- Verify doesn't crash, uses default mtime
|
||||
|
||||
4. Add test for search(): "stops searching when maxResults=1 reached"
|
||||
- Multiple files with matches
|
||||
- Verify only 1 result returned
|
||||
|
||||
5. Add test for search(): "adjusts snippet for long lines at end"
|
||||
- Mock line longer than snippetLength ending with match
|
||||
- Verify snippet adjustment logic (line 650)
|
||||
|
||||
6. Run coverage to confirm lines 267, 325, 374, 608, 620, 650 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/vault-tools.test.ts`
|
||||
|
||||
**Expected outcome:** Lines 267, 325, 374, 608, 620, 650 covered
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Add Vault-Tools Defensive Code Coverage
|
||||
|
||||
**Objective:** Cover lines 200, 452-456, 524-528, 777
|
||||
|
||||
**Steps:**
|
||||
1. Analyze if lines 200, 452-456, 524-528 are truly unreachable
|
||||
- If unreachable: Document why (defensive code)
|
||||
- If reachable: Add tests to trigger them
|
||||
|
||||
2. Add test for search(): "handles file read errors gracefully"
|
||||
- Mock vault.read to throw error
|
||||
- Verify error caught, logged to console, search continues
|
||||
- Covers line 777
|
||||
|
||||
3. For defensive returns (452-456, 524-528):
|
||||
- Attempt to trigger "path doesn't exist" cases
|
||||
- If impossible: Document as unreachable defensive code
|
||||
|
||||
4. Run coverage to verify maximum possible coverage
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/vault-tools.test.ts`
|
||||
- Possibly: add comments in source code marking defensive code
|
||||
|
||||
**Expected outcome:** Lines covered or documented as unreachable
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Verify 100% Coverage
|
||||
|
||||
**Objective:** Confirm 100% coverage achieved
|
||||
|
||||
**Steps:**
|
||||
1. Run `npm run test:coverage`
|
||||
2. Check coverage report:
|
||||
- note-tools.ts: 100% or documented gaps
|
||||
- vault-tools.ts: 100% or documented gaps
|
||||
3. If any gaps remain:
|
||||
- Identify what's uncovered
|
||||
- Add tests or document as unreachable
|
||||
4. Final coverage verification
|
||||
|
||||
**Expected outcome:** Both tools at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Run Full Test Suite and Build
|
||||
|
||||
**Objective:** Verify no regressions
|
||||
|
||||
**Steps:**
|
||||
1. Run `npm test` - all tests must pass
|
||||
2. Run `npm run build` - must succeed
|
||||
3. Verify total test count increased
|
||||
4. Document final metrics
|
||||
|
||||
**Expected outcome:** All tests passing, build successful
|
||||
|
||||
---
|
||||
|
||||
### Task 9: Create Summary and Merge
|
||||
|
||||
**Objective:** Document and integrate work
|
||||
|
||||
**Steps:**
|
||||
1. Update IMPLEMENTATION_SUMMARY.md with:
|
||||
- Coverage improvements (before/after)
|
||||
- Test counts
|
||||
- Any unreachable code documented
|
||||
2. Use finishing-a-development-branch skill
|
||||
3. Merge to master
|
||||
|
||||
**Expected outcome:** Work merged, documentation updated
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] note-tools.ts at 100% statement coverage
|
||||
- [x] vault-tools.ts at 100% statement coverage
|
||||
- [x] All tests passing
|
||||
- [x] Build succeeds
|
||||
- [x] Any unreachable code documented
|
||||
- [x] Work merged to master
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
**If some lines are truly unreachable:**
|
||||
- Document with inline comments explaining why
|
||||
- Accept 99.x% if justified
|
||||
- Focus on getting all reachable code to 100%
|
||||
|
||||
**If tests become too complex:**
|
||||
- Consider minor refactoring for testability
|
||||
- Use subagent review to validate approach
|
||||
- Ensure tests remain maintainable
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
- Note-tools tests: ~1 hour (7 new test cases)
|
||||
- Vault-tools tests: ~1.5 hours (10-12 new test cases)
|
||||
- Verification and cleanup: ~0.5 hours
|
||||
- **Total: ~3 hours**
|
||||
@@ -1,207 +0,0 @@
|
||||
# Implementation Plan: 100% Utils Coverage
|
||||
|
||||
**Date:** 2025-01-20
|
||||
**Goal:** Achieve 100% test coverage on all utils modules
|
||||
**Approach:** Remove dead code + Add targeted test cases
|
||||
|
||||
## Overview
|
||||
|
||||
This plan addresses the remaining coverage gaps in the utils modules to achieve 100% statement coverage as part of pre-release validation. Unlike the tools coverage work, this combines dead code removal with targeted testing.
|
||||
|
||||
## Current Coverage Status
|
||||
|
||||
- **error-messages.ts:** 82.6% → Target: 100% (lines 182-198 uncovered)
|
||||
- **version-utils.ts:** 88.88% → Target: 100% (line 52 uncovered)
|
||||
- **path-utils.ts:** 98.18% → Target: 100% (line 70 uncovered)
|
||||
- **frontmatter-utils.ts:** 96.55% → Target: 100% (lines 253-255, 310 uncovered)
|
||||
|
||||
## Gap Analysis
|
||||
|
||||
### Dead Code (To Remove)
|
||||
|
||||
1. **error-messages.ts (lines 182-198)**:
|
||||
- `permissionDenied()` - Never called anywhere in codebase
|
||||
- `formatError()` - Never called anywhere in codebase
|
||||
|
||||
2. **version-utils.ts (line 52)**:
|
||||
- `createVersionedResponse()` - Never called (only documented in CHANGELOG)
|
||||
|
||||
### Untested Code (To Test)
|
||||
|
||||
1. **path-utils.ts (line 70)**:
|
||||
- Windows absolute path validation: `/^[A-Za-z]:/` regex check
|
||||
|
||||
2. **frontmatter-utils.ts (lines 253-255)**:
|
||||
- Excalidraw parsing fallback: code fence without language specifier
|
||||
|
||||
3. **frontmatter-utils.ts (line 310)**:
|
||||
- Excalidraw decompression error handler
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Task 1: Remove Dead Code from error-messages.ts
|
||||
|
||||
**Objective:** Delete unused methods to improve coverage
|
||||
|
||||
**Steps:**
|
||||
1. Delete `permissionDenied()` method (lines 178-189)
|
||||
2. Delete `formatError()` method (lines 191-204)
|
||||
3. Run tests to verify no broken imports
|
||||
4. Run coverage to confirm improved percentage
|
||||
|
||||
**Files to modify:**
|
||||
- `src/utils/error-messages.ts`
|
||||
|
||||
**Expected outcome:** error-messages.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 2: Remove Dead Code from version-utils.ts
|
||||
|
||||
**Objective:** Delete unused method to improve coverage
|
||||
|
||||
**Steps:**
|
||||
1. Delete `createVersionedResponse()` method (lines 48-57)
|
||||
2. Run tests to verify no broken imports
|
||||
3. Run coverage to confirm improved percentage
|
||||
|
||||
**Files to modify:**
|
||||
- `src/utils/version-utils.ts`
|
||||
|
||||
**Expected outcome:** version-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Clean Up CHANGELOG.md
|
||||
|
||||
**Objective:** Remove references to deleted code
|
||||
|
||||
**Steps:**
|
||||
1. Remove `createVersionedResponse()` reference from line 282
|
||||
2. Keep surrounding context intact
|
||||
3. Verify file still well-formed
|
||||
|
||||
**Files to modify:**
|
||||
- `CHANGELOG.md`
|
||||
|
||||
**Expected outcome:** CHANGELOG accurate to current codebase
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Add path-utils Windows Absolute Path Tests
|
||||
|
||||
**Objective:** Cover line 70 (Windows path validation)
|
||||
|
||||
**Steps:**
|
||||
1. Add test: "rejects Windows absolute paths (C: drive)"
|
||||
- Test `isValidVaultPath('C:\\Users\\file.md')` returns false
|
||||
2. Add test: "rejects Windows absolute paths (D: drive)"
|
||||
- Test `isValidVaultPath('D:\\Documents\\note.md')` returns false
|
||||
3. Run coverage to confirm line 70 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/path-utils.test.ts`
|
||||
|
||||
**Expected outcome:** path-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Add frontmatter-utils Code Fence Fallback Test
|
||||
|
||||
**Objective:** Cover lines 253-255 (code fence without language specifier)
|
||||
|
||||
**Steps:**
|
||||
1. Create Excalidraw note with ` ``` ` fence (no language)
|
||||
2. Add test: "parses Excalidraw with code fence lacking language specifier"
|
||||
3. Call `parseExcalidrawMetadata()` on content
|
||||
4. Verify JSON parsed correctly
|
||||
5. Run coverage to confirm lines 253-255 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/frontmatter-utils.test.ts`
|
||||
|
||||
**Expected outcome:** Lines 253-255 covered
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Add frontmatter-utils Decompression Failure Test
|
||||
|
||||
**Objective:** Cover line 310 (decompression error handler)
|
||||
|
||||
**Steps:**
|
||||
1. Create Excalidraw note with invalid compressed data
|
||||
2. Add test: "handles decompression failure gracefully"
|
||||
3. Mock or create scenario where decompression throws error
|
||||
4. Verify graceful fallback with `hasCompressedData: true`
|
||||
5. Run coverage to confirm line 310 covered
|
||||
|
||||
**Files to modify:**
|
||||
- `tests/frontmatter-utils.test.ts`
|
||||
|
||||
**Expected outcome:** frontmatter-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Verify 100% Coverage
|
||||
|
||||
**Objective:** Confirm 100% coverage achieved on all utils
|
||||
|
||||
**Steps:**
|
||||
1. Run `npm run test:coverage`
|
||||
2. Check coverage report:
|
||||
- error-messages.ts: 100%
|
||||
- version-utils.ts: 100%
|
||||
- path-utils.ts: 100%
|
||||
- frontmatter-utils.ts: 100%
|
||||
3. If any gaps remain:
|
||||
- Identify what's uncovered
|
||||
- Add tests or document as unreachable
|
||||
4. Final coverage verification
|
||||
|
||||
**Expected outcome:** All 4 utils at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Create Summary and Merge
|
||||
|
||||
**Objective:** Document and integrate work
|
||||
|
||||
**Steps:**
|
||||
1. Create `UTILS_COVERAGE_SUMMARY.md` with:
|
||||
- Coverage improvements (before/after)
|
||||
- Test counts
|
||||
- Dead code removed
|
||||
2. Use finishing-a-development-branch skill
|
||||
3. Merge to master
|
||||
|
||||
**Expected outcome:** Work merged, documentation updated
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] error-messages.ts at 100% statement coverage
|
||||
- [ ] version-utils.ts at 100% statement coverage
|
||||
- [ ] path-utils.ts at 100% statement coverage
|
||||
- [ ] frontmatter-utils.ts at 100% statement coverage
|
||||
- [ ] All tests passing (505+)
|
||||
- [ ] Build succeeds
|
||||
- [ ] Dead code removed cleanly
|
||||
- [ ] Work merged to master
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
**If dead code is actually used:**
|
||||
- Full test suite will catch broken imports immediately
|
||||
- TypeScript compilation will fail if methods are referenced
|
||||
- Git revert available if needed
|
||||
|
||||
**If edge case tests are too complex:**
|
||||
- Document specific difficulty encountered
|
||||
- Consider if code is truly reachable
|
||||
- Mark with istanbul ignore if unreachable
|
||||
|
||||
## Estimated Effort
|
||||
|
||||
- Dead code removal: ~15 minutes (3 simple deletions)
|
||||
- Test additions: ~20 minutes (3 test cases)
|
||||
- Verification and cleanup: ~10 minutes
|
||||
- **Total: ~45 minutes**
|
||||
@@ -1,373 +0,0 @@
|
||||
# Implementation Plan: 100% Utility Coverage
|
||||
|
||||
**Date:** 2025-01-20
|
||||
**Branch:** feature/utils-coverage
|
||||
**Goal:** Achieve 100% test coverage on all utility modules using dependency injection pattern
|
||||
|
||||
## Overview
|
||||
|
||||
Apply the same adapter pattern used for tools to utility modules, enabling comprehensive testing. This is pre-release validation work.
|
||||
|
||||
## Current Coverage Status
|
||||
|
||||
- glob-utils.ts: 14.03%
|
||||
- frontmatter-utils.ts: 47.86%
|
||||
- search-utils.ts: 1.78%
|
||||
- link-utils.ts: 13.76%
|
||||
- waypoint-utils.ts: 49.18%
|
||||
|
||||
**Target:** 100% on all utilities
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### Task 2: Add comprehensive tests for glob-utils.ts
|
||||
|
||||
**Objective:** Achieve 100% coverage on glob-utils.ts (pure utility, no refactoring needed)
|
||||
|
||||
**Steps:**
|
||||
1. Create `tests/glob-utils.test.ts`
|
||||
2. Test `globToRegex()` pattern conversion:
|
||||
- `*` matches any chars except `/`
|
||||
- `**` matches any chars including `/`
|
||||
- `?` matches single char except `/`
|
||||
- `[abc]` character classes
|
||||
- `{a,b}` alternatives
|
||||
- Edge cases: unclosed brackets, unclosed braces
|
||||
3. Test `matches()` with various patterns
|
||||
4. Test `matchesIncludes()` with empty/populated arrays
|
||||
5. Test `matchesExcludes()` with empty/populated arrays
|
||||
6. Test `shouldInclude()` combining includes and excludes
|
||||
7. Run coverage to verify 100%
|
||||
8. Commit: "test: add comprehensive glob-utils tests"
|
||||
|
||||
**Files to create:**
|
||||
- `tests/glob-utils.test.ts`
|
||||
|
||||
**Expected outcome:** glob-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 3: Add comprehensive tests for frontmatter-utils.ts
|
||||
|
||||
**Objective:** Achieve 100% coverage on frontmatter-utils.ts
|
||||
|
||||
**Steps:**
|
||||
1. Create `tests/frontmatter-utils.test.ts`
|
||||
2. Mock `parseYaml` from obsidian module
|
||||
3. Test `extractFrontmatter()`:
|
||||
- Valid frontmatter with `---` delimiters
|
||||
- No frontmatter
|
||||
- Missing closing delimiter
|
||||
- Parse errors (mock parseYaml throwing)
|
||||
4. Test `extractFrontmatterSummary()`:
|
||||
- Null input
|
||||
- Title, tags, aliases extraction
|
||||
- Tags/aliases as string vs array
|
||||
5. Test `hasFrontmatter()` quick check
|
||||
6. Test `serializeFrontmatter()`:
|
||||
- Arrays, objects, strings with special chars
|
||||
- Empty objects
|
||||
- Strings needing quotes
|
||||
7. Test `parseExcalidrawMetadata()`:
|
||||
- Valid Excalidraw with markers
|
||||
- Compressed data detection
|
||||
- Uncompressed JSON parsing
|
||||
- Missing JSON blocks
|
||||
8. Run coverage to verify 100%
|
||||
9. Commit: "test: add comprehensive frontmatter-utils tests"
|
||||
|
||||
**Files to create:**
|
||||
- `tests/frontmatter-utils.test.ts`
|
||||
|
||||
**Expected outcome:** frontmatter-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 4: Refactor search-utils.ts to use IVaultAdapter
|
||||
|
||||
**Objective:** Decouple search-utils from App, use IVaultAdapter
|
||||
|
||||
**Steps:**
|
||||
1. Change `SearchUtils.search()` signature:
|
||||
- From: `search(app: App, options: SearchOptions)`
|
||||
- To: `search(vault: IVaultAdapter, options: SearchOptions)`
|
||||
2. Update method body:
|
||||
- Replace `app.vault.getMarkdownFiles()` with `vault.getMarkdownFiles()`
|
||||
- Replace `app.vault.read(file)` with `vault.read(file)`
|
||||
3. Change `SearchUtils.searchWaypoints()` signature:
|
||||
- From: `searchWaypoints(app: App, folder?: string)`
|
||||
- To: `searchWaypoints(vault: IVaultAdapter, folder?: string)`
|
||||
4. Update method body:
|
||||
- Replace `app.vault.getMarkdownFiles()` with `vault.getMarkdownFiles()`
|
||||
- Replace `app.vault.read(file)` with `vault.read(file)`
|
||||
5. Run tests to ensure no breakage (will update callers in Task 7)
|
||||
6. Commit: "refactor: search-utils to use IVaultAdapter"
|
||||
|
||||
**Files to modify:**
|
||||
- `src/utils/search-utils.ts`
|
||||
|
||||
**Expected outcome:** search-utils.ts uses adapters instead of App
|
||||
|
||||
---
|
||||
|
||||
### Task 5: Refactor link-utils.ts to use adapters
|
||||
|
||||
**Objective:** Decouple link-utils from App, use adapters
|
||||
|
||||
**Steps:**
|
||||
1. Change `LinkUtils.resolveLink()` signature:
|
||||
- From: `resolveLink(app: App, sourcePath: string, linkText: string)`
|
||||
- To: `resolveLink(vault: IVaultAdapter, metadata: IMetadataCacheAdapter, sourcePath: string, linkText: string)`
|
||||
2. Update method body:
|
||||
- Replace `app.vault.getAbstractFileByPath()` with `vault.getAbstractFileByPath()`
|
||||
- Replace `app.metadataCache.getFirstLinkpathDest()` with `metadata.getFirstLinkpathDest()`
|
||||
3. Change `LinkUtils.findSuggestions()` signature:
|
||||
- From: `findSuggestions(app: App, linkText: string, ...)`
|
||||
- To: `findSuggestions(vault: IVaultAdapter, linkText: string, ...)`
|
||||
4. Update: `app.vault.getMarkdownFiles()` → `vault.getMarkdownFiles()`
|
||||
5. Change `LinkUtils.getBacklinks()` signature:
|
||||
- From: `getBacklinks(app: App, targetPath: string, ...)`
|
||||
- To: `getBacklinks(vault: IVaultAdapter, metadata: IMetadataCacheAdapter, targetPath: string, ...)`
|
||||
6. Update method body:
|
||||
- Replace `app.vault` calls with `vault` calls
|
||||
- Replace `app.metadataCache` calls with `metadata` calls
|
||||
7. Change `LinkUtils.validateWikilinks()` signature:
|
||||
- From: `validateWikilinks(app: App, filePath: string)`
|
||||
- To: `validateWikilinks(vault: IVaultAdapter, metadata: IMetadataCacheAdapter, filePath: string)`
|
||||
8. Update all internal calls to `resolveLink()` to pass both adapters
|
||||
9. Run tests (will break until Task 7)
|
||||
10. Commit: "refactor: link-utils to use adapters"
|
||||
|
||||
**Files to modify:**
|
||||
- `src/utils/link-utils.ts`
|
||||
|
||||
**Expected outcome:** link-utils.ts uses adapters instead of App
|
||||
|
||||
---
|
||||
|
||||
### Task 6: Refactor waypoint-utils.ts to use IVaultAdapter
|
||||
|
||||
**Objective:** Decouple waypoint-utils from App, use IVaultAdapter
|
||||
|
||||
**Steps:**
|
||||
1. Change `WaypointUtils.isFolderNote()` signature:
|
||||
- From: `isFolderNote(app: App, file: TFile)`
|
||||
- To: `isFolderNote(vault: IVaultAdapter, file: TFile)`
|
||||
2. Update method body:
|
||||
- Replace `await app.vault.read(file)` with `await vault.read(file)`
|
||||
3. Run tests (will break until Task 7)
|
||||
4. Commit: "refactor: waypoint-utils to use IVaultAdapter"
|
||||
|
||||
**Files to modify:**
|
||||
- `src/utils/waypoint-utils.ts`
|
||||
|
||||
**Expected outcome:** waypoint-utils.ts uses adapters instead of App
|
||||
|
||||
---
|
||||
|
||||
### Task 7: Update VaultTools to pass adapters to utilities
|
||||
|
||||
**Objective:** Fix all callers of refactored utilities
|
||||
|
||||
**Steps:**
|
||||
1. In VaultTools.search() method:
|
||||
- Change: `SearchUtils.search(this.app, options)`
|
||||
- To: `SearchUtils.search(this.vault, options)`
|
||||
2. In VaultTools.searchWaypoints() method:
|
||||
- Change: `SearchUtils.searchWaypoints(this.app, folder)`
|
||||
- To: `SearchUtils.searchWaypoints(this.vault, folder)`
|
||||
3. In VaultTools.validateWikilinks() method:
|
||||
- Change: `LinkUtils.validateWikilinks(this.app, filePath)`
|
||||
- To: `LinkUtils.validateWikilinks(this.vault, this.metadata, filePath)`
|
||||
4. In VaultTools.resolveWikilink() method:
|
||||
- Change: `LinkUtils.resolveLink(this.app, sourcePath, linkText)`
|
||||
- To: `LinkUtils.resolveLink(this.vault, this.metadata, sourcePath, linkText)`
|
||||
5. In VaultTools.getBacklinks() method:
|
||||
- Change: `LinkUtils.getBacklinks(this.app, targetPath, includeUnlinked)`
|
||||
- To: `LinkUtils.getBacklinks(this.vault, this.metadata, targetPath, includeUnlinked)`
|
||||
6. In VaultTools.isFolderNote() method:
|
||||
- Change: `WaypointUtils.isFolderNote(this.app, file)`
|
||||
- To: `WaypointUtils.isFolderNote(this.vault, file)`
|
||||
7. Run all tests to verify no breakage
|
||||
8. Commit: "refactor: update VaultTools to pass adapters to utils"
|
||||
|
||||
**Files to modify:**
|
||||
- `src/tools/vault-tools.ts`
|
||||
|
||||
**Expected outcome:** All tests passing, utilities use adapters
|
||||
|
||||
---
|
||||
|
||||
### Task 8: Add comprehensive tests for search-utils.ts
|
||||
|
||||
**Objective:** Achieve 100% coverage on search-utils.ts
|
||||
|
||||
**Steps:**
|
||||
1. Create `tests/search-utils.test.ts`
|
||||
2. Set up mock IVaultAdapter
|
||||
3. Test `SearchUtils.search()`:
|
||||
- Basic literal search
|
||||
- Regex search with pattern
|
||||
- Case sensitive vs insensitive
|
||||
- Folder filtering
|
||||
- Glob includes/excludes filtering
|
||||
- Snippet extraction with long lines
|
||||
- Filename matching (line: 0)
|
||||
- MaxResults limiting
|
||||
- File read errors (catch block)
|
||||
- Zero-width regex matches (prevent infinite loop)
|
||||
4. Test `SearchUtils.searchWaypoints()`:
|
||||
- Finding waypoint blocks
|
||||
- Extracting links from waypoints
|
||||
- Folder filtering
|
||||
- Unclosed waypoints
|
||||
- File read errors
|
||||
5. Run coverage to verify 100%
|
||||
6. Commit: "test: add comprehensive search-utils tests"
|
||||
|
||||
**Files to create:**
|
||||
- `tests/search-utils.test.ts`
|
||||
|
||||
**Expected outcome:** search-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 9: Add comprehensive tests for link-utils.ts
|
||||
|
||||
**Objective:** Achieve 100% coverage on link-utils.ts
|
||||
|
||||
**Steps:**
|
||||
1. Create `tests/link-utils.test.ts`
|
||||
2. Set up mock IVaultAdapter and IMetadataCacheAdapter
|
||||
3. Test `LinkUtils.parseWikilinks()`:
|
||||
- Simple links `[[target]]`
|
||||
- Links with aliases `[[target|alias]]`
|
||||
- Links with headings `[[note#heading]]`
|
||||
- Multiple links per line
|
||||
4. Test `LinkUtils.resolveLink()`:
|
||||
- Valid link resolution
|
||||
- Invalid source path
|
||||
- Link not found (returns null)
|
||||
5. Test `LinkUtils.findSuggestions()`:
|
||||
- Exact basename match
|
||||
- Partial basename match
|
||||
- Path contains match
|
||||
- Character similarity scoring
|
||||
- MaxSuggestions limiting
|
||||
6. Test `LinkUtils.getBacklinks()`:
|
||||
- Linked backlinks from resolvedLinks
|
||||
- Unlinked mentions when includeUnlinked=true
|
||||
- Skip target file itself
|
||||
- Extract snippets
|
||||
7. Test `LinkUtils.validateWikilinks()`:
|
||||
- Resolved links
|
||||
- Unresolved links with suggestions
|
||||
- File not found
|
||||
8. Test `LinkUtils.extractSnippet()` private method via public methods
|
||||
9. Run coverage to verify 100%
|
||||
10. Commit: "test: add comprehensive link-utils tests"
|
||||
|
||||
**Files to create:**
|
||||
- `tests/link-utils.test.ts`
|
||||
|
||||
**Expected outcome:** link-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 10: Add comprehensive tests for waypoint-utils.ts
|
||||
|
||||
**Objective:** Achieve 100% coverage on waypoint-utils.ts
|
||||
|
||||
**Steps:**
|
||||
1. Create `tests/waypoint-utils.test.ts`
|
||||
2. Set up mock IVaultAdapter
|
||||
3. Test `WaypointUtils.extractWaypointBlock()`:
|
||||
- Valid waypoint with links
|
||||
- No waypoint in content
|
||||
- Unclosed waypoint
|
||||
- Empty waypoint
|
||||
4. Test `WaypointUtils.hasWaypointMarker()`:
|
||||
- Content with both markers
|
||||
- Content missing markers
|
||||
5. Test `WaypointUtils.isFolderNote()`:
|
||||
- Basename match (reason: basename_match)
|
||||
- Waypoint marker (reason: waypoint_marker)
|
||||
- Both (reason: both)
|
||||
- Neither (reason: none)
|
||||
- File read errors
|
||||
6. Test `WaypointUtils.wouldAffectWaypoint()`:
|
||||
- Waypoint removed
|
||||
- Waypoint content changed
|
||||
- Waypoint moved but content same
|
||||
- No waypoint in either version
|
||||
7. Test pure helper methods:
|
||||
- `getParentFolderPath()`
|
||||
- `getBasename()`
|
||||
8. Run coverage to verify 100%
|
||||
9. Commit: "test: add comprehensive waypoint-utils tests"
|
||||
|
||||
**Files to create:**
|
||||
- `tests/waypoint-utils.test.ts`
|
||||
|
||||
**Expected outcome:** waypoint-utils.ts at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 11: Verify 100% coverage on all utilities
|
||||
|
||||
**Objective:** Confirm all utilities at 100% coverage
|
||||
|
||||
**Steps:**
|
||||
1. Run `npm run test:coverage`
|
||||
2. Check coverage report for:
|
||||
- glob-utils.ts: 100%
|
||||
- frontmatter-utils.ts: 100%
|
||||
- search-utils.ts: 100%
|
||||
- link-utils.ts: 100%
|
||||
- waypoint-utils.ts: 100%
|
||||
3. If any gaps remain, identify uncovered lines
|
||||
4. Add tests to cover any remaining gaps
|
||||
5. Commit any additional tests
|
||||
6. Final coverage verification
|
||||
|
||||
**Expected outcome:** All utilities at 100% coverage
|
||||
|
||||
---
|
||||
|
||||
### Task 12: Run full test suite and build
|
||||
|
||||
**Objective:** Verify all tests pass and build succeeds
|
||||
|
||||
**Steps:**
|
||||
1. Run `npm test` to verify all tests pass
|
||||
2. Run `npm run build` to verify no type errors
|
||||
3. Check test count increased significantly
|
||||
4. Verify no regressions in existing tests
|
||||
5. Document final test counts and coverage
|
||||
|
||||
**Expected outcome:** All tests passing, build successful
|
||||
|
||||
---
|
||||
|
||||
### Task 13: Create summary and merge to master
|
||||
|
||||
**Objective:** Document work and integrate to master
|
||||
|
||||
**Steps:**
|
||||
1. Create summary document with:
|
||||
- Coverage improvements
|
||||
- Test counts before/after
|
||||
- Architecture changes (adapter pattern in utils)
|
||||
2. Use finishing-a-development-branch skill
|
||||
3. Merge to master
|
||||
4. Clean up worktree
|
||||
|
||||
**Expected outcome:** Work merged, worktree cleaned up
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] All utilities at 100% statement coverage
|
||||
- [ ] All tests passing (expected 300+ tests)
|
||||
- [ ] Build succeeds with no type errors
|
||||
- [ ] Adapter pattern consistently applied
|
||||
- [ ] Work merged to master branch
|
||||
@@ -1,367 +0,0 @@
|
||||
# 100% Test Coverage via Dependency Injection
|
||||
|
||||
**Date:** 2025-10-19
|
||||
**Goal:** Achieve 100% test coverage through dependency injection refactoring
|
||||
**Current Coverage:** 90.58% overall (VaultTools: 71.72%, NoteTools: 92.77%)
|
||||
|
||||
## Motivation
|
||||
|
||||
We want codebase confidence for future refactoring and feature work. The current test suite has good coverage but gaps remain in:
|
||||
- Error handling paths
|
||||
- Edge cases (type coercion, missing data)
|
||||
- Complex conditional branches
|
||||
|
||||
The current testing approach directly mocks Obsidian's `App` object, leading to:
|
||||
- Complex, brittle mock setups
|
||||
- Duplicated mocking code across test files
|
||||
- Difficulty isolating specific behaviors
|
||||
- Hard-to-test error conditions
|
||||
|
||||
## Solution: Dependency Injection Architecture
|
||||
|
||||
### Core Principle
|
||||
Extract interfaces for Obsidian API dependencies, allowing tools to depend on abstractions rather than concrete implementations. This enables clean, simple mocks in tests while maintaining production functionality.
|
||||
|
||||
### Architecture Overview
|
||||
|
||||
**Current State:**
|
||||
```typescript
|
||||
class NoteTools {
|
||||
constructor(private app: App) {}
|
||||
// Methods use: this.app.vault.X, this.app.metadataCache.Y, etc.
|
||||
}
|
||||
```
|
||||
|
||||
**Target State:**
|
||||
```typescript
|
||||
class NoteTools {
|
||||
constructor(
|
||||
private vault: IVaultAdapter,
|
||||
private metadata: IMetadataCacheAdapter,
|
||||
private fileManager: IFileManagerAdapter
|
||||
) {}
|
||||
// Methods use: this.vault.X, this.metadata.Y, etc.
|
||||
}
|
||||
|
||||
// Production usage via factory:
|
||||
function createNoteTools(app: App): NoteTools {
|
||||
return new NoteTools(
|
||||
new VaultAdapter(app.vault),
|
||||
new MetadataCacheAdapter(app.metadataCache),
|
||||
new FileManagerAdapter(app.fileManager)
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Interface Design
|
||||
|
||||
### IVaultAdapter
|
||||
Wraps file system operations from Obsidian's Vault API.
|
||||
|
||||
```typescript
|
||||
interface IVaultAdapter {
|
||||
// File reading
|
||||
read(path: string): Promise<string>;
|
||||
|
||||
// File existence and metadata
|
||||
exists(path: string): boolean;
|
||||
stat(path: string): { ctime: number; mtime: number; size: number } | null;
|
||||
|
||||
// File retrieval
|
||||
getAbstractFileByPath(path: string): TAbstractFile | null;
|
||||
getMarkdownFiles(): TFile[];
|
||||
|
||||
// Directory operations
|
||||
getRoot(): TFolder;
|
||||
}
|
||||
```
|
||||
|
||||
### IMetadataCacheAdapter
|
||||
Wraps metadata and link resolution from Obsidian's MetadataCache API.
|
||||
|
||||
```typescript
|
||||
interface IMetadataCacheAdapter {
|
||||
// Cache access
|
||||
getFileCache(file: TFile): CachedMetadata | null;
|
||||
|
||||
// Link resolution
|
||||
getFirstLinkpathDest(linkpath: string, sourcePath: string): TFile | null;
|
||||
|
||||
// Backlinks
|
||||
getBacklinksForFile(file: TFile): { [key: string]: any };
|
||||
|
||||
// Additional metadata methods as needed
|
||||
}
|
||||
```
|
||||
|
||||
### IFileManagerAdapter
|
||||
Wraps file modification operations from Obsidian's FileManager API.
|
||||
|
||||
```typescript
|
||||
interface IFileManagerAdapter {
|
||||
// File operations
|
||||
rename(file: TAbstractFile, newPath: string): Promise<void>;
|
||||
delete(file: TAbstractFile): Promise<void>;
|
||||
create(path: string, content: string): Promise<TFile>;
|
||||
modify(file: TFile, content: string): Promise<void>;
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
src/
|
||||
├── adapters/
|
||||
│ ├── interfaces.ts # Interface definitions
|
||||
│ ├── vault-adapter.ts # VaultAdapter implementation
|
||||
│ ├── metadata-adapter.ts # MetadataCacheAdapter implementation
|
||||
│ └── file-manager-adapter.ts # FileManagerAdapter implementation
|
||||
├── tools/
|
||||
│ ├── note-tools.ts # Refactored to use adapters
|
||||
│ └── vault-tools.ts # Refactored to use adapters
|
||||
tests/
|
||||
├── __mocks__/
|
||||
│ ├── adapters.ts # Mock adapter factories
|
||||
│ └── obsidian.ts # Existing Obsidian mocks (minimal usage going forward)
|
||||
```
|
||||
|
||||
### Migration Approach
|
||||
|
||||
**Step 1: Create Adapters**
|
||||
- Define interfaces in `src/adapters/interfaces.ts`
|
||||
- Implement concrete adapters (simple pass-through wrappers initially)
|
||||
- Create mock adapter factories in `tests/__mocks__/adapters.ts`
|
||||
|
||||
**Step 2: Refactor VaultTools**
|
||||
- Update constructor to accept adapter interfaces
|
||||
- Replace all `this.app.X` calls with `this.X` (using injected adapters)
|
||||
- Create `createVaultTools(app: App)` factory function
|
||||
- Update tests to use mock adapters
|
||||
|
||||
**Step 3: Refactor NoteTools**
|
||||
- Same pattern as VaultTools
|
||||
- Create `createNoteTools(app: App)` factory function
|
||||
- Update tests to use mock adapters
|
||||
|
||||
**Step 4: Integration**
|
||||
- Update ToolRegistry to use factory functions
|
||||
- Update main.ts to use factory functions
|
||||
- Verify all existing functionality preserved
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
**Plugin Code (main.ts, ToolRegistry):**
|
||||
- Uses factory functions: `createNoteTools(app)`, `createVaultTools(app)`
|
||||
- No awareness of adapters - just passes the App object
|
||||
- Public API unchanged
|
||||
|
||||
**Tool Classes:**
|
||||
- Constructors accept adapters (new signature)
|
||||
- All methods work identically (internal implementation detail)
|
||||
- External callers use factory functions
|
||||
|
||||
## Test Suite Overhaul
|
||||
|
||||
### Mock Adapter Pattern
|
||||
|
||||
**Centralized Mock Creation:**
|
||||
```typescript
|
||||
// tests/__mocks__/adapters.ts
|
||||
export function createMockVaultAdapter(overrides?: Partial<IVaultAdapter>): IVaultAdapter {
|
||||
return {
|
||||
read: jest.fn(),
|
||||
exists: jest.fn(),
|
||||
stat: jest.fn(),
|
||||
getAbstractFileByPath: jest.fn(),
|
||||
getMarkdownFiles: jest.fn(),
|
||||
getRoot: jest.fn(),
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
export function createMockMetadataCacheAdapter(overrides?: Partial<IMetadataCacheAdapter>): IMetadataCacheAdapter {
|
||||
return {
|
||||
getFileCache: jest.fn(),
|
||||
getFirstLinkpathDest: jest.fn(),
|
||||
getBacklinksForFile: jest.fn(),
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
|
||||
export function createMockFileManagerAdapter(overrides?: Partial<IFileManagerAdapter>): IFileManagerAdapter {
|
||||
return {
|
||||
rename: jest.fn(),
|
||||
delete: jest.fn(),
|
||||
create: jest.fn(),
|
||||
modify: jest.fn(),
|
||||
...overrides
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**Test Setup Simplification:**
|
||||
```typescript
|
||||
// Before: Complex App mock with nested properties
|
||||
const mockApp = {
|
||||
vault: { read: jest.fn(), ... },
|
||||
metadataCache: { getFileCache: jest.fn(), ... },
|
||||
fileManager: { ... },
|
||||
// Many more properties...
|
||||
};
|
||||
|
||||
// After: Simple, targeted mocks
|
||||
const vaultAdapter = createMockVaultAdapter({
|
||||
read: jest.fn().mockResolvedValue('file content')
|
||||
});
|
||||
const tools = new VaultTools(vaultAdapter, mockMetadata, mockFileManager);
|
||||
```
|
||||
|
||||
### Coverage Strategy by Feature Area
|
||||
|
||||
**1. Frontmatter Operations**
|
||||
- Test string tags → array conversion
|
||||
- Test array tags → preserved as array
|
||||
- Test missing frontmatter → base metadata only
|
||||
- Test frontmatter parsing errors → error handling path
|
||||
- Test all field types (title, aliases, custom fields)
|
||||
|
||||
**2. Wikilink Validation**
|
||||
- Test resolved links → included in results
|
||||
- Test unresolved links → included with error details
|
||||
- Test missing file → error path
|
||||
- Test heading links (`[[note#heading]]`)
|
||||
- Test alias links (`[[note|alias]]`)
|
||||
|
||||
**3. Backlinks**
|
||||
- Test `includeSnippets: true` → snippets included
|
||||
- Test `includeSnippets: false` → snippets removed
|
||||
- Test `includeUnlinked: true` → unlinked mentions included
|
||||
- Test `includeUnlinked: false` → only linked mentions
|
||||
- Test error handling paths
|
||||
|
||||
**4. Search Utilities**
|
||||
- Test glob pattern filtering
|
||||
- Test regex search with matches
|
||||
- Test regex search with no matches
|
||||
- Test invalid regex → error handling
|
||||
- Test edge cases (empty results, malformed patterns)
|
||||
|
||||
**5. Note CRUD Operations**
|
||||
- Test all conflict strategies: error, overwrite, rename
|
||||
- Test version mismatch → conflict error
|
||||
- Test missing file on update → error path
|
||||
- Test permission errors → error handling
|
||||
- Test all edge cases in uncovered lines
|
||||
|
||||
**6. Path Validation Edge Cases**
|
||||
- Test all PathUtils error conditions
|
||||
- Test leading/trailing slash handling
|
||||
- Test `..` traversal attempts
|
||||
- Test absolute path rejection
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Foundation (Adapters)
|
||||
**Deliverables:**
|
||||
- `src/adapters/interfaces.ts` - All interface definitions
|
||||
- `src/adapters/vault-adapter.ts` - VaultAdapter implementation
|
||||
- `src/adapters/metadata-adapter.ts` - MetadataCacheAdapter implementation
|
||||
- `src/adapters/file-manager-adapter.ts` - FileManagerAdapter implementation
|
||||
- `tests/__mocks__/adapters.ts` - Mock adapter factories
|
||||
- Tests for adapters (basic pass-through verification)
|
||||
|
||||
**Success Criteria:**
|
||||
- All adapters compile without errors
|
||||
- Mock adapters available for test usage
|
||||
- Simple adapter tests pass
|
||||
|
||||
### Phase 2: VaultTools Refactoring
|
||||
**Deliverables:**
|
||||
- Refactored VaultTools class using adapters
|
||||
- `createVaultTools()` factory function
|
||||
- Updated vault-tools.test.ts using mock adapters
|
||||
- New tests for uncovered lines:
|
||||
- Frontmatter extraction (lines 309-352)
|
||||
- Wikilink validation error path (lines 716-735)
|
||||
- Backlinks snippet removal (lines 824-852)
|
||||
- Other uncovered paths
|
||||
|
||||
**Success Criteria:**
|
||||
- VaultTools achieves 100% coverage (all metrics)
|
||||
- All existing tests pass
|
||||
- No breaking changes to public API
|
||||
|
||||
### Phase 3: NoteTools Refactoring
|
||||
**Deliverables:**
|
||||
- Refactored NoteTools class using adapters
|
||||
- `createNoteTools()` factory function
|
||||
- Updated note-tools.test.ts using mock adapters
|
||||
- New tests for uncovered error paths and edge cases
|
||||
|
||||
**Success Criteria:**
|
||||
- NoteTools achieves 100% coverage (all metrics)
|
||||
- All existing tests pass
|
||||
- No breaking changes to public API
|
||||
|
||||
### Phase 4: Integration & Verification
|
||||
**Deliverables:**
|
||||
- Updated ToolRegistry using factory functions
|
||||
- Updated main.ts using factory functions
|
||||
- Full test suite passing
|
||||
- Coverage report showing 100% across all files
|
||||
- Build succeeding with no errors
|
||||
|
||||
**Success Criteria:**
|
||||
- 100% test coverage: statements, branches, functions, lines
|
||||
- All 400+ tests passing
|
||||
- `npm run build` succeeds
|
||||
- Manual smoke test in Obsidian confirms functionality
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
**Risk: Breaking existing functionality**
|
||||
- Mitigation: Incremental refactoring, existing tests updated alongside code changes
|
||||
- Factory pattern keeps plugin code nearly unchanged
|
||||
|
||||
**Risk: Incomplete interface coverage**
|
||||
- Mitigation: Start with methods actually used by tools, add to interfaces as needed
|
||||
- Adapters are simple pass-throughs, easy to extend
|
||||
|
||||
**Risk: Complex migration**
|
||||
- Mitigation: Phased approach allows stopping after any phase
|
||||
- Git worktree isolates changes from main branch
|
||||
|
||||
**Risk: Test maintenance burden**
|
||||
- Mitigation: Centralized mock factories reduce duplication
|
||||
- Cleaner mocks are easier to maintain than complex App mocks
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Coverage Goals:**
|
||||
- Statement coverage: 100%
|
||||
- Branch coverage: 100%
|
||||
- Function coverage: 100%
|
||||
- Line coverage: 100%
|
||||
|
||||
**Quality Goals:**
|
||||
- All existing tests pass
|
||||
- No type errors in build
|
||||
- Plugin functions correctly in Obsidian
|
||||
- Test code is cleaner and more maintainable
|
||||
|
||||
**Timeline:**
|
||||
- Phase 1: ~2-3 hours (adapters + mocks)
|
||||
- Phase 2: ~3-4 hours (VaultTools refactor + tests)
|
||||
- Phase 3: ~2-3 hours (NoteTools refactor + tests)
|
||||
- Phase 4: ~1 hour (integration + verification)
|
||||
- Total: ~8-11 hours of focused work
|
||||
|
||||
## Future Benefits
|
||||
|
||||
**After this refactoring:**
|
||||
- Adding new tools is easier (use existing adapters)
|
||||
- Testing new features is trivial (mock only what you need)
|
||||
- Obsidian API changes isolated to adapter layer
|
||||
- Confidence in comprehensive test coverage enables fearless refactoring
|
||||
- New team members can understand test setup quickly
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
616
docs/plans/2025-10-26-public-release-version-reset.md
Normal file
616
docs/plans/2025-10-26-public-release-version-reset.md
Normal file
@@ -0,0 +1,616 @@
|
||||
# Public Release Version Reset to 1.0.0 Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Reset version to 1.0.0 in preparation for public release while preserving git history
|
||||
|
||||
**Architecture:** Update version identifiers in manifest.json, package.json, and versions.json to mark 1.0.0 as the target for public release. The existing git history (95 commits) will be preserved to demonstrate development quality and maintain context for future contributors. Previous development versions (1.0.0-3.0.0) become private development history. Git tagging will be done separately when development is complete and ready for actual release.
|
||||
|
||||
**Tech Stack:** Node.js version-bump.mjs script, JSON files, git
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Current state:
|
||||
- Version: 3.0.0 (in manifest.json, package.json)
|
||||
- versions.json contains: 1.0.0, 1.1.0, 1.2.0, 2.0.0, 2.1.0, 3.0.0 (all mapped to minAppVersion 0.15.0)
|
||||
- 95 commits in git history with no sensitive data
|
||||
- Clean commit history with conventional commit format
|
||||
- CHANGELOG.md contains extensive development history (versions 1.0.0 through 9.0.0)
|
||||
|
||||
Decision: Keep git history (demonstrates quality, security-conscious development, comprehensive testing) and reset version to 1.0.0 in preparation for public release.
|
||||
|
||||
**Important:** Development is ongoing. This plan resets the version number but does NOT create a git tag. The tag will be created separately when development is complete and the plugin is ready for actual public release.
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Update manifest.json Version
|
||||
|
||||
**Files:**
|
||||
- Modify: `manifest.json:4`
|
||||
|
||||
**Step 1: Read current manifest.json**
|
||||
|
||||
Verify current version before modifying.
|
||||
|
||||
Run: `cat manifest.json`
|
||||
Expected: Shows `"version": "3.0.0"`
|
||||
|
||||
**Step 2: Update version to 1.0.0**
|
||||
|
||||
Change version field from "3.0.0" to "1.0.0".
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "obsidian-mcp-server",
|
||||
"name": "MCP Server",
|
||||
"version": "1.0.0",
|
||||
"minAppVersion": "0.15.0",
|
||||
"description": "Exposes Obsidian vault operations via Model Context Protocol (MCP) over HTTP",
|
||||
"author": "Bill Ballou",
|
||||
"isDesktopOnly": true
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: Verify the change**
|
||||
|
||||
Run: `cat manifest.json | grep version`
|
||||
Expected: Shows `"version": "1.0.0"` and `"minAppVersion": "0.15.0"`
|
||||
|
||||
---
|
||||
|
||||
## Task 2: Update package.json Version
|
||||
|
||||
**Files:**
|
||||
- Modify: `package.json:3`
|
||||
|
||||
**Step 1: Read current package.json**
|
||||
|
||||
Verify current version before modifying.
|
||||
|
||||
Run: `cat package.json | head -5`
|
||||
Expected: Shows `"version": "3.0.0"`
|
||||
|
||||
**Step 2: Update version to 1.0.0**
|
||||
|
||||
Change version field from "3.0.0" to "1.0.0".
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "obsidian-mcp-server",
|
||||
"version": "1.0.0",
|
||||
"description": "MCP (Model Context Protocol) server plugin for Obsidian - exposes vault operations via HTTP",
|
||||
```
|
||||
|
||||
**Step 3: Verify the change**
|
||||
|
||||
Run: `cat package.json | grep '"version"'`
|
||||
Expected: Shows `"version": "1.0.0"`
|
||||
|
||||
---
|
||||
|
||||
## Task 3: Reset versions.json
|
||||
|
||||
**Files:**
|
||||
- Modify: `versions.json` (entire file)
|
||||
|
||||
**Step 1: Read current versions.json**
|
||||
|
||||
Verify current content before modifying.
|
||||
|
||||
Run: `cat versions.json`
|
||||
Expected: Shows entries for 1.0.0 through 3.0.0
|
||||
|
||||
**Step 2: Replace with single 1.0.0 entry**
|
||||
|
||||
Clear all development version history, keep only 1.0.0 as first public release.
|
||||
|
||||
```json
|
||||
{
|
||||
"1.0.0": "0.15.0"
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3: Verify the change**
|
||||
|
||||
Run: `cat versions.json`
|
||||
Expected: Shows only one entry: `"1.0.0": "0.15.0"`
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Update CHANGELOG.md for Public Release
|
||||
|
||||
**Files:**
|
||||
- Modify: `CHANGELOG.md:1-1366`
|
||||
|
||||
**Step 1: Read current CHANGELOG structure**
|
||||
|
||||
Run: `head -50 CHANGELOG.md`
|
||||
Expected: Shows "# Changelog" header and extensive version history
|
||||
|
||||
**Step 2: Create new public-release CHANGELOG**
|
||||
|
||||
Replace entire file with simplified version for public release. Remove private development version entries (1.0.0-9.0.0), keep only new 1.0.0 public release entry.
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
All notable changes to the Obsidian MCP Server plugin will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
---
|
||||
|
||||
## [1.0.0] - 2025-10-26
|
||||
|
||||
### 🎉 Initial Public Release
|
||||
|
||||
The Obsidian MCP Server plugin is now publicly available! This plugin exposes your Obsidian vault via the Model Context Protocol (MCP) over HTTP, enabling AI assistants and other MCP clients to interact with your vault programmatically.
|
||||
|
||||
#### Core Features
|
||||
|
||||
**MCP Server**
|
||||
- HTTP server implementing MCP protocol version 2024-11-05
|
||||
- JSON-RPC 2.0 message handling
|
||||
- Localhost-only binding (127.0.0.1) for security
|
||||
- Configurable port (default: 3000)
|
||||
- Auto-start option
|
||||
|
||||
**Note Operations**
|
||||
- `read_note` - Read note content with optional frontmatter parsing
|
||||
- `create_note` - Create notes with conflict handling (error/overwrite/rename)
|
||||
- `update_note` - Update existing notes with concurrency control
|
||||
- `delete_note` - Delete notes (soft delete to .trash or permanent)
|
||||
- `update_frontmatter` - Update frontmatter fields without modifying content
|
||||
- `update_sections` - Update specific sections by line range
|
||||
- `rename_file` - Rename or move files with automatic wikilink updates
|
||||
- `read_excalidraw` - Read Excalidraw drawing files with metadata
|
||||
|
||||
**Vault Operations**
|
||||
- `search` - Advanced search with regex, glob filtering, and snippets
|
||||
- `search_waypoints` - Find Waypoint plugin markers
|
||||
- `list` - List files/directories with filtering and pagination
|
||||
- `stat` - Get detailed file/folder metadata
|
||||
- `exists` - Quick existence check
|
||||
- `get_vault_info` - Vault metadata and statistics
|
||||
|
||||
**Waypoint Integration**
|
||||
- `get_folder_waypoint` - Extract Waypoint blocks from folder notes
|
||||
- `is_folder_note` - Detect folder notes
|
||||
- Automatic waypoint edit protection
|
||||
|
||||
**Link Management**
|
||||
- `validate_wikilinks` - Validate all links in a note
|
||||
- `resolve_wikilink` - Resolve single wikilink to target path
|
||||
- `backlinks` - Get backlinks with optional unlinked mentions
|
||||
|
||||
**Security**
|
||||
- Mandatory Bearer token authentication
|
||||
- Auto-generated, cryptographically secure API keys (32 characters)
|
||||
- API keys encrypted using system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
|
||||
- Host header validation (DNS rebinding protection)
|
||||
- CORS policy fixed to localhost-only origins
|
||||
- Desktop-only (requires Node.js HTTP server)
|
||||
|
||||
**User Interface**
|
||||
- Settings panel with full configuration
|
||||
- Status bar indicator showing server state
|
||||
- Ribbon icon for quick server toggle
|
||||
- Start/Stop/Restart commands
|
||||
- Real-time connection information
|
||||
- Copy API key and configuration snippets
|
||||
- Notification system for tool calls (optional)
|
||||
- Notification history viewer
|
||||
|
||||
**Developer Experience**
|
||||
- Cross-platform path handling (Windows/macOS/Linux)
|
||||
- Comprehensive error messages with troubleshooting tips
|
||||
- Path validation and normalization utilities
|
||||
- Concurrency control via ETag-based versioning
|
||||
- Type-safe TypeScript implementation
|
||||
- Extensive test coverage
|
||||
- Well-documented codebase
|
||||
|
||||
#### Technical Details
|
||||
|
||||
**Dependencies**
|
||||
- express: ^4.18.2
|
||||
- cors: ^2.8.5
|
||||
- obsidian: latest
|
||||
|
||||
**Build**
|
||||
- TypeScript 4.7.4
|
||||
- esbuild 0.17.3
|
||||
- Jest 30.2.0 for testing
|
||||
|
||||
**Compatibility**
|
||||
- Obsidian minimum version: 0.15.0
|
||||
- Desktop only (not available on mobile)
|
||||
- Protocol: MCP 2024-11-05
|
||||
|
||||
#### Known Limitations
|
||||
|
||||
- Desktop only (requires Node.js HTTP server)
|
||||
- Single vault per server instance
|
||||
- HTTP only (no WebSocket support)
|
||||
- Localhost-only (no SSL/TLS)
|
||||
- Excalidraw support limited to uncompressed format (compressed format planned)
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
### Planned Features
|
||||
|
||||
**Resources API**
|
||||
- Expose notes as MCP resources
|
||||
- Real-time resource updates
|
||||
|
||||
**Prompts API**
|
||||
- Templated prompts for common operations
|
||||
- Custom prompt registration
|
||||
|
||||
**Batch Operations**
|
||||
- Multiple operations in single request
|
||||
- Transactional batching
|
||||
|
||||
**WebSocket Transport**
|
||||
- Real-time updates and notifications
|
||||
- Bidirectional communication
|
||||
|
||||
**Enhanced Graph API**
|
||||
- Graph visualization data
|
||||
- Advanced graph traversal
|
||||
|
||||
**Tag & Canvas APIs**
|
||||
- Query and manage tags
|
||||
- Manipulate canvas files
|
||||
|
||||
**Dataview Integration**
|
||||
- Query vault using Dataview syntax
|
||||
- Advanced data queries
|
||||
|
||||
**Performance Enhancements**
|
||||
- Indexing for faster searches
|
||||
- Caching for frequently accessed notes
|
||||
- Streaming for large files
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or contributions:
|
||||
- GitHub Issues: [Report bugs and request features]
|
||||
- Documentation: See README.md and CLAUDE.md
|
||||
- Include version number (1.0.0) in bug reports
|
||||
|
||||
---
|
||||
|
||||
## Credits
|
||||
|
||||
- MCP Protocol: https://modelcontextprotocol.io
|
||||
- Obsidian API: https://github.com/obsidianmd/obsidian-api
|
||||
- Built with TypeScript, Express.js, and dedication to quality
|
||||
```
|
||||
|
||||
**Step 3: Verify the change**
|
||||
|
||||
Run: `wc -l CHANGELOG.md && head -20 CHANGELOG.md`
|
||||
Expected: Shows much shorter file (~200 lines vs 1400+), starts with "# Changelog" and "## [1.0.0] - 2025-10-26"
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Verify All Version Changes
|
||||
|
||||
**Files:**
|
||||
- Read: `manifest.json`, `package.json`, `versions.json`
|
||||
|
||||
**Step 1: Check all version files**
|
||||
|
||||
Run: `echo "=== manifest.json ===" && cat manifest.json | grep version && echo "=== package.json ===" && cat package.json | grep version && echo "=== versions.json ===" && cat versions.json`
|
||||
|
||||
Expected output:
|
||||
```
|
||||
=== manifest.json ===
|
||||
"version": "1.0.0",
|
||||
"minAppVersion": "0.15.0",
|
||||
=== package.json ===
|
||||
"version": "1.0.0",
|
||||
"version": "node version-bump.mjs && git add manifest.json versions.json"
|
||||
=== versions.json ===
|
||||
{
|
||||
"1.0.0": "0.15.0"
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Verify version-bump.mjs script compatibility**
|
||||
|
||||
The version-bump.mjs script (used by `npm version`) reads from package.json and updates manifest.json and versions.json. With all files now at 1.0.0, future version bumps will work correctly.
|
||||
|
||||
Run: `cat version-bump.mjs`
|
||||
Expected: Script reads `npm_package_version`, updates manifest.json version, and conditionally updates versions.json
|
||||
|
||||
**Step 3: Test build**
|
||||
|
||||
Ensure the plugin still builds correctly after version changes.
|
||||
|
||||
Run: `npm run build`
|
||||
Expected: TypeScript compiles successfully, esbuild creates main.js, no errors
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Commit Version Reset
|
||||
|
||||
**Files:**
|
||||
- Modify: `manifest.json`, `package.json`, `versions.json`, `CHANGELOG.md`
|
||||
|
||||
**Step 1: Review changes to commit**
|
||||
|
||||
Run: `git status`
|
||||
Expected: Shows modified files: manifest.json, package.json, versions.json, CHANGELOG.md
|
||||
|
||||
**Step 2: Review diff**
|
||||
|
||||
Run: `git diff manifest.json package.json versions.json`
|
||||
Expected: Shows version changes from 3.0.0 to 1.0.0, versions.json reduced to single entry
|
||||
|
||||
**Step 3: Stage all changes**
|
||||
|
||||
Run: `git add manifest.json package.json versions.json CHANGELOG.md`
|
||||
|
||||
**Step 4: Create commit**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git commit -m "$(cat <<'EOF'
|
||||
chore: reset version to 1.0.0 for initial public release
|
||||
|
||||
This marks version 1.0.0 as the first public release of the plugin.
|
||||
Previous versions (1.0.0-3.0.0) were private development iterations.
|
||||
|
||||
Changes:
|
||||
- Reset manifest.json version to 1.0.0
|
||||
- Reset package.json version to 1.0.0
|
||||
- Clear versions.json to single entry (1.0.0 -> 0.15.0)
|
||||
- Rewrite CHANGELOG.md for public release
|
||||
- Remove private development history
|
||||
- Document all features as part of 1.0.0
|
||||
- Add future roadmap section
|
||||
|
||||
Git history is preserved to demonstrate:
|
||||
- Development quality and security practices
|
||||
- Comprehensive test coverage efforts
|
||||
- Thoughtful evolution of features
|
||||
|
||||
This plugin implements MCP (Model Context Protocol) to expose
|
||||
Obsidian vault operations via HTTP for AI assistants and other clients.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
**Step 5: Verify commit**
|
||||
|
||||
Run: `git log -1 --stat`
|
||||
Expected: Shows commit with 4 files changed, commit message explains version reset
|
||||
|
||||
**Step 6: Verify git history is preserved**
|
||||
|
||||
Run: `git log --oneline | wc -l`
|
||||
Expected: Shows 96 commits (95 previous + 1 new commit)
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Document Version Reset Decision
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/VERSION_HISTORY.md`
|
||||
|
||||
**Step 1: Create version history documentation**
|
||||
|
||||
Document why version was reset and what happened to previous versions.
|
||||
|
||||
```markdown
|
||||
# Version History
|
||||
|
||||
## Public Release Version Strategy
|
||||
|
||||
### Initial Public Release: 1.0.0 (2025-10-26)
|
||||
|
||||
This plugin's first public release is marked as **version 1.0.0**.
|
||||
|
||||
### Development History
|
||||
|
||||
Prior to public release, the plugin went through private development with internal versions 1.0.0 through 3.0.0. These versions were used during development and testing but were never publicly released.
|
||||
|
||||
When preparing for public release, we reset the version to 1.0.0 to clearly mark this as the first public version available to users.
|
||||
|
||||
### Why Reset to 1.0.0?
|
||||
|
||||
**Semantic Versioning**: Version 1.0.0 signals the first stable, public release of the plugin. It indicates:
|
||||
- The API is stable and ready for public use
|
||||
- All core features are implemented and tested
|
||||
- The plugin is production-ready
|
||||
|
||||
**User Clarity**: Starting at 1.0.0 for the public release avoids confusion:
|
||||
- Users don't wonder "what happened to versions 1-2?"
|
||||
- Version number accurately reflects the public release history
|
||||
- Clear signal that this is the first version they can install
|
||||
|
||||
**Git History Preserved**: The development history (95 commits) is preserved to:
|
||||
- Demonstrate development quality and security practices
|
||||
- Show comprehensive testing and iterative refinement
|
||||
- Provide context for future contributors
|
||||
- Maintain git blame and bisect capabilities
|
||||
|
||||
### Version Numbering Going Forward
|
||||
|
||||
From 1.0.0 onward, the plugin follows [Semantic Versioning](https://semver.org/):
|
||||
|
||||
- **MAJOR** version (1.x.x): Incompatible API changes or breaking changes
|
||||
- **MINOR** version (x.1.x): New functionality in a backward-compatible manner
|
||||
- **PATCH** version (x.x.1): Backward-compatible bug fixes
|
||||
|
||||
### Development Version Mapping
|
||||
|
||||
For reference, here's what the private development versions contained:
|
||||
|
||||
| Dev Version | Key Features Added |
|
||||
|-------------|-------------------|
|
||||
| 1.0.0 | Initial MCP server, basic CRUD tools |
|
||||
| 1.1.0 | Path normalization, error handling |
|
||||
| 1.2.0 | Enhanced authentication, parent folder detection |
|
||||
| 2.0.0 | API unification, typed results |
|
||||
| 2.1.0 | Discovery endpoints (stat, exists) |
|
||||
| 3.0.0 | Enhanced list operations |
|
||||
|
||||
All these features are included in the public 1.0.0 release.
|
||||
|
||||
### Commit History
|
||||
|
||||
The git repository contains the complete development history showing the evolution from initial implementation through all features. This history demonstrates:
|
||||
|
||||
- Security-conscious development (API key encryption, authentication)
|
||||
- Comprehensive test coverage (100% coverage goals)
|
||||
- Careful refactoring and improvements
|
||||
- Documentation and planning
|
||||
- Bug fixes and edge case handling
|
||||
|
||||
No sensitive data exists in the git history (verified via audit).
|
||||
|
||||
---
|
||||
|
||||
## Future Versioning
|
||||
|
||||
**Next versions** will be numbered according to the changes made:
|
||||
|
||||
- **1.0.1**: Bug fixes and patches
|
||||
- **1.1.0**: New features (e.g., Resources API, Prompts API)
|
||||
- **2.0.0**: Breaking changes to tool schemas or behavior
|
||||
|
||||
The CHANGELOG.md will document all public releases starting from 1.0.0.
|
||||
```
|
||||
|
||||
**Step 2: Verify file was created**
|
||||
|
||||
Run: `cat docs/VERSION_HISTORY.md | head -30`
|
||||
Expected: Shows version history explanation
|
||||
|
||||
**Step 3: Commit version history documentation**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
git add docs/VERSION_HISTORY.md
|
||||
git commit -m "docs: add version history explanation for 1.0.0 reset"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 8: Final Verification
|
||||
|
||||
**Files:**
|
||||
- Read: All modified files
|
||||
|
||||
**Step 1: Verify all version references**
|
||||
|
||||
Check that no stray version references remain.
|
||||
|
||||
Run: `grep -r "3\.0\.0" --include="*.json" --include="*.md" . 2>/dev/null | grep -v node_modules | grep -v ".git"`
|
||||
Expected: No results (all 3.0.0 references should be gone from project files)
|
||||
|
||||
**Step 2: Verify package.json npm version script**
|
||||
|
||||
The `npm version` command should work correctly for future version bumps.
|
||||
|
||||
Run: `cat package.json | grep '"version"'`
|
||||
Expected: Shows `"version": "1.0.0"` and version script with version-bump.mjs
|
||||
|
||||
**Step 3: Verify build output**
|
||||
|
||||
Run: `npm run build 2>&1 | tail -5`
|
||||
Expected: Build succeeds, no errors
|
||||
|
||||
**Step 4: Check git status**
|
||||
|
||||
Run: `git status`
|
||||
Expected: Working tree clean, no uncommitted changes
|
||||
|
||||
**Step 5: Verify commit history**
|
||||
|
||||
Run: `git log --oneline -5`
|
||||
Expected: Shows recent commits including version reset and documentation
|
||||
|
||||
**Step 6: Final summary**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
echo "=== Version Files ===" && \
|
||||
cat manifest.json | grep version && \
|
||||
cat package.json | grep '"version"' && \
|
||||
cat versions.json && \
|
||||
echo "=== Git Info ===" && \
|
||||
git log --oneline | wc -l && \
|
||||
echo "=== Build Status ===" && \
|
||||
ls -lh main.js
|
||||
```
|
||||
|
||||
Expected:
|
||||
- All versions show 1.0.0
|
||||
- versions.json has single entry
|
||||
- Git shows 96+ commits
|
||||
- main.js exists and is recent
|
||||
|
||||
---
|
||||
|
||||
## Completion Checklist
|
||||
|
||||
- [ ] manifest.json version is 1.0.0
|
||||
- [ ] package.json version is 1.0.0
|
||||
- [ ] versions.json contains only {"1.0.0": "0.15.0"}
|
||||
- [ ] CHANGELOG.md rewritten for public release
|
||||
- [ ] All changes committed with descriptive message
|
||||
- [ ] Git history preserved (95+ commits)
|
||||
- [ ] VERSION_HISTORY.md documents the reset decision
|
||||
- [ ] No stray 3.0.0 references remain
|
||||
- [ ] Build succeeds (main.js created)
|
||||
- [ ] Working tree is clean
|
||||
|
||||
**Note:** Git tag creation (1.0.0) is NOT part of this plan. The tag will be created later when development is complete and the plugin is ready for actual public release.
|
||||
|
||||
## Post-Implementation Notes
|
||||
|
||||
After completing this plan, the version numbers are reset to 1.0.0 in preparation for public release:
|
||||
|
||||
**Current State After Plan:**
|
||||
- Version files (manifest.json, package.json, versions.json) all show 1.0.0
|
||||
- CHANGELOG.md rewritten for public consumption
|
||||
- VERSION_HISTORY.md documents the version reset decision
|
||||
- Git history preserved with all development commits
|
||||
- No git tag created yet (tag will be created when ready for actual release)
|
||||
|
||||
**When Ready for Actual Public Release:**
|
||||
|
||||
1. **Final Development**: Complete any remaining development work and commit changes
|
||||
|
||||
2. **Create Git Tag**: Create the 1.0.0 annotated tag:
|
||||
```bash
|
||||
git tag -a 1.0.0 -m "Release 1.0.0 - Initial Public Release"
|
||||
```
|
||||
|
||||
3. **GitHub Release**: Create a GitHub release from the 1.0.0 tag with:
|
||||
- Release title: "v1.0.0 - Initial Public Release"
|
||||
- Release notes: Use CHANGELOG.md content for 1.0.0
|
||||
- Attach files: manifest.json, main.js, styles.css
|
||||
|
||||
4. **Obsidian Plugin Directory**: Submit to Obsidian's community plugins with:
|
||||
- Plugin ID: obsidian-mcp-server
|
||||
- Version: 1.0.0
|
||||
- Links to GitHub repository and release
|
||||
|
||||
5. **Future Versions**: Use `npm version [major|minor|patch]` which will:
|
||||
- Update package.json version
|
||||
- Run version-bump.mjs to update manifest.json and versions.json
|
||||
- Create git commit and tag automatically
|
||||
- Then push tag to trigger release workflow
|
||||
|
||||
The git history demonstrates the quality and care taken during development, while the clean version numbering provides clarity for public users.
|
||||
@@ -1,355 +0,0 @@
|
||||
# Manual Integration Testing Checklist
|
||||
## Task 9: CORS Simplification and Mandatory Auth
|
||||
|
||||
**Date:** 2025-10-25
|
||||
**Implementation Plan:** docs/plans/2025-10-25-simplify-cors-mandatory-auth.md
|
||||
**Purpose:** Verify that all code changes work correctly in a real Obsidian environment
|
||||
|
||||
---
|
||||
|
||||
## Test 1: Fresh Install Test
|
||||
|
||||
### Prerequisites
|
||||
- Access to a test vault
|
||||
- Built plugin files (main.js, manifest.json, styles.css)
|
||||
|
||||
### Steps
|
||||
1. ✅ Remove plugin from test vault (if exists): `rm -rf .obsidian/plugins/obsidian-mcp-server/`
|
||||
2. ✅ Build plugin: `npm run build`
|
||||
3. ✅ Copy built plugin files to vault: `.obsidian/plugins/obsidian-mcp-server/`
|
||||
4. ✅ Enable plugin in Obsidian Settings → Community Plugins
|
||||
5. ✅ Open browser console (Ctrl+Shift+I)
|
||||
6. ✅ Verify log message: "Generating new API key..."
|
||||
7. ✅ Check `.obsidian/plugins/obsidian-mcp-server/data.json`:
|
||||
- Key should be present
|
||||
- Key should start with "encrypted:" (if encryption available)
|
||||
8. ✅ Verify server starts successfully (check plugin settings or console)
|
||||
|
||||
### Expected Results
|
||||
- [ ] API key auto-generated on first install
|
||||
- [ ] Key is encrypted in data.json
|
||||
- [ ] No CORS settings in data.json
|
||||
- [ ] Server starts without errors
|
||||
- [ ] No "enableCORS" or "allowedOrigins" fields in data.json
|
||||
|
||||
---
|
||||
|
||||
## Test 2: Migration Test
|
||||
|
||||
### Prerequisites
|
||||
- Test vault with plugin already installed
|
||||
- Access to data.json file
|
||||
|
||||
### Steps
|
||||
1. ✅ Stop Obsidian
|
||||
2. ✅ Manually edit `.obsidian/plugins/obsidian-mcp-server/data.json`:
|
||||
```json
|
||||
{
|
||||
"port": 3000,
|
||||
"enableCORS": true,
|
||||
"allowedOrigins": ["*"],
|
||||
"enableAuth": false,
|
||||
"apiKey": "old-plaintext-key",
|
||||
"autoStart": false
|
||||
}
|
||||
```
|
||||
3. ✅ Save file
|
||||
4. ✅ Start Obsidian
|
||||
5. ✅ Open browser console
|
||||
6. ✅ Verify log message: "Migrating legacy CORS settings..."
|
||||
7. ✅ Check updated data.json:
|
||||
- "enableCORS" should be removed
|
||||
- "allowedOrigins" should be removed
|
||||
- "enableAuth" should be true
|
||||
- "apiKey" should be encrypted
|
||||
8. ✅ Verify server still works
|
||||
|
||||
### Expected Results
|
||||
- [ ] Legacy CORS settings removed from data.json
|
||||
- [ ] enableAuth set to true
|
||||
- [ ] API key encrypted (if not already)
|
||||
- [ ] Other settings preserved (port, autoStart, notifications)
|
||||
- [ ] Server functionality not affected
|
||||
|
||||
---
|
||||
|
||||
## Test 3: API Key Encryption Test
|
||||
|
||||
### Prerequisites
|
||||
- Plugin installed and running
|
||||
- Access to plugin settings UI
|
||||
|
||||
### Steps
|
||||
1. ✅ Open plugin settings in Obsidian
|
||||
2. ✅ Locate "API Key Management" section
|
||||
3. ✅ Click "Copy Key" button
|
||||
4. ✅ Note the plaintext key (save to clipboard)
|
||||
5. ✅ Stop Obsidian completely
|
||||
6. ✅ Open `.obsidian/plugins/obsidian-mcp-server/data.json`
|
||||
7. ✅ Verify apiKey field starts with "encrypted:" (or is plaintext if encryption unavailable)
|
||||
8. ✅ Restart Obsidian
|
||||
9. ✅ Open plugin settings
|
||||
10. ✅ Verify API key display shows the same plaintext key from step 4
|
||||
11. ✅ Verify server starts and accepts the key
|
||||
|
||||
### Expected Results
|
||||
- [ ] API key displayed in plaintext in UI
|
||||
- [ ] API key encrypted in data.json file
|
||||
- [ ] Same key works after restart
|
||||
- [ ] "Copy Key" button copies plaintext key
|
||||
- [ ] Encryption status indicator shows correct state
|
||||
|
||||
---
|
||||
|
||||
## Test 4: API Key Regeneration Test
|
||||
|
||||
### Prerequisites
|
||||
- Plugin installed with existing API key
|
||||
- Access to plugin settings UI
|
||||
|
||||
### Steps
|
||||
1. ✅ Open plugin settings
|
||||
2. ✅ Copy current API key (note it down)
|
||||
3. ✅ Click "Regenerate Key" button
|
||||
4. ✅ Verify success notification
|
||||
5. ✅ Verify displayed key has changed
|
||||
6. ✅ Copy new key
|
||||
7. ✅ Verify old key ≠ new key
|
||||
8. ✅ Stop Obsidian
|
||||
9. ✅ Check data.json - verify encrypted key has changed
|
||||
10. ✅ Restart Obsidian
|
||||
11. ✅ Verify new key is displayed correctly
|
||||
12. ✅ Verify server restart prompt if server was running
|
||||
|
||||
### Expected Results
|
||||
- [ ] Regenerate button generates a new key
|
||||
- [ ] New key is different from old key
|
||||
- [ ] New key is properly encrypted on disk
|
||||
- [ ] New key persists across restart
|
||||
- [ ] Server restart prompted if needed
|
||||
|
||||
---
|
||||
|
||||
## Test 5: Authentication Test
|
||||
|
||||
### Prerequisites
|
||||
- Plugin installed and server running
|
||||
- curl or similar HTTP client
|
||||
|
||||
### Steps
|
||||
1. ✅ Start MCP server from plugin settings
|
||||
2. ✅ Copy API key from settings UI
|
||||
3. ✅ Try request WITHOUT auth:
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:3000/mcp \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","method":"ping","id":1}'
|
||||
```
|
||||
4. ✅ Verify response is 401 Unauthorized
|
||||
5. ✅ Try request WITH correct Bearer token:
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:3000/mcp \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_API_KEY_HERE" \
|
||||
-d '{"jsonrpc":"2.0","method":"ping","id":1}'
|
||||
```
|
||||
6. ✅ Verify response is 200 OK with pong result
|
||||
7. ✅ Try request with WRONG Bearer token:
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:3000/mcp \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer wrong-token" \
|
||||
-d '{"jsonrpc":"2.0","method":"ping","id":1}'
|
||||
```
|
||||
8. ✅ Verify response is 401 Unauthorized
|
||||
|
||||
### Expected Results
|
||||
- [ ] Requests without auth rejected (401)
|
||||
- [ ] Requests with invalid token rejected (401)
|
||||
- [ ] Requests with valid token accepted (200)
|
||||
- [ ] No way to bypass authentication
|
||||
|
||||
---
|
||||
|
||||
## Test 6: CORS Test (Optional - Requires Web Client)
|
||||
|
||||
### Prerequisites
|
||||
- MCP server running
|
||||
- Simple HTML file or local web server
|
||||
|
||||
### Steps
|
||||
1. ✅ Create test HTML file:
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<body>
|
||||
<button onclick="testCORS()">Test CORS</button>
|
||||
<div id="result"></div>
|
||||
<script>
|
||||
async function testCORS() {
|
||||
const apiKey = 'YOUR_API_KEY_HERE';
|
||||
try {
|
||||
const response = await fetch('http://localhost:3000/mcp', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${apiKey}`
|
||||
},
|
||||
body: JSON.stringify({"jsonrpc":"2.0","method":"ping","id":1})
|
||||
});
|
||||
document.getElementById('result').innerText =
|
||||
`Success: ${response.status} ${await response.text()}`;
|
||||
} catch(e) {
|
||||
document.getElementById('result').innerText = `Error: ${e.message}`;
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
2. ✅ Serve HTML from localhost:8080: `python3 -m http.server 8080`
|
||||
3. ✅ Open http://localhost:8080 in browser
|
||||
4. ✅ Update apiKey in HTML with actual key
|
||||
5. ✅ Click "Test CORS" button
|
||||
6. ✅ Verify request succeeds (CORS allowed from localhost:8080)
|
||||
7. ✅ Try accessing from non-localhost origin (if possible)
|
||||
8. ✅ Verify CORS blocks non-localhost origins
|
||||
|
||||
### Expected Results
|
||||
- [ ] Requests from localhost origins succeed
|
||||
- [ ] Requests from 127.0.0.1 origins succeed
|
||||
- [ ] Requests from non-localhost origins blocked by CORS
|
||||
- [ ] HTTPS localhost origins also work
|
||||
|
||||
---
|
||||
|
||||
## Test 7: Settings UI Verification
|
||||
|
||||
### Prerequisites
|
||||
- Plugin installed
|
||||
- Access to plugin settings
|
||||
|
||||
### Steps
|
||||
1. ✅ Open Obsidian Settings → Community Plugins → Obsidian MCP Server
|
||||
2. ✅ Verify NO "Enable CORS" toggle is visible
|
||||
3. ✅ Verify NO "Allowed origins" text input is visible
|
||||
4. ✅ Verify NO "Enable authentication" toggle is visible
|
||||
5. ✅ Verify "Authentication" heading is present
|
||||
6. ✅ Verify description text mentions "mandatory" and "encrypted"
|
||||
7. ✅ Verify encryption status indicator is displayed:
|
||||
- 🔒 "Encryption: Available" OR
|
||||
- ⚠️ "Encryption: Unavailable"
|
||||
8. ✅ Verify "API Key Management" section is always visible
|
||||
9. ✅ Verify API key is displayed in monospace font
|
||||
10. ✅ Verify "Copy Key" and "Regenerate Key" buttons are visible
|
||||
11. ✅ Verify "MCP Client Configuration" section always includes Authorization header
|
||||
|
||||
### Expected Results
|
||||
- [ ] No CORS configuration options visible
|
||||
- [ ] No authentication toggle (always enabled)
|
||||
- [ ] Clear messaging about mandatory auth
|
||||
- [ ] Encryption status displayed
|
||||
- [ ] API key section always visible
|
||||
- [ ] Configuration snippet includes auth header
|
||||
|
||||
---
|
||||
|
||||
## Test 8: No Regressions Test
|
||||
|
||||
### Prerequisites
|
||||
- Plugin installed and server running
|
||||
- Test vault with notes
|
||||
|
||||
### Steps
|
||||
1. ✅ Test all MCP tools work:
|
||||
- `read_note` - Read an existing note
|
||||
- `create_note` - Create a new note
|
||||
- `update_note` - Modify a note
|
||||
- `delete_note` - Delete a note
|
||||
- `list` - List notes in vault
|
||||
- `search` - Search for text
|
||||
- Other tools as applicable
|
||||
2. ✅ Test notifications (if enabled):
|
||||
- Enable notifications in settings
|
||||
- Call an MCP tool
|
||||
- Verify notification appears in Obsidian
|
||||
3. ✅ Test server controls:
|
||||
- Stop server
|
||||
- Start server
|
||||
- Restart server
|
||||
4. ✅ Test settings save/load:
|
||||
- Change port number
|
||||
- Toggle autoStart
|
||||
- Restart Obsidian
|
||||
- Verify settings preserved
|
||||
|
||||
### Expected Results
|
||||
- [ ] All MCP tools function correctly
|
||||
- [ ] No errors in console related to CORS/auth changes
|
||||
- [ ] Notifications work as before
|
||||
- [ ] Server controls work correctly
|
||||
- [ ] Settings persist across restarts
|
||||
- [ ] No functionality regressions
|
||||
|
||||
---
|
||||
|
||||
## Test 9: Error Handling Test
|
||||
|
||||
### Prerequisites
|
||||
- Plugin installed
|
||||
|
||||
### Steps
|
||||
1. ✅ Test empty API key scenario:
|
||||
- Stop Obsidian
|
||||
- Edit data.json to set `apiKey: ""`
|
||||
- Start Obsidian
|
||||
- Verify new key is auto-generated
|
||||
2. ✅ Test decryption failure:
|
||||
- Stop Obsidian
|
||||
- Edit data.json to set `apiKey: "encrypted:invalid-base64!!!"`
|
||||
- Start Obsidian
|
||||
- Verify error notice displayed
|
||||
- Verify user prompted to regenerate key
|
||||
3. ✅ Test server start with no API key:
|
||||
- Stop Obsidian
|
||||
- Edit data.json to remove apiKey field entirely
|
||||
- Start Obsidian
|
||||
- Verify key auto-generated
|
||||
- Verify server can start
|
||||
|
||||
### Expected Results
|
||||
- [ ] Empty API key triggers auto-generation
|
||||
- [ ] Invalid encrypted key shows error notice
|
||||
- [ ] User can recover from decryption failures
|
||||
- [ ] Server doesn't start with invalid key state
|
||||
|
||||
---
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
After completing all tests above, verify:
|
||||
|
||||
- [ ] Fresh install generates and encrypts API key
|
||||
- [ ] Legacy CORS settings are migrated correctly
|
||||
- [ ] API keys are encrypted at rest
|
||||
- [ ] API key regeneration works
|
||||
- [ ] Authentication is mandatory and enforced
|
||||
- [ ] CORS allows localhost origins only
|
||||
- [ ] Settings UI shows correct options (no CORS, no auth toggle)
|
||||
- [ ] Encryption status is displayed
|
||||
- [ ] All existing MCP tools work correctly
|
||||
- [ ] No console errors related to changes
|
||||
- [ ] Error scenarios handled gracefully
|
||||
|
||||
---
|
||||
|
||||
## Test Results
|
||||
|
||||
**Tester:** [Name]
|
||||
**Date:** [Date]
|
||||
**Obsidian Version:** [Version]
|
||||
**Plugin Version:** [Version]
|
||||
**Platform:** [Windows/macOS/Linux]
|
||||
|
||||
**Overall Status:** [ ] PASS / [ ] FAIL
|
||||
**Notes:**
|
||||
@@ -1,97 +0,0 @@
|
||||
# Manual Testing Checklist - Task 5: Settings UI Updates
|
||||
|
||||
**Date:** 2025-10-25
|
||||
**Task:** Update Settings UI to reflect mandatory authentication and encryption
|
||||
|
||||
## Changes Made
|
||||
|
||||
### Step 2: Updated Authentication Section
|
||||
- ✅ Removed "Enable authentication" toggle
|
||||
- ✅ Added "Authentication (Always Enabled)" heading (h3)
|
||||
- ✅ Added description: "Authentication is required for all requests. Your API key is encrypted and stored securely using your system's credential storage."
|
||||
- ✅ Added encryption status indicator showing:
|
||||
- "🔒 Encryption: Available (using system keychain)" when available
|
||||
- "⚠️ Encryption: Unavailable (API key stored in plaintext)" when not available
|
||||
|
||||
### Step 3: Updated API Key Display
|
||||
- ✅ Changed condition from `if (this.plugin.settings.enableAuth)` to always show
|
||||
- ✅ API key section now always visible since auth is mandatory
|
||||
|
||||
### Step 4: Updated MCP Client Configuration
|
||||
- ✅ Changed from conditional auth headers to always including them
|
||||
- ✅ Authorization header always included in generated config
|
||||
- ✅ Fallback text "YOUR_API_KEY_HERE" if apiKey is missing
|
||||
|
||||
### Step 5: Added Encryption Utils Import
|
||||
- ✅ Added import for `isEncryptionAvailable` from './utils/encryption-utils'
|
||||
|
||||
### Additional Fixes
|
||||
- ✅ Fixed variable name collision: renamed `buttonContainer` to `apiKeyButtonContainer` in API key section
|
||||
|
||||
## What to Verify Manually (When Available in Obsidian)
|
||||
|
||||
Since this is a settings UI change, manual verification would include:
|
||||
|
||||
### Visual Verification
|
||||
1. ✅ **CORS Settings Removed** - No "Enable CORS" toggle visible
|
||||
2. ✅ **No "Allowed Origins" field** - Field should not be present
|
||||
3. ✅ **Authentication Section**:
|
||||
- Should show "Authentication" heading
|
||||
- Should display description about mandatory authentication
|
||||
- Should show encryption status (🔒 or ⚠️ depending on platform)
|
||||
4. ✅ **API Key Section**:
|
||||
- Should always be visible (not conditional)
|
||||
- Should show "Copy Key" and "Regenerate Key" buttons
|
||||
- Should display the API key in monospace font
|
||||
5. ✅ **MCP Client Configuration**:
|
||||
- Should always include Authorization header
|
||||
- Config JSON should show Bearer token
|
||||
|
||||
### Functional Verification
|
||||
1. ✅ **Copy Key Button** - Should copy API key to clipboard
|
||||
2. ✅ **Regenerate Key Button** - Should generate new key and refresh display
|
||||
3. ✅ **Copy Configuration Button** - Should copy full JSON config with auth header
|
||||
4. ✅ **Encryption Status** - Should reflect actual platform capability
|
||||
|
||||
## Test Results
|
||||
|
||||
### Build Status
|
||||
- ✅ TypeScript compilation: **PASS**
|
||||
- ✅ Build successful: **PASS**
|
||||
|
||||
### Test Suite
|
||||
- ✅ All 550 tests passed
|
||||
- ✅ No new test failures
|
||||
- ✅ Encryption utils tests: **PASS**
|
||||
- ✅ Settings types tests: **PASS**
|
||||
- ✅ Main migration tests: **PASS**
|
||||
|
||||
## Files Changed
|
||||
- `/home/bballou/obsidian-mcp-plugin/src/settings.ts`
|
||||
|
||||
## Code Changes Summary
|
||||
|
||||
1. **Import added**: `isEncryptionAvailable` from encryption-utils
|
||||
2. **Lines 60-82**: Replaced authentication toggle with always-enabled section
|
||||
3. **Lines 81-127**: Removed conditional, API key section always visible
|
||||
4. **Lines 142-152**: Config always includes Authorization header
|
||||
5. **Line 92**: Renamed variable to avoid collision
|
||||
|
||||
## Observations
|
||||
|
||||
- All changes align with Task 5 specifications
|
||||
- No regression in existing functionality
|
||||
- Settings UI now correctly reflects mandatory authentication model
|
||||
- Encryption status provides user transparency about security
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
1. **Variable Name Collision**:
|
||||
- Issue: Two `buttonContainer` variables in same scope
|
||||
- Resolution: Renamed to `apiKeyButtonContainer` in API key section
|
||||
- Impact: No functional change, compiler error resolved
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Commit changes as per Step 7
|
||||
- Integration testing in Obsidian (when available)
|
||||
Reference in New Issue
Block a user