mcp-adr-analysis-server 2.1.9 → 2.1.19

package/dist/src/resources/project-status-resource.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Project Status Resource
+ * Provides comprehensive project status and health metrics
+ */
+import { ResourceGenerationResult } from './index.js';
+export interface ProjectStatus {
+    version: string;
+    timestamp: string;
+    overallHealth: 'excellent' | 'good' | 'fair' | 'poor';
+    components: {
+        tasks: any;
+        research: any;
+        rules: any;
+    };
+    metrics: {
+        completionRate: number;
+        qualityScore: number;
+        resourceCoverage: number;
+    };
+}
+/**
+ * Generate comprehensive project status resource aggregating data from multiple sources.
+ *
+ * This function provides a holistic view of the project's current state by combining
+ * task management, research documentation, and rule compliance metrics.
+ *
+ * @returns Promise resolving to resource generation result containing:
+ *   - data: Complete project status including health metrics and component breakdown
+ *   - contentType: "application/json"
+ *   - lastModified: ISO timestamp of generation
+ *   - cacheKey: Unique identifier for caching
+ *   - ttl: Cache duration (120 seconds)
+ *   - etag: Entity tag for cache validation
+ *
+ * @throws {McpAdrError} When resource generation fails due to:
+ *   - Inability to generate todo/research/rules resources
+ *   - Invalid data structure from component resources
+ *   - Cache operation failures
+ *
+ * @example
+ * ```typescript
+ * const status = await generateProjectStatusResource();
+ * console.log(`Project health: ${status.data.overallHealth}`);
+ * console.log(`Completion rate: ${status.data.metrics.completionRate}%`);
+ *
+ * // Expected output structure:
+ * {
+ *   data: {
+ *     version: "1.0.0",
+ *     timestamp: "2025-10-12T17:00:00.000Z",
+ *     overallHealth: "good",
+ *     components: {
+ *       tasks: { summary: { total: 10, completed: 7 } },
+ *       research: { summary: { total: 5 } },
+ *       rules: { summary: { enabled: 15, total: 20 } }
+ *     },
+ *     metrics: {
+ *       completionRate: 70,
+ *       qualityScore: 85,
+ *       resourceCoverage: 35
+ *     }
+ *   },
+ *   contentType: "application/json",
+ *   cacheKey: "project-status:current",
+ *   ttl: 120
+ * }
+ * ```
+ *
+ * @since v2.0.0
+ * @see {@link generateTodoListResource} for task management data
+ * @see {@link generateResearchIndexResource} for research documentation
+ * @see {@link generateRuleCatalogResource} for rule compliance
+ */
+export declare function generateProjectStatusResource(): Promise<ResourceGenerationResult>;
+//# sourceMappingURL=project-status-resource.d.ts.map

package/dist/src/resources/project-status-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-status-resource.d.ts","sourceRoot":"","sources":["../../../src/resources/project-status-resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAKtD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACtD,UAAU,EAAE;QACV,KAAK,EAAE,GAAG,CAAC;QACX,QAAQ,EAAE,GAAG,CAAC;QACd,KAAK,EAAE,GAAG,CAAC;KACZ,CAAC;IACF,OAAO,EAAE;QACP,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAwFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAwDvF"}

package/dist/src/resources/project-status-resource.js

