tsc-ts 0.0.3 → 0.0.5

package/src/library/errors.ts

@@ -0,0 +1,26 @@
+// Errors of tsc-ts's public API.
+
+/**
+ * A failure inside tsc-ts while it answered an API call: an exception the compiler threw, as tsgo panics.
+ * `cause` is the exception. The program's checker may be inconsistent after one; dispose of the program.
+ */
+export class InternalCompilerError extends Error {
+  constructor(cause: unknown) {
+    super('panic: ' + (cause instanceof Error ? cause.message : String(cause)), { cause });
+    this.name = 'InternalCompilerError';
+  }
+}
+
+/** A call on a program, or on its checker, after `dispose()`. */
+export class DisposedProgramError extends Error {
+  constructor() {
+    super('the program is disposed');
+    this.name = 'DisposedProgramError';
+  }
+}
+
+/** `e` as an InternalCompilerError; errors of using a disposed program are rethrown as they are. */
+export function internalError(e: unknown): Error {
+  if (e instanceof InternalCompilerError || e instanceof DisposedProgramError) return e;
+  return new InternalCompilerError(e);
+}

package/src/library/host.ts

@@ -0,0 +1,63 @@
+// The file system a program of tsc-ts's public API reads through its host.
+
+import { diskEntries, diskReadFile, diskRealpath, diskStat } from './disk.js';
+import { ParseOptions, ScriptKind, type ExternalModuleIndicatorOptions, type SourceFile } from '../compiler/ast.js';
+import { CompilerHost } from '../compiler/file-loader.js';
+import { DirectoryEntries, FileSystem } from '../compiler/file-system.js';
+import { takePreparedFile } from '../compiler/parallel-parse.js';
+import { parseSourceFile } from '../compiler/parser.js';
+import type { ProgramHost } from './types.js';
+
+/**
+ * The host's answers, and the disk's where a callback is missing or answers undefined, as `tsc-ts --api`
+ * reads through its client's callbacks. `readFile` answering null means the file doesn't exist.
+ */
+export class HostFileSystem extends FileSystem {
+  constructor(private readonly host: ProgramHost) {
+    super(host.useCaseSensitiveFileNames());
+  }
+
+  fileExists(path: string): boolean {
+    const answer = this.host.fileExists?.(path);
+    return answer ?? diskStat(path)?.isDirectory === false;
+  }
+
+  directoryExists(path: string): boolean {
+    const answer = this.host.directoryExists?.(path);
+    return answer ?? diskStat(path)?.isDirectory === true;
+  }
+
+  readFile(path: string): string | undefined {
+    const answer = this.host.readFile?.(path);
+    if (answer === null) return undefined;
+    return answer ?? diskReadFile(path);
+  }
+
+  getAccessibleEntries(path: string): DirectoryEntries {
+    const entries = this.host.getAccessibleEntries?.(path) ?? diskEntries(path);
+    return new DirectoryEntries(entries.files.slice(), entries.directories.slice(), undefined);
+  }
+
+  realpath(path: string): string {
+    return this.host.realpath?.(path) ?? diskRealpath(path);
+  }
+}
+
+/**
+ * The compiler host of a program of tsc-ts's public API. A file that parse threads prepared, reading the disk, is
+ * taken only when the host gives the same text for it; the program parses the host's text otherwise.
+ */
+export class LibraryCompilerHost extends CompilerHost {
+  getSourceFile(
+    fileName: string,
+    path: string,
+    externalModuleIndicatorOptions: ExternalModuleIndicatorOptions,
+  ): SourceFile | undefined {
+    const text = this.readFile(fileName);
+    if (text === undefined) return undefined;
+    return (
+      takePreparedFile(fileName, path, externalModuleIndicatorOptions, text) ??
+      parseSourceFile(fileName, text, new ParseOptions(path, ScriptKind.Unknown, externalModuleIndicatorOptions))
+    );
+  }
+}

package/src/library/index.ts

