@aiready/context-analyzer 0.21.23 → 0.21.24

package/src/__tests__/auto-detection.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { buildDependencyGraph } from '../index';
 
 describe('Auto-detection from folder structure', () => {
-  it('should auto-detect domain keywords from folder paths', () => {
+  it('should auto-detect domain keywords from folder paths', async () => {
     const files = [
       {
         file: 'src/payments/process.ts',
@@ -14,7 +14,7 @@ describe('Auto-detection from folder structure', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const paymentsNode = graph.nodes.get('src/payments/process.ts');
     const ordersNode = graph.nodes.get('src/orders/create.ts');
 
@@ -25,7 +25,7 @@ describe('Auto-detection from folder structure', () => {
     expect(ordersNode?.exports[0].inferredDomain).toBe('order');
   });
 
-  it('should detect domains from nested folders', () => {
+  it('should detect domains from nested folders', async () => {
     const files = [
       {
         file: 'src/api/invoices/handler.ts',
@@ -33,14 +33,14 @@ describe('Auto-detection from folder structure', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const node = graph.nodes.get('src/api/invoices/handler.ts');
 
     // Should detect 'invoice' from path (invoices folder)
     expect(node?.exports[0].inferredDomain).toBe('invoice');
   });
 
-  it('should skip common infrastructure folders', () => {
+  it('should skip common infrastructure folders', async () => {
     const files = [
       {
         file: 'src/utils/helpers/format.ts',
@@ -48,14 +48,14 @@ describe('Auto-detection from folder structure', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const node = graph.nodes.get('src/utils/helpers/format.ts');
 
     // 'utils' and 'helpers' should be skipped, no domain detected
     expect(node?.exports[0].inferredDomain).toBe('unknown');
   });
 
-  it('should merge auto-detected with custom keywords', () => {
+  it('should merge auto-detected with custom keywords', async () => {
     const files = [
       {
         file: 'src/receipts/scan.ts',
@@ -63,7 +63,7 @@ describe('Auto-detection from folder structure', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files, {
+    const graph = await buildDependencyGraph(files, {
       domainKeywords: ['receipt'], // Custom keyword
     });
     const node = graph.nodes.get('src/receipts/scan.ts');
@@ -74,7 +74,7 @@ describe('Auto-detection from folder structure', () => {
 });
 
 describe('Import-path domain inference', () => {
-  it('should infer domain from import paths', () => {
+  it('should infer domain from import paths', async () => {
     const files = [
       {
         file: 'src/lib/session.ts',
@@ -89,14 +89,14 @@ describe('Import-path domain inference', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const sessionNode = graph.nodes.get('src/lib/session.ts');
 
     // session.ts imports from '../payments/...' so should infer 'payment' domain
     expect(sessionNode?.exports[0].inferredDomain).toBe('payment');
   });
 
-  it('should infer domain from absolute import paths', () => {
+  it('should infer domain from absolute import paths', async () => {
     const files = [
       {
         file: 'src/components/nav-links.ts',
@@ -111,14 +111,14 @@ describe('Import-path domain inference', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const navNode = graph.nodes.get('src/components/nav-links.ts');
 
     // nav-links.ts imports from '@/orders/...' so should infer 'order' domain
     expect(navNode?.exports[0].inferredDomain).toBe('order');
   });
 
-  it('should use identifier name first before import-path fallback', () => {
+  it('should use identifier name first before import-path fallback', async () => {
     const files = [
       {
         file: 'src/lib/handler.ts',
@@ -129,14 +129,14 @@ describe('Import-path domain inference', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const node = graph.nodes.get('src/lib/handler.ts');
 
     // processInvoice should match 'invoice' from identifier, not 'payment' from imports
     expect(node?.exports[0].inferredDomain).toBe('invoice');
   });
 
-  it('should fall back to import-path when identifier is generic', () => {
+  it('should fall back to import-path when identifier is generic', async () => {
     const files = [
       {
         file: 'src/lib/dynamodb.ts',
@@ -147,7 +147,7 @@ describe('Import-path domain inference', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const node = graph.nodes.get('src/lib/dynamodb.ts');
 
     // 'connect' is generic, should infer 'customer' from import path

package/src/__tests__/fragmentation-coupling.test.ts

@@ -6,7 +6,7 @@ import {
 } from '../index';
 
 describe('fragmentation coupling discount', () => {
-  it('does not apply discount when files have no shared imports', () => {
+  it('does not apply discount when files have no shared imports', async () => {
     const files = [
       {
         file: 'src/billing/a.ts',
@@ -22,7 +22,7 @@ describe('fragmentation coupling discount', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const clusters = detectModuleClusters(graph);
     const cluster = clusters.find((c) => c.domain === 'billing');
     expect(cluster).toBeDefined();
@@ -38,7 +38,7 @@ describe('fragmentation coupling discount', () => {
     expect(cluster!.fragmentationScore).toBeCloseTo(expected, 6);
   });
 
-  it('applies up-to-20% discount when files share identical imports', () => {
+  it('applies up-to-20% discount when files share identical imports', async () => {
     const files = [
       {
         file: 'src/billing/a.ts',
@@ -54,7 +54,7 @@ describe('fragmentation coupling discount', () => {
       },
     ];
 
-    const graph = buildDependencyGraph(files);
+    const graph = await buildDependencyGraph(files);
     const clusters = detectModuleClusters(graph);
     const cluster = clusters.find((c) => c.domain === 'billing');
     expect(cluster).toBeDefined();

package/src/__tests__/python-context.test.ts

@@ -3,9 +3,10 @@ import * as pythonContext from '../analyzers/python-context';
 
 // Mock @aiready/core
 vi.mock('@aiready/core', () => ({
-  getParser: vi.fn((filename: string) => {
+  getParser: vi.fn(async (filename: string) => {
     if (filename.endsWith('.py')) {
       return {
+        initialize: vi.fn().mockResolvedValue(undefined),
         parse: vi.fn(() => ({
           imports: [
             { source: 'os', specifiers: ['path'], isRelative: false },
@@ -16,6 +17,7 @@ vi.mock('@aiready/core', () => ({
             { name: 'my_function', type: 'function' },
           ],
         })),
+        language: 'python',
       };
     }
     return null;
@@ -39,7 +41,7 @@ describe('python-context', () => {
   describe('analyzePythonContext', () => {
     it('should return empty array when parser is not available', async () => {
       const { getParser } = await import('@aiready/core');
-      vi.mocked(getParser).mockReturnValueOnce(null);
+      vi.mocked(getParser).mockResolvedValueOnce(null);
 
       const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 

package/src/__tests__/report/html-report.test.ts

@@ -11,6 +11,17 @@ vi.mock('@aiready/core', () => ({
     `<table><thead><tr>${options.headers.map((h) => `<th>${h}</th>`).join('')}</thead><tbody>${options.rows.map((r) => `<tr>${r.map((c) => `<td>${c}</td>`).join('')}</tr>`).join('')}</tbody></table>`,
   generateReportFooter: (options: any) =>
     `<footer>${options.title} - ${options.packageUrl}</footer>`,
+  generateReportHero: (title: string, subtitle?: string) =>
+    `<div class="hero"><h1>${title}</h1><p>${subtitle}</p></div>`,
+  generateIssueSummary: (
+    critical: number,
+    major: number,
+    minor: number,
+    savings?: number
+  ) =>
+    `<div class="issue-summary">Issues: Critical:${critical}, Major:${major}, Minor:${minor}. Savings: ${savings}</div>`,
+  wrapInCard: (content: string, title?: string) =>
+    `<div class="card"><h2>${title}</h2>${content}</div>`,
 }));
 
 describe('generateHTMLReport', () => {
@@ -98,11 +109,11 @@ describe('generateHTMLReport', () => {
 
     const html = generateHTMLReport(summary, results);
 
-    expect(html).toContain('Issues Summary');
+    expect(html).toContain('Issues:');
     expect(html).toContain('Critical:');
     expect(html).toContain('Major:');
     expect(html).toContain('Minor:');
-    expect(html).toContain('Potential Savings');
+    expect(html).toContain('Savings');
   });
 
   it('should not include issues section when no issues', () => {
@@ -227,6 +238,6 @@ describe('generateHTMLReport', () => {
     const html = generateHTMLReport(summary, results);
 
     // Should show issues section
-    expect(html).toContain('Issues Summary');
+    expect(html).toContain('Issues:');
   });
 });

package/src/__tests__/scoring.test.ts

@@ -38,7 +38,7 @@ describe('Context Scoring', () => {
       const result = calculateContextScore(summary);
 
       expect(result.score).toBeLessThan(70);
-      expect(result.factors.some((f) => f.name === 'Context Budget')).toBe(
+      expect(result.factors.some((f: any) => f.name === 'Context Budget')).toBe(
         true
       );
       expect(result.recommendations.length).toBeGreaterThan(0);
@@ -60,9 +60,13 @@ describe('Context Scoring', () => {
 
       // With depth=12: depthScore=80, rawScore=100*0.35+80*0.25+100*0.25=80, no bonus (frag=0.2 not <0.2)
       expect(result.score).toBe(80);
-      expect(result.factors.some((f) => f.name === 'Import Depth')).toBe(true);
+      expect(result.factors.some((f: any) => f.name === 'Import Depth')).toBe(
+        true
+      );
       expect(
-        result.recommendations.some((r) => r.action.includes('import chains'))
+        result.recommendations.some((r: any) =>
+          r.action.includes('import chains')
+        )
       ).toBe(true);
     });
 
@@ -86,7 +90,9 @@ describe('Context Scoring', () => {
       // Actually frag=0.7 >= 0.2, so no bonus
       // rawScore = 80, no penalties = 80
       expect(result.score).toBeLessThan(85); // Adjusted for new calculation
-      expect(result.factors.some((f) => f.name === 'Fragmentation')).toBe(true);
+      expect(result.factors.some((f: any) => f.name === 'Fragmentation')).toBe(
+        true
+      );
     });
 
     it('should apply critical issue penalties', () => {
@@ -108,9 +114,9 @@ describe('Context Scoring', () => {
       // criticalPenalty = min(20, 5*3) = min(20,15) = 15
       // finalScore = 85 - 15 = 70
       expect(result.score).toBe(70);
-      expect(result.factors.some((f) => f.name === 'Critical Issues')).toBe(
-        true
-      );
+      expect(
+        result.factors.some((f: any) => f.name === 'Critical Issues')
+      ).toBe(true);
     });
 
     it('should handle extreme max budget penalty', () => {
@@ -128,10 +134,10 @@ describe('Context Scoring', () => {
       const result = calculateContextScore(summary);
 
       expect(
-        result.factors.some((f) => f.name === 'Extreme File Detected')
+        result.factors.some((f: any) => f.name === 'Extreme File Detected')
       ).toBe(true);
       expect(
-        result.recommendations.some((r) =>
+        result.recommendations.some((r: any) =>
           r.action.includes('Split large file')
         )
       ).toBe(true);
@@ -214,7 +220,7 @@ describe('Context Scoring', () => {
         // finalScore = 90
         expect(result.score).toBe(90);
         expect(
-          result.factors.some((f) => f.name === 'Well-Organized Codebase')
+          result.factors.some((f: any) => f.name === 'Well-Organized Codebase')
         ).toBe(true);
       });
 
@@ -235,7 +241,7 @@ describe('Context Scoring', () => {
         // No bonus because fragmentation >= 0.2
         expect(result.score).toBe(85); // 100*0.35 + 100*0.25 + 100*0.25 = 85
         expect(
-          result.factors.some((f) => f.name === 'Well-Organized Codebase')
+          result.factors.some((f: any) => f.name === 'Well-Organized Codebase')
         ).toBe(false);
       });
 

package/src/analyzers/python-context.ts

@@ -51,7 +51,7 @@ export async function analyzePythonContext(
   rootDir: string
 ): Promise<PythonContextMetrics[]> {
   const results: PythonContextMetrics[] = [];
-  const parser = getParser('dummy.py');
+  const parser = await getParser('dummy.py');
 
   if (!parser) {
     console.warn('Python parser not available');
@@ -135,7 +135,7 @@ async function buildPythonDependencyGraph(
   rootDir: string
 ): Promise<Map<string, Set<string>>> {
   const graph = new Map<string, Set<string>>();
-  const parser = getParser('dummy.py');
+  const parser = await getParser('dummy.py');
 
   if (!parser) return graph;
 

package/src/ast-utils.ts

@@ -12,14 +12,14 @@ import { inferDomain, extractExports } from './semantic/domain-inference';
  * @returns Array of high-fidelity export metadata.
  * @lastUpdated 2026-03-18
  */
-export function extractExportsWithAST(
+export async function extractExportsWithAST(
   content: string,
   filePath: string,
   domainOptions?: { domainKeywords?: string[] },
   fileImports?: string[]
-): ExportInfo[] {
+): Promise<ExportInfo[]> {
   try {
-    const { exports: astExports } = parseFileExports(content, filePath);
+    const { exports: astExports } = await parseFileExports(content, filePath);
 
     if (astExports.length === 0 && !isTestFile(filePath)) {
       // If AST fails to find anything, we still use regex as a last resort

package/src/graph-builder.ts

@@ -128,10 +128,10 @@ export function extractDomainKeywordsFromPaths(files: FileContent[]): string[] {
  * @param options - Optional configuration for domain detection.
  * @returns Complete dependency graph with nodes, edges, and semantic matrices.
  */
-export function buildDependencyGraph(
+export async function buildDependencyGraph(
   files: FileContent[],
   options?: { domainKeywords?: string[] }
-): DependencyGraph {
+): Promise<DependencyGraph> {
   const nodes = new Map<string, DependencyNode>();
   const edges = new Map<string, Set<string>>();
 
@@ -142,7 +142,7 @@ export function buildDependencyGraph(
 
   for (const { file, content } of files) {
     // 1. Get high-fidelity AST-based imports & exports
-    const { imports: astImports } = parseFileExports(content, file);
+    const { imports: astImports } = await parseFileExports(content, file);
 
     // 2. Resolve imports to absolute paths in the graph
     const resolvedImports = astImports
@@ -152,7 +152,7 @@ export function buildDependencyGraph(
     const importSources = astImports.map((i) => i.source);
 
     // 3. Wrap with platform-specific metadata (v0.11+)
-    const exports = extractExportsWithAST(
+    const exports = await extractExportsWithAST(
       content,
       file,
       { domainKeywords: autoDetectedKeywords },

package/src/mapper.ts

@@ -27,6 +27,12 @@ export interface MappingOptions {
 
 /**
  * Maps a single dependency node to a comprehensive ContextAnalysisResult.
+ *
+ * @param node - The dependency node to map
+ * @param graph - The full dependency graph
+ * @param clusters - All identified module clusters
+ * @param allCircularDeps - All identified circular dependencies
+ * @param options - Mapping options for detailed analysis
  */
 export function mapNodeToResult(
   node: DependencyNode,

package/src/orchestrator.ts

@@ -69,7 +69,7 @@ export async function analyzeContext(
     }))
   );
 
-  const graph = buildDependencyGraph(
+  const graph = await buildDependencyGraph(
     fileContents.filter((f) => !f.file.toLowerCase().endsWith('.py'))
   );
 

package/src/report/html-report.ts

@@ -2,9 +2,12 @@ import { analyzeContext } from '../analyzer';
 import { generateSummary } from '../summary';
 import {
   generateReportHead,
+  generateReportHero,
   generateStatCards,
+  generateIssueSummary,
   generateTable,
   generateReportFooter,
+  wrapInCard,
 } from '@aiready/core';
 
 /**
@@ -33,22 +36,21 @@ export function generateHTMLReport(
     },
   ]);
 
-  let body = `<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 30px; border-radius: 8px; margin-bottom: 30px;">
-    <h1 style="border: none; color: white; margin: 0;">🔍 AIReady Context Analysis Report</h1>
-    <p style="margin: 10px 0 0 0;">Generated on ${new Date().toLocaleString()}</p>
-  </div>
+  const hero = generateReportHero(
+    '🔍 AIReady Context Analysis Report',
+    `Generated on ${new Date().toLocaleString()}`
+  );
+
+  let body = `${hero}
 ${stats}`;
 
   if (totalIssues > 0) {
-    body += `<div class="card" style="margin-bottom: 30px;">
-    <h2>⚠️ Issues Summary</h2>
-    <p>
-      <span class="critical">🔴 Critical: ${summary.criticalIssues}</span> &nbsp;
-      <span class="major">🟡 Major: ${summary.majorIssues}</span> &nbsp;
-      <span class="minor">🔵 Minor: ${summary.minorIssues}</span>
-    </p>
-    <p><strong>Potential Savings:</strong> ${summary.totalPotentialSavings.toLocaleString()} tokens</p>
-  </div>`;
+    body += generateIssueSummary(
+      summary.criticalIssues,
+      summary.majorIssues,
+      summary.minorIssues,
+      summary.totalPotentialSavings
+    );
   }
 
   if (summary.fragmentedModules.length > 0) {
@@ -58,10 +60,13 @@ ${stats}`;
       `${(m.fragmentationScore * 100).toFixed(0)}%`,
       m.totalTokens.toLocaleString(),
     ]);
-    body += `<div class="card" style="margin-bottom: 30px;">
-    <h2>🧩 Fragmented Modules</h2>
-    ${generateTable({ headers: ['Domain', 'Files', 'Fragmentation', 'Token Cost'], rows: fragmentedRows })}
-  </div>`;
+    body += wrapInCard(
+      generateTable({
+        headers: ['Domain', 'Files', 'Fragmentation', 'Token Cost'],
+        rows: fragmentedRows,
+      }),
+      '🧩 Fragmented Modules'
+    );
   }
 
   if (summary.topExpensiveFiles.length > 0) {
@@ -70,10 +75,13 @@ ${stats}`;
       `${f.contextBudget.toLocaleString()} tokens`,
       `<span class="issue-${f.severity}">${f.severity.toUpperCase()}</span>`,
     ]);
-    body += `<div class="card" style="margin-bottom: 30px;">
-    <h2>💸 Most Expensive Files</h2>
-    ${generateTable({ headers: ['File', 'Context Budget', 'Severity'], rows: expensiveRows })}
-  </div>`;
+    body += wrapInCard(
+      generateTable({
+        headers: ['File', 'Context Budget', 'Severity'],
+        rows: expensiveRows,
+      }),
+      '💸 Most Expensive Files'
+    );
   }
 
   const footer = generateReportFooter({