@fgv/ts-res 5.0.0-3 → 5.0.0-31

package/lib/packlets/zip-archive/zipArchiveLoader.d.ts

@@ -0,0 +1,70 @@
+import { Result } from '@fgv/ts-utils';
+import type { IZipArchiveLoadOptions, IZipArchiveLoadResult, ZipArchiveProgressCallback } from './types';
+/**
+ * ZIP archive loader extending ts-extras foundation
+ * @public
+ */
+export declare class ZipArchiveLoader {
+    /**
+     * Load ZIP archive from File object (Browser)
+     * @param file - File object from file input
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    loadFromFile(file: File, options?: IZipArchiveLoadOptions, onProgress?: ZipArchiveProgressCallback): Promise<Result<IZipArchiveLoadResult>>;
+    /**
+     * Load ZIP archive from ArrayBuffer (Universal)
+     * @param buffer - ZIP data buffer
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    loadFromBuffer(buffer: ArrayBuffer, options?: IZipArchiveLoadOptions, onProgress?: ZipArchiveProgressCallback): Promise<Result<IZipArchiveLoadResult>>;
+    /**
+     * Load manifest from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @returns Result containing parsed manifest
+     */
+    private _loadManifestFromAccessors;
+    /**
+     * Load configuration from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @param manifest - Parsed manifest (may be undefined)
+     * @param options - Loading options
+     * @returns Result containing parsed configuration
+     */
+    private _loadConfigurationFromAccessors;
+    /**
+     * Extract files and directory structure from ZIP
+     * @param zipAccessors - ZIP file tree accessors
+     * @param onProgress - Optional progress callback
+     * @returns Result containing files and directory structure
+     */
+    private _extractFilesFromAccessors;
+    /**
+     * Recursively process file tree items
+     * @param zipAccessors - ZIP file tree accessors
+     * @param currentPath - Current directory path
+     * @param items - Items to process
+     * @param files - Files collection
+     * @param directories - Directories collection
+     * @param onProgress - Optional progress callback
+     * @param processed - Processing counter
+     */
+    private _processFileTreeItems;
+    /**
+     * Build directory structure from files
+     * @param files - Extracted files
+     * @param directories - Directories map
+     * @returns Root directory structure or null
+     */
+    private _buildDirectoryStructure;
+    /**
+     * Get file MIME type based on extension
+     * @param filename - Filename
+     * @returns MIME type
+     */
+    private _getFileType;
+}
+//# sourceMappingURL=zipArchiveLoader.d.ts.map

package/lib/packlets/zip-archive/zipArchiveLoader.js