@@ -0,0 +1,71 @@
+// tsc-ts's public API (`tsc-ts/api`): the types of programs, checkers, nodes, symbols, types and
+// signatures, and the enums that number their kinds and flags as TypeScript 7's API does.
+
+export * from './ast.js';
+export * from './enums.generated.js';
+export type { CompilerOptions } from './compiler-options.generated.js';
+export { symbolName } from './symbols.js';
+export { createProgram, createProgramFromConfigFile, getPreEmitDiagnostics, parseConfigFile } from './program.js';
+export { DisposedProgramError, InternalCompilerError } from './errors.js';
+export { parseSourceFile, type ParseSourceFileOptions } from './parse.js';
+export {
+  canHaveModifiers,
+  flattenDiagnosticMessageText,
+  forEachChild,
+  getCombinedModifierFlags,
+  getCombinedNodeFlags,
+  getJSDoc,
+  getLineAndCharacterOfPosition,
+  getLineStarts,
+  getModifiers,
+  getPositionOfLineAndCharacter,
+  getSourceFileOfNode,
+  getTextOfNode,
+  tokenStartOfNode,
+  tokenToString,
+  walkPreorder,
+} from './nodes.js';
+export type {
+  __String,
+  BigIntLiteralType,
+  BooleanLiteralType,
+  ConditionalType,
+  CreateProgramOptions,
+  Diagnostic,
+  FileSystemEntries,
+  FreshableType,
+  IndexedAccessType,
+  IndexInfo,
+  IndexType,
+  InterfaceType,
+  IntersectionType,
+  IntrinsicType,
+  LiteralType,
+  NumberLiteralType,
+  ObjectType,
+  ParsedConfigFile,
+  Program,
+  ProgramHost,
+  Signature,
+  SourceFileMetadata,
+  StringLiteralType,
+  StringMappingType,
+  SubstitutionType,
+  Symbol,
+  TemplateLiteralType,
+  TupleType,
+  TupleTypeReference,
+  Type,
+  TypeChecker,
+  TypeParameter,
+  TypePredicate,
+  TypeReference,
+  UnionOrIntersectionType,
+  UnionType,
+} from './types.js';
+
+/** The kind of an index signature's key, as TypeScript 5 numbers it. */
+export enum IndexKind {
+  String = 0,
+  Number = 1,
+}

package/src/library/nodes.ts

