Core Analysis Engine

/**
 * Main analyzer class for Lit template static analysis
 * Provides diagnostics, completions, definitions, and code fixes
 */
class LitAnalyzer {
  /**
   * Creates a new LitAnalyzer instance
   * @param context - The analyzer context containing TypeScript program and configuration
   */
  constructor(context: LitAnalyzerContext);
}

/**
 * Get all diagnostics for a source file
 * Analyzes template literals for binding errors, type mismatches, and rule violations
 * @param file - TypeScript source file to analyze
 * @returns Array of diagnostic messages with locations and severity
 */
getDiagnosticsInFile(file: SourceFile): LitDiagnostic[];

import { LitAnalyzer, DefaultLitAnalyzerContext, makeConfig, type LitPluginContextHandler } from "lit-analyzer";
import * as ts from "typescript";

const program = ts.createProgram(["src/my-component.ts"], {});
const handler: LitPluginContextHandler = {
  ts: ts,
  getProgram: () => program
};
const context = new DefaultLitAnalyzerContext(handler);
const config = makeConfig({ strict: true });
context.updateConfig(config);
const analyzer = new LitAnalyzer(context);

const sourceFile = program.getSourceFile("src/my-component.ts")!;
const diagnostics = analyzer.getDiagnosticsInFile(sourceFile);

diagnostics.forEach(diagnostic => {
  const severity = diagnostic.severity;
  const message = diagnostic.message;
  const line = diagnostic.location.start;
  console.log(`${severity} at line ${line}: ${message}`);
});

/**
 * Get code completions at a specific position
 * Provides attribute names, property names, event names, and element names
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @returns Array of completion items or undefined if not in a template
 */
getCompletionsAtPosition(file: SourceFile, position: SourceFilePosition): LitCompletion[] | undefined;

/**
 * Get detailed information about a specific completion item
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @param name - Name of the completion item
 * @returns Detailed completion information or undefined
 */
getCompletionDetailsAtPosition(file: SourceFile, position: SourceFilePosition, name: string): LitCompletionDetails | undefined;

/**
 * Get definition information at a specific position
 * Finds the definition of attributes, properties, events, or elements
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @returns Definition information or undefined if no definition found
 */
getDefinitionAtPosition(file: SourceFile, position: SourceFilePosition): LitDefinition | undefined;

/**
 * Get hover information at a specific position
 * Provides type information and documentation for template elements
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @returns Quick info object or undefined
 */
getQuickInfoAtPosition(file: SourceFile, position: SourceFilePosition): LitQuickInfo | undefined;

/**
 * Get rename information at a specific position
 * Determines if the element at the position can be renamed
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @returns Rename information or undefined if element cannot be renamed
 */
getRenameInfoAtPosition(file: SourceFile, position: SourceFilePosition): LitRenameInfo | undefined;

/**
 * Get all rename locations for an element
 * Finds all occurrences of the element that would be renamed
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @returns Array of rename locations
 */
getRenameLocationsAtPosition(file: SourceFile, position: SourceFilePosition): LitRenameLocation[];

/**
 * Get available code fixes for a specific range
 * Provides automatic fixes for common template issues
 * @param file - TypeScript source file containing the template
 * @param sourceFileRange - Range where the issue occurs
 * @returns Array of available code fixes
 */
getCodeFixesAtPositionRange(file: SourceFile, sourceFileRange: Range): LitCodeFix[];

/**
 * Get format edits for templates in a file
 * Provides formatting corrections for HTML and CSS within templates
 * @param file - TypeScript source file containing templates
 * @param settings - TypeScript format code settings
 * @returns Array of format edit operations
 */
getFormatEditsInFile(file: SourceFile, settings: FormatCodeSettings): LitFormatEdit[];

/**
 * Get outlining spans for code folding
 * Identifies template regions that can be collapsed
 * @param file - TypeScript source file containing templates
 * @returns Array of outlining spans
 */
getOutliningSpansInFile(file: SourceFile): LitOutliningSpan[];

/**
 * Get closing tag information for auto-completion
 * Determines the appropriate closing tag at a position
 * @param file - TypeScript source file containing the template
 * @param position - Character position within the file
 * @returns Closing tag information or undefined
 */
getClosingTagAtPosition(file: SourceFile, position: SourceFilePosition): LitClosingTagInfo | undefined;

/**
 * Generate index entries for static analysis systems
 * Useful for Kythe, Language Server Index Format, or custom indexing
 * @param file - TypeScript source file to index
 * @returns Iterator of index entries describing template regions
 */
indexFile(file: SourceFile): IterableIterator<LitIndexEntry>;

interface LitDiagnostic {
  /** Location of the diagnostic in the source file */
  location: SourceFileRange;
  /** Optional diagnostic code number */
  code?: number;
  /** Human-readable diagnostic message */
  message: string;
  /** Optional fix message suggesting a solution */
  fixMessage?: string;
  /** Optional suggestion for improvement */
  suggestion?: string;
  /** Rule ID that generated this diagnostic */
  source: LitAnalyzerRuleId;
  /** Severity level of the diagnostic */
  severity: LitDiagnosticSeverity;
  /** Source file containing the diagnostic */
  file: SourceFile;
}

interface LitCompletion {
  /** Name of the completion item */
  name: string;
  /** Type/kind of the completion */
  kind: LitTargetKind;
  /** Optional modifiers (e.g., "color" for CSS color values) */
  kindModifiers?: "color";
  /** Text to insert when completion is selected */
  insert: string;
  /** Optional range to replace */
  range?: SourceFileRange;
  /** Priority for sorting completions */
  importance?: "high" | "medium" | "low";
  /** Custom sort text for ordering */
  sortText?: string;
  /** Function to get documentation for this completion */
  documentation?(): string | undefined;
}

interface LitDefinition {
  /** Name of the definition */
  name: string;
  /** Location of the definition */
  location: SourceFileRange;
  /** Source file containing the definition */
  file: SourceFile;
  /** Type of the definition */
  kind: LitTargetKind;
}

interface LitQuickInfo {
  /** Range of the element being described */
  range: SourceFileRange;
  /** Display name of the element */
  displayName: string;
  /** Documentation text */
  documentation?: string;
  /** Type information */
  type?: string;
}

type LitIndexEntry = HtmlNodeIndexEntry | HtmlNodeAttrIndexEntry;

interface HtmlNodeIndexEntry {
  /** Type of index entry */
  kind: "NODE-REFERENCE";
  /** HTML node being referenced */
  node: HtmlNode;
  /** Document containing the node */
  document: HtmlDocument;
  /** Definition information for the node */
  definition: LitDefinition;
}

interface HtmlNodeAttrIndexEntry {
  /** Type of index entry */
  kind: "ATTRIBUTE-REFERENCE";
  /** HTML attribute being referenced */
  attribute: HtmlNodeAttr;
  /** Document containing the attribute */
  document: HtmlDocument;
  /** Definition information for the attribute */
  definition: LitDefinition;
}