ac-storage 0.14.1 → 0.15.1

package/TEST_COMMENTS_REVIEW.md

@@ -0,0 +1,283 @@
+# 테스트 주석 검토 보고서
+
+## 검토 일시
+2025-12-11
+
+---
+
+## 주석 품질 분류
+
+### ✅ 좋은 주석 패턴
+
+#### 1. 파일 레벨 문서화
+```typescript
+// electron-ipc-simulation.test.ts
+/**
+ * Electron IPC 환경에서의 JSONAccessor 데이터 손실 시뮬레이션
+ *
+ * Electron 환경 특성:
+ * 1. Renderer Process -> IPC -> Main Process -> 파일 시스템
+ * 2. 여러 Renderer (BrowserWindow)가 동시에 IPC 요청 가능
+ * ...
+ */
+```
+**평가**: ✅ 훌륭함 - 테스트 파일의 목적과 컨텍스트를 명확히 설명
+
+---
+
+#### 2. 복잡한 로직 설명
+```typescript
+// invalid-operation-order.test.ts
+/**
+ * 잘못된 작업 순서 검증 테스트
+ * 
+ * 이 테스트는 멱등성(같은 작업 반복)이 아닌,
+ * 잘못된 순서로 작업을 수행했을 때의 동작을 검증합니다.
+ */
+```
+**평가**: ✅ 좋음 - 테스트의 목적과 범위를 명확히 구분
+
+---
+
+#### 3. 단계별 주석
+```typescript
+// storage-fs.test.ts
+// 0. 초기 상태
+verifyState({ config: false, data: false }, 0);
+
+// 1. 저장소 등록
+storage.register({ ... });
+
+// 2. JSONAccessor 접근
+await storage.accessAsJSON('config.json');
+```
+**평가**: ✅ 훌륭함 - 복잡한 시퀀스를 단계별로 명확히 설명
+
+---
+
+### ⚠️ 개선 필요한 주석
+
+#### 1. 불필요한 주석 (자명한 내용)
+```typescript
+// idempotent-operations.test.ts
+// Should return the same instance
+expect(accessor1).toBe(accessor2);
+
+// First release should work
+await storage.release('test.json');
+
+// Second release should not throw
+await expect(storage.release('test.json')).resolves.not.toThrow();
+```
+**문제**: 코드만 봐도 알 수 있는 내용을 반복
+**개선안**: 제거하거나 "왜"를 설명
+```typescript
+// Idempotent: Multiple access returns same instance
+expect(accessor1).toBe(accessor2);
+```
+
+---
+
+#### 2. 모호한 주석
+```typescript
+// electron-ipc-simulation.test.ts
+// IPC 통신 지연 시뮬레이션 (0-5ms)
+await new Promise(resolve => setTimeout(resolve, Math.random() * 5));
+```
+**문제**: 왜 0-5ms인지, 왜 지연이 필요한지 설명 부족
+**개선안**:
+```typescript
+// Simulate real IPC latency (0-5ms) to test race conditions
+await new Promise(resolve => setTimeout(resolve, Math.random() * 5));
+```
+
+---
+
+#### 3. 중복 주석
+```typescript
+// access-separation.test.ts
+// ===== CREATE Tests =====
+describe('create()', () => {
+
+// ===== OPEN Tests =====
+describe('open()', () => {
+
+// ===== ACCESS Tests (기존 동작) =====
+describe('access()', () => {
+```
+**문제**: describe 이름이 이미 명확한데 주석이 중복
+**개선안**: 제거 또는 추가 정보 제공
+```typescript
+// CREATE: File must not exist
+describe('create()', () => {
+
+// OPEN: File must exist
+describe('open()', () => {
+```
+
+---
+
+#### 4. 잘못된/오래된 주석
+```typescript
+// electron-ipc-simulation.test.ts (라인 340-346)
+// unsaved 데이터는 commit되지 않아 손실... 아니,
+// 단일 ACStorage이므로 메모리에 남아있음
+// release() 전에는 메모리 데이터 유지
+// 하지만 앱이 완전히 종료되면 손실됨
+// 이 테스트에서는 release 전 commit이 없으므로
+// release가 commit을 포함하므로 데이터 유지
+```
+**문제**: 
+- "... 아니,"로 시작하는 자기 수정
+- 여러 조건이 혼재되어 혼란스러움
+- 결론이 불명확
+
+**개선안**:
+```typescript
+// release() automatically commits, so data is persisted even without explicit commit
+// Data loss only occurs if process crashes before release()
+```
+
+---
+
+### ❌ 제거해야 할 주석
+
+#### 1. 주석 처리된 설명
+```typescript
+// electron-ipc-simulation.test.ts (라인 393)
+// (실제로는 권한 문제, 디스크 풀 등)
+```
+**문제**: 괄호 안 설명은 코드로 구현하거나 테스트 설명에 포함
+**개선안**: 테스트 이름에 반영하거나 describe에 문서화
+
+---
+
+#### 2. TODO 스타일 주석
+```typescript
+// 실제로는 process.exit() 또는 crash
+```
+**문제**: "실제로는"은 테스트가 불완전함을 암시
+**개선안**: 제거하거나 명확한 문서화
+
+---
+
+## 파일별 주석 개선 권장사항
+
+### 1. idempotent-operations.test.ts
+**현재**: 자명한 단계 주석 남발
+```typescript
+// First release should work
+// Second release should not throw
+// Third release should also not throw
+```
+
+**개선**:
+```typescript
+test('duplicate release calls', async () => {
+    // Idempotent: Multiple release calls should be safe
+    await storage.release('test.json');
+    await expect(storage.release('test.json')).resolves.not.toThrow();
+    await expect(storage.release('test.json')).resolves.not.toThrow();
+});
+```
+
+---
+
+### 2. electron-ipc-simulation.test.ts
+**현재**: 일부 주석이 너무 장황하거나 혼란스러움
+
+**개선 필요**:
+- 라인 340-346: 자기 수정 주석 정리
+- 라인 393: 괄호 설명 제거
+- IPC 핸들러 주석 통일
+
+---
+
+### 3. storage-fs.test.ts
+**현재**: 단계별 주석이 좋음 ✅
+**추가 제안**: 각 단계의 목적 추가
+```typescript
+// Step 1: Register storage (setup)
+// Step 2: Access JSON file (triggers creation)
+```
+
+---
+
+### 4. invalid-operation-order.test.ts
+**현재**: 파일 레벨 문서화 좋음 ✅
+**개선**: 각 섹션에 왜 no-op인지 설명 추가
+```typescript
+describe('Operations after drop', () => {
+    // After drop: accessor removed from memory and file deleted
+    // All operations become no-op as there's nothing to operate on
+});
+```
+
+---
+
+## 주석 작성 가이드라인 제안
+
+### DO ✅
+1. **파일 레벨**: 테스트 파일의 목적과 컨텍스트
+2. **복잡한 로직**: 왜(Why) 이렇게 하는지
+3. **비명확한 동작**: 예상치 못한 동작 설명
+4. **단계별 시퀀스**: 복잡한 테스트 플로우
+
+### DON'T ❌
+1. **자명한 코드**: 코드만 봐도 아는 것
+2. **중복 설명**: describe/test 이름과 같은 내용
+3. **주석 처리 설명**: (괄호)로 추가 설명
+4. **불완전한 설명**: "... 아니," 같은 자기 수정
+
+### 좋은 주석 예시
+```typescript
+// GOOD: Explains WHY
+test('concurrent access safety', async () => {
+    // json-accessor v0.7 uses write lock to serialize concurrent commits
+    // This test verifies no data corruption occurs
+});
+
+// BAD: Explains WHAT (obvious from code)
+test('concurrent access safety', async () => {
+    // Call commit 100 times
+    for (let i = 0; i < 100; i++) {
+        await commit();
+    }
+});
+```
+
+---
+
+## 우선순위 개선 항목
+
+### High Priority (즉시 수정)
+1. ❌ electron-ipc-simulation.test.ts 라인 340-346: 혼란스러운 주석 정리
+2. ❌ idempotent-operations.test.ts: 자명한 주석 제거
+
+### Medium Priority (검토 후 수정)
+3. ⚠️ 모든 파일: "// IPC:", "// First", "// Second" 등 반복 패턴 통일
+4. ⚠️ access-separation.test.ts: "=====" 스타일 주석 제거 또는 개선
+
+### Low Priority (선택적)
+5. 📝 모든 describe에 간단한 문서화 주석 추가 고려
+6. 📝 테스트 이름이 불명확한 경우 주석으로 보완
+
+---
+
+## 결론
+
+### 현재 상태
+- ✅ 파일 레벨 문서화: 좋음
+- ⚠️ 코드 레벨 주석: 개선 필요
+- ❌ 일부 혼란스럽거나 불필요한 주석 존재
+
+### 개선 방향
+1. 자명한 주석 제거
+2. "왜"에 집중하는 주석
+3. 혼란스러운 주석 정리
+4. 주석 스타일 통일
+
+### 예상 효과
+- 코드 가독성 향상
+- 유지보수 용이
+- 새로운 개발자의 이해도 향상