@@ -0,0 +1,285 @@
+"use strict";
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZipArchiveLoader = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const ts_extras_1 = require("@fgv/ts-extras");
+const zipArchiveFormat_1 = require("./zipArchiveFormat");
+/**
+ * ZIP archive loader extending ts-extras foundation
+ * @public
+ */
+class ZipArchiveLoader {
+    /**
+     * Load ZIP archive from File object (Browser)
+     * @param file - File object from file input
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    async loadFromFile(file, options = {}, onProgress) {
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('reading-file', 0, `Reading file: ${file.name}`);
+        if (!(0, zipArchiveFormat_1.isZipFile)(file.name)) {
+            return (0, ts_utils_1.fail)(`File ${file.name} is not a ZIP file`);
+        }
+        try {
+            const buffer = await file.arrayBuffer();
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress('reading-file', 100, 'File read complete');
+            return await this.loadFromBuffer(buffer, options, onProgress);
+            /* c8 ignore next 3 - defense in depth against internal error */
+        }
+        catch (error) {
+            return (0, ts_utils_1.fail)(`Failed to read file: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Load ZIP archive from ArrayBuffer (Universal)
+     * @param buffer - ZIP data buffer
+     * @param options - Loading options
+     * @param onProgress - Optional progress callback
+     * @returns Result containing loaded archive data
+     */
+    async loadFromBuffer(buffer, options = {}, onProgress) {
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('parsing-zip', 0, 'Parsing ZIP archive');
+        const zipAccessorsResult = ts_extras_1.ZipFileTree.ZipFileTreeAccessors.fromBuffer(buffer);
+        if (zipAccessorsResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse ZIP: ${zipAccessorsResult.message}`);
+        }
+        const zipAccessors = zipAccessorsResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('parsing-zip', 100, 'ZIP archive parsed');
+        // Load manifest
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-manifest', 0, 'Loading manifest');
+        const manifestResult = this._loadManifestFromAccessors(zipAccessors);
+        if (manifestResult.isFailure()) {
+            return (0, ts_utils_1.fail)(manifestResult.message);
+        }
+        const manifest = manifestResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-manifest', 100, 'Manifest loaded');
+        // Load configuration
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-config', 0, 'Loading configuration');
+        const configResult = this._loadConfigurationFromAccessors(zipAccessors, manifest, options);
+        if (configResult.isFailure()) {
+            return (0, ts_utils_1.fail)(configResult.message);
+        }
+        const config = configResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('loading-config', 100, 'Configuration loaded');
+        // Extract files and directory structure
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 0, 'Extracting files');
+        const filesResult = await this._extractFilesFromAccessors(zipAccessors, onProgress);
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (filesResult.isFailure()) {
+            return (0, ts_utils_1.fail)(filesResult.message);
+        }
+        const { files, directory } = filesResult.value;
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 100, `Extracted ${files.length} files`);
+        onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 100, 'ZIP loading complete');
+        return (0, ts_utils_1.succeed)({
+            manifest,
+            config,
+            files,
+            directory
+        });
+    }
+    /**
+     * Load manifest from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @returns Result containing parsed manifest
+     */
+    _loadManifestFromAccessors(zipAccessors) {
+        const manifestResult = zipAccessors.getFileContents('manifest.json');
+        if (manifestResult.isFailure()) {
+            // Manifest is optional - return success with undefined
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        const parseResult = (0, zipArchiveFormat_1.parseZipArchiveManifest)(manifestResult.value);
+        if (parseResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to parse manifest.json: ${parseResult.message}`);
+        }
+        return (0, ts_utils_1.succeed)(parseResult.value);
+    }
+    /**
+     * Load configuration from ZIP using ZipFileTreeAccessors
+     * @param zipAccessors - ZIP file tree accessors
+     * @param manifest - Parsed manifest (may be undefined)
+     * @param options - Loading options
+     * @returns Result containing parsed configuration
+     */
+    _loadConfigurationFromAccessors(zipAccessors, manifest, options) {
+        // Check if manifest specifies a config file
+        const manifestSpecifiesConfig = (manifest === null || manifest === void 0 ? void 0 : manifest.config) !== undefined;
+        if (!manifestSpecifiesConfig) {
+            // If no config specified in manifest, config is optional
+            return (0, ts_utils_1.succeed)(undefined);
+        }
+        // Get the config path from the manifest
+        const configPath = manifest.config.archivePath;
+        return zipAccessors
+            .getFileContents(configPath)
+            .withErrorFormat(() => `Manifest specifies config file at '${configPath}' but it was not found in archive`)
+            .onSuccess((configContent) => (0, zipArchiveFormat_1.parseZipArchiveConfiguration)(configContent))
+            .withErrorFormat((e) => `Failed to parse config file '${configPath}': ${e}`);
+    }
+    /**
+     * Extract files and directory structure from ZIP
+     * @param zipAccessors - ZIP file tree accessors
+     * @param onProgress - Optional progress callback
+     * @returns Result containing files and directory structure
+     */
+    async _extractFilesFromAccessors(zipAccessors, onProgress) {
+        try {
+            const files = [];
+            const directories = new Map();
+            // Get all children from root
+            const rootChildrenResult = zipAccessors.getChildren('/');
+            /* c8 ignore next 3 - defense in depth against internal error */
+            if (rootChildrenResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Failed to read ZIP contents: ${rootChildrenResult.message}`);
+            }
+            // Process all items recursively
+            await this._processFileTreeItems(zipAccessors, '/', rootChildrenResult.value, files, directories, onProgress);
+            // Build directory structure
+            const directory = this._buildDirectoryStructure(files, directories);
+            return (0, ts_utils_1.succeed)({ files, directory });
+            /* c8 ignore next 3 - defense in depth against internal error */
+        }
+        catch (error) {
+            return (0, ts_utils_1.fail)(`Failed to extract files: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Recursively process file tree items
+     * @param zipAccessors - ZIP file tree accessors
+     * @param currentPath - Current directory path
+     * @param items - Items to process
+     * @param files - Files collection
+     * @param directories - Directories collection
+     * @param onProgress - Optional progress callback
+     * @param processed - Processing counter
+     */
+    async _processFileTreeItems(zipAccessors, currentPath, items, files, directories, onProgress, processed = { count: 0 }) {
+        for (const item of items) {
+            /* c8 ignore next 1 - defense in depth */
+            const itemPath = item.absolutePath.startsWith('/') ? item.absolutePath.substring(1) : item.absolutePath;
+            if (item.type === 'directory') {
+                // Track directory
+                if (!directories.has(itemPath)) {
+                    directories.set(itemPath, {
+                        name: item.name,
+                        files: [],
+                        subdirectories: []
+                    });
+                }
+                // Recursively process children
+                const childrenResult = zipAccessors.getChildren(item.absolutePath);
+                if (childrenResult.isSuccess()) {
+                    await this._processFileTreeItems(zipAccessors, item.absolutePath, childrenResult.value, files, directories, onProgress, processed);
+                }
+            }
+            else if (item.type === 'file') {
+                // Get file content
+                const contentResult = item.getRawContents();
+                const content = contentResult.orDefault('');
+                files.push({
+                    name: item.name,
+                    path: itemPath,
+                    content,
+                    type: this._getFileType(item.name)
+                });
+            }
+            processed.count++;
+            onProgress === null || onProgress === void 0 ? void 0 : onProgress('extracting-files', 0, `Processing ${itemPath}`);
+        }
+    }
+    /**
+     * Build directory structure from files
+     * @param files - Extracted files
+     * @param directories - Directories map
+     * @returns Root directory structure or null
+     */
+    _buildDirectoryStructure(files, directories) {
+        /* c8 ignore next 3 - should never happen with fflate */
+        if (files.length === 0) {
+            return undefined;
+        }
+        const rootDir = {
+            name: 'root',
+            files: [],
+            subdirectories: []
+        };
+        // Process files to build directory structure
+        for (const file of files) {
+            const pathParts = file.path.split('/').filter((part) => part.length > 0);
+            /* c8 ignore next 1 - defense in depth should never happen */
+            if (pathParts.length === 0)
+                continue;
+            // Ensure all parent directories exist
+            let currentDir = rootDir;
+            for (let i = 0; i < pathParts.length - 1; i++) {
+                const dirName = pathParts[i];
+                let foundDir = currentDir.subdirectories.find((d) => d.name === dirName);
+                if (!foundDir) {
+                    foundDir = {
+                        name: dirName,
+                        files: [],
+                        subdirectories: []
+                    };
+                    currentDir.subdirectories.push(foundDir);
+                }
+                currentDir = foundDir;
+            }
+            // Add file to its parent directory
+            currentDir.files.push(file);
+        }
+        return rootDir;
+    }
+    /**
+     * Get file MIME type based on extension
+     * @param filename - Filename
+     * @returns MIME type
+     */
+    _getFileType(filename) {
+        const ext = filename.toLowerCase().split('.').pop();
+        /* c8 ignore next 20 - no need to test every one */
+        switch (ext) {
+            case 'json':
+                return 'application/json';
+            case 'yaml':
+            case 'yml':
+                return 'application/yaml';
+            case 'xml':
+                return 'application/xml';
+            case 'txt':
+                return 'text/plain';
+            case 'md':
+                return 'text/markdown';
+            case 'js':
+                return 'application/javascript';
+            case 'ts':
+                return 'application/typescript';
+            default:
+                return 'application/octet-stream';
+        }
+    }
+}
+exports.ZipArchiveLoader = ZipArchiveLoader;
+//# sourceMappingURL=zipArchiveLoader.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-res",
-  "version": "5.0.0-3",
+  "version": "5.0.0-31",
   "description": "Multi-dimensional Resource Runtime",
   "main": "lib/index.js",
   "types": "dist/ts-res.d.ts",
@@ -18,48 +18,42 @@
   "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-res#readme",
   "sideEffects": false,
   "devDependencies": {
-    "@microsoft/api-documenter": "^7.26.29",
-    "@microsoft/api-extractor": "^7.49.1",
+    "@microsoft/api-documenter": "^7.26.31",
+    "@microsoft/api-extractor": "^7.52.10",
     "@types/jest": "^29.5.14",
-    "@types/luxon": "^3.6.2",
+    "@types/luxon": "^3.7.1",
     "@types/node": "^20.14.9",
-    "@typescript-eslint/eslint-plugin": "^7.14.1",
-    "@typescript-eslint/parser": "^7.14.1",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^10.1.5",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-prettier": "^5.5.1",
-    "eslint-plugin-promise": "^6.2.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-promise": "^7.2.1",
     "jest": "^29.7.0",
     "prettier": "^3.6.2",
-    "rimraf": "^5.0.7",
-    "ts-jest": "^29.4.0",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
-    "typescript": "^5.7.3",
-    "eslint-plugin-n": "^16.6.2",
-    "@rushstack/eslint-config": "~4.4.0",
-    "@rushstack/heft": "~0.74.0",
-    "@rushstack/heft-jest-plugin": "~0.16.9",
-    "@rushstack/heft-node-rig": "~2.9.0",
+    "typescript": "5.8.3",
+    "eslint-plugin-n": "^17.21.3",
+    "@rushstack/eslint-config": "4.4.0",
+    "@rushstack/heft": "0.74.4",
+    "@rushstack/heft-jest-plugin": "0.16.13",
+    "@rushstack/heft-node-rig": "2.9.5",
     "@types/heft-jest": "1.0.6",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-3",
-    "@fgv/ts-utils-jest": "5.0.0-3",
-    "@fgv/ts-extras": "5.0.0-3",
-    "@fgv/ts-json-base": "5.0.0-3",
-    "@fgv/ts-bcp47": "5.0.0-3",
-    "@fgv/ts-json": "5.0.0-3"
+    "@fgv/ts-utils-jest": "5.0.0-31",
+    "@fgv/ts-extras": "5.0.0-31"
   },
   "dependencies": {
-    "luxon": "^3.6.1"
-  },
-  "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-3",
-    "@fgv/ts-json-base": "5.0.0-3",
-    "@fgv/ts-extras": "5.0.0-3",
-    "@fgv/ts-bcp47": "5.0.0-3",
-    "@fgv/ts-json": "5.0.0-3"
+    "luxon": "^3.7.2",
+    "fflate": "~0.8.2",
+    "@fgv/ts-utils": "5.0.0-31",
+    "@fgv/ts-json-base": "5.0.0-31",
+    "@fgv/ts-bcp47": "5.0.0-31",
+    "@fgv/ts-json": "5.0.0-31"
   },
   "scripts": {
     "build": "heft build --clean",

package/CLAUDE.md

@@ -1,186 +0,0 @@
-# CLAUDE.md
-
-This file provides ts-res-specific guidance to Claude Code (claude.ai/code) when working with the `@fgv/ts-res` library.
-
-**For general repository guidelines, testing philosophy, and TypeScript standards, see the root [CLAUDE.md](../../CLAUDE.md).**
-
-## Project Overview
-
-This is `@fgv/ts-res`, a TypeScript library for multidimensional resource management with internationalization and localization support. It provides a sophisticated system for managing resources with complex conditional logic based on qualifiers like language, territory, and custom dimensions.
-
-## Development Commands
-
-### Build & Test
-- `rushx build` - Build the project (uses heft build --clean)
-- `rushx test` - Run tests (uses heft test --clean)  
-- `rushx build-all` - Build project and generate documentation
-- `rushx coverage` - Run tests with coverage reporting
-- `rushx clean` - Clean build artifacts
-
-### Linting & Code Quality
-- `rushx lint` - Run ESLint on source files
-- `rushx fixlint` - Run ESLint with automatic fixes
-- Tests must maintain 100% coverage (branches, functions, lines, statements)
-
-### Documentation
-- `rushx build-docs` - Generate API documentation using api-documenter
-- Documentation is generated in the `docs/` directory
-- **IMPORTANT**: Always run `rushx build-docs` before check-in when making public API changes to regenerate API documentation
-
-### Testing
-- Uses Jest with ts-jest for TypeScript support
-- Run single test: `jest path/to/test.test.ts`
-- Run with open handles detection: `rushx test-handles`
-- Clear Jest cache: `rushx clean-jest`
-
-## Architecture
-
-The library is organized into "packlets" - cohesive modules that group related functionality:
-
-### Core Components
-
-**Resources** (`src/packlets/resources/`):
-- `ResourceManager` - Central orchestrator for all resource operations
-- `Resource` - Individual resource with candidates for different contexts
-- `ResourceCandidate` - Specific resource variant with conditions and merge method
-- `ResourceBuilder` - Builder pattern for constructing resources
-
-**Conditions** (`src/packlets/conditions/`):
-- `Condition` - Individual condition with qualifier, operator, and value
-- `ConditionSet` - Collection of conditions that must all match
-- `ConditionCollector` - Manages and validates condition collections
-- `ConditionSetCollector` - Manages condition set collections
-
-**Qualifiers** (`src/packlets/qualifiers/`):
-- `Qualifier` - Named dimension for resource qualification (e.g., "language", "territory")
-- `QualifierCollector` - Manages qualifier definitions and validation
-
-**Qualifier Types** (`src/packlets/qualifier-types/`):
-- `QualifierType` - Defines validation and matching logic for qualifier values
-- `LanguageQualifierType` - BCP47 language tag validation
-- `TerritoryQualifierType` - Territory/region validation
-- `LiteralQualifierType` - Enumerated literal values with optional hierarchy
-
-**Decisions** (`src/packlets/decisions/`):
-- `Decision` - Represents a resolved resource choice for a context
-- `AbstractDecision` - Template for decisions with condition sets
-- `ConcreteDecision` - Fully resolved decision with specific candidates
-
-**Context** (`src/packlets/context/`):
-- Defines the context against which resources are matched (e.g., {language: "en-US", territory: "US"})
-
-**Import** (`src/packlets/import/`):
-- `ImportManager` - Orchestrates importing resources from various sources
-- `FsItemImporter` - Imports from file system items
-- `PathImporter` - Imports from file paths
-- `JsonImporter` - Imports from JSON structures
-- `CollectionImporter` - Imports from resource collections
-
-**Resource JSON** (`src/packlets/resource-json/`):
-- JSON serialization and deserialization of resource structures
-- Supports both tree and collection formats
-
-### Key Patterns
-
-1. **Result Pattern**: All operations that can fail return `Result<T>` objects from `@fgv/ts-utils`. Avoid throwing errors directly as much as possible, preferring to return a Result and use .orThrow() on paths that must throw.
-2. **Collector Pattern**: Used throughout for managing collections with validation
-3. **Builder Pattern**: `ResourceBuilder` for constructing complex resources
-4. **Converter Pattern**: Each major type has convert functions for declaration-to-object transformation
-5. **Type-Safe Validation Pattern**: Always use proper Converter and Validator objects for type validation instead of manual checks and unsafe casts (see [root CLAUDE.md](../../CLAUDE.md) for detailed guidelines)
-
-### Dependencies
-
-- `@fgv/ts-utils` - Core utilities including Result pattern and collections
-- `@fgv/ts-extras` - Additional utility functions
-- `@fgv/ts-json-base` - JSON validation and processing
-- `@fgv/ts-bcp47` - BCP47 language tag processing
-- `@fgv/ts-json` - JSON schema validation
-- `luxon` - Date/time handling
-
-## Testing Approach
-
-**This library follows the repository-wide testing philosophy outlined in the [root CLAUDE.md](../../CLAUDE.md).**
-
-**For comprehensive coverage guidelines and systematic approaches to achieving 100% test coverage, see [COVERAGE_GUIDELINES.md](../../COVERAGE_GUIDELINES.md).**
-
-### ts-res-Specific Testing Patterns
-
-#### Testing ts-res Components
-```typescript
-// ✅ Good - Test through ResourceManager public API
-expect(ResourceManager.create(params)).toSucceedAndSatisfy((manager) => {
-  expect(manager.qualifiers.size).toBe(2);
-  expect(manager.resourceTypes.size).toBe(1);
-  expect(manager.getResource('test')).toSucceed();
-});
-
-// ✅ Good - Test internal validators through Runtime exports
-expect(TsRes.Runtime.resourceCandidate.validate(data)).toSucceed();
-
-// ✅ Good - Test interface through concrete implementation
-const leafNode: IReadOnlyResourceTreeLeaf<T> = ResourceTreeLeaf.create(...).orThrow();
-expect(leafNode.isLeaf).toBe(true);
-```
-
-#### ts-res Result Pattern Examples
-```typescript
-// ✅ Good - Setup uses standard Result methods
-beforeEach(() => {
-  const qualifierTypesResult = QualifierTypeCollector.create(params);
-  qualifierTypes = qualifierTypesResult.orThrow(); // OK in setup
-  
-  // Or use onSuccess for conditional setup
-  resourceManager = ResourceManager.create(params).onSuccess((manager) => {
-    manager.addResource(testResource).orThrow(); // OK in setup
-    return manager;
-  }).orThrow();
-});
-
-// ✅ Good - Test cases use Result matchers
-test('should create manager', () => {
-  expect(ResourceManager.create(params)).toSucceedAndSatisfy((manager) => {
-    expect(manager.qualifiers.size).toBe(2);
-  });
-});
-```
-
-#### ts-res Error Testing
-```typescript
-// ✅ Good - Test ts-res-specific error conditions
-expect(qualifierCollector.create(invalidParams)).toFailWith(/invalid qualifier/i);
-expect(resourceManager.getResource('missing')).toFailWith(/resource not found/i);
-expect(conditionSet.validate(context)).toFailWith(/condition not satisfied/i);
-```
-
-#### TypeScript in ts-res Tests
-```typescript
-// ✅ Good - Proper type assertions for ts-res branded types
-const corruptedData = {
-  id: 'invalid' as unknown as TsRes.ResourceId,
-  type: 999 as unknown as TsRes.ResourceTypeIndex
-};
-
-// ❌ Bad - Never use any type
-const corruptedData = {
-  id: 'invalid' as any,
-  type: 999 as any
-};
-```
-
-## Development Workflow
-
-### Before Check-in Checklist
-When making changes that affect the public API:
-1. Run `rushx test` to ensure all tests pass
-2. Run `rushx lint` to ensure code quality
-3. **Run `rushx build-docs` to regenerate API documentation**
-4. Commit changes including updated documentation files
-
-## Code Organization
-
-- Main entry point: `src/index.ts`
-- Packlet-based organization under `src/packlets/`
-- Each packlet has its own `index.ts` for exports
-- Common utilities in `src/packlets/common/`
-- Comprehensive type definitions throughout
-- Uses Rush monorepo tooling with workspace dependencies