@aiready/core 0.23.2 → 0.23.3

package/dist/client-BxGrPuuN.d.mts

@@ -0,0 +1,1191 @@
+import { z } from 'zod';
+
+/**
+ * Severity levels for all AIReady issues.
+ */
+declare enum Severity {
+  Critical = 'critical',
+  Major = 'major',
+  Minor = 'minor',
+  Info = 'info',
+}
+/**
+ * Canonical Tool Names (IDs)
+ * Used everywhere as the single source of truth for tool identification.
+ */
+declare enum ToolName {
+  PatternDetect = 'pattern-detect',
+  ContextAnalyzer = 'context-analyzer',
+  NamingConsistency = 'naming-consistency',
+  AiSignalClarity = 'ai-signal-clarity',
+  AgentGrounding = 'agent-grounding',
+  TestabilityIndex = 'testability-index',
+  DocDrift = 'doc-drift',
+  DependencyHealth = 'dependency-health',
+  ChangeAmplification = 'change-amplification',
+  CognitiveLoad = 'cognitive-load',
+  PatternEntropy = 'pattern-entropy',
+  ConceptCohesion = 'concept-cohesion',
+  SemanticDistance = 'semantic-distance',
+}
+/**
+ * Standardized issue types across all AIReady tools.
+ */
+declare enum IssueType {
+  DuplicatePattern = 'duplicate-pattern',
+  PatternInconsistency = 'pattern-inconsistency',
+  ContextFragmentation = 'context-fragmentation',
+  DependencyHealth = 'dependency-health',
+  CircularDependency = 'circular-dependency',
+  DocDrift = 'doc-drift',
+  NamingInconsistency = 'naming-inconsistency',
+  NamingQuality = 'naming-quality',
+  ArchitectureInconsistency = 'architecture-inconsistency',
+  DeadCode = 'dead-code',
+  MissingTypes = 'missing-types',
+  MagicLiteral = 'magic-literal',
+  BooleanTrap = 'boolean-trap',
+  AiSignalClarity = 'ai-signal-clarity',
+  LowTestability = 'low-testability',
+  AgentNavigationFailure = 'agent-navigation-failure',
+  AmbiguousApi = 'ambiguous-api',
+  ChangeAmplification = 'change-amplification',
+}
+/**
+ * AI Model Context Tiers.
+ */
+declare enum ModelTier {
+  Compact = 'compact',
+  Standard = 'standard',
+  Extended = 'extended',
+  Frontier = 'frontier',
+}
+/**
+ * Source code location schema.
+ */
+/** Zod schema for Location object */
+declare const LocationSchema: z.ZodObject<
+  {
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    endColumn: z.ZodOptional<z.ZodNumber>;
+  },
+  z.core.$strip
+>;
+type Location = z.infer<typeof LocationSchema>;
+/**
+ * Standard Issue schema.
+ */
+/** Zod schema for Issue object */
+declare const IssueSchema: z.ZodObject<
+  {
+    type: z.ZodEnum<typeof IssueType>;
+    severity: z.ZodEnum<typeof Severity>;
+    message: z.ZodString;
+    location: z.ZodObject<
+      {
+        file: z.ZodString;
+        line: z.ZodNumber;
+        column: z.ZodOptional<z.ZodNumber>;
+        endLine: z.ZodOptional<z.ZodNumber>;
+        endColumn: z.ZodOptional<z.ZodNumber>;
+      },
+      z.core.$strip
+    >;
+    suggestion: z.ZodOptional<z.ZodString>;
+  },
+  z.core.$strip
+>;
+type Issue = z.infer<typeof IssueSchema>;
+/**
+ * Standard Metrics schema.
+ */
+/** Zod schema for Metrics object */
+declare const MetricsSchema: z.ZodObject<
+  {
+    tokenCost: z.ZodOptional<z.ZodNumber>;
+    complexityScore: z.ZodOptional<z.ZodNumber>;
+    consistencyScore: z.ZodOptional<z.ZodNumber>;
+    docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+    aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+    agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+    testabilityScore: z.ZodOptional<z.ZodNumber>;
+    docDriftScore: z.ZodOptional<z.ZodNumber>;
+    dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+    modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+    estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+    estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+    comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+    totalSymbols: z.ZodOptional<z.ZodNumber>;
+    totalExports: z.ZodOptional<z.ZodNumber>;
+  },
+  z.core.$strip
+>;
+type Metrics = z.infer<typeof MetricsSchema>;
+/**
+ * Individual file/module analysis result.
+ */
+declare const AnalysisResultSchema: z.ZodObject<
+  {
+    fileName: z.ZodString;
+    issues: z.ZodArray<
+      z.ZodObject<
+        {
+          type: z.ZodEnum<typeof IssueType>;
+          severity: z.ZodEnum<typeof Severity>;
+          message: z.ZodString;
+          location: z.ZodObject<
+            {
+              file: z.ZodString;
+              line: z.ZodNumber;
+              column: z.ZodOptional<z.ZodNumber>;
+              endLine: z.ZodOptional<z.ZodNumber>;
+              endColumn: z.ZodOptional<z.ZodNumber>;
+            },
+            z.core.$strip
+          >;
+          suggestion: z.ZodOptional<z.ZodString>;
+        },
+        z.core.$strip
+      >
+    >;
+    metrics: z.ZodObject<
+      {
+        tokenCost: z.ZodOptional<z.ZodNumber>;
+        complexityScore: z.ZodOptional<z.ZodNumber>;
+        consistencyScore: z.ZodOptional<z.ZodNumber>;
+        docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+        aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+        agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+        testabilityScore: z.ZodOptional<z.ZodNumber>;
+        docDriftScore: z.ZodOptional<z.ZodNumber>;
+        dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+        modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+        estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+        estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+        comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+        totalSymbols: z.ZodOptional<z.ZodNumber>;
+        totalExports: z.ZodOptional<z.ZodNumber>;
+      },
+      z.core.$strip
+    >;
+  },
+  z.core.$strip
+>;
+type AnalysisResult = z.infer<typeof AnalysisResultSchema>;
+/**
+ * Standard spoke tool output contract.
+ */
+declare const SpokeOutputSchema: z.ZodObject<
+  {
+    results: z.ZodArray<
+      z.ZodObject<
+        {
+          fileName: z.ZodString;
+          issues: z.ZodArray<
+            z.ZodObject<
+              {
+                type: z.ZodEnum<typeof IssueType>;
+                severity: z.ZodEnum<typeof Severity>;
+                message: z.ZodString;
+                location: z.ZodObject<
+                  {
+                    file: z.ZodString;
+                    line: z.ZodNumber;
+                    column: z.ZodOptional<z.ZodNumber>;
+                    endLine: z.ZodOptional<z.ZodNumber>;
+                    endColumn: z.ZodOptional<z.ZodNumber>;
+                  },
+                  z.core.$strip
+                >;
+                suggestion: z.ZodOptional<z.ZodString>;
+              },
+              z.core.$strip
+            >
+          >;
+          metrics: z.ZodObject<
+            {
+              tokenCost: z.ZodOptional<z.ZodNumber>;
+              complexityScore: z.ZodOptional<z.ZodNumber>;
+              consistencyScore: z.ZodOptional<z.ZodNumber>;
+              docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+              aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+              agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+              testabilityScore: z.ZodOptional<z.ZodNumber>;
+              docDriftScore: z.ZodOptional<z.ZodNumber>;
+              dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+              modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+              estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+              estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+              comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+              totalSymbols: z.ZodOptional<z.ZodNumber>;
+              totalExports: z.ZodOptional<z.ZodNumber>;
+            },
+            z.core.$strip
+          >;
+        },
+        z.core.$strip
+      >
+    >;
+    summary: z.ZodObject<
+      {
+        totalFiles: z.ZodOptional<z.ZodNumber>;
+        totalIssues: z.ZodOptional<z.ZodNumber>;
+        criticalIssues: z.ZodOptional<z.ZodNumber>;
+        majorIssues: z.ZodOptional<z.ZodNumber>;
+        score: z.ZodOptional<z.ZodNumber>;
+      },
+      z.core.$catchall<z.ZodAny>
+    >;
+    metadata: z.ZodOptional<
+      z.ZodObject<
+        {
+          toolName: z.ZodString;
+          version: z.ZodOptional<z.ZodString>;
+          timestamp: z.ZodOptional<z.ZodString>;
+          config: z.ZodOptional<z.ZodAny>;
+        },
+        z.core.$catchall<z.ZodAny>
+      >
+    >;
+  },
+  z.core.$strip
+>;
+type SpokeOutput = z.infer<typeof SpokeOutputSchema>;
+/**
+ * Master Unified Report contract (CLI -> Platform).
+ */
+declare const UnifiedReportSchema: z.ZodObject<
+  {
+    summary: z.ZodObject<
+      {
+        totalFiles: z.ZodNumber;
+        totalIssues: z.ZodNumber;
+        criticalIssues: z.ZodNumber;
+        majorIssues: z.ZodNumber;
+        businessImpact: z.ZodOptional<
+          z.ZodObject<
+            {
+              estimatedMonthlyWaste: z.ZodOptional<z.ZodNumber>;
+              potentialSavings: z.ZodOptional<z.ZodNumber>;
+              productivityHours: z.ZodOptional<z.ZodNumber>;
+            },
+            z.core.$strip
+          >
+        >;
+      },
+      z.core.$strip
+    >;
+    results: z.ZodArray<
+      z.ZodObject<
+        {
+          fileName: z.ZodString;
+          issues: z.ZodArray<
+            z.ZodObject<
+              {
+                type: z.ZodEnum<typeof IssueType>;
+                severity: z.ZodEnum<typeof Severity>;
+                message: z.ZodString;
+                location: z.ZodObject<
+                  {
+                    file: z.ZodString;
+                    line: z.ZodNumber;
+                    column: z.ZodOptional<z.ZodNumber>;
+                    endLine: z.ZodOptional<z.ZodNumber>;
+                    endColumn: z.ZodOptional<z.ZodNumber>;
+                  },
+                  z.core.$strip
+                >;
+                suggestion: z.ZodOptional<z.ZodString>;
+              },
+              z.core.$strip
+            >
+          >;
+          metrics: z.ZodObject<
+            {
+              tokenCost: z.ZodOptional<z.ZodNumber>;
+              complexityScore: z.ZodOptional<z.ZodNumber>;
+              consistencyScore: z.ZodOptional<z.ZodNumber>;
+              docFreshnessScore: z.ZodOptional<z.ZodNumber>;
+              aiSignalClarityScore: z.ZodOptional<z.ZodNumber>;
+              agentGroundingScore: z.ZodOptional<z.ZodNumber>;
+              testabilityScore: z.ZodOptional<z.ZodNumber>;
+              docDriftScore: z.ZodOptional<z.ZodNumber>;
+              dependencyHealthScore: z.ZodOptional<z.ZodNumber>;
+              modelContextTier: z.ZodOptional<z.ZodEnum<typeof ModelTier>>;
+              estimatedMonthlyCost: z.ZodOptional<z.ZodNumber>;
+              estimatedDeveloperHours: z.ZodOptional<z.ZodNumber>;
+              comprehensionDifficultyIndex: z.ZodOptional<z.ZodNumber>;
+              totalSymbols: z.ZodOptional<z.ZodNumber>;
+              totalExports: z.ZodOptional<z.ZodNumber>;
+            },
+            z.core.$strip
+          >;
+        },
+        z.core.$strip
+      >
+    >;
+    scoring: z.ZodOptional<
+      z.ZodObject<
+        {
+          overall: z.ZodNumber;
+          rating: z.ZodString;
+          timestamp: z.ZodString;
+          breakdown: z.ZodArray<
+            z.ZodObject<
+              {
+                toolName: z.ZodUnion<
+                  readonly [z.ZodEnum<typeof ToolName>, z.ZodString]
+                >;
+                score: z.ZodNumber;
+              },
+              z.core.$catchall<z.ZodAny>
+            >
+          >;
+        },
+        z.core.$strip
+      >
+    >;
+  },
+  z.core.$catchall<z.ZodAny>
+>;
+type UnifiedReport = z.infer<typeof UnifiedReportSchema>;
+
+/**
+ * AST Parsing and Export Extraction Types
+ */
+interface ExportWithImports {
+  name: string;
+  type: 'function' | 'class' | 'const' | 'type' | 'interface' | 'default';
+  imports: string[];
+  dependencies: string[];
+  typeReferences: string[];
+  loc?: {
+    start: {
+      line: number;
+      column: number;
+    };
+    end: {
+      line: number;
+      column: number;
+    };
+  };
+}
+interface FileImport {
+  source: string;
+  specifiers: string[];
+  isTypeOnly: boolean;
+}
+interface ASTNode {
+  type: string;
+  loc?: {
+    start: {
+      line: number;
+      column: number;
+    };
+    end: {
+      line: number;
+      column: number;
+    };
+  };
+}
+/**
+ * AI token budget unit economics (v0.13+)
+ */
+interface TokenBudget {
+  totalContextTokens: number;
+  estimatedResponseTokens?: number;
+  wastedTokens: {
+    total: number;
+    bySource: {
+      duplication: number;
+      fragmentation: number;
+      chattiness: number;
+    };
+  };
+  efficiencyRatio: number;
+  potentialRetrievableTokens: number;
+}
+
+/**
+ * Shared types for graph-based visualizations
+ */
+interface GraphNode {
+  id: string;
+  label: string;
+  path?: string;
+  size?: number;
+  value?: number;
+  color?: string;
+  group?: string;
+  title?: string;
+  x?: number;
+  y?: number;
+  duplicates?: number;
+  tokenCost?: number;
+  severity?: string;
+}
+interface GraphEdge {
+  source: string;
+  target: string;
+  type?: string;
+  weight?: number;
+}
+interface GraphData {
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  clusters?: {
+    id: string;
+    name: string;
+    nodeIds: string[];
+  }[];
+  issues?: {
+    id: string;
+    type: string;
+    severity: string;
+    nodeIds: string[];
+    message: string;
+  }[];
+  metadata?: any;
+}
+
+/**
+ * AI readiness configuration
+ */
+interface AIReadyConfig {
+  threshold?: number;
+  include?: string[];
+  exclude?: string[];
+  scan?: {
+    include?: string[];
+    exclude?: string[];
+    parallel?: boolean;
+    deep?: boolean;
+  };
+  output?: {
+    format?: 'json' | 'console' | 'html';
+    path?: string;
+    saveTo?: string;
+    showBreakdown?: boolean;
+    compareBaseline?: string;
+  };
+  tools?: Record<string, any>;
+  scoring?: {
+    profile?: string;
+    weights?: Record<string, number>;
+  };
+}
+/**
+ * Legacy alias for Config
+ */
+type Config = AIReadyConfig;
+/**
+ * Common tool options
+ */
+interface ToolOptions {
+  rootDir: string;
+  include?: string[];
+  exclude?: string[];
+  config?: any;
+  [key: string]: any;
+}
+/**
+ * Scan options for tool providers
+ */
+interface ScanOptions extends ToolOptions {
+  output?: string;
+  format?: 'json' | 'console' | 'html';
+  parallel?: boolean;
+}
+/**
+ * Result of a single tool execution
+ */
+interface ToolOutput {
+  toolName: ToolName | string;
+  success: boolean;
+  issues: IssueType[] | any[];
+  metrics: Metrics;
+  duration?: number;
+}
+/**
+ * Overall scan result
+ */
+interface ScanResult {
+  timestamp: string;
+  rootDir: string;
+  filesAnalyzed: number;
+  totalIssues: number;
+  issuesByType: Record<string, number>;
+  issuesBySeverity: Record<Severity | string, number>;
+  score: number;
+  tools: ToolOutput[];
+}
+/**
+ * Cost configuration for business impact analysis
+ */
+interface CostConfig {
+  pricePer1KTokens: number;
+  queriesPerDevPerDay: number;
+  developerCount: number;
+  daysPerMonth: number;
+}
+/**
+ * Productivity impact metrics
+ */
+interface ProductivityImpact {
+  totalHours: number;
+  hourlyRate: number;
+  totalCost: number;
+  bySeverity: Record<
+    Severity | string,
+    {
+      hours: number;
+      cost: number;
+    }
+  >;
+}
+/**
+ * AI suggestion acceptance prediction
+ */
+interface AcceptancePrediction {
+  rate: number;
+  confidence: number;
+  factors: Array<{
+    name: string;
+    impact: number;
+  }>;
+}
+/**
+ * Technical Value Chain summary
+ */
+interface TechnicalValueChain {
+  score?: number;
+  density?: number;
+  complexity?: number;
+  surface?: number;
+  issueType?: string;
+  technicalMetric?: string;
+  technicalValue?: number;
+  aiImpact?: {
+    description: string;
+    scoreImpact: number;
+  };
+  developerImpact?: {
+    description: string;
+    productivityLoss: number;
+  };
+  businessOutcome?: {
+    directCost: number;
+    opportunityCost: number;
+    riskLevel: 'low' | 'moderate' | 'high' | 'critical';
+  };
+}
+/**
+ * Compatibility alias
+ */
+type TechnicalValueChainSummary = TechnicalValueChain;
+/**
+ * Code comprehension difficulty metrics
+ */
+interface ComprehensionDifficulty {
+  score: number;
+  rating: 'trivial' | 'easy' | 'moderate' | 'difficult' | 'expert';
+  factors: {
+    budgetRatio: number;
+    depthRatio: number;
+    fragmentation: number;
+  };
+}
+/**
+ * Business impact metrics (v0.10+)
+ */
+interface BusinessMetrics {
+  estimatedMonthlyCost?: number;
+  estimatedDeveloperHours?: number;
+  aiAcceptanceRate?: number;
+  aiReadinessScore?: number;
+}
+/**
+ * Constants for tests and configuration stability
+ */
+declare const GLOBAL_INFRA_OPTIONS: string[];
+declare const COMMON_FINE_TUNING_OPTIONS: string[];
+
+/**
+ * Analysis issue mapping to graph
+ */
+type GraphIssueSeverity = Severity;
+/**
+ * Graph metadata
+ */
+interface GraphMetadata {
+  projectName?: string;
+  timestamp: string;
+  totalFiles: number;
+  totalDependencies: number;
+  analysisTypes: string[];
+  criticalIssues: number;
+  majorIssues: number;
+  minorIssues: number;
+  infoIssues: number;
+  /** AI token budget unit economics (v0.13+) */
+  tokenBudget?: TokenBudget;
+  /** Execution time in milliseconds */
+  executionTime?: number;
+}
+
+/**
+ * Language-agnostic AST and parser interfaces for multi-language support
+ *
+ * This module provides abstractions for parsing different programming languages
+ * while maintaining a consistent interface for analysis tools.
+ */
+/**
+ * Supported programming languages
+ */
+declare enum Language {
+  TypeScript = 'typescript',
+  JavaScript = 'javascript',
+  Python = 'python',
+  Java = 'java',
+  Go = 'go',
+  Rust = 'rust',
+  CSharp = 'csharp',
+}
+/**
+ * File extensions mapped to languages
+ */
+declare const LANGUAGE_EXTENSIONS: Record<string, Language>;
+/**
+ * Location information in source code
+ */
+interface SourceLocation {
+  line: number;
+  column: number;
+}
+interface SourceRange {
+  start: SourceLocation;
+  end: SourceLocation;
+}
+/**
+ * Common AST node type (language-agnostic)
+ */
+interface CommonASTNode {
+  type: string;
+  loc?: SourceRange;
+  raw?: any;
+}
+/**
+ * Export information (function, class, variable, etc.)
+ */
+interface ExportInfo {
+  name: string;
+  type:
+    | 'function'
+    | 'class'
+    | 'const'
+    | 'type'
+    | 'interface'
+    | 'default'
+    | 'variable';
+  loc?: SourceRange;
+  /** Imports used within this export */
+  imports?: string[];
+  /** Dependencies on other exports in same file */
+  dependencies?: string[];
+  /** TypeScript types referenced */
+  typeReferences?: string[];
+  /** For methods: parent class name */
+  parentClass?: string;
+  /** For functions/methods: parameters */
+  parameters?: string[];
+  /** For classes/interfaces: number of methods and properties */
+  methodCount?: number;
+  propertyCount?: number;
+  /** Visibility (public, private, protected) */
+  visibility?: 'public' | 'private' | 'protected';
+  /** Behavioral metadata for advanced metrics */
+  isPure?: boolean;
+  hasSideEffects?: boolean;
+  /** Associated documentation */
+  documentation?: {
+    content: string;
+    type: 'jsdoc' | 'docstring' | 'comment' | 'xml-doc';
+    isStale?: boolean;
+  };
+}
+/**
+ * Import information
+ */
+interface ImportInfo {
+  /** Module being imported from */
+  source: string;
+  /** What's being imported */
+  specifiers: string[];
+  /** Is this a type-only import (TypeScript) */
+  isTypeOnly?: boolean;
+  /** Location in source */
+  loc?: SourceRange;
+}
+/**
+ * Parse result containing exports and imports
+ */
+interface ParseResult {
+  exports: ExportInfo[];
+  imports: ImportInfo[];
+  /** Language of the parsed file */
+  language: Language;
+  /** Any parse warnings (non-fatal) */
+  warnings?: string[];
+}
+/**
+ * Naming convention rules per language
+ */
+interface NamingConvention {
+  /** Allowed variable naming patterns */
+  variablePattern: RegExp;
+  /** Allowed function naming patterns */
+  functionPattern: RegExp;
+  /** Allowed class naming patterns */
+  classPattern: RegExp;
+  /** Allowed constant naming patterns */
+  constantPattern: RegExp;
+  /** Allowed type naming patterns */
+  typePattern?: RegExp;
+  /** Allowed interface naming patterns */
+  interfacePattern?: RegExp;
+  /** Language-specific exceptions (e.g., __init__ in Python) */
+  exceptions?: string[];
+}
+/**
+ * Language-specific configuration
+ */
+interface LanguageConfig {
+  language: Language;
+  /** File extensions for this language */
+  extensions: string[];
+  /** Naming conventions */
+  namingConventions: NamingConvention;
+  /** Common abbreviations allowed */
+  allowedAbbreviations?: string[];
+  /** Language-specific keywords to ignore */
+  keywords?: string[];
+}
+/**
+ * Abstract interface for language parsers
+ * Each language implementation should implement this interface
+ */
+interface LanguageParser {
+  /** Language this parser handles */
+  readonly language: Language;
+  /** File extensions this parser supports */
+  readonly extensions: string[];
+  /**
+   * Parse source code and extract structure
+   * @param code - Source code to parse
+   * @param filePath - Path to the file (for context)
+   * @returns Parse result with exports and imports
+   * @throws ParseError if code has syntax errors
+   */
+  parse(code: string, filePath: string): ParseResult;
+  /**
+   * Get naming conventions for this language
+   */
+  getNamingConventions(): NamingConvention;
+  /**
+   * Initialize the parser (e.g. load WASM)
+   */
+  initialize(): Promise<void>;
+  /**
+   * Check if this parser can handle a file
+   * @param filePath - File path to check
+   */
+  canHandle(filePath: string): boolean;
+  /**
+   * Get the raw AST for advanced querying
+   * @param code - Source code to parse
+   * @param filePath - Path to the file
+   */
+  getAST(code: string, filePath: string): Promise<any>;
+  /**
+   * Analyze structural metadata for a node (e.g. purity)
+   * @param node - The AST node to analyze (language specific)
+   * @param code - The original source code
+   */
+  analyzeMetadata(node: any, code: string): Partial<ExportInfo>;
+}
+/**
+ * Parser error with location information
+ */
+declare class ParseError extends Error {
+  readonly filePath: string;
+  readonly loc?: SourceLocation | undefined;
+  constructor(
+    message: string,
+    filePath: string,
+    loc?: SourceLocation | undefined
+  );
+}
+/**
+ * Statistics about parsed code
+ */
+interface ParseStatistics {
+  language: Language;
+  filesAnalyzed: number;
+  totalExports: number;
+  totalImports: number;
+  parseErrors: number;
+  warnings: number;
+}
+
+/**
+ * Priority levels for actionable recommendations
+ */
+declare enum RecommendationPriority {
+  High = 'high',
+  Medium = 'medium',
+  Low = 'low',
+}
+/**
+ * AI Readiness Rating categories
+ */
+declare enum ReadinessRating {
+  Excellent = 'Excellent',
+  Good = 'Good',
+  Fair = 'Fair',
+  NeedsWork = 'Needs Work',
+  Critical = 'Critical',
+}
+/**
+ * Output structure for a single tool's scoring analysis
+ */
+interface ToolScoringOutput {
+  /** Unique tool identifier (e.g., "pattern-detect") */
+  toolName: string;
+  /** Normalized 0-100 score for this tool */
+  score: number;
+  /** AI token budget unit economics (v0.13+) */
+  tokenBudget?: TokenBudget;
+  /** Raw metrics used to calculate the score */
+  rawMetrics: Record<string, any>;
+  /** Factors that influenced the score */
+  factors: Array<{
+    /** Human-readable name of the factor */
+    name: string;
+    /** Points contribution (positive or negative) */
+    impact: number;
+    /** Explanation of the factor's impact */
+    description: string;
+  }>;
+  /** Actionable recommendations with estimated impact */
+  recommendations: Array<{
+    /** The recommended action to take */
+    action: string;
+    /** Potential points increase if implemented */
+    estimatedImpact: number;
+    /** Implementation priority */
+    priority: RecommendationPriority | 'high' | 'medium' | 'low';
+  }>;
+}
+/**
+ * Consolidated scoring result across all tools
+ */
+interface ScoringResult {
+  /** Overall AI Readiness Score (0-100) */
+  overall: number;
+  /** Rating category representing the overall readiness */
+  rating: ReadinessRating | string;
+  /** Timestamp of score calculation */
+  timestamp: string;
+  /** Tools that contributed to this score */
+  toolsUsed: string[];
+  /** Breakdown by individual tool */
+  breakdown: ToolScoringOutput[];
+  /** Internal calculation details for transparency */
+  calculation: {
+    /** Textual representation of the calculation formula */
+    formula: string;
+    /** Weights applied to each tool */
+    weights: Record<string, number>;
+    /** Simplified normalized formula output */
+    normalized: string;
+  };
+}
+/**
+ * Configuration options for the scoring system
+ */
+interface ScoringConfig {
+  /** Minimum passing score (CLI will exit with non-zero if below) */
+  threshold?: number;
+  /** Whether to show the detailed tool-by-tool breakdown */
+  showBreakdown?: boolean;
+  /** Path to a baseline report JSON for trend comparison */
+  compareBaseline?: string;
+  /** Target file path to persist the calculated score */
+  saveTo?: string;
+}
+/**
+ * Default weights for known tools. Weights sum to 100 and read directly as
+ * percentage contribution to the overall score.
+ * New tools get weight of 5 if not specified.
+ */
+/**
+ * Default weights for known tools. Weights sum to 100 and read directly as
+ * percentage contribution to the overall score.
+ * New tools get weight of 5 if not specified.
+ */
+declare const DEFAULT_TOOL_WEIGHTS: Record<string, number>;
+/**
+ * Tool name normalization map (shorthand -> canonical name)
+ */
+/**
+ * Tool name normalization map (shorthand -> canonical name)
+ */
+declare const TOOL_NAME_MAP: Record<string, string>;
+/**
+ * Model context tiers for context-aware threshold calibration.
+ */
+type ModelContextTier = 'compact' | 'standard' | 'extended' | 'frontier';
+/**
+ * Scoring profiles for project-type-aware weighting.
+ */
+declare enum ScoringProfile {
+  Default = 'default',
+  Agentic = 'agentic', // Focus on AI agent navigation and signal
+  Logic = 'logic', // Focus on testability and complexity
+  UI = 'ui', // Focus on consistency and context (lower penalty for magic literals)
+  Cost = 'cost', // Focus on token waste (duplication and fragmentation)
+  Security = 'security',
+}
+/**
+ * Project-type-aware tool weight presets.
+ */
+/**
+ * Project-type-aware tool weight presets.
+ */
+declare const SCORING_PROFILES: Record<ScoringProfile, Record<string, number>>;
+/**
+ * Context budget thresholds per tier.
+ */
+/**
+ * Context budget thresholds per tier.
+ */
+declare const CONTEXT_TIER_THRESHOLDS: Record<
+  ModelContextTier,
+  {
+    idealTokens: number;
+    criticalTokens: number;
+    idealDepth: number;
+  }
+>;
+/**
+ * Project-size-adjusted minimum thresholds.
+ */
+/**
+ * Project-size-adjusted minimum thresholds.
+ */
+declare const SIZE_ADJUSTED_THRESHOLDS: Record<string, number>;
+/**
+ * Determine project size tier based on the total number of files
+ *
+ * @param fileCount Total number of files in the project
+ * @returns A string identifier for the project size tier (xs, small, medium, large, enterprise)
+ */
+declare function getProjectSizeTier(
+  fileCount: number
+): keyof typeof SIZE_ADJUSTED_THRESHOLDS;
+/**
+ * Calculate the recommended minimum AI readiness threshold for a project
+ *
+ * @param fileCount Total number of files in the project
+ * @param modelTier The model context tier targeted (compact, standard, extended, frontier)
+ * @returns The recommended score threshold (0-100)
+ */
+declare function getRecommendedThreshold(
+  fileCount: number,
+  modelTier?: ModelContextTier
+): number;
+/**
+ * Normalize a tool name from a shorthand or alias to its canonical ID
+ *
+ * @param shortName The tool shorthand or alias name
+ * @returns The canonical tool ID
+ */
+declare function normalizeToolName(shortName: string): string;
+/**
+ * Retrieve the weight for a specific tool, considering overrides and profiles
+ *
+ * @param toolName The canonical tool ID
+ * @param toolConfig Optional configuration for the tool containing a weight
+ * @param cliOverride Optional weight override from the CLI
+ * @param profile Optional scoring profile to use
+ * @returns The weight to be used for this tool in overall scoring
+ */
+declare function getToolWeight(
+  toolName: string,
+  toolConfig?: {
+    scoreWeight?: number;
+  },
+  cliOverride?: number,
+  profile?: ScoringProfile
+): number;
+/**
+ * Parse a comma-separated weight string (e.g. "patterns:30,context:10")
+ *
+ * @param weightStr The raw weight string from the CLI or config
+ * @returns A Map of tool IDs to their parsed weights
+ */
+declare function parseWeightString(weightStr?: string): Map<string, number>;
+/**
+ * Calculate the overall consolidated AI Readiness Score
+ *
+ * @param toolOutputs Map of tool IDs to their individual scoring outputs
+ * @param config Optional global configuration
+ * @param cliWeights Optional weight overrides from the CLI
+ * @returns Consolidate ScoringResult including overall score and rating
+ */
+declare function calculateOverallScore(
+  toolOutputs: Map<string, ToolScoringOutput>,
+  config?: any,
+  cliWeights?: Map<string, number>
+): ScoringResult;
+/**
+ * Convert numeric score to rating category
+ *
+ * @param score The numerical AI readiness score (0-100)
+ * @returns The corresponding ReadinessRating category
+ */
+declare function getRating(score: number): ReadinessRating;
+/**
+ * Get a URL-friendly slug representing the rating
+ *
+ * @param score The numerical score
+ * @returns A kebab-case string (e.g., 'excellent', 'needs-work')
+ */
+declare function getRatingSlug(score: number): string;
+/**
+ * Convert score to rating with project-size awareness.
+ *
+ * @param score The numerical AI readiness score
+ * @param fileCount Total number of files in the project
+ * @param modelTier The model context tier being targeted
+ * @returns The size-adjusted ReadinessRating
+ */
+declare function getRatingWithContext(
+  score: number,
+  fileCount: number,
+  modelTier?: ModelContextTier
+): ReadinessRating;
+/**
+ * Get rating display properties (emoji and color)
+ *
+ * @param rating The readiness rating category
+ * @returns Object containing display emoji and color string
+ */
+declare function getRatingDisplay(rating: ReadinessRating | string): {
+  emoji: string;
+  color: string;
+};
+/**
+ * Format score for human-readable console display
+ *
+ * @param result The consolidated scoring result
+ * @returns Formatted string for display
+ */
+declare function formatScore(result: ScoringResult): string;
+/**
+ * Format individual tool score for detailed console display
+ *
+ * @param output The scoring output for a single tool
+ * @returns Formatted string with factors and recommendations
+ */
+declare function formatToolScore(output: ToolScoringOutput): string;
+
+/**
+ * Visualization utilities for generating HTML from graph data
+ */
+
+/**
+ * Generate HTML visualization from graph data
+ * Creates an interactive HTML page with a canvas-based graph visualization
+ *
+ * @param graph - The graph data to visualize
+ * @returns HTML string representing the interactive visualization
+ */
+declare function generateHTML(graph: GraphData): string;
+
+export {
+  type SourceRange as $,
+  type AnalysisResult as A,
+  type BusinessMetrics as B,
+  type CostConfig as C,
+  DEFAULT_TOOL_WEIGHTS as D,
+  type ExportWithImports as E,
+  type FileImport as F,
+  GLOBAL_INFRA_OPTIONS as G,
+  type Metrics as H,
+  type ImportInfo as I,
+  ParseError as J,
+  type ParseStatistics as K,
+  type LanguageParser as L,
+  type ModelContextTier as M,
+  type NamingConvention as N,
+  RecommendationPriority as O,
+  type ProductivityImpact as P,
+  SCORING_PROFILES as Q,
+  ReadinessRating as R,
+  type ScanOptions as S,
+  ToolName as T,
+  SIZE_ADJUSTED_THRESHOLDS as U,
+  type ScanResult as V,
+  type ScoringConfig as W,
+  ScoringProfile as X,
+  type ScoringResult as Y,
+  Severity as Z,
+  type SourceLocation as _,
+  type SpokeOutput as a,
+  TOOL_NAME_MAP as a0,
+  type ToolOptions as a1,
+  type ToolOutput as a2,
+  type UnifiedReport as a3,
+  calculateOverallScore as a4,
+  formatScore as a5,
+  formatToolScore as a6,
+  generateHTML as a7,
+  getProjectSizeTier as a8,
+  getRating as a9,
+  getRatingDisplay as aa,
+  getRatingSlug as ab,
+  getRatingWithContext as ac,
+  getRecommendedThreshold as ad,
+  getToolWeight as ae,
+  normalizeToolName as af,
+  parseWeightString as ag,
+  type ToolScoringOutput as b,
+  type ASTNode as c,
+  type AIReadyConfig as d,
+  type TokenBudget as e,
+  type AcceptancePrediction as f,
+  type ComprehensionDifficulty as g,
+  type TechnicalValueChainSummary as h,
+  type TechnicalValueChain as i,
+  Language as j,
+  type ExportInfo as k,
+  type ParseResult as l,
+  COMMON_FINE_TUNING_OPTIONS as m,
+  CONTEXT_TIER_THRESHOLDS as n,
+  type CommonASTNode as o,
+  type Config as p,
+  type GraphData as q,
+  type GraphEdge as r,
+  type GraphIssueSeverity as s,
+  type GraphMetadata as t,
+  type GraphNode as u,
+  type Issue as v,
+  IssueType as w,
+  LANGUAGE_EXTENSIONS as x,
+  type LanguageConfig as y,
+  type Location as z,
+};