tsc-ts 0.0.4 → 0.0.5

package/src/library/parse.ts

@@ -0,0 +1,63 @@
+// Parsing one file with tsc-ts's public API.
+
+import { ParseOptions, type ScriptKind as CompilerScriptKind } from '../compiler/ast.js';
+import { CompilerHost, sourceFileMetadataOf } from '../compiler/file-loader.js';
+import { CachedFileSystem } from '../compiler/file-system.js';
+import { Resolver } from '../compiler/module-resolution.js';
+import { parseSourceFile as parse } from '../compiler/parser.js';
+import { getNormalizedAbsolutePath, toPath } from '../compiler/path.js';
+import { getExternalModuleIndicatorOptions } from '../compiler/program-utilities.js';
+import type { SourceFile } from './ast.js';
+import type { CompilerOptions } from './compiler-options.generated.js';
+import { ScriptKind } from './enums.generated.js';
+import { internalError } from './errors.js';
+import { HostFileSystem } from './host.js';
+import { type ApiCompilerOptions, compilerOptionsFromApi } from './options.js';
+import type { ProgramHost } from './types.js';
+
+export interface ParseSourceFileOptions {
+  /** The options of the program the file would be in: they decide what makes it a module. */
+  readonly compilerOptions?: CompilerOptions;
+  /** Where the nearest package.json of the file is looked up; the disk without a host. */
+  readonly host?: ProgramHost;
+  /** The script kind; by default, the kind the file name's extension implies. */
+  readonly scriptKind?: ScriptKind;
+}
+
+/**
+ * `fileName` (absolute, or relative to the host's current directory) with the contents `text`, parsed
+ * as a program with `compilerOptions` parses it: the same tree `tsc-ts --api` gives for the file in a
+ * project of that file alone, with parents set. Whether the file is a module depends on its nearest
+ * package.json, as in a program. The tree is not bound.
+ */
+export function parseSourceFile(fileName: string, text: string, options: ParseSourceFileOptions = {}): SourceFile {
+  try {
+    const host = options.host ?? diskHost();
+    const currentDirectory = host.getCurrentDirectory();
+    const compilerOptions = compilerOptionsFromApi((options.compilerOptions ?? {}) as ApiCompilerOptions);
+    const normalized = getNormalizedAbsolutePath(fileName, currentDirectory);
+    const path = toPath(normalized, currentDirectory, host.useCaseSensitiveFileNames());
+    const compilerHost = new CompilerHost(
+      new CachedFileSystem(new HostFileSystem(host)),
+      currentDirectory,
+      host.getDefaultLibraryDirectory(),
+    );
+    const metadata = sourceFileMetadataOf(new Resolver(compilerHost, compilerOptions), compilerOptions, normalized);
+    const parseOptions = new ParseOptions(
+      path,
+      (options.scriptKind ?? ScriptKind.Unknown) as number as CompilerScriptKind,
+      getExternalModuleIndicatorOptions(normalized, compilerOptions, metadata),
+    );
+    return parse(normalized, text, parseOptions) as unknown as SourceFile;
+  } catch (e) {
+    throw internalError(e);
+  }
+}
+
+function diskHost(): ProgramHost {
+  return {
+    getCurrentDirectory: () => process.cwd(),
+    useCaseSensitiveFileNames: () => process.platform !== 'win32' && process.platform !== 'darwin',
+    getDefaultLibraryDirectory: () => '',
+  };
+}

package/src/library/program.ts

