cc-agentic-framework 1.14.1

package/dist/lib/backlog/milestone-generator.js

@@ -0,0 +1,378 @@
+/**
+ * Milestone Generator Module
+ *
+ * Ported from Python: modules/backlog/src/backlog/milestone_generator.py
+ *
+ * Auto-generates milestone overview files from ticket metadata. Scans all tickets
+ * in the backlog, groups them by milestone field, and generates organized
+ * milestone overview files.
+ *
+ * Features:
+ * - Milestone directory creation with sanitized names
+ * - Milestone index file generation
+ * - Epic and story organization
+ * - Story grouping by parent epic
+ * - Progress tracking and summaries
+ *
+ * @module milestone-generator
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { glob } from 'glob';
+import { parseFrontmatter, stringifyFrontmatter, updateFrontmatter } from '../common/yaml-frontmatter.js';
+import { ensureDirectory, fileExists } from '../common/file-utils.js';
+import { sanitizeMilestoneName } from './milestone-sanitizer.js';
+/**
+ * Group stories by their parent epic.
+ *
+ * Separates stories that have an epic field from standalone stories.
+ *
+ * @param tickets - List of all milestone tickets
+ * @returns Object with stories grouped by epic ID and array of standalone stories
+ */
+function groupStoriesByEpic(tickets) {
+    const byEpic = {};
+    const standalone = [];
+    for (const ticket of tickets) {
+        if (ticket.type === 'stories') {
+            if (ticket.epic) {
+                if (!byEpic[ticket.epic]) {
+                    byEpic[ticket.epic] = [];
+                }
+                byEpic[ticket.epic].push(ticket);
+            }
+            else {
+                standalone.push(ticket);
+            }
+        }
+        else {
+            // Non-stories are treated as standalone
+            standalone.push(ticket);
+        }
+    }
+    return { byEpic, standalone };
+}
+/**
+ * Generate milestone index file content.
+ *
+ * Creates a markdown file with YAML frontmatter containing milestone metadata
+ * and organized sections for epics, stories (grouped by epic), tasks, and bugs.
+ *
+ * @param milestoneId - Sanitized milestone ID (filename without .md)
+ * @param config - Milestone configuration
+ * @param tickets - List of tickets in this milestone
+ * @param epics - List of epics in this milestone
+ * @returns Markdown content with frontmatter
+ */
+function generateMilestoneContent(milestoneId, config, tickets, epics) {
+    // Calculate totals
+    const stories = tickets.filter((t) => t.type === 'stories');
+    const tasks = tickets.filter((t) => t.type === 'tasks');
+    const bugs = tickets.filter((t) => t.type === 'bugs');
+    const storyPoints = stories.reduce((sum, t) => sum + (t.storyPoints || 0), 0);
+    // Build frontmatter
+    const frontmatter = {
+        milestoneId,
+        fullName: config.name,
+        status: 'planning',
+    };
+    // Build markdown content
+    const lines = [];
+    lines.push(`# Milestone: ${milestoneId}`);
+    lines.push('');
+    if (config.description) {
+        lines.push(`**${config.description}**`);
+    }
+    else {
+        lines.push(`**${config.name}**`);
+    }
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- **Epics:** ${epics.length}`);
+    lines.push(`- **Stories:** ${stories.length}`);
+    lines.push(`- **Tasks:** ${tasks.length}`);
+    lines.push(`- **Bugs:** ${bugs.length}`);
+    lines.push(`- **Total Story Points:** ${storyPoints}`);
+    lines.push('');
+    // Epics section
+    if (epics.length > 0) {
+        lines.push('## Epics');
+        lines.push('');
+        for (let i = 0; i < epics.length; i++) {
+            const epic = epics[i];
+            lines.push(`${i + 1}. [${epic.title}](${epic.path}) - Epic`);
+        }
+        lines.push('');
+    }
+    // Stories section (grouped by epic)
+    if (stories.length > 0) {
+        lines.push('## Stories');
+        lines.push('');
+        const { byEpic, standalone } = groupStoriesByEpic(tickets);
+        // Stories with epic
+        const epicIds = Object.keys(byEpic).sort();
+        for (const epicId of epicIds) {
+            lines.push(`### Epic: ${epicId}`);
+            lines.push('');
+            for (const story of byEpic[epicId]) {
+                const sp = story.storyPoints ? ` - ${story.storyPoints} SP` : '';
+                lines.push(`- [${story.title}](${story.path})${sp}`);
+            }
+            lines.push('');
+        }
+        // Standalone stories (no epic)
+        const standaloneStories = standalone.filter((t) => t.type === 'stories');
+        if (standaloneStories.length > 0) {
+            lines.push('### Standalone Stories');
+            lines.push('');
+            for (const story of standaloneStories) {
+                const sp = story.storyPoints ? ` - ${story.storyPoints} SP` : '';
+                lines.push(`- [${story.title}](${story.path})${sp}`);
+            }
+            lines.push('');
+        }
+    }
+    // Tasks section
+    if (tasks.length > 0) {
+        lines.push('## Tasks');
+        lines.push('');
+        for (const task of tasks) {
+            lines.push(`- [${task.title}](${task.path})`);
+        }
+        lines.push('');
+    }
+    // Bugs section
+    if (bugs.length > 0) {
+        lines.push('## Bugs');
+        lines.push('');
+        for (const bug of bugs) {
+            lines.push(`- [${bug.title}](${bug.path})`);
+        }
+        lines.push('');
+    }
+    // Status summary
+    lines.push('---');
+    lines.push('');
+    lines.push(`**Last Generated:** ${new Date().toISOString().split('T')[0]} ${new Date().toTimeString().split(' ')[0]}`);
+    const content = lines.join('\n');
+    return stringifyFrontmatter(frontmatter, content);
+}
+/**
+ * Create a new milestone directory and index file.
+ *
+ * Creates a milestones/{sanitized-name} directory and generates the milestone
+ * index file with frontmatter and initial structure.
+ *
+ * @param config - Milestone configuration
+ * @param basePath - Base directory for milestones (typically backlog root)
+ * @returns Path to created milestone directory
+ * @throws {Error} If milestone directory already exists
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   name: 'APM-R: App: March 2026 (W9, W11, W13)',
+ *   description: 'March 2026 delivery'
+ * };
+ *
+ * const milestonePath = await createMilestoneDirectory(config, '/path/to/backlog');
+ * // Creates: /path/to/backlog/milestones/apm-r-app-march-2026-w9-w11-w13/
+ * ```
+ */
+export async function createMilestoneDirectory(config, basePath) {
+    const milestonesDir = path.join(basePath, 'milestones');
+    // Sanitize milestone name for directory
+    const sanitizedFilename = sanitizeMilestoneName(config.name);
+    const milestoneId = sanitizedFilename.replace('.md', '');
+    const milestonePath = path.join(milestonesDir, milestoneId);
+    const indexPath = path.join(milestonePath, sanitizedFilename);
+    // Check if already exists
+    if (await fileExists(indexPath)) {
+        throw new Error(`Milestone ${config.name} already exists at ${indexPath}`);
+    }
+    // Create directory
+    await ensureDirectory(milestonePath);
+    // Generate initial index with no tickets
+    const content = generateMilestoneContent(milestoneId, config, [], []);
+    // Write index file
+    await fs.writeFile(indexPath, content, 'utf-8');
+    return milestonePath;
+}
+/**
+ * Generate or regenerate milestone index file.
+ *
+ * Creates the milestone index markdown file with frontmatter containing
+ * all milestone metadata and organized sections for epics and tickets.
+ *
+ * @param milestonePath - Path to milestone directory
+ * @param milestoneId - Milestone ID (sanitized filename without .md)
+ * @param config - Milestone configuration
+ * @param tickets - List of tickets in this milestone
+ * @param epics - List of epics in this milestone
+ *
+ * @example
+ * ```typescript
+ * const tickets = [
+ *   {
+ *     type: 'stories',
+ *     title: 'User Login',
+ *     path: '../tickets/stories/STORY-123.md',
+ *     storyPoints: 5,
+ *     epic: 'EPIC-AUTH'
+ *   }
+ * ];
+ *
+ * const epics = [
+ *   {
+ *     type: 'epic',
+ *     title: 'Authentication System',
+ *     path: '../epics/EPIC-AUTH.md'
+ *   }
+ * ];
+ *
+ * await generateMilestoneIndex(milestonePath, 'mar2026', config, tickets, epics);
+ * ```
+ */
+export async function generateMilestoneIndex(milestonePath, milestoneId, config, tickets, epics) {
+    const indexPath = path.join(milestonePath, `${milestoneId}.md`);
+    const content = generateMilestoneContent(milestoneId, config, tickets, epics);
+    await fs.writeFile(indexPath, content, 'utf-8');
+}
+/**
+ * Link an epic to a milestone by updating its frontmatter.
+ *
+ * Adds or updates the 'milestone' field in the epic's frontmatter.
+ *
+ * @param epicPath - Path to epic file
+ * @param milestoneName - Milestone name to link to
+ *
+ * @example
+ * ```typescript
+ * await linkEpicToMilestone('/path/to/epics/EPIC-123.md', 'Mar2026');
+ * // Updates epic frontmatter to include: milestone: Mar2026
+ * ```
+ */
+export async function linkEpicToMilestone(epicPath, milestoneName) {
+    await updateFrontmatter(epicPath, { milestone: milestoneName });
+}
+/**
+ * Scan backlog tickets directory and group by milestone.
+ *
+ * Scans all ticket types (stories, tasks, bugs, spikes) and groups them
+ * by their milestone field. Tickets without a milestone field are skipped.
+ *
+ * @param backlogDir - Path to backlog root directory
+ * @returns Object mapping milestone names to arrays of tickets
+ *
+ * @example
+ * ```typescript
+ * const ticketsByMilestone = await scanTicketsForMilestone('/path/to/backlog');
+ * // Returns: {
+ * //   'Mar2026': [ticket1, ticket2, ...],
+ * //   'Apr2026': [ticket3, ticket4, ...]
+ * // }
+ * ```
+ */
+export async function scanTicketsForMilestone(backlogDir) {
+    const ticketsByMilestone = {};
+    // Scan ticket types
+    const ticketTypes = [
+        'stories',
+        'tasks',
+        'bugs',
+        'spikes',
+    ];
+    for (const ticketType of ticketTypes) {
+        const pattern = path.join(backlogDir, 'tickets', ticketType, '*.md');
+        const files = await glob(pattern, { absolute: true });
+        for (const filePath of files) {
+            // Skip README files
+            if (filePath.endsWith('README.md')) {
+                continue;
+            }
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const { data } = parseFrontmatter(content);
+                // Skip tickets without milestone field
+                if (!data.milestone) {
+                    continue;
+                }
+                const milestone = data.milestone;
+                const filename = path.basename(filePath);
+                const relativePath = `../tickets/${ticketType}/${filename}`;
+                const ticket = {
+                    type: ticketType,
+                    title: data.title || filename,
+                    path: relativePath,
+                    storyPoints: data.storyPoints || 0,
+                    epic: data.epic,
+                };
+                if (!ticketsByMilestone[milestone]) {
+                    ticketsByMilestone[milestone] = [];
+                }
+                ticketsByMilestone[milestone].push(ticket);
+            }
+            catch (error) {
+                // Skip files that can't be read or parsed
+                console.warn(`Warning: Could not process ${filePath}:`, error);
+            }
+        }
+    }
+    return ticketsByMilestone;
+}
+/**
+ * Scan backlog epics directory and group by milestone.
+ *
+ * Scans all epics and groups them by their milestone field.
+ * Epics without a milestone field are skipped.
+ *
+ * @param backlogDir - Path to backlog root directory
+ * @returns Object mapping milestone names to arrays of epics
+ *
+ * @example
+ * ```typescript
+ * const epicsByMilestone = await scanEpicsForMilestone('/path/to/backlog');
+ * // Returns: {
+ * //   'Mar2026': [epic1, epic2, ...],
+ * //   'Apr2026': [epic3, epic4, ...]
+ * // }
+ * ```
+ */
+export async function scanEpicsForMilestone(backlogDir) {
+    const epicsByMilestone = {};
+    const pattern = path.join(backlogDir, 'epics', '*.md');
+    const files = await glob(pattern, { absolute: true });
+    for (const filePath of files) {
+        // Skip README files
+        if (filePath.endsWith('README.md')) {
+            continue;
+        }
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const { data } = parseFrontmatter(content);
+            // Skip epics without milestone field
+            if (!data.milestone) {
+                continue;
+            }
+            const milestone = data.milestone;
+            const filename = path.basename(filePath);
+            const relativePath = `../epics/${filename}`;
+            const epic = {
+                type: 'epic',
+                title: data.title || filename,
+                path: relativePath,
+            };
+            if (!epicsByMilestone[milestone]) {
+                epicsByMilestone[milestone] = [];
+            }
+            epicsByMilestone[milestone].push(epic);
+        }
+        catch (error) {
+            // Skip files that can't be read or parsed
+            console.warn(`Warning: Could not process ${filePath}:`, error);
+        }
+    }
+    return epicsByMilestone;
+}
+//# sourceMappingURL=milestone-generator.js.map