package/TEST_REFACTORING_REPORT.md

@@ -0,0 +1,209 @@
+# 테스트 리팩토링 보고서 - 잘못된 작업 순서 분리
+
+## 작업 일시
+2025-12-11
+
+## 작업 내용
+멱등성 테스트에서 "잘못된 작업 순서" 테스트를 분리하여 별도 파일로 생성
+
+---
+
+## 문제점 분석
+
+### 멱등성(Idempotent)의 정의
+**올바른 정의**: 같은 작업을 여러 번 수행해도 결과가 동일
+- `commit → commit → commit` ✅
+- `release → release → release` ✅ 
+- `drop → drop → drop` ✅
+
+**잘못된 해석**: 다른 작업 후에도 안전
+- `drop → commit` ❌ (순서 오류)
+- `release → commit` ❌ (의미 불명확)
+- `drop → release` ❌ (무의미한 작업)
+
+### 기존 파일의 문제
+`idempotent-operations.test.ts`에 두 가지 다른 목적의 테스트가 혼재:
+1. 진짜 멱등성 테스트 (같은 작업 반복)
+2. 잘못된 작업 순서 테스트 (다른 작업 후 실행)
+
+---
+
+## 제거된 테스트 (idempotent-operations.test.ts에서)
+
+### 1. `release then drop` (라인 117-131)
+```typescript
+test('release then drop', async () => {
+    await storage.release('test.json');
+    
+    // Re-access and drop (release removes from memory, need to access again to drop)
+    await storage.accessAsJSON('test.json');
+    await storage.drop('test.json');
+});
+```
+**제거 이유**: 
+- 주석이 오해의 소지 ("need to access again"은 정상 동작)
+- 멱등성 테스트가 아님
+
+---
+
+### 2. `mixed scenario: file1 release→drop, file2 drop→release` (라인 247-271)
+```typescript
+test('mixed scenario: file1 release→drop, file2 drop→release', async () => {
+    // File2: drop then try release (should not throw on non-existent)
+    await storage.drop('file2.json');
+    await expect(storage.release('file2.json')).resolves.not.toThrow();
+});
+```
+**제거 이유**: 
+- drop 후 release는 무의미한 작업
+- 멱등성 테스트가 아님
+
+---
+
+### 3. `commit → release → commit cycle` (라인 293-308)
+```typescript
+test('commit → release → commit cycle', async () => {
+    await storage.commit('test.json');
+    await storage.release('test.json');
+    
+    // Try to commit released file (should not throw)
+    await expect(storage.commit('test.json')).resolves.not.toThrow();
+});
+```
+**제거 이유**: 
+- release 후 commit의 동작이 불명확
+- 멱등성 테스트가 아님
+
+---
+
+### 4. `commit after drop` (라인 310-322)
+```typescript
+test('commit after drop', async () => {
+    await storage.drop('test.json');
+    
+    // Commit after drop (should not throw, but file is gone)
+    await expect(storage.commit('test.json')).resolves.not.toThrow();
+});
+```
+**제거 이유**: 
+- drop 후 commit은 무의미한 작업
+- 멱등성 테스트가 아님
+
+---
+
+## 새로운 테스트 파일 생성
+
+### `invalid-operation-order.test.ts`
+
+**목적**: 잘못된 작업 순서의 동작을 명확히 검증
+
+#### 테스트 구조:
+
+##### 1. Operations after drop
+- `commit after drop should be no-op`
+- `release after drop should be no-op`
+- `multiple operations after drop should all be no-op`
+
+**검증 내용**: drop 후 모든 작업은 no-op이며 에러를 던지지 않음
+
+---
+
+##### 2. Operations after release
+- `commit after release should be no-op`
+- `multiple commits after release should be no-op`
+
+**검증 내용**: release 후 commit은 no-op (메모리에 accessor 없음)
+
+---
+
+##### 3. Complex invalid sequences
+- `commit → drop → commit → release sequence`
+- `release → commit → release → drop sequence`
+
+**검증 내용**: 복잡한 잘못된 순서에서도 안전하게 동작
+
+---
+
+##### 4. Documentation: Correct patterns
+- `correct pattern: access → modify → commit → release`
+- `correct pattern: access → modify → drop`
+- `correct pattern: release → access → modify → drop`
+
+**목적**: 올바른 사용 패턴을 문서화
+
+---
+
+## 결과
+
+### 테스트 통계:
+- **테스트 파일**: 15개 → 16개 (+1)
+- **총 테스트**: 97개 → 103개 (+6)
+- **통과율**: 100% → 100% ✅
+
+### idempotent-operations.test.ts 변경:
+- **제거된 테스트**: 4개
+- **남은 테스트**: 순수 멱등성 테스트만 유지
+  - duplicate access
+  - duplicate release
+  - duplicate drop
+  - duplicate commit
+  - duplicate releaseDir/dropDir/releaseAll/dropAll
+
+### invalid-operation-order.test.ts 신규:
+- **추가된 테스트**: 10개
+- **목적**: 잘못된 작업 순서의 안전성 검증
+- **구조**: 명확한 카테고리 분리
+  - Operations after drop (3개)
+  - Operations after release (2개)
+  - Complex invalid sequences (2개)
+  - Documentation: Correct patterns (3개)
+
+---
+
+## 개선 효과
+
+### 1. 명확성 향상
+- 멱등성 테스트와 잘못된 순서 테스트가 명확히 분리
+- 각 테스트의 목적이 파일명으로 명확히 표현됨
+
+### 2. 유지보수성 향상
+- `idempotent-operations.test.ts`: 순수 멱등성만 검증
+- `invalid-operation-order.test.ts`: 잘못된 순서 안전성 검증
+- 각 파일의 책임이 명확함
+
+### 3. 문서화 기능 추가
+- "Correct patterns" 섹션으로 올바른 사용법 문서화
+- 새로운 개발자가 올바른 패턴을 학습할 수 있음
+
+### 4. 테스트 커버리지 향상
+- 기존: 잘못된 순서를 일부만 테스트
+- 현재: 다양한 잘못된 순서 조합을 체계적으로 테스트
+
+---
+
+## 향후 고려사항
+
+### 1. 에러 정책 검토
+현재 잘못된 순서(drop 후 commit 등)에서 에러를 던지지 않고 no-op으로 처리.
+이것이 의도된 동작인지 확인 필요:
+- **Option A**: no-op (현재 동작) - 관대한 정책
+- **Option B**: 에러 발생 - 엄격한 정책
+
+### 2. 로깅 추가 고려
+잘못된 순서 작업 시 경고 로그 추가 고려:
+- 개발자가 실수를 인지할 수 있음
+- 디버깅에 도움
+
+### 3. TypeScript 타입 강화
+잘못된 순서를 타입 레벨에서 방지할 수 있는지 검토
+
+---
+
+## 결론
+
+멱등성 테스트에서 잘못된 작업 순서 테스트를 분리하여:
+1. ✅ 테스트 목적 명확화
+2. ✅ 유지보수성 향상
+3. ✅ 문서화 기능 추가
+4. ✅ 커버리지 향상
+5. ✅ 100% 테스트 통과율 유지