@@ -0,0 +1,189 @@
+/**
+ * Project Status Resource
+ * Provides comprehensive project status and health metrics
+ */
+import { McpAdrError } from '../types/index.js';
+import { resourceCache, generateETag } from './resource-cache.js';
+import { generateTodoListResource } from './todo-list-resource.js';
+import { generateResearchIndexResource } from './research-index-resource.js';
+import { generateRuleCatalogResource } from './rule-catalog-resource.js';
+/**
+ * Calculate overall health score
+ */
+function calculateOverallHealth(components) {
+    // Simple heuristic based on completion rates and issues
+    let score = 0;
+    let maxScore = 0;
+    for (const component of components) {
+        if (component && typeof component === 'object') {
+            maxScore += 100;
+            if (component.summary) {
+                // Score based on completion
+                if (component.summary.completed !== undefined && component.summary.total !== undefined) {
+                    const completionRate = component.summary.total > 0
+                        ? (component.summary.completed / component.summary.total) * 100
+                        : 100;
+                    score += completionRate;
+                }
+                else {
+                    score += 75; // Neutral score if no completion data
+                }
+            }
+            else {
+                score += 50; // Lower score for missing data
+            }
+        }
+    }
+    const avgScore = maxScore > 0 ? (score / maxScore) * 100 : 50;
+    if (avgScore >= 90)
+        return 'excellent';
+    if (avgScore >= 75)
+        return 'good';
+    if (avgScore >= 50)
+        return 'fair';
+    return 'poor';
+}
+/**
+ * Calculate completion rate from todo statistics
+ */
+function calculateCompletionRate(todoStats) {
+    if (!todoStats || !todoStats.summary)
+        return 0;
+    const { total, completed } = todoStats.summary;
+    return total > 0 ? (completed / total) * 100 : 0;
+}
+/**
+ * Calculate quality score from various metrics
+ */
+function calculateQualityScore(components) {
+    // Simplified quality score calculation
+    // In production, this would analyze code quality, test coverage, etc.
+    let score = 75; // Baseline score
+    // Adjust based on rule compliance
+    if (components.rules && components.rules.summary) {
+        const { enabled, total } = components.rules.summary;
+        if (total > 0) {
+            score += (enabled / total) * 10;
+        }
+    }
+    // Adjust based on research documentation
+    if (components.research && components.research.summary) {
+        const { total } = components.research.summary;
+        if (total > 5) {
+            score += 5; // Bonus for good documentation
+        }
+    }
+    return Math.min(Math.max(score, 0), 100);
+}
+/**
+ * Calculate resource coverage
+ */
+function calculateResourceCoverage() {
+    // Currently: 7 resources (3 original refactored + 4 new)
+    // Target: 20+ resources
+    const current = 7;
+    const target = 20;
+    return (current / target) * 100;
+}
+/**
+ * Generate comprehensive project status resource aggregating data from multiple sources.
+ *
+ * This function provides a holistic view of the project's current state by combining
+ * task management, research documentation, and rule compliance metrics.
+ *
+ * @returns Promise resolving to resource generation result containing:
+ *   - data: Complete project status including health metrics and component breakdown
+ *   - contentType: "application/json"
+ *   - lastModified: ISO timestamp of generation
+ *   - cacheKey: Unique identifier for caching
+ *   - ttl: Cache duration (120 seconds)
+ *   - etag: Entity tag for cache validation
+ *
+ * @throws {McpAdrError} When resource generation fails due to:
+ *   - Inability to generate todo/research/rules resources
+ *   - Invalid data structure from component resources
+ *   - Cache operation failures
+ *
+ * @example
+ * ```typescript
+ * const status = await generateProjectStatusResource();
+ * console.log(`Project health: ${status.data.overallHealth}`);
+ * console.log(`Completion rate: ${status.data.metrics.completionRate}%`);
+ *
+ * // Expected output structure:
+ * {
+ *   data: {
+ *     version: "1.0.0",
+ *     timestamp: "2025-10-12T17:00:00.000Z",
+ *     overallHealth: "good",
+ *     components: {
+ *       tasks: { summary: { total: 10, completed: 7 } },
+ *       research: { summary: { total: 5 } },
+ *       rules: { summary: { enabled: 15, total: 20 } }
+ *     },
+ *     metrics: {
+ *       completionRate: 70,
+ *       qualityScore: 85,
+ *       resourceCoverage: 35
+ *     }
+ *   },
+ *   contentType: "application/json",
+ *   cacheKey: "project-status:current",
+ *   ttl: 120
+ * }
+ * ```
+ *
+ * @since v2.0.0
+ * @see {@link generateTodoListResource} for task management data
+ * @see {@link generateResearchIndexResource} for research documentation
+ * @see {@link generateRuleCatalogResource} for rule compliance
+ */
+export async function generateProjectStatusResource() {
+    try {
+        const cacheKey = 'project-status:current';
+        // Check cache
+        const cached = await resourceCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        // Aggregate status from multiple sources
+        const todoResource = await generateTodoListResource();
+        const researchResource = await generateResearchIndexResource();
+        const rulesResource = await generateRuleCatalogResource();
+        const components = {
+            tasks: todoResource.data,
+            research: researchResource.data,
+            rules: rulesResource.data,
+        };
+        const projectStatusData = {
+            version: '1.0.0',
+            timestamp: new Date().toISOString(),
+            overallHealth: calculateOverallHealth([
+                todoResource.data,
+                researchResource.data,
+                rulesResource.data,
+            ]),
+            components,
+            metrics: {
+                completionRate: calculateCompletionRate(todoResource.data),
+                qualityScore: calculateQualityScore(components),
+                resourceCoverage: calculateResourceCoverage(),
+            },
+        };
+        const result = {
+            data: projectStatusData,
+            contentType: 'application/json',
+            lastModified: new Date().toISOString(),
+            cacheKey,
+            ttl: 120, // 2 minutes cache (status changes frequently)
+            etag: generateETag(projectStatusData),
+        };
+        // Cache result
+        resourceCache.set(cacheKey, result, result.ttl);
+        return result;
+    }
+    catch (error) {
+        throw new McpAdrError(`Failed to generate project status resource: ${error instanceof Error ? error.message : String(error)}`, 'RESOURCE_GENERATION_ERROR');
+    }
+}
+//# sourceMappingURL=project-status-resource.js.map