@@ -0,0 +1,293 @@
+// Programs of tsc-ts's public API: createProgram, parseConfigFile and Program.
+
+// The emit pipeline, loaded first as tsc-ts's command line loads it: programs and checked programs refer to its
+// classes (EmitIndexes, EmitResult), which scriptc compiles only when the program imports their modules as values.
+// CheckedProgram is imported through it, not as a side effect, so that the declarations of tsc-ts/api don't import
+// the compiler's modules.
+import { CheckedProgram } from '../compiler/compile-program.js';
+import type { SourceFile as CompilerSourceFile } from '../compiler/ast.js';
+import { dropLibGlobals } from '../compiler/checker-symbols.js';
+import type { Diagnostic as CompilerDiagnostic } from '../compiler/diagnostics.js';
+import { CachedFileSystem } from '../compiler/file-system.js';
+import { getNormalizedAbsolutePath } from '../compiler/path.js';
+import { Program as CompilerProgram, sortAndDeduplicateDiagnostics } from '../compiler/program.js';
+import { ConfigParser, ParsedCommandLine } from '../compiler/tsconfig.js';
+import type { SourceFile } from './ast.js';
+import { LibraryTypeChecker } from './checker.js';
+import type { CompilerOptions } from './compiler-options.generated.js';
+import { type DiagnosticKind, diagnosticOf, programDiagnostics } from './diagnostics.js';
+import { DisposedProgramError, internalError } from './errors.js';
+import { HostFileSystem, LibraryCompilerHost } from './host.js';
+import { type ApiCompilerOptions, compilerOptionsFromApi, compilerOptionsOf } from './options.js';
+import type {
+  CreateProgramOptions,
+  Diagnostic,
+  ParsedConfigFile,
+  Program,
+  ProgramHost,
+  SourceFileMetadata,
+  TypeChecker,
+} from './types.js';
+
+/**
+ * A program of `rootNames` with `options`, reading files through `host`. It loads its files as `tsc-ts`
+ * loads a project's: resolving imports and references from the root files, with the default libraries of
+ * the options from the host's default library directory.
+ */
+export function createProgram(options: CreateProgramOptions): Program {
+  try {
+    const host = options.host;
+    const currentDirectory = host.getCurrentDirectory();
+    const rootNames = options.rootNames.map((name) => getNormalizedAbsolutePath(name, currentDirectory));
+    const config = new ParsedCommandLine(
+      compilerOptionsFromApi(options.options as ApiCompilerOptions),
+      undefined,
+      rootNames,
+      [],
+      undefined,
+      [],
+      currentDirectory,
+      host.useCaseSensitiveFileNames(),
+      rootNames.length,
+    );
+    return programOf(config, host);
+  } catch (e) {
+    throw internalError(e);
+  }
+}
+
+/** The program of a config file (`parseConfigFile`'s options and files), reading files through `host`. */
+export function createProgramFromConfigFile(configFileName: string, host: ProgramHost): Program {
+  try {
+    return programOf(parsedConfig(configFileName, host).config, host);
+  } catch (e) {
+    throw internalError(e);
+  }
+}
+
+/**
+ * The options and root files of a config file, with the diagnostics of reading it, as `tsc-ts --api`'s
+ * parseConfigFile returns them. A config file that can't be read gives one diagnostic and no files.
+ */
+export function parseConfigFile(configFileName: string, host: ProgramHost): ParsedConfigFile {
+  try {
+    const { config, errors } = parsedConfig(configFileName, host);
+    return {
+      options: compilerOptionsOf(config.options) as CompilerOptions,
+      fileNames: config.fileNames.slice(),
+      diagnostics: errors.map(diagnosticOf),
+    };
+  } catch (e) {
+    throw internalError(e);
+  }
+}
+
+function parsedConfig(
+  configFileName: string,
+  host: ProgramHost,
+): { config: ParsedCommandLine; errors: CompilerDiagnostic[] } {
+  const currentDirectory = host.getCurrentDirectory();
+  const errors: CompilerDiagnostic[] = [];
+  const config =
+    new ConfigParser(new HostFileSystem(host), currentDirectory).parseConfigFile(
+      getNormalizedAbsolutePath(configFileName, currentDirectory),
+      undefined,
+      undefined,
+      errors,
+    ) ??
+    new ParsedCommandLine(
+      {},
+      undefined,
+      [],
+      [],
+      undefined,
+      errors,
+      currentDirectory,
+      host.useCaseSensitiveFileNames(),
+      0,
+    );
+  return { config, errors: config.errors };
+}
+
+function programOf(config: ParsedCommandLine, host: ProgramHost): Program {
+  const fs = new CachedFileSystem(new HostFileSystem(host));
+  const compilerHost = new LibraryCompilerHost(fs, host.getCurrentDirectory(), host.getDefaultLibraryDirectory());
+  return new LibraryProgram(new CheckedProgram(new CompilerProgram(config, compilerHost)));
+}
+
+/**
+ * TypeScript's `getPreEmitDiagnostics`: the config file parsing, program, syntactic, global and semantic
+ * diagnostics of `program` (of `sourceFile` only, for the syntactic and semantic ones), sorted and without
+ * duplicates as tsc-ts sorts them. `program` must be one tsc-ts/api created.
+ */
+export function getPreEmitDiagnostics(program: Program, sourceFile?: SourceFile): readonly Diagnostic[] {
+  if (!(program instanceof LibraryProgram))
+    throw new TypeError('getPreEmitDiagnostics takes a program created by tsc-ts/api');
+  return program.preEmitDiagnostics(sourceFile);
+}
+
+class LibraryProgram implements Program {
+  private options: CompilerOptions | undefined = undefined;
+  private typeChecker: LibraryTypeChecker | undefined = undefined;
+  private disposed = false;
+
+  constructor(private readonly checked: CheckedProgram) {}
+
+  private get program(): CompilerProgram {
+    this.checkNotDisposed();
+    return this.checked.program;
+  }
+
+  private checkNotDisposed(): void {
+    if (this.disposed) throw new DisposedProgramError();
+  }
+
+  getCompilerOptions(): CompilerOptions {
+    try {
+      this.options ??= compilerOptionsOf(this.program.options) as CompilerOptions;
+      return this.options;
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  getSourceFile(fileName: string): SourceFile | undefined {
+    try {
+      return this.program.getSourceFile(fileName) as unknown as SourceFile | undefined;
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  getSourceFiles(): readonly SourceFile[] {
+    try {
+      return this.program.getSourceFiles() as unknown as readonly SourceFile[];
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  getSourceFileNames(): readonly string[] {
+    try {
+      return this.program.getSourceFiles().map((file) => file.fileName);
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  getSourceFileMetadata(fileName: string): SourceFileMetadata | undefined {
+    try {
+      const program = this.program;
+      const file = program.getSourceFile(fileName);
+      if (file === undefined) return undefined;
+      const metadata = program.sourceFileMetadata(file.path);
+      return {
+        isDefaultLibrary: program.isSourceFileDefaultLibrary(file.path),
+        isFromExternalLibrary: program.isSourceFileFromExternalLibrary(file),
+        packageJsonType: metadata.packageJsonType,
+        packageJsonDirectory: metadata.packageJsonDirectory,
+        impliedNodeFormat: metadata.impliedNodeFormat,
+      };
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  isSourceFileDefaultLibrary(file: SourceFile): boolean {
+    try {
+      return this.program.isSourceFileDefaultLibrary((file as unknown as CompilerSourceFile).path);
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  isSourceFileFromExternalLibrary(file: SourceFile): boolean {
+    try {
+      return this.program.isSourceFileFromExternalLibrary(file as unknown as CompilerSourceFile);
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  getTypeChecker(): TypeChecker {
+    try {
+      if (this.typeChecker === undefined) {
+        this.checkNotDisposed();
+        this.typeChecker = new LibraryTypeChecker(this.checked.createChecker());
+      }
+      return this.typeChecker;
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  private diagnostics(kind: DiagnosticKind, file: SourceFile | undefined): readonly Diagnostic[] {
+    try {
+      this.checkNotDisposed();
+      return programDiagnostics(this.checked, kind, file as unknown as CompilerSourceFile | undefined).map(
+        diagnosticOf,
+      );
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  preEmitDiagnostics(file: SourceFile | undefined): readonly Diagnostic[] {
+    try {
+      this.checkNotDisposed();
+      const compilerFile = file as unknown as CompilerSourceFile | undefined;
+      const all: CompilerDiagnostic[] = [];
+      for (const kind of ['config', 'program', 'syntactic', 'global', 'semantic'] as const)
+        for (const d of programDiagnostics(
+          this.checked,
+          kind,
+          kind === 'syntactic' || kind === 'semantic' ? compilerFile : undefined,
+        ))
+          all.push(d);
+      return sortAndDeduplicateDiagnostics(all).map(diagnosticOf);
+    } catch (e) {
+      throw internalError(e);
+    }
+  }
+
+  getSyntacticDiagnostics(file?: SourceFile): readonly Diagnostic[] {
+    return this.diagnostics('syntactic', file);
+  }
+
+  getBindDiagnostics(file?: SourceFile): readonly Diagnostic[] {
+    return this.diagnostics('bind', file);
+  }
+
+  getSemanticDiagnostics(file?: SourceFile): readonly Diagnostic[] {
+    return this.diagnostics('semantic', file);
+  }
+
+  getSuggestionDiagnostics(file?: SourceFile): readonly Diagnostic[] {
+    return this.diagnostics('suggestion', file);
+  }
+
+  getDeclarationDiagnostics(file?: SourceFile): readonly Diagnostic[] {
+    return this.diagnostics('declaration', file);
+  }
+
+  getProgramDiagnostics(): readonly Diagnostic[] {
+    return this.diagnostics('program', undefined);
+  }
+
+  getGlobalDiagnostics(): readonly Diagnostic[] {
+    return this.diagnostics('global', undefined);
+  }
+
+  getConfigFileParsingDiagnostics(): readonly Diagnostic[] {
+    return this.diagnostics('config', undefined);
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.typeChecker?.dispose();
+    this.typeChecker = undefined;
+    this.checked.disposeCheckers();
+    dropLibGlobals(this.checked.program.getSourceFiles());
+    this.disposed = true;
+  }
+}

package/src/library/types.ts

@@ -52,6 +52,11 @@ export interface Symbol {
  */
 export interface Type {
   readonly flags: TypeFlags;
+  /**
+   * The object flags of an object type (TypeFlags.Object). Other types carry flags the checker keeps for
+   * itself, such as ObjectFlags.PrimitiveUnion, where TypeScript 7's API gives 0. Flags the checker
+   * caches, such as ObjectFlags.MembersResolved, are set as queries compute them.
+   */
   readonly objectFlags: ObjectFlags;
   readonly id: number;
   getSymbol(): Symbol | undefined;
@@ -146,6 +151,9 @@ export interface TupleType extends InterfaceType {
   readonly readonly: boolean;
 }
 
+/** A reference to a tuple type (`[string, number]`): `getTarget()` is the TupleType (`isTupleType()`). */
+export interface TupleTypeReference extends TypeReference {}
+
 export interface UnionOrIntersectionType extends Type {}
 
 export interface UnionType extends UnionOrIntersectionType {}
@@ -312,6 +320,7 @@ export interface TypeChecker {
   /** The type of a symbol as narrowed at `location`. */
   getTypeOfSymbolAtLocation(symbol: Symbol, location: Node): Type;
   getTypeArguments(type: TypeReference): readonly Type[];
+  /** The target of an alias (SymbolFlags.Alias); throws an InternalCompilerError for any other symbol. */
   getAliasedSymbol(symbol: Symbol): Symbol;
   getPropertyOfType(type: Type, name: string): Symbol | undefined;
   getPropertiesOfType(type: Type): readonly Symbol[];
@@ -333,8 +342,12 @@ export interface TypeChecker {
   isArrayLikeType(type: Type): boolean;
   isTypeAssignableTo(source: Type, target: Type): boolean;
   resolveName(name: string, meaning: SymbolFlags, location?: Node, excludeGlobals?: boolean): Symbol | undefined;
+  /** The value `node` names where it is: `resolveName(node.text, SymbolFlags.Value | SymbolFlags.ExportValue, node)`. */
   getResolvedSymbol(node: Identifier): Symbol | undefined;
-  /** The text TypeScript 7's API gives for `type`, printed in `enclosingDeclaration` with `flags`. */
+  /**
+   * The text TypeScript 7's API gives for `type`, printed in `enclosingDeclaration` with `flags`; without
+   * flags, or with 0, with TypeFormatFlags.AllowUniqueESSymbolType and UseAliasDefinedOutsideCurrentScope.
+   */
   typeToString(type: Type, enclosingDeclaration?: Node, flags?: TypeFormatFlags): string;
   getAnyType(): Type;
   getUnknownType(): Type;