kiro-spec-engine 1.2.2 → 1.3.0

package/docs/developer-guide.md

@@ -0,0 +1,615 @@
+# Developer Guide
+
+This guide is for developers who want to contribute to Kiro Spec Engine or extend its functionality.
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Core Components](#core-components)
+- [Migration Script Interface](#migration-script-interface)
+- [Extension Points](#extension-points)
+- [API Documentation](#api-documentation)
+- [Testing Guidelines](#testing-guidelines)
+- [Contributing](#contributing)
+
+---
+
+## Architecture Overview
+
+Kiro Spec Engine follows a modular architecture with clear separation of concerns:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI Layer                             │
+│  (bin/kiro-spec-engine.js, lib/commands/*.js)              │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Core Systems                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │  Adoption    │  │   Upgrade    │  │   Backup     │     │
+│  │  System      │  │   System     │  │   System     │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   Utility Layer                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │  Version     │  │  Validation  │  │  File System │     │
+│  │  Manager     │  │  Utils       │  │  Utils       │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Design Principles
+
+1. **Modularity**: Each component has a single responsibility
+2. **Safety**: All operations are atomic with automatic backups
+3. **Extensibility**: Clear extension points for future features
+4. **Testability**: Components are designed for easy testing
+5. **User-Friendly**: Clear error messages and progress indicators
+
+---
+
+## Core Components
+
+### 1. DetectionEngine (`lib/adoption/detection-engine.js`)
+
+Analyzes project structure and determines the appropriate adoption strategy.
+
+**Key Methods**:
+- `analyze(projectPath)`: Scans project structure
+- `determineStrategy()`: Selects adoption mode (fresh/partial/full)
+- `detectProjectType()`: Identifies Node.js/Python/mixed projects
+- `detectConflicts()`: Finds template file conflicts
+
+**Usage Example**:
+```javascript
+const DetectionEngine = require('./lib/adoption/detection-engine');
+
+const engine = new DetectionEngine('/path/to/project');
+const analysis = engine.analyze();
+console.log(analysis.mode); // 'fresh', 'partial', or 'full'
+```
+
+### 2. AdoptionStrategy (`lib/adoption/adoption-strategy.js`)
+
+Implements different adoption modes for various project states.
+
+**Strategies**:
+- `FreshAdoption`: Creates complete .kiro/ structure from scratch
+- `PartialAdoption`: Adds missing components to existing .kiro/
+- `FullAdoption`: Upgrades existing complete .kiro/ to current version
+
+**Usage Example**:
+```javascript
+const { getStrategy } = require('./lib/adoption/adoption-strategy');
+
+const strategy = getStrategy('fresh');
+await strategy.execute('/path/to/project', {
+  preserveSpecs: true,
+  backupFirst: true
+});
+```
+
+### 3. VersionManager (`lib/version/version-manager.js`)
+
+Manages project versions and upgrade paths.
+
+**Key Methods**:
+- `readVersion(projectPath)`: Reads version.json
+- `writeVersion(projectPath, versionInfo)`: Writes version.json atomically
+- `needsUpgrade(currentVersion, targetVersion)`: Checks if upgrade needed
+- `calculateUpgradePath(from, to)`: Calculates intermediate versions
+
+**Usage Example**:
+```javascript
+const VersionManager = require('./lib/version/version-manager');
+
+const vm = new VersionManager();
+const needsUpgrade = vm.needsUpgrade('1.0.0', '1.2.0');
+if (needsUpgrade) {
+  const path = vm.calculateUpgradePath('1.0.0', '1.2.0');
+  console.log(path); // ['1.0.0', '1.1.0', '1.2.0']
+}
+```
+
+### 4. MigrationEngine (`lib/upgrade/migration-engine.js`)
+
+Plans and executes version upgrades with migration scripts.
+
+**Key Methods**:
+- `planUpgrade(from, to)`: Creates upgrade plan
+- `executeUpgrade(projectPath, plan)`: Runs migrations sequentially
+- `loadMigration(version)`: Loads migration script
+- `validate(projectPath)`: Post-upgrade validation
+
+**Usage Example**:
+```javascript
+const MigrationEngine = require('./lib/upgrade/migration-engine');
+
+const engine = new MigrationEngine();
+const plan = engine.planUpgrade('1.0.0', '1.2.0');
+await engine.executeUpgrade('/path/to/project', plan);
+```
+
+### 5. BackupSystem (`lib/backup/backup-system.js`)
+
+Creates, manages, and restores backups for safe operations.
+
+**Key Methods**:
+- `createBackup(projectPath, reason)`: Creates timestamped backup
+- `listBackups(projectPath)`: Lists available backups
+- `restore(projectPath, backupId)`: Restores from backup
+- `validateBackup(backupPath)`: Verifies backup integrity
+
+**Usage Example**:
+```javascript
+const BackupSystem = require('./lib/backup/backup-system');
+
+const backup = new BackupSystem();
+const backupId = await backup.createBackup('/path/to/project', 'before-upgrade');
+// ... perform operations ...
+if (failed) {
+  await backup.restore('/path/to/project', backupId);
+}
+```
+
+---
+
+## Migration Script Interface
+
+Migration scripts enable smooth upgrades between versions with breaking changes.
+
+### Script Structure
+
+Create migration scripts in `lib/upgrade/migrations/` with the naming pattern:
+`{from-version}-to-{to-version}.js`
+
+Example: `1.0.0-to-1.1.0.js`
+
+### Required Interface
+
+```javascript
+/**
+ * Migration script from version X to version Y
+ */
+module.exports = {
+  /**
+   * Migrate project from old version to new version
+   * @param {string} projectPath - Absolute path to project root
+   * @param {Object} context - Migration context
+   * @param {Object} context.oldVersion - Old version info
+   * @param {Object} context.newVersion - New version info
+   * @param {Object} context.logger - Logger instance
+   * @returns {Promise<Object>} Migration result
+   */
+  async migrate(projectPath, context) {
+    const { oldVersion, newVersion, logger } = context;
+    
+    logger.info(`Migrating from ${oldVersion.version} to ${newVersion.version}`);
+    
+    // Perform migration steps
+    // 1. Read existing files
+    // 2. Transform data/structure
+    // 3. Write new files
+    // 4. Update configuration
+    
+    return {
+      success: true,
+      changes: [
+        'Added new steering file: ENVIRONMENT.md',
+        'Updated version.json structure'
+      ],
+      warnings: []
+    };
+  },
+
+  /**
+   * Rollback migration (optional but recommended)
+   * @param {string} projectPath - Absolute path to project root
+   * @param {Object} context - Migration context
+   * @returns {Promise<Object>} Rollback result
+   */
+  async rollback(projectPath, context) {
+    const { logger } = context;
+    
+    logger.info('Rolling back migration');
+    
+    // Reverse migration steps
+    // Usually handled by backup restore, but can be implemented
+    // for more granular control
+    
+    return {
+      success: true,
+      message: 'Rollback completed'
+    };
+  },
+
+  /**
+   * Validate migration result (optional)
+   * @param {string} projectPath - Absolute path to project root
+   * @returns {Promise<Object>} Validation result
+   */
+  async validate(projectPath) {
+    // Verify migration was successful
+    // Check file existence, structure, etc.
+    
+    return {
+      valid: true,
+      errors: []
+    };
+  }
+};
+```
+
+### Migration Best Practices
+
+1. **Idempotency**: Migrations should be safe to run multiple times
+2. **Validation**: Always validate before and after migration
+3. **Logging**: Log all significant operations
+4. **Error Handling**: Handle errors gracefully with clear messages
+5. **Rollback**: Implement rollback when possible
+6. **Testing**: Test migrations with various project states
+
+### Example Migration Script
+
+```javascript
+const fs = require('fs-extra');
+const path = require('path');
+
+module.exports = {
+  async migrate(projectPath, context) {
+    const { logger } = context;
+    const changes = [];
+    
+    // Add new steering file
+    const steeringDir = path.join(projectPath, '.kiro', 'steering');
+    const envFile = path.join(steeringDir, 'ENVIRONMENT.md');
+    
+    if (!fs.existsSync(envFile)) {
+      const template = `# Environment Configuration
+...template content...`;
+      await fs.writeFile(envFile, template, 'utf8');
+      changes.push('Created ENVIRONMENT.md');
+      logger.info('✅ Created ENVIRONMENT.md');
+    }
+    
+    // Update version.json structure
+    const versionFile = path.join(projectPath, '.kiro', 'version.json');
+    const versionData = await fs.readJson(versionFile);
+    
+    if (!versionData.upgradeHistory) {
+      versionData.upgradeHistory = [];
+      await fs.writeJson(versionFile, versionData, { spaces: 2 });
+      changes.push('Added upgradeHistory to version.json');
+      logger.info('✅ Updated version.json structure');
+    }
+    
+    return {
+      success: true,
+      changes,
+      warnings: []
+    };
+  },
+
+  async validate(projectPath) {
+    const errors = [];
+    
+    // Check ENVIRONMENT.md exists
+    const envFile = path.join(projectPath, '.kiro', 'steering', 'ENVIRONMENT.md');
+    if (!fs.existsSync(envFile)) {
+      errors.push('ENVIRONMENT.md not found');
+    }
+    
+    // Check version.json structure
+    const versionFile = path.join(projectPath, '.kiro', 'version.json');
+    const versionData = await fs.readJson(versionFile);
+    if (!versionData.upgradeHistory) {
+      errors.push('version.json missing upgradeHistory field');
+    }
+    
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+};
+```
+
+---
+
+## Extension Points
+
+### 1. Custom Adoption Strategies
+
+Add new adoption strategies by extending the base class:
+
+```javascript
+const { AdoptionStrategy } = require('./lib/adoption/adoption-strategy');
+
+class CustomAdoption extends AdoptionStrategy {
+  async execute(projectPath, options) {
+    // Custom adoption logic
+  }
+}
+
+// Register strategy
+const strategies = {
+  custom: CustomAdoption
+};
+```
+
+### 2. Custom Validation Rules
+
+Extend validation system with custom rules:
+
+```javascript
+const validation = require('./lib/utils/validation');
+
+function validateCustomRule(projectPath) {
+  // Custom validation logic
+  return {
+    valid: true,
+    errors: []
+  };
+}
+
+// Use in validation pipeline
+const result = await validation.validateProject(projectPath, {
+  customValidators: [validateCustomRule]
+});
+```
+
+### 3. Custom Migration Hooks
+
+Add hooks to migration process:
+
+```javascript
+const MigrationEngine = require('./lib/upgrade/migration-engine');
+
+class CustomMigrationEngine extends MigrationEngine {
+  async beforeMigration(projectPath, plan) {
+    // Pre-migration hook
+  }
+
+  async afterMigration(projectPath, result) {
+    // Post-migration hook
+  }
+}
+```
+
+### 4. Custom CLI Commands
+
+Add new commands to the CLI:
+
+```javascript
+// lib/commands/my-command.js
+module.exports = {
+  name: 'my-command',
+  description: 'My custom command',
+  
+  async execute(options) {
+    // Command logic
+  }
+};
+
+// Register in bin/kiro-spec-engine.js
+program
+  .command('my-command')
+  .description('My custom command')
+  .action(require('../lib/commands/my-command').execute);
+```
+
+---
+
+## API Documentation
+
+### DetectionEngine API
+
+#### `constructor(projectPath)`
+Creates a new DetectionEngine instance.
+
+#### `analyze()`
+Analyzes project structure and returns analysis result.
+
+**Returns**: `Object`
+```javascript
+{
+  mode: 'fresh' | 'partial' | 'full',
+  projectType: 'nodejs' | 'python' | 'mixed',
+  hasKiroDir: boolean,
+  hasSpecs: boolean,
+  hasVersion: boolean,
+  conflicts: string[],
+  currentVersion: string | null
+}
+```
+
+### VersionManager API
+
+#### `readVersion(projectPath)`
+Reads version.json from project.
+
+**Returns**: `Promise<Object>`
+```javascript
+{
+  version: '1.2.0',
+  kseVersion: '1.2.0',
+  createdAt: '2026-01-23T00:00:00.000Z',
+  updatedAt: '2026-01-23T00:00:00.000Z',
+  upgradeHistory: []
+}
+```
+
+#### `needsUpgrade(currentVersion, targetVersion)`
+Checks if upgrade is needed.
+
+**Returns**: `boolean`
+
+#### `calculateUpgradePath(fromVersion, toVersion)`
+Calculates intermediate versions for upgrade.
+
+**Returns**: `string[]` - Array of versions in upgrade order
+
+### BackupSystem API
+
+#### `createBackup(projectPath, reason)`
+Creates a timestamped backup.
+
+**Returns**: `Promise<string>` - Backup ID
+
+#### `listBackups(projectPath)`
+Lists available backups.
+
+**Returns**: `Promise<Array>`
+```javascript
+[
+  {
+    id: 'backup-20260123-120000',
+    timestamp: '2026-01-23T12:00:00.000Z',
+    reason: 'before-upgrade',
+    size: 1024000
+  }
+]
+```
+
+#### `restore(projectPath, backupId)`
+Restores project from backup.
+
+**Returns**: `Promise<void>`
+
+---
+
+## Testing Guidelines
+
+### Unit Tests
+
+Unit tests are located in `tests/unit/` and test individual components.
+
+**Running unit tests**:
+```bash
+npm run test:unit
+```
+
+**Writing unit tests**:
+```javascript
+const DetectionEngine = require('../../lib/adoption/detection-engine');
+
+describe('DetectionEngine', () => {
+  test('should detect fresh adoption mode', () => {
+    const engine = new DetectionEngine('/path/to/project');
+    const analysis = engine.analyze();
+    expect(analysis.mode).toBe('fresh');
+  });
+});
+```
+
+### Property-Based Tests
+
+Property-based tests are located in `tests/properties/` and test universal properties.
+
+**Running property tests**:
+```bash
+npm run test:properties
+```
+
+**Writing property tests**:
+```javascript
+const fc = require('fast-check');
+const VersionManager = require('../../lib/version/version-manager');
+
+describe('VersionManager Properties', () => {
+  test('version comparison is transitive', () => {
+    fc.assert(
+      fc.property(
+        fc.string(), fc.string(), fc.string(),
+        (v1, v2, v3) => {
+          const vm = new VersionManager();
+          // If v1 < v2 and v2 < v3, then v1 < v3
+          // Property test logic
+        }
+      )
+    );
+  });
+});
+```
+
+### Integration Tests
+
+Integration tests are located in `tests/integration/` and test end-to-end flows.
+
+**Running integration tests**:
+```bash
+npm run test:integration
+```
+
+---
+
+## Contributing
+
+### Development Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/heguangyong/kiro-spec-engine.git
+cd kiro-spec-engine
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Run tests:
+```bash
+npm test
+```
+
+4. Install globally for testing:
+```bash
+npm run install-global
+```
+
+### Code Style
+
+- Use 2 spaces for indentation
+- Use semicolons
+- Use single quotes for strings
+- Follow existing code patterns
+- Add JSDoc comments for public APIs
+
+### Pull Request Process
+
+1. Create a feature branch from `main`
+2. Make your changes with tests
+3. Ensure all tests pass
+4. Update documentation if needed
+5. Submit pull request with clear description
+
+### Commit Message Format
+
+Follow conventional commits:
+```
+feat: add new adoption strategy
+fix: correct version comparison logic
+docs: update developer guide
+test: add property tests for backup system
+```
+
+---
+
+## Additional Resources
+
+- [User Adoption Guide](./adoption-guide.md)
+- [User Upgrade Guide](./upgrade-guide.md)
+- [Spec Workflow Guide](../.kiro/specs/SPEC_WORKFLOW_GUIDE.md)
+- [GitHub Repository](https://github.com/heguangyong/kiro-spec-engine)
+- [Issue Tracker](https://github.com/heguangyong/kiro-spec-engine/issues)
+
+---
+
+**Version**: 1.0  
+**Last Updated**: 2026-01-23