@@ -0,0 +1,232 @@
+// Node functions of tsc-ts's public API, with TypeScript 7's behavior.
+
+import {
+  getModifiers as compilerGetModifiers,
+  type Node as CompilerNode,
+  type ModifierList as CompilerModifierList,
+  type NodeList as CompilerNodeList,
+  NodeVisitor,
+  type SourceFile as CompilerSourceFile,
+} from '../compiler/ast.js';
+import { getTokenPosOfNode } from '../compiler/astnav.js';
+import {
+  getCombinedModifierFlags as compilerModifierFlags,
+  getCombinedNodeFlags as compilerNodeFlags,
+  getSourceFileOfNode as compilerSourceFileOfNode,
+} from '../compiler/binder-utilities.js';
+import { getJSDoc as compilerGetJSDoc } from '../compiler/parser.js';
+import { computeLineOfPosition, tokenToString as compilerTokenToString } from '../compiler/scanner.js';
+import { SyntaxKind as CompilerSyntaxKind } from '../compiler/syntax-kind.js';
+import type { JSDoc, LineAndCharacter, ModifierList, Node, NodeList, SourceFile } from './ast.js';
+import type { ModifierFlags, NodeFlags, SyntaxKind } from './enums.generated.js';
+import type { Diagnostic } from './types.js';
+
+const compilerNode = (node: Node): CompilerNode => node as unknown as CompilerNode;
+
+/** Visits the children of a node; stops at the first callback that answers a truthy value. */
+class CallbackVisitor extends NodeVisitor {
+  result: unknown = undefined;
+
+  constructor(
+    private readonly cbNode: (node: Node) => unknown,
+    private readonly cbNodes: ((nodes: NodeList) => unknown) | undefined,
+  ) {
+    super();
+  }
+
+  visitNode(node: CompilerNode): boolean {
+    const result = this.cbNode(node as unknown as Node);
+    if (!result) return false;
+    this.result = result;
+    return true;
+  }
+
+  visitList(list: CompilerNodeList): boolean {
+    if (this.cbNodes === undefined) return super.visitList(list);
+    const result = this.cbNodes(list as unknown as NodeList);
+    if (!result) return false;
+    this.result = result;
+    return true;
+  }
+
+  visitModifiers(list: CompilerModifierList): boolean {
+    return this.visitList(list);
+  }
+}
+
+/**
+ * Calls `cbNode` for each child of `node`, in source order, or `cbNodes` for each list of children when it
+ * is given; returns the first truthy value a callback answers. JSDoc is not visited (`getJSDoc`).
+ */
+export function forEachChild<T>(
+  node: Node,
+  cbNode: (node: Node) => T | undefined,
+  cbNodes?: (nodes: NodeList) => T | undefined,
+): T | undefined {
+  const visitor = new CallbackVisitor(cbNode, cbNodes);
+  compilerNode(node).forEachChild(visitor);
+  return visitor.result as T | undefined;
+}
+
+/** Collects the children of a node, in source order. */
+class ChildCollector extends NodeVisitor {
+  readonly children: CompilerNode[] = [];
+
+  visitNode(node: CompilerNode): boolean {
+    this.children.push(node);
+    return false;
+  }
+}
+
+/**
+ * Visits `root` and its descendants in preorder, with `depth` the number of levels below `root`, without
+ * recursion. The callback may answer 'skip' to leave a node's children unvisited, or 'stop' to end the walk.
+ */
+export function walkPreorder(root: Node, cb: (node: Node, depth: number) => void | 'skip' | 'stop'): void {
+  const stack: CompilerNode[] = [compilerNode(root)];
+  const depths: number[] = [0];
+  const collector = new ChildCollector();
+  // Declared outside the loop: scriptc compiles the node's conversion to the public Node from a variable there.
+  let node: CompilerNode;
+  while (stack.length > 0) {
+    node = stack.pop()!;
+    const depth = depths.pop()!;
+    const verdict = cb(node as unknown as Node, depth);
+    if (verdict === 'stop') return;
+    if (verdict === 'skip') continue;
+    collector.children.length = 0;
+    node.forEachChild(collector);
+    const children = collector.children;
+    for (let i = children.length - 1; i >= 0; i--) {
+      stack.push(children[i]!);
+      depths.push(depth + 1);
+    }
+  }
+}
+
+/**
+ * The start of the first token of `node`, after its leading trivia; with `includeJSDoc`, the start of its
+ * first JSDoc comment where it has one.
+ */
+export function tokenStartOfNode(node: Node, includeJSDoc = false): number {
+  const file = compilerSourceFileOfNode(compilerNode(node));
+  return getTokenPosOfNode(compilerNode(node), file, includeJSDoc);
+}
+
+/** The source file `node` is in: the root of its parents. */
+export function getSourceFileOfNode(node: Node): SourceFile {
+  let current = node;
+  while (current.parent !== undefined) current = current.parent;
+  return current as SourceFile;
+}
+
+/**
+ * The text of `node` in its source file, from the start of its first token (`tokenStartOfNode`) to its end:
+ * TypeScript's `node.getText()`.
+ */
+export function getTextOfNode(node: Node): string {
+  const file = compilerSourceFileOfNode(compilerNode(node));
+  return file.text.substring(getTokenPosOfNode(compilerNode(node), file, false), node.end);
+}
+
+/** The JSDoc comments of `node`, as the JSDoc nodes TypeScript 7 attaches to it (parsed on first use). */
+export function getJSDoc(node: Node): readonly JSDoc[] {
+  const file = compilerSourceFileOfNode(compilerNode(node));
+  return compilerGetJSDoc(file, compilerNode(node)) as unknown as readonly JSDoc[];
+}
+
+/** The modifiers of a declaration, decorators included, as TypeScript 7 keeps them. */
+export function getModifiers(node: Node): ModifierList | undefined {
+  return compilerGetModifiers(compilerNode(node)) as unknown as ModifierList | undefined;
+}
+
+/** Whether a node of this kind can have modifiers (TypeScript 7's CanHaveModifiers). */
+export function canHaveModifiers(node: Node): boolean {
+  switch (compilerNode(node).kind) {
+    case CompilerSyntaxKind.TypeParameter:
+    case CompilerSyntaxKind.Parameter:
+    case CompilerSyntaxKind.PropertySignature:
+    case CompilerSyntaxKind.PropertyDeclaration:
+    case CompilerSyntaxKind.MethodSignature:
+    case CompilerSyntaxKind.MethodDeclaration:
+    case CompilerSyntaxKind.Constructor:
+    case CompilerSyntaxKind.GetAccessor:
+    case CompilerSyntaxKind.SetAccessor:
+    case CompilerSyntaxKind.IndexSignature:
+    case CompilerSyntaxKind.ConstructorType:
+    case CompilerSyntaxKind.FunctionExpression:
+    case CompilerSyntaxKind.ArrowFunction:
+    case CompilerSyntaxKind.ClassExpression:
+    case CompilerSyntaxKind.VariableStatement:
+    case CompilerSyntaxKind.FunctionDeclaration:
+    case CompilerSyntaxKind.ClassDeclaration:
+    case CompilerSyntaxKind.InterfaceDeclaration:
+    case CompilerSyntaxKind.TypeAliasDeclaration:
+    case CompilerSyntaxKind.EnumDeclaration:
+    case CompilerSyntaxKind.ModuleDeclaration:
+    case CompilerSyntaxKind.ImportEqualsDeclaration:
+    case CompilerSyntaxKind.ImportDeclaration:
+    case CompilerSyntaxKind.JSImportDeclaration:
+    case CompilerSyntaxKind.ExportAssignment:
+    case CompilerSyntaxKind.ExportDeclaration:
+      return true;
+  }
+  return false;
+}
+
+/**
+ * The modifier flags of a declaration with those of the declarations it is part of: for a binding element,
+ * of the declaration of its outermost pattern; for a variable declaration, of its list and statement.
+ */
+export function getCombinedModifierFlags(node: Node): ModifierFlags {
+  return compilerModifierFlags(compilerNode(node)) as number as ModifierFlags;
+}
+
+/** The node flags of a declaration with those of the declarations it is part of, as getCombinedModifierFlags. */
+export function getCombinedNodeFlags(node: Node): NodeFlags {
+  return compilerNodeFlags(compilerNode(node)) as number as NodeFlags;
+}
+
+/** The UTF-16 offset at which each line of the file starts. */
+export function getLineStarts(file: SourceFile): readonly number[] {
+  return (file as unknown as CompilerSourceFile).lineStarts();
+}
+
+/** The 0-based line and character of a UTF-16 position in the file. */
+export function getLineAndCharacterOfPosition(file: SourceFile, position: number): LineAndCharacter {
+  const lineStarts = getLineStarts(file);
+  const line = computeLineOfPosition(lineStarts, position);
+  return { line, character: position - lineStarts[line]! };
+}
+
+/** The UTF-16 position of a 0-based line and character in the file. */
+export function getPositionOfLineAndCharacter(file: SourceFile, line: number, character: number): number {
+  return getLineStarts(file)[line]! + character;
+}
+
+/** The text of a punctuation or keyword token kind, or undefined for other kinds. */
+export function tokenToString(kind: SyntaxKind): string | undefined {
+  const text = compilerTokenToString(kind as number as CompilerSyntaxKind);
+  return text === '' ? undefined : text;
+}
+
+/**
+ * A diagnostic's text with its chain of messages, each on its own line, indented two spaces per level of
+ * the chain, as TypeScript prints them.
+ */
+export function flattenDiagnosticMessageText(
+  diagnostic: Diagnostic | string | undefined,
+  newLine: string,
+  indent = 0,
+): string {
+  if (diagnostic === undefined) return '';
+  if (typeof diagnostic === 'string') return diagnostic;
+  let result = '';
+  if (indent > 0) {
+    result += newLine;
+    for (let i = 0; i < indent; i++) result += '  ';
+  }
+  result += diagnostic.text;
+  for (const child of diagnostic.messageChain) result += flattenDiagnosticMessageText(child, newLine, indent + 1);
+  return result;
+}