package/dist/lib/backlog/milestone-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestone-generator.js","sourceRoot":"","sources":["../../../src/lib/backlog/milestone-generator.ts"],"names":[],"mappings":"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"}

package/dist/lib/backlog/milestone-migrator.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Milestone Migration Module
+ *
+ * Ported from Python: modules/backlog/src/backlog/migrate_milestones.py
+ *                     modules/backlog/src/backlog/validate_milestone_migration.py
+ *
+ * Handles migration of milestone files from local ID naming convention
+ * (Jan2026.md) to Jira source-of-truth naming (apm-r-app-january-2026-w51-w1-w3.md).
+ *
+ * Features:
+ * - Detect old milestone format
+ * - Convert to new format preserving data
+ * - Validate migration success
+ * - Track changes for rollback
+ *
+ * @module milestone-migrator
+ */
+/**
+ * Milestone metadata extracted from frontmatter
+ */
+export interface MilestoneMetadata {
+    /** Jira milestone name */
+    milestoneName?: string;
+    /** Jira milestone ID */
+    jiraMilestoneId?: string;
+}
+/**
+ * Migration plan entry for a single milestone
+ */
+export interface MigrationPlanEntry {
+    /** New sanitized filename */
+    newFilename: string;
+    /** Original Jira milestone name */
+    milestoneName?: string;
+    /** Jira milestone ID */
+    jiraMilestoneId?: string;
+}
+/**
+ * Complete migration plan mapping old filenames to new filenames
+ */
+export interface MigrationPlan {
+    [oldFilename: string]: MigrationPlanEntry;
+}
+/**
+ * Migration changes tracking data
+ */
+export interface MigrationChanges {
+    /** Timestamp of migration */
+    timestamp: string;
+    /** Old filename to new filename mapping */
+    milestoneRenames: {
+        [oldName: string]: string;
+    };
+    /** List of ticket files updated */
+    ticketUpdates: string[];
+}
+/**
+ * Validation result for milestone architecture
+ */
+export interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** List of errors found */
+    errors: string[];
+    /** List of warnings found */
+    warnings: string[];
+}
+/**
+ * Track migration changes for reporting and rollback
+ */
+export declare class MigrationTracker {
+    changes: MigrationChanges;
+    private trackerFile;
+    constructor(trackerFile?: string);
+    /**
+     * Track a milestone file rename
+     */
+    addRename(oldName: string, newName: string): void;
+    /**
+     * Track a ticket file update
+     */
+    addTicketUpdate(ticketPath: string): void;
+    /**
+     * Save migration tracking file
+     */
+    save(): Promise<void>;
+    /**
+     * Load migration tracking file
+     */
+    static load(trackerFile?: string): Promise<MigrationChanges | null>;
+}
+/**
+ * Extract milestone name and Jira ID from milestone file frontmatter.
+ *
+ * @param milestoneFile - Path to milestone markdown file
+ * @returns Milestone metadata or empty object if not found
+ * @throws {Error} If file cannot be read
+ */
+export declare function readMilestoneMetadata(milestoneFile: string): Promise<MilestoneMetadata>;
+/**
+ * Build migration plan for all milestones in a directory.
+ *
+ * Scans milestone directory and identifies files that need migration.
+ * Skips already-sanitized files and files without Jira metadata.
+ *
+ * @param milestonesDir - Path to milestones directory
+ * @returns Migration plan mapping old filenames to new filenames
+ *
+ * @example
+ * ```typescript
+ * const plan = await getMigrationPlan('/path/to/backlog/milestones');
+ * // Returns: {
+ * //   'Jan2026.md': {
+ * //     newFilename: 'apm-r-app-january-2026-w51-w1-w3.md',
+ * //     milestoneName: 'APM-R: App: January 2026 (W51, W1, W3)',
+ * //     jiraMilestoneId: undefined
+ * //   }
+ * // }
+ * ```
+ */
+export declare function getMigrationPlan(milestonesDir: string): Promise<MigrationPlan>;
+/**
+ * Apply the migration plan to rename milestone files.
+ *
+ * Renames files according to the migration plan and tracks all changes.
+ * In dry-run mode, no files are actually changed.
+ *
+ * @param backlogDir - Base backlog directory
+ * @param plan - Migration plan from getMigrationPlan()
+ * @param dryRun - If true, preview changes only without applying
+ * @returns Migration tracker with all changes recorded
+ *
+ * @example
+ * ```typescript
+ * const plan = await getMigrationPlan(milestonesDir);
+ * const tracker = await applyMigration('/path/to/backlog', plan, false);
+ * await tracker.save(); // Save for rollback capability
+ * ```
+ */
+export declare function applyMigration(backlogDir: string, plan: MigrationPlan, dryRun?: boolean): Promise<MigrationTracker>;
+/**
+ * Validate milestone architecture compliance.
+ *
+ * Checks that:
+ * 1. Milestone files use sanitized Jira names for filenames
+ * 2. Ticket files don't have deprecated 'milestone:' field
+ * 3. Milestone files have Jira metadata (milestoneName or jiraMilestoneId)
+ *
+ * @param backlogDir - Path to backlog directory
+ * @param verbose - If true, show detailed validation for each file
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await validateMilestoneArchitecture('/path/to/backlog', false);
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateMilestoneArchitecture(backlogDir: string, verbose?: boolean): Promise<ValidationResult>;
+/**
+ * Print migration plan for user review
+ *
+ * @param plan - Migration plan to display
+ */
+export declare function printMigrationPlan(plan: MigrationPlan): void;
+/**
+ * Print validation results
+ *
+ * @param result - Validation result to display
+ */
+export declare function printValidationResults(result: ValidationResult): void;
+//# sourceMappingURL=milestone-migrator.d.ts.map

package/dist/lib/backlog/milestone-migrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestone-migrator.d.ts","sourceRoot":"","sources":["../../../src/lib/backlog/milestone-migrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0BAA0B;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,gBAAgB,EAAE;QAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChD,mCAAmC;IACnC,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,2BAA2B;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IACpB,OAAO,EAAE,gBAAgB,CAAC;IACjC,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,CAAC,EAAE,MAAM;IAShC;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjD;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIzC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;WACU,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAO1E;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAQ7F;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAqCpF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,aAAa,EACnB,MAAM,GAAE,OAAe,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAkC3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,OAAe,GACvB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAsHD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CA8B5D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAsCrE"}