ac-storage 0.15.0 → 0.16.0

package/INCONSISTENT_TESTS_REPORT.md

@@ -1,165 +0,0 @@
-# 버그 수정 후 의도와 맞지 않는 테스트 보고서
-
-## 분석 기준
-json-accessor v0.7에서 drop된 accessor는 더 이상 사용할 수 없도록 변경되었습니다.
-drop 후 commit/release 등의 작업은 실제로는 에러를 발생시켜야 하지만, 
-일부 테스트는 "에러가 발생하지 않음"을 검증하고 있어 의도와 맞지 않습니다.
-
----
-
-## 1. idempotent-operations.test.ts
-
-### 문제 있는 테스트:
-
-#### Test 1: `release then drop` (라인 117-131)
-```typescript
-test('release then drop', async () => {
-    // Release first (saves file)
-    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');
-    expect(fs.existsSync(filePath)).toBeFalsy();
-});
-```
-**문제**: 주석에 "release removes from memory, need to access again to drop"라고 명시
-- 이는 버그가 아니라 정상 동작
-- release 후 drop하려면 다시 access 해야 함
-- 테스트가 이를 "회피 방법"처럼 설명하고 있음
-
-**판단**: ⚠️ 오해의 소지 - 주석 수정 필요
-
----
-
-#### Test 2: `commit after drop` (라인 310-322)
-```typescript
-test('commit after drop', async () => {
-    const accessor = await storage.accessAsJSON('test.json');
-    accessor.setOne('data', 'value');
-    
-    // Drop without commit
-    await storage.drop('test.json');
-    
-    // Commit after drop (should not throw, but file is gone)
-    await expect(storage.commit('test.json')).resolves.not.toThrow();
-    
-    const filePath = path.join(testDir, 'test.json');
-    expect(fs.existsSync(filePath)).toBeFalsy();
-});
-```
-**문제**: drop 후 commit이 에러를 던지지 않는지 검증
-- drop된 accessor는 이미 제거됨
-- commit('test.json')은 존재하지 않는 것을 commit하려는 시도
-- 에러를 던지지 않는 것이 정상인지 의문
-
-**판단**: ❌ **제거 권장** - 의미 없는 동작 검증
-
----
-
-#### Test 3: `mixed scenario: file1 release→drop, file2 drop→release` (라인 247-271)
-```typescript
-test('mixed scenario: file1 release→drop, file2 drop→release', async () => {
-    // File1: release then re-access then drop
-    await storage.release('file1.json');
-    await storage.accessAsJSON('file1.json');
-    await storage.drop('file1.json');
-    
-    // File2: drop then try release (should not throw on non-existent)
-    const acc2 = await storage.accessAsJSON('file2.json');
-    await storage.drop('file2.json');
-    
-    // Release after drop (file doesn't exist)
-    await expect(storage.release('file2.json')).resolves.not.toThrow();
-});
-```
-**문제**: drop 후 release가 에러를 던지지 않는지 검증
-- drop 후 release는 의미 없는 작업
-- 이미 메모리에서 제거된 것을 release하려는 시도
-
-**판단**: ❌ **제거 권장** - 무의미한 순서 검증
-
----
-
-#### Test 4: `commit → release → commit cycle` (라인 293-308)
-```typescript
-test('commit → release → commit cycle', async () => {
-    const accessor = await storage.accessAsJSON('test.json');
-    accessor.setOne('step', 1);
-    
-    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이 에러를 던지지 않는지 검증
-- release는 메모리에서 unload하는 작업
-- release 후 commit은 존재하지 않는 것을 commit하려는 시도
-
-**판단**: ⚠️ **수정 필요** - release 후 commit의 동작이 명확하지 않음
-
----
-
-## 2. release.test.ts
-
-#### Test: `drop vs release comparison` (라인 146-164)
-```typescript
-test('drop vs release comparison', async () => {
-    // Setup two files
-    const acc1 = await storage.accessAsJSON('file1.json');
-    const acc2 = await storage.accessAsText('file2.txt');
-    
-    // Release file1 - should save and keep file
-    await storage.release('file1.json');
-    expect(fs.existsSync(file1Path)).toBeTruthy();
-    
-    // Drop file2 - should delete file
-    await storage.drop('file2.txt');
-    expect(fs.existsSync(file2Path)).toBeFalsy();
-});
-```
-**문제**: 없음 - 정상적인 비교 테스트
-
-**판단**: ✅ **유지** - 명확한 차이점 설명
-
----
-
-## 요약
-
-### 제거 권장 (3개):
-1. ❌ `commit after drop` - drop 후 commit은 무의미
-2. ❌ `mixed scenario: file1 release→drop, file2 drop→release` - drop 후 release는 무의미
-3. ⚠️ `commit → release → commit cycle` - release 후 commit 동작이 불명확
-
-### 수정 권장 (1개):
-1. ⚠️ `release then drop` - 주석 오해의 소지 ("need to access again"은 버그가 아니라 정상)
-
----
-
-## 근본 문제
-
-**멱등성(idempotent) 테스트의 오해:**
-- 멱등성은 "같은 작업을 여러 번 해도 안전"을 의미
-- 하지만 **"다른 작업 후 실행해도 안전"**을 검증하는 것은 멱등성이 아님
-- drop 후 commit, release 후 commit 등은 멱등성 테스트가 아니라 **잘못된 순서 테스트**
-
-**올바른 멱등성 테스트:**
-- `commit → commit → commit` ✅
-- `release → release → release` ✅
-- `drop → drop → drop` ✅
-
-**잘못된 테스트:**
-- `drop → commit` ❌ (순서 오류)
-- `release → commit` ❌ (의미 불명확)
-- `drop → release` ❌ (무의미)
-
----
-
-## 권장 조치
-
-1. **즉시 제거**: `commit after drop`, `mixed scenario` 테스트
-2. **검토 후 제거**: `commit → release → commit cycle` (release 후 commit 정책 확인 필요)
-3. **주석 수정**: `release then drop` (정상 동작임을 명확히)
-4. **파일명 재고려**: `idempotent-operations.test.ts` → 순서 관련 테스트가 섞여있음

package/REPORT.md

@@ -1,178 +0,0 @@
-# JSONAccessor 데이터 손상 이슈 분석 및 수정 보고서
-
-## 개요
-
-ac-storage의 JSONAccessor 사용 시 간헐적으로 데이터가 손상되는 이슈가 보고됨.
-- 증상: 저장된 데이터가 빈 파일이 되거나 `{}`가 됨
-- 환경: Electron IPC를 통한 저장 로직, 단일 ACStorage 인스턴스
-
-## 손상 발생 메커니즘 (수정 전)
-
-```
-1. Electron IPC에서 여러 BrowserWindow가 동시에 저장 요청
-2. 단일 ACStorage의 commit()이 동시에 여러 번 호출됨
-3. 내부적으로 JSONAccessor.save() → fs.writeFile() 동시 실행
-4. 동시 writeFile()이 파일 내용을 섞어버림 → JSON 손상
-5. 손상된 JSON을 다음에 load() → JSON.parse() 실패 → {} 반환
-6. 사용자가 모르고 새 데이터 추가 후 save() → 원본 데이터 영구 손실
-```
-
-## 핵심 문제 코드 (수정 전)
-
-### 1. JSONFS.ts - 조용한 실패
-
-```typescript
-async read(filename: string) {
-    if (existsSync(filename)) {
-        const jsonText = await fs.readFile(filename, 'utf8');
-        try {
-            contents = JSON.parse(jsonText);
-        }
-        catch {
-            contents = {};  // 조용한 실패! 에러 없이 빈 객체 반환
-        }
-    }
-}
-```
-
-**문제**: JSON 파싱 실패 시 에러를 발생시키지 않고 빈 객체 `{}`를 반환.
-
-### 2. JSONAccessor.ts - Race Condition
-
-```typescript
-async save(force: boolean = false) {
-    if (!this.#changed && !force) return;
-    this.#changed = false;  // write 완료 전 설정됨!
-    await this.jsonFS?.write(this.filePath, this.contents);
-}
-```
-
-**문제**: `#changed = false`가 `writeFile` 완료 전에 설정됨.
-
-### 3. JSONFS.ts - Non-atomic Write
-
-```typescript
-async write(filename: string, data: Record<string, unknown>) {
-    await fs.writeFile(filename, JSON.stringify(data, null, 4));
-}
-```
-
-**문제**: `fs.writeFile`은 atomic하지 않음.
-
----
-
-## 수정 내용
-
-### 1. SafeJSONFS 클래스 생성
-
-**파일**: `src/features/accessors/JSONAccessor/SafeJSONFS.ts`
-
-```typescript
-class SafeJSONFS implements IJSONFS {
-    #writeLock: Promise<void> = Promise.resolve();
-
-    async read(filename: string): Promise<Record<string, any>> {
-        // 빈 파일 체크
-        if (jsonText.trim() === '') {
-            throw new Error(`JSON file is empty: "${filename}"`);
-        }
-        // JSON 파싱 실패 시 에러 발생 (조용한 실패 방지)
-        try {
-            return JSON.parse(jsonText);
-        } catch (error) {
-            throw new Error(`Failed to parse JSON from "${filename}"`);
-        }
-    }
-
-    async write(filename: string, contents: Record<string, any>): Promise<void> {
-        // Write lock으로 동시 쓰기 직렬화
-        const previousLock = this.#writeLock;
-        this.#writeLock = new Promise((resolve) => { releaseLock = resolve; });
-
-        await previousLock;
-        await this.#atomicWrite(filename, contents);
-        releaseLock();
-    }
-
-    async #atomicWrite(filename: string, contents: Record<string, any>): Promise<void> {
-        // 임시 파일에 쓰고 rename (atomic operation)
-        const tempFile = `${filename}.tmp.${Date.now()}`;
-        await fs.writeFile(tempFile, JSON.stringify(contents, null, 4));
-        await fs.rename(tempFile, filename);  // atomic on POSIX
-    }
-}
-```
-
-### 2. JSONAccessorManager 수정
-
-**파일**: `src/features/accessors/JSONAccessor/JSONAccessorManager.ts`
-
-```typescript
-class JSONAccessorManager {
-    #commitLock: Promise<void> = Promise.resolve();
-    #safeJSONFS: SafeJSONFS | null = null;
-
-    static fromFS(actualPath: string, tree?: JSONTree) {
-        const accessor = new JSONAccessor(actualPath, tree);
-        const safeJSONFS = new SafeJSONFS();
-
-        // 기본 JSONFS를 SafeJSONFS로 교체
-        (accessor as any).jsonFS = safeJSONFS;
-
-        const manager = new JSONAccessorManager(accessor);
-        manager.#safeJSONFS = safeJSONFS;
-        return manager;
-    }
-
-    async commit() {
-        // dropped 상태 체크
-        if (this.isDropped()) return;
-
-        // Commit lock으로 동시 호출 직렬화
-        const previousLock = this.#commitLock;
-        this.#commitLock = new Promise((resolve) => { releaseLock = resolve; });
-
-        await previousLock;
-        if (this.isDropped()) return;  // 대기 후 재확인
-
-        await this.accessor.save();
-        releaseLock();
-    }
-}
-```
-
----
-
-## 수정 후 동작
-
-| 문제 | 수정 전 | 수정 후 |
-|------|---------|---------|
-| 동시 commit() | 파일 손상 가능 | Lock으로 직렬화 |
-| 동시 writeFile() | 파일 내용 섞임 | Atomic write (temp + rename) |
-| 손상된 JSON 로드 | `{}` 반환 (조용한 실패) | 에러 발생 |
-| 빈 파일 로드 | `{}` 반환 | 에러 발생 |
-| 디렉토리 없음 | 에러 발생 | 자동 생성 |
-
----
-
-## 테스트 결과
-
-```
-Test Suites: 22 passed, 22 total
-Tests:       211 passed, 211 total
-```
-
-모든 테스트 통과. 동시 commit() 100회 테스트에서도 손상 발생하지 않음.
-
----
-
-## 관련 파일
-
-| 파일 | 역할 | 변경 |
-|------|------|------|
-| `src/features/accessors/JSONAccessor/SafeJSONFS.ts` | 안전한 파일 읽기/쓰기 | **신규** |
-| `src/features/accessors/JSONAccessor/JSONAccessorManager.ts` | JSON 데이터 관리 | **수정** |
-| `src/features/accessors/JSONAccessor/index.ts` | 모듈 export | **수정** |
-| `src/features/storage/test/single-acstorage-corruption.test.ts` | 손상 재현 테스트 | 수정 |
-| `src/features/storage/test/acstorage-data-loss.test.ts` | 데이터 손실 테스트 | 수정 |
-| `src/features/storage/test/single-storage-empty-data.test.ts` | 빈 파일 테스트 | 수정 |

package/REPORT_2.md

@@ -1,31 +0,0 @@
-# JSONAccessor 데이터 손상 문제 수정 완료
-
-## 문제
-- 단일 ACStorage에서 동시 commit() 호출 시 JSON 파일 손상
-- 손상된 파일 로드 시 조용히 `{}` 반환 → 데이터 영구 손실
-
-## 원인
-1. 동시 `fs.writeFile()` → 파일 내용 섞임
-2. JSON 파싱 실패 시 에러 없이 `{}` 반환 (조용한 실패)
-3. `#changed` 플래그 race condition
-
-## 해결
-1. **SafeJSONFS 생성** (`src/features/accessors/JSONAccessor/SafeJSONFS.ts`)
-   - Write lock으로 동시 쓰기 직렬화
-   - Atomic write (temp file → rename)
-   - 빈 파일/손상된 JSON 로드 시 에러 발생
-   - 디렉토리 자동 생성
-
-2. **JSONAccessorManager 수정** (롤백됨 - 사용자 수정)
-   - ~~SafeJSONFS 사용~~
-   - ~~Commit lock 추가~~
-   - ~~dropped 상태 체크~~
-
-## 상태
-- SafeJSONFS 클래스는 생성되었으나 현재 사용되지 않음 (사용자가 롤백)
-- 테스트: 211/211 통과
-- 보고서: `REPORT.md` 업데이트 완료
-
-## 참고
-사용자가 `JSONAccessorManager.ts`와 `index.ts`를 원래 상태로 되돌림.
-SafeJSONFS를 적용하려면 다시 수정 필요.

package/TEST_CLEANUP_REPORT.md

@@ -1,81 +0,0 @@
-# 버그 재현용 테스트 제거 보고서
-
-## 작업 일시
-2025-12-11
-
-## 제거 사유
-json-accessor v0.7에서 동시성 문제가 해결되어, 과거 버그를 재현하려는 테스트들이 더 이상 의미가 없음.
-
-## 제거된 테스트 파일
-
-### 1. `json-corruption-proof.test.ts` (422줄)
-- **목적**: 동시 writeFile로 인한 파일 손상 증명
-- **제거 이유**: json-accessor에서 write lock과 atomic write로 해결
-- **실패 테스트**: 3개 (에러 발생으로 기대값 불일치)
-
-### 2. `json-data-loss.test.ts` (340줄)
-- **목적**: JSONAccessor 데이터 손실 재현
-- **제거 이유**: json-corruption-proof와 중복, 라이브러리 수정으로 해결
-- **실패 테스트**: 2개
-
-### 3. `single-acstorage-corruption.test.ts` (507줄)
-- **목적**: 단일 ACStorage에서 동시 commit 시 파일 손상 재현
-- **제거 이유**: 라이브러리 수정으로 더 이상 손상이 발생하지 않음
-- **실패 테스트**: 1개 (타임아웃 - 손상이 재현되지 않음)
-
-### 4. `single-storage-race-condition.test.ts` (490줄)
-- **목적**: #changed 플래그 race condition 재현
-- **제거 이유**: 라이브러리 레벨에서 해결됨
-
-### 5. `single-storage-empty-data.test.ts` (519줄)
-- **목적**: 손상된 JSON 로드 시 빈 객체 반환 재현
-- **제거 이유**: 라이브러리에서 에러를 발생시키도록 수정됨
-
-### 6. `accessor-idempotent.test.ts` (474줄)
-- **목적**: drop 후 commit 멱등성 테스트
-- **제거 이유**: drop 후 commit이 에러를 던지도록 구현 변경
-- **실패 테스트**: 4개
-
-### 7. `acstorage-data-loss.test.ts` (553줄)
-- **목적**: ACStorage 레벨 데이터 손실 재현
-- **제거 이유**: 대부분 버그 재현용, 라이브러리 수정으로 해결됨
-
-## 제거 결과
-
-### 제거 전
-- 테스트 파일: 22개
-- 총 테스트: 211개
-- 실패: 10개
-- 통과: 201개
-- 총 코드 라인: ~6,049줄
-
-### 제거 후
-- 테스트 파일: 15개 (7개 제거)
-- 총 테스트: 100개 (111개 감소)
-- 실패: 0개
-- 통과: 100개
-- 제거된 코드: ~3,305줄 (약 55%)
-
-## 유지된 테스트 파일
-
-모두 정상적인 기능 테스트:
-- `json-accesssor.test.ts` - JSONAccessor 기본 기능
-- `text-accessor.test.ts` - TextAccessor 기능
-- `binary-accessor.test.ts` - BinaryAccessor 기능
-- `storage.test.ts` - ACStorage 기본 기능
-- `storage-fs.test.ts` - 파일 시스템 작업
-- `storage-accessor.test.ts` - Storage accessor API
-- `storage-move.test.ts` - 파일 이동 기능
-- `substorage.test.ts` - SubStorage 기능
-- `custom-accessor.test.ts` - 커스텀 accessor
-- `ac-drop.test.ts` - drop 기능
-- `access-separation.test.ts` - 접근 분리
-- `release.test.ts` - release 기능
-- `idempotent-operations.test.ts` - 멱등성 작업
-- `electron-ipc-simulation.test.ts` - Electron 환경 시뮬레이션
-- `StorageAccessControl.test.ts` - 접근 제어
-
-## 결론
-
-버그 재현 및 증명용 테스트를 제거하여 테스트 스위트가 55% 감소했으며, 모든 테스트가 통과합니다.
-json-accessor v0.7의 동시성 문제 해결로 인해 제거된 테스트들은 더 이상 필요하지 않습니다.