perf: cache HTTP operation resolution at the program level

.chronus/changes/http-operation-cache-2026-7-20-16-43-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Add `currentStage` property and `useCache` method to `Program` for stage-aware caching. `currentStage` tracks the compilation pipeline stage (parsing → checking → validating → linting → emitting), and `useCache` provides a generic caching mechanism that libraries can use to avoid redundant computation during later stages.

.chronus/changes/http-operation-cache-http-2026-7-22-19-25-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+Cache `getHttpOperation` results during linting and emitting stages using `program.useCache()`. This eliminates redundant route resolution when multiple linter rules inspect the same operations, improving linter performance on large specs.

packages/compiler/src/core/program.ts

@@ -75,6 +75,12 @@ import {
   TypeSpecScriptNode,
 } from "./types.js";
 
+/**
+ * The current stage of the compilation pipeline.
+ * Stages progress in order: parsing → checking → validating → linting → emitting.
+ */
+export type CompilationStage = "parsing" | "checking" | "validating" | "linting" | "emitting";
+
 export interface Program {
   compilerOptions: CompilerOptions;
   /** @internal */
@@ -138,6 +144,11 @@ export interface Program {
    * Project root. If a tsconfig was found/specified this is the directory for the tsconfig.json. Otherwise directory where the entrypoint is located.
    */
   readonly projectRoot: string;
+
+  /** @internal */
+  setCurrentStage(stage: CompilationStage): void;
+  /** @internal */
+  readonly currentStage: CompilationStage;
 }
 
 interface EmitterRef {
@@ -192,6 +203,7 @@ export async function compile(
   };
   const timer = perf.startTimer();
   // Emitter stage
+  program.setCurrentStage("emitting");
   for (const emitter of program.emitters) {
     // If in dry mode run and an emitter doesn't support it we have to skip it.
     if (program.compilerOptions.dryRun && !emitter.library.definition?.capabilities?.dryRun) {
@@ -229,6 +241,8 @@ async function createProgram(
   // eslint-disable-next-line prefer-const -- reassigned after source resolution
   let suppressionTracker: SuppressionTracker | undefined;
 
+  let currentStage: CompilationStage = "parsing";
+
   const logger = createLogger({ sink: host.logSink });
   const tracer = createTracer(logger, { filter: options.trace });
   const resolvedMain = await resolveTypeSpecEntrypoint(host, mainFile, reportDiagnostic);
@@ -260,6 +274,12 @@ async function createProgram(
     get suppressionTracker() {
       return suppressionTracker;
     },
+    get currentStage() {
+      return currentStage;
+    },
+    setCurrentStage(stage: CompilationStage) {
+      currentStage = stage;
+    },
     hasError() {
       return error;
     },
@@ -326,6 +346,7 @@ async function createProgram(
   }
 
   program.checker = createChecker(program, resolver);
+  currentStage = "checking";
   runtimeStats.checker = perf.time(() => program.checker.checkProgram());
 
   complexityStats.createdTypes = program.checker.stats.createdTypes;
@@ -336,6 +357,7 @@ async function createProgram(
   }
 
   // onValidate stage
+  currentStage = "validating";
   await runValidators();
 
   validateRequiredImports();
@@ -347,6 +369,7 @@ async function createProgram(
   }
 
   // Linter stage
+  currentStage = "linting";
   const lintResult = await linter.lint();
   runtimeStats.linter = lintResult.stats.runtime;
   program.reportDiagnostics(lintResult.diagnostics);

packages/compiler/src/experimental/cache.ts

@@ -0,0 +1,43 @@
+import type { Program } from "../core/program.js";
+import type { Type } from "../core/types.js";
+
+/**
+ * Get a cached value for the given key, computing it if not already cached.
+ * Caching is only active from the "validating" stage onward and only for
+ * finished types. During "parsing" and "checking", decorators are still being
+ * applied. Unfinished types (during decorator application or inside mutators)
+ * are never cached because the type graph may not yet be in a stable state.
+ *
+ * @param program The program instance.
+ * @param key A unique symbol identifying this cache namespace.
+ * @param type The type to use as the cache key within this namespace.
+ * @param compute A function that computes the value if not cached.
+ * @returns The cached or freshly computed value.
+ *
+ * @experimental
+ */
+export function useCache<T>(program: Program, key: symbol, type: Type, compute: () => T): T {
+  const stage = program.currentStage;
+  // Only cache from "validating" onward. During "parsing" and "checking",
+  // decorators are still being applied and may not have finished setting up
+  // route options, filters, or other state that affects resolution. By
+  // "validating" all decorators have completed and types are fully resolved.
+  if (stage !== "validating" && stage !== "linting" && stage !== "emitting") {
+    return compute();
+  }
+  // Don't cache results for unfinished types. Types are unfinished during
+  // decorator application (including late template instantiation in the
+  // emitting stage) and inside mutators. Caching at those points risks
+  // storing results computed against an incomplete type graph.
+  if (!type.isFinished) {
+    return compute();
+  }
+  const map = program.stateMap(key);
+  const existing = map.get(type);
+  if (existing !== undefined) {
+    return existing as T;
+  }
+  const value = compute();
+  map.set(type, value);
+  return value;
+}

packages/compiler/src/experimental/index.ts

@@ -1,4 +1,5 @@
 export { createSourceLoader as unsafe_createSourceLoader } from "../core/source-loader.js";
+export { useCache as unsafe_useCache } from "./cache.js";
 export {
   MutableType as unsafe_MutableType,
   Mutator as unsafe_Mutator,

packages/http/src/operations.ts

@@ -12,6 +12,7 @@ import {
   Operation,
   Program,
 } from "@typespec/compiler";
+import { unsafe_useCache as useCache } from "@typespec/compiler/experimental";
 import { getAuthenticationForOperation } from "./auth.js";
 import { getAuthentication } from "./decorators.js";
 import { isSharedRoute } from "./decorators/shared-route.js";
@@ -26,6 +27,8 @@ import {
   RouteResolutionOptions,
 } from "./types.js";
 
+const httpOperationCacheKey = Symbol.for("@typespec/http.httpOperationCache");
+
 /**
  * Return the Http Operation details for a given TypeSpec operation.
  * @param operation Operation
@@ -36,6 +39,11 @@ export function getHttpOperation(
   operation: Operation,
   options?: RouteResolutionOptions,
 ): [HttpOperation, readonly Diagnostic[]] {
+  if (!options) {
+    return useCache(program, httpOperationCacheKey, operation, () =>
+      getHttpOperationInternal(program, operation, options, new Map()),
+    );
+  }
   return getHttpOperationInternal(program, operation, options, new Map());
 }