@ginkoai/cli 1.0.0

package/dist/core/documents/document-migrator.js

@@ -0,0 +1,349 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-09-19
+ * @tags: [document, migration, rename, references, atomic]
+ * @related: [document-namer.ts, sequence-manager.ts]
+ * @priority: high
+ * @complexity: high
+ * @dependencies: [fs-extra, path, glob]
+ */
+import * as fs from 'fs-extra';
+import * as path from 'path';
+import { glob } from 'glob';
+/**
+ * Migrates documents to standardized naming convention and updates references.
+ * Provides safe atomic operations with rollback capability.
+ */
+export class DocumentMigrator {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Scan directories and generate a migration plan
+     */
+    async generateMigrationPlan() {
+        const operations = [];
+        const errors = [];
+        try {
+            // Get all document types and their directories
+            const typeDirectories = {
+                'ADR': 'adr',
+                'PRD': 'PRD',
+                'SPRINT': 'sprints',
+                'STRATEGY': 'strategy'
+            };
+            for (const [type, subDir] of Object.entries(typeDirectories)) {
+                const dirPath = path.join(this.config.docsRoot, subDir);
+                if (await fs.pathExists(dirPath)) {
+                    const files = await fs.readdir(dirPath);
+                    for (const file of files) {
+                        if (file.endsWith('.md') && !this.config.documentNamer.isStandardName(file)) {
+                            try {
+                                const originalPath = path.join(dirPath, file);
+                                const nameResult = await this.config.documentNamer.standardizeName(type, file);
+                                operations.push({
+                                    originalPath,
+                                    newPath: nameResult.fullPath,
+                                    originalFilename: file,
+                                    newFilename: nameResult.filename,
+                                    type,
+                                    reason: 'Non-standard naming convention',
+                                    isSafe: true
+                                });
+                            }
+                            catch (error) {
+                                errors.push({
+                                    file,
+                                    error: error instanceof Error ? error.message : 'Unknown error'
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            return {
+                operations,
+                referencesUpdated: [],
+                totalFiles: operations.length,
+                successfulMigrations: 0,
+                errors,
+                hasChanges: operations.length > 0,
+                backupDirectory: undefined
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to generate migration plan: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Execute migration plan with atomic operations
+     */
+    async executeMigration(dryRun = false) {
+        const plan = await this.generateMigrationPlan();
+        if (plan.operations.length === 0) {
+            return { ...plan, successfulMigrations: 0 };
+        }
+        if (dryRun) {
+            return plan;
+        }
+        let backupDirectory;
+        const referencesUpdated = [];
+        const errors = [...plan.errors];
+        let successfulMigrations = 0;
+        try {
+            // Create backup directory
+            backupDirectory = await this.createBackup(plan.operations);
+            // Find all references before moving files
+            const allReferences = this.config.updateReferences
+                ? await this.findAllReferences(plan.operations)
+                : [];
+            // Execute file moves
+            for (const operation of plan.operations) {
+                try {
+                    await this.executeOperation(operation);
+                    successfulMigrations++;
+                }
+                catch (error) {
+                    errors.push({
+                        file: operation.originalFilename,
+                        error: error instanceof Error ? error.message : 'Unknown error'
+                    });
+                }
+            }
+            // Update references if enabled
+            if (this.config.updateReferences && allReferences.length > 0) {
+                const updatedFiles = await this.updateReferences(allReferences, plan.operations);
+                referencesUpdated.push(...updatedFiles);
+            }
+            return {
+                operations: plan.operations,
+                referencesUpdated,
+                totalFiles: plan.operations.length,
+                successfulMigrations,
+                errors,
+                hasChanges: successfulMigrations > 0,
+                backupDirectory
+            };
+        }
+        catch (error) {
+            // Attempt rollback if backup exists
+            if (backupDirectory) {
+                try {
+                    await this.rollback(backupDirectory, plan.operations);
+                }
+                catch (rollbackError) {
+                    errors.push({
+                        file: 'rollback',
+                        error: `Rollback failed: ${rollbackError instanceof Error ? rollbackError.message : 'Unknown error'}`
+                    });
+                }
+            }
+            throw new Error(`Migration failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Find all references to files that will be migrated
+     */
+    async findAllReferences(operations) {
+        const references = [];
+        const operationMap = new Map(operations.map(op => [op.originalFilename, op]));
+        // Search all markdown files in the docs directory
+        const searchPattern = path.join(this.config.docsRoot, '**', '*.md');
+        const allFiles = await glob(searchPattern, { windowsPathsNoEscape: true });
+        for (const filePath of allFiles) {
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const lines = content.split('\n');
+                for (let i = 0; i < lines.length; i++) {
+                    const line = lines[i];
+                    // Check for various reference patterns
+                    for (const [originalFilename] of operationMap) {
+                        const refs = this.findReferencesInLine(line, originalFilename, i + 1, filePath);
+                        references.push(...refs);
+                    }
+                }
+            }
+            catch (error) {
+                // Skip files that can't be read
+                continue;
+            }
+        }
+        return references;
+    }
+    /**
+     * Find references to a specific file in a line of text
+     */
+    findReferencesInLine(line, filename, lineNumber, filePath) {
+        const references = [];
+        const baseName = path.basename(filename, '.md');
+        // Markdown link patterns
+        const markdownLinkPattern = new RegExp(`\\[([^\\]]+)\\]\\(([^\\)]*${filename}[^\\)]*)\\)`, 'g');
+        let match;
+        while ((match = markdownLinkPattern.exec(line)) !== null) {
+            references.push({
+                filePath,
+                lineNumber,
+                lineContent: line,
+                referencedFile: filename,
+                referenceType: 'markdown-link'
+            });
+        }
+        // Relative path references
+        if (line.includes(filename) || line.includes(baseName)) {
+            const relativePaths = [
+                new RegExp(`\\.\\/[^\\s]*${filename}`, 'g'),
+                new RegExp(`\\.\\.\/[^\\s]*${filename}`, 'g'),
+                new RegExp(`[^\\s]*\/${filename}`, 'g')
+            ];
+            for (const pattern of relativePaths) {
+                pattern.lastIndex = 0;
+                if (pattern.test(line)) {
+                    references.push({
+                        filePath,
+                        lineNumber,
+                        lineContent: line,
+                        referencedFile: filename,
+                        referenceType: 'relative-path'
+                    });
+                    break;
+                }
+            }
+        }
+        return references;
+    }
+    /**
+     * Update references in files
+     */
+    async updateReferences(references, operations) {
+        const updatedFiles = new Set();
+        const operationMap = new Map(operations.map(op => [op.originalFilename, op.newFilename]));
+        // Group references by file
+        const referencesByFile = new Map();
+        for (const ref of references) {
+            if (!referencesByFile.has(ref.filePath)) {
+                referencesByFile.set(ref.filePath, []);
+            }
+            referencesByFile.get(ref.filePath).push(ref);
+        }
+        for (const [filePath, fileReferences] of referencesByFile) {
+            try {
+                let content = await fs.readFile(filePath, 'utf-8');
+                let modified = false;
+                for (const ref of fileReferences) {
+                    const newFilename = operationMap.get(ref.referencedFile);
+                    if (newFilename) {
+                        // Replace the old filename with the new one
+                        const oldPattern = new RegExp(ref.referencedFile.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g');
+                        const newContent = content.replace(oldPattern, newFilename);
+                        if (newContent !== content) {
+                            content = newContent;
+                            modified = true;
+                        }
+                    }
+                }
+                if (modified) {
+                    await fs.writeFile(filePath, content, 'utf-8');
+                    updatedFiles.add(filePath);
+                }
+            }
+            catch (error) {
+                // Continue with other files if one fails
+                continue;
+            }
+        }
+        return Array.from(updatedFiles);
+    }
+    /**
+     * Create backup of files before migration
+     */
+    async createBackup(operations) {
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const backupDir = this.config.backupDir || path.join(this.config.docsRoot, '.migration-backup');
+        const backupPath = path.join(backupDir, `backup-${timestamp}`);
+        await fs.ensureDir(backupPath);
+        for (const operation of operations) {
+            const relativePath = path.relative(this.config.docsRoot, operation.originalPath);
+            const backupFilePath = path.join(backupPath, relativePath);
+            await fs.ensureDir(path.dirname(backupFilePath));
+            await fs.copy(operation.originalPath, backupFilePath);
+        }
+        return backupPath;
+    }
+    /**
+     * Execute a single migration operation
+     */
+    async executeOperation(operation) {
+        // Ensure target directory exists
+        await fs.ensureDir(path.dirname(operation.newPath));
+        // Move the file
+        await fs.move(operation.originalPath, operation.newPath);
+    }
+    /**
+     * Rollback migration using backup
+     */
+    async rollback(backupDirectory, operations) {
+        for (const operation of operations) {
+            const relativePath = path.relative(this.config.docsRoot, operation.originalPath);
+            const backupFilePath = path.join(backupDirectory, relativePath);
+            if (await fs.pathExists(backupFilePath)) {
+                // Remove the new file if it exists
+                if (await fs.pathExists(operation.newPath)) {
+                    await fs.remove(operation.newPath);
+                }
+                // Restore from backup
+                await fs.move(backupFilePath, operation.originalPath);
+            }
+        }
+    }
+    /**
+     * Validate migration safety
+     */
+    async validateMigration() {
+        const issues = [];
+        try {
+            const plan = await this.generateMigrationPlan();
+            // Check for potential conflicts
+            const newPaths = new Set();
+            for (const operation of plan.operations) {
+                if (newPaths.has(operation.newPath)) {
+                    issues.push(`Duplicate target path: ${operation.newPath}`);
+                }
+                newPaths.add(operation.newPath);
+                // Check if target already exists
+                if (await fs.pathExists(operation.newPath)) {
+                    issues.push(`Target file already exists: ${operation.newPath}`);
+                }
+            }
+            // Check for circular references or dependency issues
+            if (this.config.updateReferences) {
+                const references = await this.findAllReferences(plan.operations);
+                if (references.length > 100) {
+                    issues.push(`Large number of references to update (${references.length}). Consider reviewing manually.`);
+                }
+            }
+            return {
+                isValid: issues.length === 0,
+                issues
+            };
+        }
+        catch (error) {
+            issues.push(`Validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return { isValid: false, issues };
+        }
+    }
+}
+/**
+ * Create a document migrator instance
+ */
+export function createDocumentMigrator(documentNamer, sequenceManager, docsRoot, options) {
+    return new DocumentMigrator({
+        documentNamer,
+        sequenceManager,
+        docsRoot,
+        updateReferences: options?.updateReferences ?? true,
+        backupDir: options?.backupDir
+    });
+}
+//# sourceMappingURL=document-migrator.js.map

package/dist/core/documents/document-migrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-migrator.js","sourceRoot":"","sources":["../../../src/core/documents/document-migrator.ts"],"names":[],"mappings":"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"}

package/dist/core/documents/document-namer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-09-19
+ * @tags: [document, naming, convention, sanitization]
+ * @related: [sequence-manager.ts, document-migrator.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [path]
+ */
+import { DocumentType, SequenceManager } from './sequence-manager.js';
+/**
+ * Configuration for document naming
+ */
+export interface DocumentNamerConfig {
+    /** Sequence manager for number allocation */
+    sequenceManager: SequenceManager;
+    /** Base directory for documents */
+    docsRoot: string;
+    /** Whether to enforce strict naming conventions */
+    strictMode?: boolean;
+}
+/**
+ * Result of a name generation operation
+ */
+export interface NameGenerationResult {
+    /** The generated filename */
+    filename: string;
+    /** The full path to the document */
+    fullPath: string;
+    /** The sequence number used */
+    sequenceNumber: number;
+    /** Whether the name was adjusted for uniqueness */
+    wasAdjusted: boolean;
+    /** Original description if adjusted */
+    originalDescription?: string;
+}
+/**
+ * Options for generating document names
+ */
+export interface GenerateNameOptions {
+    /** Document type */
+    type: DocumentType;
+    /** Description for the document */
+    description: string;
+    /** Whether to check for existing files and adjust if needed */
+    ensureUnique?: boolean;
+    /** Custom sequence number (overrides auto-increment) */
+    customSequence?: number;
+}
+/**
+ * Generates standardized document names following TYPE-###-description.md convention.
+ * Handles sanitization, collision detection, and ensures naming consistency.
+ */
+export declare class DocumentNamer {
+    private config;
+    constructor(config: DocumentNamerConfig);
+    /**
+     * Generate a standardized document name
+     */
+    generateName(options: GenerateNameOptions): Promise<NameGenerationResult>;
+    /**
+     * Parse an existing document name to extract components
+     */
+    parseDocumentName(filename: string): {
+        type: DocumentType;
+        sequence: number;
+        description: string;
+    } | null;
+    /**
+     * Check if a filename follows the standard naming convention
+     */
+    isStandardName(filename: string): boolean;
+    /**
+     * Generate a standard name from a non-standard filename
+     */
+    standardizeName(type: DocumentType, originalFilename: string): Promise<NameGenerationResult>;
+    /**
+     * Get the full path for a document type and filename
+     */
+    getFullPath(type: DocumentType, filename: string): string;
+    /**
+     * Get the directory path for a document type
+     */
+    getTypeDirectory(type: DocumentType): string;
+    /**
+     * Validate document type
+     */
+    private validateDocumentType;
+    /**
+     * Validate description
+     */
+    private validateDescription;
+    /**
+     * Sanitize description for use in filename
+     */
+    private sanitizeDescription;
+    /**
+     * Format the complete filename
+     */
+    private formatFilename;
+    /**
+     * Ensure filename uniqueness by checking filesystem and adjusting if needed
+     */
+    private ensureUniqueness;
+}
+/**
+ * Create a document namer instance
+ */
+export declare function createDocumentNamer(sequenceManager: SequenceManager, docsRoot: string): DocumentNamer;
+//# sourceMappingURL=document-namer.d.ts.map

package/dist/core/documents/document-namer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-namer.d.ts","sourceRoot":"","sources":["../../../src/core/documents/document-namer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,eAAe,EAAE,eAAe,CAAC;IACjC,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,WAAW,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,oBAAoB;IACpB,IAAI,EAAE,YAAY,CAAC;IACnB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAsB;gBAExB,MAAM,EAAE,mBAAmB;IAIvC;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA0C/E;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAczG;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIzC;;OAEG;IACG,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkClG;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAYzD;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAW5C;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;IACH,OAAO,CAAC,cAAc;IAKtB;;OAEG;YACW,gBAAgB;CAoC/B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,CAMrG"}