Expose initScaffolding via an internals export

.chronus/changes/expose-init-internals-2025-2-8-20-55-39.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/compiler"
+---
+
+Expose initScaffolding via an internals export

packages/compiler/package.json

@@ -49,6 +49,10 @@
     "./experimental/typekit": {
       "types": "./dist/src/experimental/typekit/index.d.ts",
       "default": "./dist/src/experimental/typekit/index.js"
+    },
+    "./internals": {
+      "types": "./dist/src/internals/index.d.ts",
+      "import": "./dist/src/internals/index.js"
     }
   },
   "browser": {

packages/compiler/src/config/config-loader.ts

@@ -3,7 +3,8 @@ import { getDirectoryPath, isPathAbsolute, joinPaths, resolvePath } from "../cor
 import { createJSONSchemaValidator } from "../core/schema-validator.js";
 import { createSourceFile } from "../core/source-file.js";
 import { CompilerHost, Diagnostic, NoTarget, SourceFile } from "../core/types.js";
-import { deepClone, deepFreeze, doIO, omitUndefined } from "../utils/misc.js";
+import { doIO } from "../utils/io.js";
+import { deepClone, deepFreeze, omitUndefined } from "../utils/misc.js";
 import { getLocationInYamlScript } from "../yaml/index.js";
 import { parseYaml } from "../yaml/parser.js";
 import { YamlScript } from "../yaml/types.js";

packages/compiler/src/config/config-to-options.ts

@@ -3,7 +3,8 @@ import { createDiagnostic } from "../core/messages.js";
 import { CompilerOptions } from "../core/options.js";
 import { getDirectoryPath, normalizePath } from "../core/path-utils.js";
 import { CompilerHost, Diagnostic, NoTarget } from "../core/types.js";
-import { deepClone, doIO, omitUndefined } from "../utils/misc.js";
+import { doIO } from "../utils/io.js";
+import { deepClone, omitUndefined } from "../utils/misc.js";
 import { expandConfigVariables } from "./config-interpolation.js";
 import { loadTypeSpecConfigForPath, validateConfigPathsAbsolute } from "./config-loader.js";
 import { EmitterOptions, TypeSpecConfig } from "./types.js";

packages/compiler/src/core/cli/actions/compile/compile.ts

@@ -1,4 +1,4 @@
-import { typespecVersion } from "../../../../utils/misc.js";
+import { typespecVersion } from "../../../../manifest.js";
 import { logDiagnostics } from "../../../diagnostics.js";
 import { resolveTypeSpecEntrypoint } from "../../../entrypoint-resolution.js";
 import { CompilerOptions } from "../../../options.js";

packages/compiler/src/core/cli/cli.ts

@@ -8,7 +8,7 @@ try {
 
 import yargs from "yargs";
 import { installTypeSpecDependencies } from "../../install/install.js";
-import { typespecVersion } from "../../utils/misc.js";
+import { typespecVersion } from "../../manifest.js";
 import { getTypeSpecEngine } from "../engine.js";
 import { compileAction } from "./actions/compile/compile.js";
 import { formatAction } from "./actions/format.js";

packages/compiler/src/core/entrypoint-resolution.ts

@@ -1,4 +1,5 @@
-import { doIO, loadFile, resolveTspMain } from "../utils/misc.js";
+import { doIO, loadFile } from "../utils/io.js";
+import { resolveTspMain } from "../utils/misc.js";
 import { DiagnosticHandler } from "./diagnostics.js";
 import { resolvePath } from "./path-utils.js";
 import { CompilerHost } from "./types.js";

packages/compiler/src/core/node-host.ts

@@ -1,11 +1,11 @@
-import { realpath } from "fs";
-import { mkdir, readdir, readFile, rm, stat, writeFile } from "fs/promises";
+import { mkdir, stat } from "fs/promises";
 import { fileURLToPath, pathToFileURL } from "url";
-import { findProjectRoot } from "../utils/misc.js";
+import { findProjectRoot } from "../utils/io.js";
 import { createConsoleSink } from "./logger/index.js";
+import { NodeSystemHost } from "./node-system-host.js";
 import { joinPaths } from "./path-utils.js";
-import { createSourceFile, getSourceFileKindFromExt } from "./source-file.js";
-import { CompilerHost, RmOptions } from "./types.js";
+import { getSourceFileKindFromExt } from "./source-file.js";
+import { CompilerHost } from "./types.js";
 
 export const CompilerPackageRoot = (await findProjectRoot(stat, fileURLToPath(import.meta.url)))!;
 
@@ -14,37 +14,13 @@ export const CompilerPackageRoot = (await findProjectRoot(stat, fileURLToPath(im
  * This is the the CompilerHost used by TypeSpec CLI.
  */
 export const NodeHost: CompilerHost = {
-  readUrl: async (url: string) => {
-    const response = await fetch(url, { redirect: "follow" });
-    const text = await response.text();
-    return createSourceFile(text, response.url);
-  },
-  readFile: async (path: string) => createSourceFile(await readUtf8File(path), path),
-  writeFile: (path: string, content: string) => writeFile(path, content, { encoding: "utf-8" }),
-  readDir: (path: string) => readdir(path),
-  rm: (path: string, options: RmOptions) => rm(path, options),
+  ...NodeSystemHost,
   getExecutionRoot: () => CompilerPackageRoot,
   getJsImport: (path: string) => import(pathToFileURL(path).href),
   getLibDirs() {
     const rootDir = this.getExecutionRoot();
     return [joinPaths(rootDir, "lib/std")];
   },
-  stat(path: string) {
-    return stat(path);
-  },
-  realpath(path) {
-    // BUG in the promise version of realpath https://github.com/microsoft/typespec/issues/2783
-    // Fix was only made to node 21.6 at this time. https://github.com/nodejs/node/issues/51031
-    return new Promise((resolve, reject) => {
-      realpath(path, (err, resolvedPath) => {
-        if (err) {
-          reject(err);
-        } else {
-          resolve(resolvedPath);
-        }
-      });
-    });
-  },
   getSourceFileKind: getSourceFileKindFromExt,
   mkdirp: (path: string) => mkdir(path, { recursive: true }),
   logSink: createConsoleSink(),
@@ -53,26 +29,3 @@ export const NodeHost: CompilerHost = {
     return pathToFileURL(path).href;
   },
 };
-
-async function readUtf8File(path: string) {
-  const buffer = await readFile(path);
-  const len = buffer.length;
-  if (len >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
-    throw new InvalidEncodingError("UTF-16 BE");
-  }
-  if (len >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
-    throw new InvalidEncodingError("UTF-16 LE");
-  }
-  if (len >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
-    // UTF-8 byte order mark detected
-    return buffer.toString("utf8", 3);
-  }
-  // Default is UTF-8 with no byte order mark
-  return buffer.toString("utf8");
-}
-
-export class InvalidEncodingError extends Error {
-  constructor(encoding: string) {
-    super(`Invalid encoding ${encoding}. TypeSpec only supports UTF-8 and UTF-8 with bom`);
-  }
-}

packages/compiler/src/core/node-system-host.ts

@@ -0,0 +1,59 @@
+import { realpath } from "fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "fs/promises";
+import { createSourceFile } from "./source-file.js";
+import { RmOptions, SystemHost } from "./types.js";
+
+/**
+ * Implementation of the @see SystemHost using the real file system.
+ */
+export const NodeSystemHost: SystemHost = {
+  readUrl: async (url: string) => {
+    const response = await fetch(url, { redirect: "follow" });
+    const text = await response.text();
+    return createSourceFile(text, response.url);
+  },
+  readFile: async (path: string) => createSourceFile(await readUtf8File(path), path),
+  writeFile: (path: string, content: string) => writeFile(path, content, { encoding: "utf-8" }),
+  readDir: (path: string) => readdir(path),
+  rm: (path: string, options: RmOptions) => rm(path, options),
+  stat(path: string) {
+    return stat(path);
+  },
+  realpath(path) {
+    // BUG in the promise version of realpath https://github.com/microsoft/typespec/issues/2783
+    // Fix was only made to node 21.6 at this time. https://github.com/nodejs/node/issues/51031
+    return new Promise((resolve, reject) => {
+      realpath(path, (err, resolvedPath) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve(resolvedPath);
+        }
+      });
+    });
+  },
+  mkdirp: (path: string) => mkdir(path, { recursive: true }),
+};
+
+async function readUtf8File(path: string) {
+  const buffer = await readFile(path);
+  const len = buffer.length;
+  if (len >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+    throw new InvalidEncodingError("UTF-16 BE");
+  }
+  if (len >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+    throw new InvalidEncodingError("UTF-16 LE");
+  }
+  if (len >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
+    // UTF-8 byte order mark detected
+    return buffer.toString("utf8", 3);
+  }
+  // Default is UTF-8 with no byte order mark
+  return buffer.toString("utf8");
+}
+
+export class InvalidEncodingError extends Error {
+  constructor(encoding: string) {
+    super(`Invalid encoding ${encoding}. TypeSpec only supports UTF-8 and UTF-8 with bom`);
+  }
+}

packages/compiler/src/core/program.ts

@@ -11,7 +11,8 @@ import {
   resolveModule,
 } from "../module-resolver/module-resolver.js";
 import { PackageJson } from "../types/package-json.js";
-import { deepEquals, findProjectRoot, isDefined, mapEquals, mutate } from "../utils/misc.js";
+import { findProjectRoot } from "../utils/io.js";
+import { deepEquals, isDefined, mapEquals, mutate } from "../utils/misc.js";
 import { createBinder } from "./binder.js";
 import { Checker, createChecker } from "./checker.js";
 import { createSuppressCodeFix } from "./compiler-code-fixes/suppress.codefix.js";

packages/compiler/src/core/source-loader.ts

@@ -6,7 +6,8 @@ import {
   ResolveModuleHost,
 } from "../module-resolver/module-resolver.js";
 import { PackageJson } from "../types/package-json.js";
-import { deepEquals, doIO, resolveTspMain } from "../utils/misc.js";
+import { doIO } from "../utils/io.js";
+import { deepEquals, resolveTspMain } from "../utils/misc.js";
 import { compilerAssert, createDiagnosticCollector } from "./diagnostics.js";
 import { resolveTypeSpecEntrypointForDir } from "./entrypoint-resolution.js";
 import { createDiagnostic } from "./messages.js";

packages/compiler/src/core/types.ts

@@ -2034,18 +2034,13 @@ export interface RmOptions {
   recursive?: boolean;
 }
 
-export interface CompilerHost {
+export interface SystemHost {
   /** read a file at the given url. */
   readUrl(url: string): Promise<SourceFile>;
 
   /** read a utf-8 or utf-8 with bom encoded file */
   readFile(path: string): Promise<SourceFile>;
 
-  /**
-   * Optional cache to reuse the results of parsing and binding across programs.
-   */
-  parseCache?: WeakMap<SourceFile, TypeSpecScriptNode>;
-
   /**
    * Write the file.
    * @param path Path to the file.
@@ -2072,6 +2067,19 @@ export interface CompilerHost {
    */
   mkdirp(path: string): Promise<string | undefined>;
 
+  // get info about a path
+  stat(path: string): Promise<{ isDirectory(): boolean; isFile(): boolean }>;
+
+  // get the real path of a possibly symlinked path
+  realpath(path: string): Promise<string>;
+}
+
+export interface CompilerHost extends SystemHost {
+  /**
+   * Optional cache to reuse the results of parsing and binding across programs.
+   */
+  parseCache?: WeakMap<SourceFile, TypeSpecScriptNode>;
+
   // get the directory TypeSpec is executing from
   getExecutionRoot(): string;
 
@@ -2081,14 +2089,8 @@ export interface CompilerHost {
   // get a promise for the ESM module shape of a JS module
   getJsImport(path: string): Promise<Record<string, any>>;
 
-  // get info about a path
-  stat(path: string): Promise<{ isDirectory(): boolean; isFile(): boolean }>;
-
   getSourceFileKind(path: string): SourceFileKind | undefined;
 
-  // get the real path of a possibly symlinked path
-  realpath(path: string): Promise<string>;
-
   // convert a file URL to a path in a file system
   fileURLToPath(url: string): string;
 

packages/compiler/src/init/core-templates.ts

@@ -1,6 +1,6 @@
 import { CompilerPackageRoot } from "../core/node-host.js";
 import { resolvePath } from "../core/path-utils.js";
-import { CompilerHost } from "../index.js";
+import type { SystemHost } from "../core/types.js";
 
 export const templatesDir = resolvePath(CompilerPackageRoot, "templates");
 export interface LoadedCoreTemplates {
@@ -9,7 +9,7 @@ export interface LoadedCoreTemplates {
 }
 
 let typeSpecCoreTemplates: LoadedCoreTemplates | undefined;
-export async function getTypeSpecCoreTemplates(host: CompilerHost): Promise<LoadedCoreTemplates> {
+export async function getTypeSpecCoreTemplates(host: SystemHost): Promise<LoadedCoreTemplates> {
   if (typeSpecCoreTemplates === undefined) {
     const file = await host.readFile(resolvePath(templatesDir, "scaffolding.json"));
     const content = JSON.parse(file.text);

packages/compiler/src/init/scaffold.ts

@@ -1,19 +1,19 @@
 import { stringify } from "yaml";
-import { TypeSpecConfigFilename } from "../config/config-loader.js";
-import { TypeSpecRawConfig } from "../config/types.js";
-import { formatTypeSpec } from "../core/formatter.js";
+import type { TypeSpecRawConfig } from "../config/types.js";
 import { getDirectoryPath, joinPaths } from "../core/path-utils.js";
-import { CompilerHost } from "../core/types.js";
-import { PackageJson } from "../types/package-json.js";
+import type { SystemHost } from "../core/types.js";
+import type { PackageJson } from "../types/package-json.js";
 import { readUrlOrPath, resolveRelativeUrlOrPath } from "../utils/misc.js";
-import { FileTemplatingContext, createFileTemplatingContext, render } from "./file-templating.js";
-import {
+import { createFileTemplatingContext, render } from "./file-templating.js";
+import type {
   InitTemplate,
   InitTemplateFile,
   InitTemplateLibrary,
   InitTemplateLibrarySpec,
 } from "./init-template.js";
 
+export const TypeSpecConfigFilename = "tspconfig.yaml";
+
 export interface ScaffoldingConfig {
   /** Template used to resolve that config */
   template: InitTemplate;
@@ -83,7 +83,7 @@ export function makeScaffoldingConfig(
  * @param host
  * @param config
  */
-export async function scaffoldNewProject(host: CompilerHost, config: ScaffoldingConfig) {
+export async function scaffoldNewProject(host: SystemHost, config: ScaffoldingConfig) {
   await host.mkdirp(config.directory);
   await writePackageJson(host, config);
   await writeConfig(host, config);
@@ -101,7 +101,7 @@ export function isFileSkipGeneration(fileName: string, files: InitTemplateFile[]
   return false;
 }
 
-async function writePackageJson(host: CompilerHost, config: ScaffoldingConfig) {
+async function writePackageJson(host: SystemHost, config: ScaffoldingConfig) {
   if (isFileSkipGeneration("package.json", config.template.files ?? [])) {
     return;
   }
@@ -156,7 +156,7 @@ const placeholderConfig = `
 # warn-as-error: true                           # Treat warnings as errors
 # output-dir: "{project-root}/_generated"       # Configure the base output directory for all emitters
 `.trim();
-async function writeConfig(host: CompilerHost, config: ScaffoldingConfig) {
+async function writeConfig(host: SystemHost, config: ScaffoldingConfig) {
   if (isFileSkipGeneration(TypeSpecConfigFilename, config.template.files ?? [])) {
     return;
   }
@@ -178,7 +178,7 @@ async function writeConfig(host: CompilerHost, config: ScaffoldingConfig) {
   return host.writeFile(joinPaths(config.directory, TypeSpecConfigFilename), content);
 }
 
-async function writeMain(host: CompilerHost, config: ScaffoldingConfig) {
+async function writeMain(host: SystemHost, config: ScaffoldingConfig) {
   if (isFileSkipGeneration("main.tsp", config.template.files ?? [])) {
     return;
   }
@@ -191,7 +191,7 @@ async function writeMain(host: CompilerHost, config: ScaffoldingConfig) {
   const lines = [...config.libraries.map((x) => `import "${x.name}";`), ""];
   const content = lines.join("\n");
 
-  return host.writeFile(joinPaths(config.directory, "main.tsp"), await formatTypeSpec(content));
+  return host.writeFile(joinPaths(config.directory, "main.tsp"), content);
 }
 
 const defaultGitignore = `
@@ -205,15 +205,15 @@ dist/
 # Dependency directories
 node_modules/
 `.trim();
-async function writeGitignore(host: CompilerHost, config: ScaffoldingConfig) {
+async function writeGitignore(host: SystemHost, config: ScaffoldingConfig) {
   if (!config.includeGitignore || isFileSkipGeneration(".gitignore", config.template.files ?? [])) {
     return;
   }
 
   return host.writeFile(joinPaths(config.directory, ".gitignore"), defaultGitignore);
 }
 
-async function writeFiles(host: CompilerHost, config: ScaffoldingConfig) {
+async function writeFiles(host: SystemHost, config: ScaffoldingConfig) {
   const templateContext = createFileTemplatingContext(config);
   if (!config.template.files) {
     return;
@@ -226,9 +226,9 @@ async function writeFiles(host: CompilerHost, config: ScaffoldingConfig) {
 }
 
 async function writeFile(
-  host: CompilerHost,
+  host: SystemHost,
   config: ScaffoldingConfig,
-  context: FileTemplatingContext,
+  context: any,
   file: InitTemplateFile,
 ) {
   const baseDir = config.baseUri + "/";