Feature: tspconfig project with entrypoint

.chronus/changes/feature-project-config-2026-3-29-10-7-4.md

@@ -0,0 +1,14 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Add `kind: project` and `entrypoint` support to `tspconfig.yaml` for defining project boundaries and entrypoint resolution. See [Project Configuration](https://typespec.io/docs/handbook/configuration/configuration#project-configuration) for more details.
+
+```yaml title=tspconfig.yaml
+kind: project
+entrypoint: src/service.tsp
+emit:
+  - "@typespec/openapi3"
+```

packages/compiler/.scripts/build-init-templates.ts

@@ -14,6 +14,9 @@ const builtInTemplates: Record<string, InitTemplate> = {
     description: "Create a project representing a generic REST API service.",
     compilerVersion: minCompilerVersion,
     libraries: ["@typespec/http", "@typespec/rest", "@typespec/openapi", "@typespec/openapi3"],
+    config: {
+      kind: "project",
+    },
     emitters: {
       "@typespec/openapi3": {
         selected: true,

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

@@ -1,5 +1,11 @@
 import { createDiagnostic } from "../core/messages.js";
-import { getDirectoryPath, isPathAbsolute, joinPaths, resolvePath } from "../core/path-utils.js";
+import {
+  getBaseFileName,
+  getDirectoryPath,
+  isPathAbsolute,
+  joinPaths,
+  resolvePath,
+} from "../core/path-utils.js";
 import { createJSONSchemaValidator } from "../core/schema-validator.js";
 import { createSourceFile } from "../core/source-file.js";
 import { Diagnostic, NoTarget, SourceFile, SystemHost } from "../core/types.js";
@@ -178,6 +184,27 @@ async function loadConfigFile(
     data = deepClone(defaultConfig) as TypeSpecRawConfig;
   }
 
+  // Validate project-specific constraints
+  if (data.kind === "project" && getBaseFileName(filename) !== TypeSpecConfigFilename) {
+    diagnostics.push(
+      createDiagnostic({
+        code: "config-project-kind-filename",
+        format: { filename: getBaseFileName(filename) },
+        target: NoTarget,
+      }),
+    );
+  }
+
+  if (data.entrypoint !== undefined && data.kind !== "project") {
+    diagnostics.push(
+      createDiagnostic({
+        code: "config-project-only-option",
+        format: { option: "entrypoint" },
+        target: NoTarget,
+      }),
+    );
+  }
+
   const emit = data.emit;
   const options = data.options;
 
@@ -187,6 +214,8 @@ async function loadConfigFile(
     filename,
     diagnostics,
     extends: data.extends,
+    kind: data.kind,
+    entrypoint: data.entrypoint,
     environmentVariables: data["environment-variables"],
     parameters: data.parameters,
     outputDir: data["output-dir"] ?? "{cwd}/tsp-output",

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

@@ -18,6 +18,15 @@ export const TypeSpecConfigJsonSchema: JSONSchemaType<TypeSpecRawConfig> = {
       type: "string",
       nullable: true,
     },
+    kind: {
+      type: "string",
+      enum: ["project"],
+      nullable: true,
+    },
+    entrypoint: {
+      type: "string",
+      nullable: true,
+    },
     "environment-variables": {
       type: "object",
       nullable: true,

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

@@ -65,6 +65,28 @@ export async function resolveCompilerOptions(
   );
   config.diagnostics.forEach((x) => diagnostics.add(x));
 
+  // Validate that --config does not point to a project config
+  if (options.configPath !== undefined && config.kind === "project") {
+    diagnostics.add(
+      createDiagnostic({
+        code: "config-project-not-as-cli-config",
+        target: NoTarget,
+      }),
+    );
+  }
+
+  // When using --config with a non-project config, auto-inherit project settings
+  // from the project tspconfig.yaml of the entrypoint (not the config file location)
+  if (options.configPath !== undefined && config.kind !== "project") {
+    const entrypointDir = entrypointStat?.isDirectory()
+      ? options.entrypoint
+      : getDirectoryPath(options.entrypoint);
+    const projectConfig = await findProjectConfig(host, entrypointDir);
+    if (projectConfig?.kind === "project") {
+      config.entrypoint ??= projectConfig.entrypoint;
+    }
+  }
+
   const compilerOptions = diagnostics.pipe(resolveOptionsFromConfig(config, options));
   return diagnostics.wrap(compilerOptions);
 }
@@ -173,3 +195,24 @@ function mergeOptions(
 function hasNestedObjects(value: any): boolean {
   return value && typeof value === "object" && !Array.isArray(value);
 }
+
+/**
+ * Walk up directories from `startDir` to find the nearest project tspconfig.yaml (one with `kind: "project"`).
+ */
+async function findProjectConfig(
+  host: SystemHost,
+  startDir: string,
+): Promise<TypeSpecConfig | undefined> {
+  let dir = startDir;
+  while (true) {
+    const config = await loadTypeSpecConfigForPath(host, dir, false, false);
+    if (config.kind === "project" && config.diagnostics.length === 0) {
+      return config;
+    }
+    const parentDir = getDirectoryPath(dir);
+    if (parentDir === dir) {
+      return undefined;
+    }
+    dir = parentDir;
+  }
+}

packages/compiler/src/config/types.ts

@@ -10,6 +10,17 @@ export interface TypeSpecConfig {
    */
   projectRoot: string;
 
+  /**
+   * Kind of the config. When set to "project", this config marks a project boundary.
+   */
+  kind?: "project";
+
+  /**
+   * Main TypeSpec file for this project, relative to the config directory.
+   * Only meaningful when `kind` is `"project"`. Defaults to `"main.tsp"`.
+   */
+  entrypoint?: string;
+
   /** Yaml file used in this configuration. */
   file?: YamlScript;
 
@@ -76,6 +87,18 @@ export interface TypeSpecConfig {
  */
 export interface TypeSpecRawConfig {
   extends?: string;
+
+  /**
+   * Kind of the config. When set to "project", this config marks a project boundary.
+   */
+  kind?: "project";
+
+  /**
+   * Main TypeSpec file for this project, relative to the config directory.
+   * Only meaningful when `kind` is `"project"`. Defaults to `"main.tsp"`.
+   */
+  entrypoint?: string;
+
   "environment-variables"?: Record<string, ConfigEnvironmentVariable>;
   parameters?: Record<string, ConfigParameter>;
 

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

@@ -1,3 +1,4 @@
+import { loadTypeSpecConfigForPath } from "../config/config-loader.js";
 import { doIO, loadFile } from "../utils/io.js";
 import { resolveTspMain } from "../utils/misc.js";
 import { DiagnosticHandler } from "./diagnostics.js";
@@ -32,6 +33,13 @@ export async function resolveTypeSpecEntrypointForDir(
   dir: string,
   reportDiagnostic: DiagnosticHandler,
 ): Promise<string> {
+  // Check for project tspconfig first
+  const config = await loadTypeSpecConfigForPath(host, dir, false, false);
+  if (config.kind === "project") {
+    const entrypoint = config.entrypoint ?? "main.tsp";
+    return resolvePath(dir, entrypoint);
+  }
+
   const pkgJsonPath = resolvePath(dir, "package.json");
   const [pkg] = await loadFile(host, pkgJsonPath, JSON.parse, reportDiagnostic, {
     allowFileNotFound: true,

packages/compiler/src/core/messages.ts

@@ -641,6 +641,25 @@ const diagnostics = {
       default: paramMessage`No configuration file found at config path "${"path"}".`,
     },
   },
+  "config-project-kind-filename": {
+    severity: "error",
+    messages: {
+      default: paramMessage`Config with \`kind: project\` must be named "tspconfig.yaml". Found in "${"filename"}".`,
+    },
+  },
+  "config-project-only-option": {
+    severity: "error",
+    messages: {
+      default: paramMessage`Property "${"option"}" can only be used in a project config (with \`kind: project\`).`,
+    },
+  },
+  "config-project-not-as-cli-config": {
+    severity: "error",
+    messages: {
+      default:
+        "`--config` cannot point to a project config (with `kind: project`). Use a non-project build config that `extends` the project config instead.",
+    },
+  },
   /**
    * Program
    */

packages/compiler/src/init/scaffold.ts

@@ -153,24 +153,29 @@ async function writePackageJson(host: SystemHost, config: ScaffoldingConfig) {
   );
 }
 
-const placeholderConfig = `
-# extends: ../tspconfig.yaml                    # Extend another config file
-# emit:                                         # Emitter name
+const commentedOptions = `\
+# entrypoint: main.tsp                           # Main TypeSpec file (default: main.tsp)
+# extends: ../tspconfig.yaml                     # Extend another config file
+# emit:                                          # Emitter name
 #   - "<emitter-name"
-# options:                                      # Emitter options
+# options:                                       # Emitter options
 #   <emitter-name>:
 #    "<option-name>": "<option-value>"
-# environment-variables:                        # Environment variables which can be used to interpolate emitter options
+# environment-variables:                         # Environment variables which can be used to interpolate emitter options
 #   <variable-name>:
 #     default: "<variable-default>"
-# parameters:                                   # Parameters which can be used to interpolate emitter options
+# parameters:                                    # Parameters which can be used to interpolate emitter options
 #   <param-name>:
 #     default: "<param-default>"
-# trace:                                        # Trace areas to enable tracing
+# trace:                                         # Trace areas to enable tracing
 #  - "<trace-name>"
-# warn-as-error: true                           # Treat warnings as errors
-# output-dir: "{project-root}/_generated"       # Configure the base output directory for all emitters
-`.trim();
+# warn-as-error: true                            # Treat warnings as errors
+# output-dir: "{project-root}/_generated"        # Configure the base output directory for all emitters`;
+
+const placeholderConfig = `\
+kind: project                                    # Marks this as a TypeSpec project
+${commentedOptions}`;
+
 async function writeConfig(host: SystemHost, config: ScaffoldingConfig) {
   if (isFileSkipGeneration(TypeSpecConfigFilename, config.template.files ?? [])) {
     return;
@@ -189,7 +194,9 @@ async function writeConfig(host: SystemHost, config: ScaffoldingConfig) {
       Object.entries(config.emitters).map(([key, emitter]) => [key, emitter.options]),
     );
   }
-  const content = rawConfig ? stringify(rawConfig) : placeholderConfig;
+  const content = rawConfig
+    ? stringify(rawConfig).trimEnd() + "\n" + commentedOptions
+    : placeholderConfig;
   return host.writeFile(joinPaths(config.directory, TypeSpecConfigFilename), content);
 }
 

packages/compiler/src/server/entrypoint-resolver.ts

@@ -1,3 +1,4 @@
+import { loadTypeSpecConfigForPath } from "../config/config-loader.js";
 import { formatDiagnostic } from "../core/logger/console-sink.js";
 import { getDirectoryPath, joinPaths } from "../core/path-utils.js";
 import { SystemHost, Diagnostic as TypeSpecDiagnostic } from "../core/types.js";
@@ -27,6 +28,19 @@ export async function resolveEntrypointFile(
   }
 
   while (true) {
+    // Check for project tspconfig first (highest priority)
+    const config = await loadTypeSpecConfigForPath(host, dir, false, false);
+    if (config.kind === "project") {
+      const entrypoint = config.entrypoint ?? "main.tsp";
+      const candidate = await existingFile(dir, entrypoint);
+      logDebug({
+        level: "debug",
+        message: `project tspconfig found in ${dir}, entrypoint: ${entrypoint}`,
+      });
+      // Project boundary found — stop walking regardless of whether entrypoint exists
+      return candidate ?? (isFilePath ? path : undefined);
+    }
+
     let pkg: any;
     const pkgPath = joinPaths(dir, "package.json");
     const cached = await fileSystemCache?.get(pkgPath);

packages/compiler/templates/__snapshots__/rest/tspconfig.yaml

@@ -1,16 +1,18 @@
-# extends: ../tspconfig.yaml                    # Extend another config file
-# emit:                                         # Emitter name
+kind: project
+# entrypoint: main.tsp                           # Main TypeSpec file (default: main.tsp)
+# extends: ../tspconfig.yaml                     # Extend another config file
+# emit:                                          # Emitter name
 #   - "<emitter-name"
-# options:                                      # Emitter options
+# options:                                       # Emitter options
 #   <emitter-name>:
 #    "<option-name>": "<option-value>"
-# environment-variables:                        # Environment variables which can be used to interpolate emitter options
+# environment-variables:                         # Environment variables which can be used to interpolate emitter options
 #   <variable-name>:
 #     default: "<variable-default>"
-# parameters:                                   # Parameters which can be used to interpolate emitter options
+# parameters:                                    # Parameters which can be used to interpolate emitter options
 #   <param-name>:
 #     default: "<param-default>"
-# trace:                                        # Trace areas to enable tracing
+# trace:                                         # Trace areas to enable tracing
 #  - "<trace-name>"
-# warn-as-error: true                           # Treat warnings as errors
-# output-dir: "{project-root}/_generated"       # Configure the base output directory for all emitters
+# warn-as-error: true                            # Treat warnings as errors
+# output-dir: "{project-root}/_generated"        # Configure the base output directory for all emitters

packages/compiler/templates/scaffolding.json

@@ -9,6 +9,9 @@
       "@typespec/openapi",
       "@typespec/openapi3"
     ],
+    "config": {
+      "kind": "project"
+    },
     "emitters": {
       "@typespec/openapi3": {
         "selected": true,