@ginkoai/cli 1.0.0 → 1.4.1

package/dist/utils/reference-parser.js

@@ -0,0 +1,363 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-10-22
+ * @tags: [references, parsing, navigation, context-linking, prd-009, task-010]
+ * @related: [config-loader.ts, log.ts, session-log-manager.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, path, glob]
+ */
+/**
+ * Reference Parser
+ *
+ * Extracts and resolves references between documentation (TASK-XXX, PRD-YYY, ADR-ZZZ, etc.)
+ * Enables bidirectional navigation: session logs → sprints → PRDs → ADRs
+ *
+ * Based on PRD-009 and TASK-010
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { promisify } from 'util';
+import glob from 'glob';
+import { resolveProjectPath, loadProjectConfig } from './config-loader.js';
+// Promisify glob for async/await usage
+const globAsync = promisify(glob);
+/**
+ * Reference patterns for extraction
+ * Matches: TASK-009, PRD-009, ADR-033, FEATURE-024, SPRINT-2025-10-22-name
+ */
+const REFERENCE_PATTERNS = {
+    task: /\bTASK-(\d+)\b/g,
+    feature: /\bFEATURE-(\d+)\b/g,
+    prd: /\bPRD-(\d+)\b/g,
+    adr: /\bADR-(\d+)\b/g,
+    sprint: /\bSPRINT-(\d{4}-\d{2}-\d{2})-[\w-]+\b/g
+};
+/**
+ * Cache for resolved paths to avoid repeated filesystem operations
+ */
+const resolvedPathCache = new Map();
+/**
+ * Extract all references from text
+ *
+ * @param text - Text to search for references
+ * @returns Array of Reference objects
+ *
+ * @example
+ * const refs = extractReferences("Fixed TASK-006 per PRD-009 and ADR-033");
+ * // → [
+ * //   { type: 'task', id: '006', rawText: 'TASK-006' },
+ * //   { type: 'prd', id: '009', rawText: 'PRD-009' },
+ * //   { type: 'adr', id: '033', rawText: 'ADR-033' }
+ * // ]
+ */
+export function extractReferences(text) {
+    const references = [];
+    const seen = new Set(); // Deduplicate
+    for (const [type, pattern] of Object.entries(REFERENCE_PATTERNS)) {
+        // Reset regex state
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const rawText = match[0];
+            const id = match[1] || rawText.split('-').slice(1).join('-');
+            // Deduplicate based on rawText
+            if (!seen.has(rawText)) {
+                seen.add(rawText);
+                references.push({
+                    type: type,
+                    id,
+                    rawText
+                });
+            }
+        }
+    }
+    return references;
+}
+/**
+ * Resolve a reference to its file path
+ * Uses config-loader to map reference types to directory paths
+ *
+ * @param reference - Reference to resolve
+ * @returns ResolvedReference with file path and exists flag
+ *
+ * @example
+ * const resolved = await resolveReference({ type: 'task', id: '006', rawText: 'TASK-006' });
+ * // → {
+ * //   type: 'task',
+ * //   id: '006',
+ * //   rawText: 'TASK-006',
+ * //   filePath: '/path/to/backlog/items/TASK-006.md',
+ * //   exists: true
+ * // }
+ */
+export async function resolveReference(reference) {
+    // Check cache first
+    const cacheKey = `${reference.type}:${reference.id}`;
+    if (resolvedPathCache.has(cacheKey)) {
+        const cachedPath = resolvedPathCache.get(cacheKey);
+        return {
+            ...reference,
+            filePath: cachedPath || null,
+            exists: cachedPath !== null
+        };
+    }
+    try {
+        const config = await loadProjectConfig();
+        // Map reference type to config path key
+        let pathKey;
+        let filePattern;
+        switch (reference.type) {
+            case 'task':
+            case 'feature':
+                pathKey = 'backlog';
+                filePattern = `${reference.rawText}*.md`;
+                break;
+            case 'prd':
+                pathKey = 'prds';
+                filePattern = `PRD-${reference.id}*.md`;
+                break;
+            case 'adr':
+                pathKey = 'adrs';
+                filePattern = `ADR-${reference.id}*.md`;
+                break;
+            case 'sprint':
+                pathKey = 'sprints';
+                filePattern = `${reference.rawText}*.md`;
+                break;
+            default:
+                resolvedPathCache.set(cacheKey, null);
+                return { ...reference, filePath: null, exists: false };
+        }
+        // Resolve directory path
+        const dirPath = await resolveProjectPath(pathKey);
+        // Handle different directory structures
+        let searchPath;
+        if (reference.type === 'task' || reference.type === 'feature') {
+            // Tasks and features are in backlog/items/
+            searchPath = path.join(dirPath, 'items', filePattern);
+        }
+        else {
+            // PRDs, ADRs, sprints are directly in their directories
+            searchPath = path.join(dirPath, filePattern);
+        }
+        // Use glob to find matching files (paths are already absolute)
+        const matches = await globAsync(searchPath);
+        if (matches.length > 0) {
+            // Take first match (should be unique per reference ID)
+            const resolvedPath = matches[0];
+            resolvedPathCache.set(cacheKey, resolvedPath);
+            return {
+                ...reference,
+                filePath: resolvedPath,
+                exists: true
+            };
+        }
+        // No match found
+        resolvedPathCache.set(cacheKey, null);
+        return {
+            ...reference,
+            filePath: null,
+            exists: false
+        };
+    }
+    catch (error) {
+        // Config loading failed or other error
+        resolvedPathCache.set(cacheKey, null);
+        return {
+            ...reference,
+            filePath: null,
+            exists: false
+        };
+    }
+}
+/**
+ * Validate references - check if all targets exist
+ * Non-blocking, returns validation results with warnings
+ *
+ * @param references - Array of references to validate
+ * @returns Validation results with broken references
+ *
+ * @example
+ * const validation = await validateReferences(refs);
+ * if (validation.broken.length > 0) {
+ *   console.warn('Broken references:', validation.broken);
+ * }
+ */
+export async function validateReferences(references) {
+    const resolved = await Promise.all(references.map(ref => resolveReference(ref)));
+    const valid = resolved.filter(r => r.exists);
+    const broken = resolved.filter(r => !r.exists);
+    return { valid, broken };
+}
+/**
+ * Load content of a referenced document
+ *
+ * @param reference - Resolved reference to load
+ * @returns File content or null if doesn't exist
+ *
+ * @example
+ * const content = await getReferencedContent(resolvedRef);
+ * if (content) {
+ *   // Parse and use content
+ * }
+ */
+export async function getReferencedContent(reference) {
+    if (!reference.exists || !reference.filePath) {
+        return null;
+    }
+    try {
+        return await fs.readFile(reference.filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Follow reference chain recursively (with depth limit)
+ * Detects circular references
+ *
+ * @param sourceRef - Starting reference to follow
+ * @param maxDepth - Maximum depth to traverse (default: 3)
+ * @returns ReferenceChain object
+ *
+ * @example
+ * const chain = await getReferenceChain(taskRef, 3);
+ * // → {
+ * //   source: 'TASK-006',
+ * //   chain: [
+ * //     { type: 'feature', id: '024', rawText: 'FEATURE-024', ... },
+ * //     { type: 'prd', id: '009', rawText: 'PRD-009', ... },
+ * //     { type: 'adr', id: '037', rawText: 'ADR-037', ... }
+ * //   ],
+ * //   depth: 3
+ * // }
+ */
+export async function getReferenceChain(sourceRef, maxDepth = 3) {
+    const chain = [];
+    const visited = new Set(); // Circular reference detection
+    async function followRef(ref, depth) {
+        if (depth >= maxDepth)
+            return;
+        const resolved = await resolveReference(ref);
+        const refKey = `${ref.type}:${ref.id}`;
+        // Circular reference detection
+        if (visited.has(refKey)) {
+            return;
+        }
+        visited.add(refKey);
+        if (!resolved.exists || !resolved.filePath) {
+            return;
+        }
+        chain.push(resolved);
+        // Load content and extract more references
+        const content = await getReferencedContent(resolved);
+        if (!content)
+            return;
+        const nestedRefs = extractReferences(content);
+        // Follow nested references
+        for (const nestedRef of nestedRefs) {
+            await followRef(nestedRef, depth + 1);
+        }
+    }
+    await followRef(sourceRef, 0);
+    return {
+        source: sourceRef.rawText,
+        chain,
+        depth: chain.length
+    };
+}
+/**
+ * Format reference chain as human-readable string
+ *
+ * @param chain - Reference chain to format
+ * @returns Formatted string like "TASK-006 → FEATURE-024 → PRD-009 → ADR-037"
+ *
+ * @example
+ * const formatted = formatReferenceChain(chain);
+ * console.log(formatted);
+ * // → "TASK-006 → FEATURE-024 → PRD-009 → ADR-037"
+ */
+export function formatReferenceChain(chain) {
+    if (chain.chain.length === 0) {
+        return chain.source;
+    }
+    const refs = [chain.source, ...chain.chain.map(r => r.rawText)];
+    return refs.join(' → ');
+}
+/**
+ * Get backlinks - find all documents referencing a given document
+ * Useful for understanding what depends on a document
+ *
+ * @param targetRef - Reference to find backlinks for
+ * @param searchPaths - Array of directory paths to search (defaults to all doc paths)
+ * @returns Array of file paths containing references to target
+ *
+ * @example
+ * const backlinks = await getBacklinks({ type: 'prd', id: '009', rawText: 'PRD-009' });
+ * // → [
+ * //   '/path/to/backlog/items/TASK-006.md',
+ * //   '/path/to/backlog/items/TASK-010.md',
+ * //   '/path/to/docs/sprints/SPRINT-2025-10-22-configuration-system.md'
+ * // ]
+ */
+export async function getBacklinks(targetRef, searchPaths) {
+    try {
+        const config = await loadProjectConfig();
+        // Default search paths: all documentation directories
+        if (!searchPaths) {
+            const pathKeys = ['backlog', 'prds', 'adrs', 'sprints', 'sessions'];
+            searchPaths = await Promise.all(pathKeys.map(key => resolveProjectPath(key)));
+        }
+        const backlinks = [];
+        // Search all markdown files in search paths
+        for (const searchPath of searchPaths) {
+            const pattern = path.join(searchPath, '**', '*.md');
+            const files = await globAsync(pattern);
+            for (const file of files) {
+                try {
+                    const content = await fs.readFile(file, 'utf-8');
+                    const refs = extractReferences(content);
+                    // Check if this file references our target
+                    const hasReference = refs.some(r => r.type === targetRef.type && r.id === targetRef.id);
+                    if (hasReference) {
+                        backlinks.push(file);
+                    }
+                }
+                catch {
+                    // Skip files that can't be read
+                    continue;
+                }
+            }
+        }
+        return backlinks;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Clear the resolved path cache
+ * Useful after file changes or for testing
+ */
+export function clearResolvedPathCache() {
+    resolvedPathCache.clear();
+}
+/**
+ * Get all references from a file
+ * Convenience wrapper around extractReferences
+ *
+ * @param filePath - Path to file to extract references from
+ * @returns Array of Reference objects
+ */
+export async function getReferencesFromFile(filePath) {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        return extractReferences(content);
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=reference-parser.js.map

package/dist/utils/reference-parser.js.map

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

package/dist/utils/synthesis.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2025-10-20
+ * @tags: [synthesis, session-resumption, flow-state, context]
+ * @related: [../core/session-log-manager.ts, ../commands/start/start-reflection.ts]
+ * @priority: critical
+ * @complexity: high
+ * @dependencies: [fs, path, simple-git, session-log-manager]
+ */
+import { LogEntry } from '../core/session-log-manager.js';
+/**
+ * Quality tier for progressive fail-safe
+ */
+export type QualityTier = 'rich' | 'medium' | 'basic' | 'minimal';
+/**
+ * Flow state assessment (1-10 scale)
+ */
+export interface FlowState {
+    score: number;
+    energy: string;
+    emotionalTone: string;
+    indicators: {
+        positive: string[];
+        negative: string[];
+    };
+    timeContext: string;
+}
+/**
+ * Work context from session
+ */
+export interface WorkContext {
+    completed: string[];
+    inProgress: string[];
+    blocked: string[];
+}
+/**
+ * Sprint context information
+ */
+export interface SprintContext {
+    goal: string;
+    progress: number;
+    tasksCompleted: string[];
+    tasksRemaining: string[];
+    estimatedCompletion: string;
+}
+/**
+ * Discoveries made during session
+ */
+export interface Discoveries {
+    decisions: LogEntry[];
+    insights: LogEntry[];
+    gotchas: string[];
+}
+/**
+ * Resume point with actionable next step
+ */
+export interface ResumePoint {
+    summary: string;
+    nextAction: string;
+    suggestedCommand: string;
+    contextFiles: string[];
+}
+/**
+ * Complete synthesis output
+ */
+export interface SynthesisOutput {
+    qualityTier: QualityTier;
+    workPerformed: WorkContext;
+    discoveries: Discoveries;
+    sprintContext: SprintContext | null;
+    flowState: FlowState;
+    resumePoint: ResumePoint;
+    warnings: string[];
+}
+/**
+ * Session Synthesis Engine
+ *
+ * Reads session logs and context to synthesize a complete picture
+ * for instant flow state on session resumption.
+ */
+export declare class SessionSynthesizer {
+    private git;
+    private sessionDir;
+    private projectRoot;
+    constructor(sessionDir: string, projectRoot: string);
+    /**
+     * Synthesize from event-based LoadedContext (ADR-043)
+     *
+     * When using event-based context loading, this method converts the loaded events
+     * into a SynthesisOutput for display during session startup.
+     *
+     * @param eventContext - Loaded context from event stream (API)
+     * @param projectRoot - Project root directory for git operations
+     * @returns Synthesis output with resume point based on loaded events
+     */
+    static synthesizeFromEvents(eventContext: any, // LoadedContext from context-loader-events.ts
+    projectRoot: string): Promise<SynthesisOutput>;
+    /**
+     * Analyze work performed (static helper for event-based synthesis)
+     */
+    private static analyzeWorkPerformed;
+    /**
+     * Assess flow state from events (static helper)
+     */
+    private static assessFlowStateFromEvents;
+    /**
+     * Generate resume point from events (static helper)
+     */
+    private static generateResumePointFromEvents;
+    /**
+     * Format time ago (static helper)
+     */
+    private static formatTimeAgoStatic;
+    /**
+     * Check warnings from git (static helper)
+     */
+    private static checkWarningsFromGit;
+    /**
+     * Main synthesis method with progressive fail-safe
+     */
+    synthesize(): Promise<SynthesisOutput>;
+    /**
+     * Tier 1: Synthesize from session log (rich quality)
+     */
+    private trySessionLog;
+    /**
+     * Tier 2: Synthesize from handoff file (medium quality)
+     */
+    private tryHandoff;
+    /**
+     * Tier 3: Synthesize from git log (basic quality)
+     */
+    private tryGitLog;
+    /**
+     * Tier 4: Git status only (minimal quality)
+     */
+    private gitStatusFallback;
+    /**
+     * Analyze work performed from timeline entries
+     */
+    private analyzeWorkPerformed;
+    /**
+     * Load sprint context from docs/sprints/
+     */
+    private loadSprintContext;
+    /**
+     * Parse sprint markdown content
+     */
+    private parseSprintContent;
+    /**
+     * Assess flow state from session log metadata and entries
+     */
+    private assessFlowState;
+    /**
+     * Generate resume point from timeline and work context
+     */
+    private generateResumePoint;
+    /**
+     * Check for warnings based on session state
+     */
+    private checkWarnings;
+    /**
+     * Helper: Format time ago
+     */
+    private formatTimeAgo;
+    /**
+     * Helper: Extract section from handoff markdown
+     */
+    private extractSection;
+    /**
+     * Helper: Assess flow state from handoff
+     */
+    private assessFlowStateFromHandoff;
+    /**
+     * Helper: Generate resume point from handoff
+     */
+    private generateResumePointFromHandoff;
+}
+//# sourceMappingURL=synthesis.d.ts.map

package/dist/utils/synthesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesis.d.ts","sourceRoot":"","sources":["../../src/utils/synthesis.ts"],"names":[],"mappings":"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"}