package/dist/src/resources/project-status-resource.js.map

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

package/dist/src/resources/research-by-topic-resource.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Research by Topic Resource - Topic-specific research documents
+ * URI Pattern: adr://research/{topic}
+ */
+import { URLSearchParams } from 'url';
+import { ResourceGenerationResult } from './index.js';
+export interface ResearchDocument {
+    id: string;
+    title: string;
+    topic: string;
+    path: string;
+    content: string;
+    lastModified: string;
+    wordCount: number;
+    size: number;
+}
+/**
+ * Generate research by topic resource
+ */
+export declare function generateResearchByTopicResource(params: Record<string, string>, _searchParams: URLSearchParams): Promise<ResourceGenerationResult>;
+//# sourceMappingURL=research-by-topic-resource.d.ts.map

package/dist/src/resources/research-by-topic-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-by-topic-resource.d.ts","sourceRoot":"","sources":["../../../src/resources/research-by-topic-resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAKtC,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAGtD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AA8DD;;GAEG;AACH,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,aAAa,EAAE,eAAe,GAC7B,OAAO,CAAC,wBAAwB,CAAC,CAgFnC"}

package/dist/src/resources/research-by-topic-resource.js

@@ -0,0 +1,125 @@
+/**
+ * Research by Topic Resource - Topic-specific research documents
+ * URI Pattern: adr://research/{topic}
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { McpAdrError } from '../types/index.js';
+import { resourceCache, generateETag } from './resource-cache.js';
+import { resourceRouter } from './resource-router.js';
+/**
+ * Extract title from markdown content
+ */
+function extractTitle(content) {
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    if (titleMatch && titleMatch[1]) {
+        return titleMatch[1].trim();
+    }
+    return 'Untitled';
+}
+/**
+ * Generate topic summary from documents
+ */
+function generateTopicSummary(documents) {
+    const firstDoc = documents[0];
+    return {
+        totalWords: documents.reduce((sum, doc) => sum + doc.wordCount, 0),
+        totalSize: documents.reduce((sum, doc) => sum + doc.size, 0),
+        lastUpdated: documents.length > 0 && firstDoc
+            ? documents.reduce((latest, doc) => (doc.lastModified > latest ? doc.lastModified : latest), firstDoc.lastModified)
+            : new Date().toISOString(),
+        documentCount: documents.length,
+    };
+}
+/**
+ * Check if a file matches the topic
+ */
+function matchesTopic(filename, content, topic) {
+    const normalizedTopic = topic.toLowerCase().replace(/-/g, '_');
+    const normalizedFilename = filename.toLowerCase();
+    const normalizedContent = content.toLowerCase();
+    // Check filename
+    if (normalizedFilename.includes(topic.toLowerCase()) ||
+        normalizedFilename.includes(normalizedTopic)) {
+        return true;
+    }
+    // Check content (first 1000 characters for keywords)
+    const contentPreview = normalizedContent.substring(0, 1000);
+    if (contentPreview.includes(topic.toLowerCase()) || contentPreview.includes(normalizedTopic)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Generate research by topic resource
+ */
+export async function generateResearchByTopicResource(params, _searchParams) {
+    const topic = params['topic'];
+    if (!topic) {
+        throw new McpAdrError('Missing required parameter: topic', 'INVALID_PARAMS');
+    }
+    const cacheKey = `research-topic:${topic}`;
+    // Check cache
+    const cached = await resourceCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const researchDirs = ['docs/research', 'custom/research'];
+    const relatedDocs = [];
+    // Scan research directories
+    for (const dir of researchDirs) {
+        const fullPath = path.resolve(process.cwd(), dir);
+        try {
+            const files = await fs.readdir(fullPath);
+            for (const file of files) {
+                if (file.endsWith('.md')) {
+                    const filePath = path.join(fullPath, file);
+                    const content = await fs.readFile(filePath, 'utf-8');
+                    // Check if file matches topic
+                    if (matchesTopic(file, content, topic)) {
+                        const stats = await fs.stat(filePath);
+                        relatedDocs.push({
+                            id: file.replace('.md', ''),
+                            title: extractTitle(content),
+                            topic,
+                            path: path.join(dir, file),
+                            content,
+                            lastModified: stats.mtime.toISOString(),
+                            wordCount: content.split(/\s+/).length,
+                            size: stats.size,
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist or can't be read, skip silently
+            continue;
+        }
+    }
+    // Sort by last modified (newest first)
+    relatedDocs.sort((a, b) => b.lastModified.localeCompare(a.lastModified));
+    if (relatedDocs.length === 0) {
+        throw new McpAdrError(`No research documents found for topic: ${topic}`, 'RESOURCE_NOT_FOUND');
+    }
+    const topicData = {
+        topic,
+        documentCount: relatedDocs.length,
+        documents: relatedDocs,
+        summary: generateTopicSummary(relatedDocs),
+    };
+    const result = {
+        data: topicData,
+        contentType: 'application/json',
+        lastModified: new Date().toISOString(),
+        cacheKey,
+        ttl: 600, // 10 minutes cache
+        etag: generateETag(topicData),
+    };
+    // Cache result
+    resourceCache.set(cacheKey, result, result.ttl);
+    return result;
+}
+// Register route
+resourceRouter.register('/research/{topic}', generateResearchByTopicResource, 'Research documents filtered by topic');
+//# sourceMappingURL=research-by-topic-resource.js.map

package/dist/src/resources/research-by-topic-resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-by-topic-resource.js","sourceRoot":"","sources":["../../../src/resources/research-by-topic-resource.ts"],"names":[],"mappings":"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"}

package/dist/src/resources/research-index-resource.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Research Index Resource
+ * Provides access to research documents and findings
+ */
+import { ResourceGenerationResult } from './index.js';
+export interface ResearchDocument {
+    id: string;
+    title: string;
+    topic: string;
+    path: string;
+    lastModified: string;
+    wordCount: number;
+    size: number;
+}
+/**
+ * Generate comprehensive research document index resource with metadata and categorization.
+ *
+ * Scans project research directories and builds an index of all research documents with
+ * metadata including titles, topics, word counts, file sizes, and last modified dates.
+ * Supports multiple research directories for organizational flexibility.
+ *
+ * **Scanned Directories:**
+ * - `docs/research/` - Primary research documentation
+ * - `custom/research/` - Custom user research notes
+ *
+ * **Document Extraction:**
+ * - Title: Extracted from first H1 heading or filename
+ * - Topic: Derived from filename prefix or directory structure
+ * - Metadata: Word count, file size, last modified timestamp
+ *
+ * @returns Promise resolving to resource generation result containing:
+ *   - data: Complete research index with documents array and summary statistics
+ *   - contentType: "application/json"
+ *   - lastModified: ISO timestamp of generation
+ *   - cacheKey: "research-index:current"
+ *   - ttl: Cache duration (300 seconds / 5 minutes)
+ *   - etag: Entity tag for cache validation
+ *
+ * @throws {McpAdrError} When research index generation fails due to:
+ *   - RESOURCE_GENERATION_ERROR: File system access errors or markdown parsing failures
+ *   - Cache operation failures
+ *
+ * @example
+ * ```typescript
+ * const researchIndex = await generateResearchIndexResource();
+ *
+ * console.log(`Total research documents: ${researchIndex.data.summary.total}`);
+ * console.log(`Topics covered: ${researchIndex.data.summary.byTopic.length}`);
+ * console.log(`Total words: ${researchIndex.data.summary.totalWords}`);
+ *
+ * // Find research by topic
+ * const architectureDocs = researchIndex.data.documents.filter(
+ *   doc => doc.topic === 'architecture'
+ * );
+ * console.log(`Architecture research docs: ${architectureDocs.length}`);
+ *
+ * // Sort by recency
+ * const recentDocs = researchIndex.data.documents
+ *   .sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime())
+ *   .slice(0, 5);
+ *
+ * // Expected output structure:
+ * {
+ *   data: {
+ *     version: "1.0.0",
+ *     timestamp: "2025-10-12T17:00:00.000Z",
+ *     summary: {
+ *       total: 55,
+ *       byTopic: {
+ *         "performance": 12,
+ *         "security": 8,
+ *         "architecture": 15
+ *       },
+ *       totalWords: 45000,
+ *       averageWordCount: 818
+ *     },
+ *     documents: [
+ *       {
+ *         id: "perform_research_research_001",
+ *         title: "TypeScript Performance Optimization",
+ *         topic: "performance",
+ *         path: "docs/research/perform_research_research_001.md",
+ *         lastModified: "2025-10-10T12:00:00.000Z",
+ *         wordCount: 1250,
+ *         size: 8192
+ *       }
+ *     ]
+ *   },
+ *   contentType: "application/json",
+ *   cacheKey: "research-index:current",
+ *   ttl: 300
+ * }
+ * ```
+ *
+ * @since v2.0.0
+ * @see {@link extractTitle} for title extraction logic
+ * @see {@link extractTopic} for topic categorization
+ */
+export declare function generateResearchIndexResource(): Promise<ResourceGenerationResult>;
+//# sourceMappingURL=research-index-resource.d.ts.map

package/dist/src/resources/research-index-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-index-resource.d.ts","sourceRoot":"","sources":["../../../src/resources/research-index-resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAkDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AACH,wBAAsB,6BAA6B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CA+EvF"}