package/TODO.md

@@ -0,0 +1,167 @@
+# TODO: Release API Implementation
+
+## Status: Phase 2 Complete ✅
+
+**Last Updated**: 2025-12-07
+
+---
+
+## Completed Tasks
+
+### ✅ Phase 1: Refactoring `release` → `destroy` (2025-12-07)
+
+Internal naming refactoring to prepare for new `release()` API.
+
+**Changes Made:**
+- Renamed `onRelease` → `onDestroy` (event callback)
+- Renamed `'release'` → `'destroy'` (public event type)
+- Renamed internal methods: `.release()` → `.destroy()`, `.releaseDir()` → `.destroyDir()`
+- Updated all test files to use `'destroy'` event
+
+**Verification:**
+- ✅ All 38 tests passing
+- ✅ Build successful
+- ✅ No TypeScript errors
+
+**Files Modified (8):**
+- `src/features/StorageAccessControl/types.ts`
+- `src/features/storage/types.ts`
+- `src/features/StorageAccessControl/StorageAccessControl.ts`
+- `src/features/StorageAccessControl/StorageAccessControl.test.ts`
+- `src/features/storage/ACStorage.ts`
+- `src/features/storage/MemACStorage.ts`
+- `src/features/storage/test/ac-drop.test.ts`
+- `README.md`
+
+---
+
+### ✅ Phase 2: Implement `release()` API (2025-12-07)
+
+**Goal**: Add new `release()` methods that commit changes and unload from memory (without deleting files).
+
+#### 2.1 Core Implementation ✅
+
+**Files Modified:**
+- `src/features/storage/types.ts` - Added method signatures to interfaces
+- `src/features/storage/ACStorage.ts` - Implemented 3 public methods + 1 private helper
+- `src/features/storage/MemACStorage.ts` - Implemented for in-memory storage
+- `src/features/storage/ACSubStorage.ts` - Implemented proxy methods
+
+**Methods Implemented:**
+- `async release(identifier: string)` - Save and unload single file
+- `async releaseDir(identifier: string)` - Save and unload directory
+- `async releaseAll()` - Save and unload all files
+- `async #unloadFromMemory(identifier)` - Private helper for memory cleanup
+
+**Key Implementation Details:**
+- `release()` commits changes before unloading (unlike `drop()`)
+- Does NOT call `accessor.drop()` - just removes from memory
+- Does NOT trigger `'destroy'` event
+- Handles nested dependencies recursively
+
+#### 2.2 Testing ✅
+
+**File Created:**
+- `src/features/storage/test/release.test.ts`
+
+**Test Results:**
+- ✅ All 12 release tests passing
+- ✅ Total: 50 tests passing (38 existing + 12 new)
+
+**Test Coverage:**
+1. ✅ Basic release - file saved and unloaded
+2. ✅ File not deleted - verify file persists on disk
+3. ✅ Changes committed - uncommitted changes saved
+4. ✅ Re-access after release - file can be loaded again
+5. ✅ Directory release - all files in dir released
+6. ✅ Release all - entire storage released
+7. ✅ Root directory error - proper error message
+8. ✅ Drop vs release comparison - behavior difference
+9. ✅ Event handling - no destroy event on release
+10. ✅ Nested dependencies - recursive release
+11. ✅ Empty accessor - no error on non-existent file
+12. ✅ Partial operations - mixed release states
+
+#### 2.3 Documentation ✅
+
+**Files Updated:**
+- `README.md` - Added release methods to API docs
+- Added operations comparison table
+- Updated event listener documentation (`'release'` → `'destroy'`)
+- Added usage examples
+
+**Documentation Includes:**
+- Method signatures and descriptions
+- Comparison table: `commit()` vs `release()` vs `drop()`
+- Code examples demonstrating the differences
+
+#### 2.4 Build Verification ✅
+
+- ✅ Build successful with no errors
+- ✅ TypeScript compilation clean
+- ✅ All type definitions properly exported
+
+---
+
+## Remaining Tasks
+
+### Phase 3: Future Enhancements (Optional)
+
+1. **Add `'release'` Event**
+   - Consider adding a new event type for when files are released
+   - `storage.addListener('release', (identifier) => { ... })`
+   - Useful for tracking memory management
+
+2. **Soft vs Hard Release**
+   - `release()`: soft release, can be re-accessed
+   - Consider if we need a "hard release" that prevents re-access
+
+3. **Auto-release Strategy**
+   - Add option to auto-release files after N accesses
+   - Memory management for long-running processes
+
+4. **Release Statistics**
+   - Track which files are in memory
+   - Add `getLoadedFiles()` method
+
+5. **Lazy Loading**
+   - Option to not auto-load on access
+   - Explicit `load()` method
+
+---
+
+## Questions to Resolve
+
+- [ ] Should `release()` trigger a new event, or remain silent?
+- [ ] Should there be a way to "lock" files to prevent release?
+- [ ] Do we need a `releaseCache()` method to clear the `.acstorage` file?
+- [ ] Should `releaseAll()` also clear the cache file?
+
+---
+
+## Version Planning
+
+**Target Version**: v0.15.0
+
+**Breaking Changes**:
+- Event name: `'release'` → `'destroy'`
+
+**New Features**:
+- `release(identifier)` - Save and unload file
+- `releaseDir(identifier)` - Save and unload directory
+- `releaseAll()` - Save and unload all files
+
+**Changelog Preview**:
+```markdown
+## [0.15.0] - 2025-12-07
+
+### Breaking Changes
+- Renamed event `'release'` to `'destroy'` to avoid confusion with new release API
+
+### Added
+- `release(identifier)`: Save changes and unload file from memory
+- `releaseDir(identifier)`: Save and unload directory from memory
+- `releaseAll()`: Save and unload all files from memory
+
+### Changed
+- Internal refactoring: all `onRelease` → `onDestroy` naming

package/_TESTPATH/ac-drop/.acstorage

@@ -0,0 +1,8 @@
+{
+    "item1": "text",
+    "layer1": "directory",
+    "layer1:item2": "text",
+    "layer1:layer2": "directory",
+    "layer1:layer2:item3": "text",
+    "layer1:layer2:item4": "text"
+}

package/_TESTPATH/access-separation-test/.acstorage

@@ -0,0 +1,5 @@
+{
+    "file3.bin": "binary",
+    "file1.json": "json",
+    "file2.txt": "text"
+}

package/_TESTPATH/data-corruption-investigation/data/config.json

@@ -0,0 +1,4 @@
+{
+    "key1": "value1",
+    "key2": "value2"
+}

package/_TESTPATH/idempotent-test/.acstorage

@@ -0,0 +1,4 @@
+{
+    "file1.json": "json",
+    "file2.json": "json"
+}

package/_TESTPATH/idempotent-test/test.json

@@ -0,0 +1,4 @@
+{
+    "value": 2,
+    "data": "test"
+}

package/_TESTPATH/invalid-operation-order-test/.acstorage

@@ -0,0 +1,3 @@
+{
+    "test.json": "json"
+}

package/_TESTPATH/release-test/.acstorage

@@ -0,0 +1,6 @@
+{
+    "dir": "directory",
+    "dir:file4.json": "json",
+    "dir:file5.txt": "text",
+    "file2.txt": "text"
+}