@azure-tools/typespec-ts 0.56.1-dev.1 → 0.57.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.56.1-dev.1",
+  "version": "0.57.0-dev.2",
   "description": "A TypeSpec emitter for TypeScript",
   "main": "dist/src/index.js",
   "type": "module",
@@ -18,7 +18,7 @@
   "license": "MIT",
   "devDependencies": {
     "@azure-rest/core-client": "^2.7.0",
-    "@azure-tools/azure-http-specs": "^0.1.0-alpha.44 || >= 0.1.0-alpha.45-dev.3",
+    "@azure-tools/azure-http-specs": "^0.1.0-alpha.44 || >= 0.1.0-alpha.45-dev.4",
     "@azure-tools/typespec-autorest": "^0.71.0 || >= 0.72.0-dev.0",
     "@azure-tools/typespec-azure-core": "^0.71.0 || >= 0.72.0-dev.0",
     "@azure-tools/typespec-azure-resource-manager": "^0.71.0 || >= 0.72.0-dev.1",
@@ -39,26 +39,26 @@
     "@microsoft/api-extractor": "^7.58.1",
     "@types/pluralize": "^0.0.33",
     "yaml": "^2.8.3",
-    "@azure-tools/spector-runner": "^0.1.0",
     "@typespec/spector": "^0.1.0-alpha.28",
+    "@azure-tools/spector-runner": "^0.1.0",
     "@typespec/spec-api": "^0.1.0-alpha.16",
-    "@typespec/http-specs": "^0.1.0-alpha.41",
     "@typespec/tspd": "^0.77.0",
-    "@typespec/compiler": "^1.15.0",
     "@typespec/http": "^1.15.0",
-    "@typespec/versioning": "^0.85.0",
+    "@typespec/compiler": "^1.15.0",
     "@typespec/openapi": "^1.15.0",
+    "@typespec/rest": "^0.85.0",
+    "@typespec/versioning": "^0.85.0",
     "@typespec/xml": "^0.85.0",
-    "@typespec/rest": "^0.85.0"
+    "@typespec/http-specs": "^0.1.0-alpha.41"
   },
   "peerDependencies": {
     "@azure-tools/typespec-azure-core": "^0.71.0 || >= 0.72.0-dev.0",
     "@azure-tools/typespec-client-generator-core": "^0.71.2 || >= 0.72.0-dev.3",
-    "@typespec/compiler": "^1.15.0",
     "@typespec/http": "^1.15.0",
     "@typespec/rest": "^0.85.0",
     "@typespec/xml": "^0.85.0",
-    "@typespec/versioning": "^0.85.0"
+    "@typespec/versioning": "^0.85.0",
+    "@typespec/compiler": "^1.15.0"
   },
   "dependencies": {
     "fast-xml-parser": "^5.10.1",

package/src/framework/hooks/sdk-types.ts

@@ -13,6 +13,7 @@ import { provideContext, useContext } from "../../context-manager.js";
 import { reportDiagnostic } from "../../lib.js";
 import { visitPackageTypes } from "../../modular/emit-models.js";
 import { getAllAncestors, getAllProperties } from "../../modular/helpers/operation-helpers.js";
+import { applyVisibilityModelSplit } from "../../modular/helpers/visibility-helpers.js";
 import { normalizeModelPropertyName } from "../../modular/type-expressions/get-type-expression.js";
 import type { SdkContext } from "../../utils/interfaces.js";
 import { NameType, normalizeName } from "../../utils/name-utils.js";
@@ -92,6 +93,7 @@ export function provideSdkTypes(context: SdkContext) {
     types: new Map<Type, SdkType>(),
     flattenProperties: new Map<SdkModelPropertyType, SdkFlattenPropertyContext>(),
   };
+  applyVisibilityModelSplit(context);
   visitPackageTypes(context);
   enrichFlattenProperties(context, sdkTypesContext.flattenProperties, flattenPropertyModelMap);
   for (const sdkModel of emitQueue) {

package/src/interfaces.ts

@@ -260,6 +260,10 @@ export interface ClientOptions {
    * Defaults to false.
    */
   generateReactNativeTarget?: boolean;
+  /**
+   * Generates visibility-specific request models. Experimental and disabled by default.
+   */
+  experimentalSplitModelsByVisibility?: boolean;
 }
 
 export interface ServiceInfo {

package/src/lib.ts

@@ -91,6 +91,7 @@ export interface EmitterOptions {
    * package.json exports). Defaults to `false`.
    */
   "generate-react-native-target"?: boolean;
+  "experimental-split-models-by-visibility"?: boolean;
 }
 
 export const EmitterOptionsSchema: JSONSchemaType<EmitterOptions> = {
@@ -312,6 +313,12 @@ export const EmitterOptionsSchema: JSONSchemaType<EmitterOptions> = {
       description:
         "When set to true, generates React Native build targets (tsconfig, warp target, package.json exports). Defaults to `false`.",
     },
+    "experimental-split-models-by-visibility": {
+      type: "boolean",
+      nullable: true,
+      description:
+        "Whether to project request-body models to their write visibility (e.g. WidgetCreate/WidgetCreateOrUpdate) so read-only properties do not leak into input types. Defaults to false",
+    },
   },
   required: [],
 };

package/src/modular/helpers/visibility-helpers.ts

@@ -0,0 +1,471 @@
+import type {
+  SdkHttpOperation,
+  SdkModelPropertyType,
+  SdkModelType,
+  SdkServiceMethod,
+  SdkType,
+} from "@azure-tools/typespec-client-generator-core";
+import { UsageFlags } from "@azure-tools/typespec-client-generator-core";
+import {
+  Visibility,
+  getVisibilitySuffix,
+  isVisible,
+  resolveRequestVisibility,
+} from "@typespec/http";
+
+import { getAllOperationsFromClient } from "../../framework/hooks/sdk-types.js";
+import type { SdkContext } from "../../utils/interfaces.js";
+import { getDirectSubtypes } from "./type-helpers.js";
+
+const responseUsageFlags =
+  UsageFlags.Output |
+  UsageFlags.Exception |
+  UsageFlags.LroInitial |
+  UsageFlags.LroPolling |
+  UsageFlags.LroFinalEnvelope;
+
+interface SplitState {
+  context: SdkContext;
+  /**
+   * Every reachable `(model, visibility)` pair in the write-body graph, keyed by
+   * an emitter-local model identity plus visibility.
+   */
+  nodes: Map<string, ModelNode>;
+  /**
+   * The write clone materialized for each node that `needsClone`, keyed the same
+   * way as `nodes`.
+   */
+  cloneByKey: Map<string, SdkModelType>;
+  /** Stable emitter-local IDs preserving `SdkModelType` object identity. */
+  modelIds: WeakMap<SdkModelType, number>;
+  nextModelId: number;
+}
+
+/** A `(model, visibility)` vertex in the write-body reference graph. */
+interface ModelNode {
+  model: SdkModelType;
+  visibility: Visibility;
+  /**
+   * Keys of referenced nodes. Discriminated hierarchy links are bidirectional
+   * so the whole hierarchy is projected together.
+   */
+  refKeys: Set<string>;
+  /** True if the model's own properties differ between `visibility` and Read. */
+  ownShapeDiffers: boolean;
+  /** True if this node can reach any shape-differing node. */
+  needsClone: boolean;
+}
+
+/**
+ * Projects request models whose write graph differs from their read graph.
+ * This must run before `visitPackageTypes` builds the emit queue.
+ */
+export function applyVisibilityModelSplit(context: SdkContext): void {
+  if (!context.emitterOptions?.experimentalSplitModelsByVisibility) {
+    return;
+  }
+
+  const state = createSplitState(context);
+  const methods = context.sdkPackage.clients.flatMap((client) =>
+    getAllOperationsFromClient(client),
+  );
+
+  // Phase 1 — collect the reachable `(model, visibility)` reference graph.
+  for (const method of methods) {
+    collectMethodRoots(state, method);
+  }
+
+  // Phase 2 — mark models whose write graph differs from their read graph.
+  markNodesNeedingClones(state);
+
+  // Phase 3 — materialize projected models and wire their references.
+  buildClones(state);
+
+  // Phase 4 — project the original response models to the canonical Read view.
+  projectResponseModelsToRead(state);
+
+  // Phase 5 — repoint operation parameters and payloads to projected models.
+  for (const method of methods) {
+    repointMethodBody(state, method);
+  }
+
+  // Register projected models for the subsequent emit queue traversal.
+  for (const clone of state.cloneByKey.values()) {
+    context.sdkPackage.models.push(clone);
+  }
+}
+
+/** Creates the graph state using Read as the canonical model visibility. */
+function createSplitState(context: SdkContext): SplitState {
+  return {
+    context,
+    nodes: new Map<string, ModelNode>(),
+    cloneByKey: new Map<string, SdkModelType>(),
+    modelIds: new WeakMap<SdkModelType, number>(),
+    nextModelId: 0,
+  };
+}
+
+/** Stable key identifying a `(model, visibility)` node (and its clone). */
+function nodeKeyFor(state: SplitState, model: SdkModelType, visibility: Visibility): string {
+  let modelId = state.modelIds.get(model);
+  if (modelId === undefined) {
+    modelId = state.nextModelId++;
+    state.modelIds.set(model, modelId);
+  }
+  return `${modelId}|${visibility}`;
+}
+
+/**
+ * Collects the write-body roots of a single operation. The root of each
+ * `methodParameterSegments` entry is the client-method parameter.
+ */
+function collectMethodRoots(state: SplitState, method: SdkServiceMethod<SdkHttpOperation>): void {
+  const operation = method.operation;
+  const bodyParam = operation?.bodyParam;
+  if (!bodyParam) {
+    return;
+  }
+
+  const visibility = resolveRequestVisibility(
+    state.context.program,
+    operation.__raw.operation,
+    operation.verb,
+  );
+
+  for (const segment of bodyParam.methodParameterSegments) {
+    const methodParam = segment[0];
+    if (!methodParam) {
+      continue;
+    }
+    collectReferencedModels(state, methodParam.type, visibility, new Set<string>());
+  }
+}
+
+/**
+ * Cycle-safe DFS that records a `(model, visibility)` node and its outgoing
+ * references. Nodes are registered before recursion so cyclic graphs terminate.
+ */
+function collectNode(state: SplitState, model: SdkModelType, visibility: Visibility): string {
+  const key = nodeKeyFor(state, model, visibility);
+  if (state.nodes.has(key)) {
+    return key;
+  }
+
+  const node: ModelNode = {
+    model,
+    visibility,
+    refKeys: new Set<string>(),
+    ownShapeDiffers: false,
+    needsClone: false,
+  };
+  // Seed before recursing so cycles terminate at the already-seeded node.
+  state.nodes.set(key, node);
+
+  for (const property of model.properties) {
+    if (property.kind === "property" && property.__raw) {
+      const visibleInWrite = isVisible(state.context.program, property.__raw, visibility);
+      const visibleInRead = isVisible(state.context.program, property.__raw, Visibility.Read);
+      if (visibleInWrite !== visibleInRead) {
+        node.ownShapeDiffers = true;
+      }
+      if (!visibleInWrite) {
+        continue;
+      }
+    }
+
+    if (property.kind === "property") {
+      collectReferencedModels(state, property.type, visibility, node.refKeys);
+    }
+  }
+
+  if (model.additionalProperties) {
+    collectReferencedModels(state, model.additionalProperties, visibility, node.refKeys);
+  }
+
+  if (model.baseModel) {
+    node.refKeys.add(collectNode(state, model.baseModel, visibility));
+  }
+
+  // Link base and subtypes bidirectionally so the projected hierarchy stays together.
+  if (findDiscriminatedRoot(model)) {
+    for (const neighbor of discriminatedNeighbors(model)) {
+      const neighborKey = collectNode(state, neighbor, visibility);
+      node.refKeys.add(neighborKey);
+      state.nodes.get(neighborKey)!.refKeys.add(key);
+    }
+  }
+
+  return key;
+}
+
+/** Collects model references nested in supported container types. */
+function collectReferencedModels(
+  state: SplitState,
+  type: SdkType,
+  visibility: Visibility,
+  refKeys: Set<string>,
+): void {
+  if (type.kind === "model") {
+    refKeys.add(collectNode(state, type, visibility));
+    return;
+  }
+  switch (type.kind) {
+    case "array":
+    case "dict":
+      collectReferencedModels(state, type.valueType, visibility, refKeys);
+      break;
+    case "nullable":
+      collectReferencedModels(state, type.type, visibility, refKeys);
+      break;
+    case "tuple":
+      for (const valueType of type.valueTypes) {
+        collectReferencedModels(state, valueType, visibility, refKeys);
+      }
+      break;
+    case "union":
+      for (const variantType of type.variantTypes) {
+        collectReferencedModels(state, variantType, visibility, refKeys);
+      }
+      break;
+  }
+}
+
+/** The base model and direct subtypes that share a node's discriminated tree. */
+function discriminatedNeighbors(model: SdkModelType): SdkModelType[] {
+  const neighbors: SdkModelType[] = [];
+  if (model.baseModel) {
+    neighbors.push(model.baseModel);
+  }
+  neighbors.push(...getDirectSubtypes(model));
+  return neighbors;
+}
+
+/**
+ * Walks up the inheritance chain and returns the top-most ancestor that
+ * declares a discriminator.
+ */
+function findDiscriminatedRoot(model: SdkModelType): SdkModelType | undefined {
+  let root: SdkModelType | undefined;
+  let current: SdkModelType | undefined = model;
+  while (current) {
+    if (current.discriminatedSubtypes) {
+      root = current;
+    }
+    current = current.baseModel;
+  }
+  return root;
+}
+
+/**
+ * Marks nodes whose write graph differs from the read graph by
+ * reverse-propagating from nodes whose own property membership differs.
+ */
+function markNodesNeedingClones(state: SplitState): void {
+  // Reverse edges propagate a nested difference back to every parent.
+  const predecessors = new Map<string, string[]>();
+  for (const [key, node] of state.nodes) {
+    for (const referencedKey of node.refKeys) {
+      let referrers = predecessors.get(referencedKey);
+      if (!referrers) {
+        referrers = [];
+        predecessors.set(referencedKey, referrers);
+      }
+      referrers.push(key);
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [key, node] of state.nodes) {
+    if (node.ownShapeDiffers) {
+      node.needsClone = true;
+      queue.push(key);
+    }
+  }
+  while (queue.length > 0) {
+    const key = queue.shift()!;
+    for (const predecessorKey of predecessors.get(key) ?? []) {
+      const predecessor = state.nodes.get(predecessorKey)!;
+      if (!predecessor.needsClone) {
+        predecessor.needsClone = true;
+        queue.push(predecessorKey);
+      }
+    }
+  }
+}
+
+/**
+ * Creates projected model shells, then wires properties and inheritance after
+ * every shell exists. This ordering lets forward, cyclic, and mutually recursive
+ * references resolve to projected models instead of the original read models.
+ */
+function buildClones(state: SplitState): void {
+  // Pass 1: create every shell before wiring references.
+  for (const [key, node] of state.nodes) {
+    if (!node.needsClone) {
+      continue;
+    }
+    const clone: SdkModelType = {
+      ...node.model,
+      name: `${node.model.name}${getVisibilitySuffix(node.visibility, Visibility.Read)}`,
+      properties: [],
+      // Write projections are request-only: preserve serialization flags, force Input,
+      // and remove inherited response roles.
+      usage: (node.model.usage | UsageFlags.Input) & ~responseUsageFlags,
+    };
+    state.cloneByKey.set(key, clone);
+  }
+
+  // Pass 2: remove dropped properties and wire surviving references.
+  for (const [key, node] of state.nodes) {
+    const clone = state.cloneByKey.get(key);
+    if (!clone) {
+      continue;
+    }
+    const { model, visibility } = node;
+
+    const properties: SdkModelPropertyType[] = [];
+    for (const property of model.properties) {
+      if (
+        property.kind === "property" &&
+        property.__raw &&
+        !isVisible(state.context.program, property.__raw, visibility)
+      ) {
+        continue;
+      }
+      let wiredProperty = property;
+      if (property.kind === "property") {
+        const projectedType = projectTypeReferences(state, property.type, visibility);
+        if (projectedType !== property.type) {
+          wiredProperty = { ...property, type: projectedType };
+        }
+      }
+      properties.push(wiredProperty);
+    }
+    clone.properties = properties;
+
+    if (model.additionalProperties) {
+      clone.additionalProperties = projectTypeReferences(
+        state,
+        model.additionalProperties,
+        visibility,
+      );
+    }
+
+    if (model.baseModel) {
+      clone.baseModel =
+        state.cloneByKey.get(nodeKeyFor(state, model.baseModel, visibility)) ?? model.baseModel;
+    }
+
+    if (findDiscriminatedRoot(model)) {
+      if (model.discriminatedSubtypes) {
+        clone.discriminatedSubtypes = Object.fromEntries(
+          Object.entries(model.discriminatedSubtypes).map(([discriminatorValue, subtype]) => [
+            discriminatorValue,
+            state.cloneByKey.get(nodeKeyFor(state, subtype, visibility)) ?? subtype,
+          ]),
+        );
+      }
+    }
+  }
+}
+
+/** Projects response-used models to the canonical Read visibility. */
+function projectResponseModelsToRead(state: SplitState): void {
+  for (const model of state.context.sdkPackage.models) {
+    if ((model.usage & responseUsageFlags) === 0) {
+      continue;
+    }
+    model.properties = model.properties.filter(
+      (property) =>
+        property.kind !== "property" ||
+        !property.__raw ||
+        isVisible(state.context.program, property.__raw, Visibility.Read),
+    );
+  }
+}
+
+/** Replaces model references nested in supported container types. */
+function projectTypeReferences(state: SplitState, type: SdkType, visibility: Visibility): SdkType {
+  if (type.kind === "model") {
+    return state.cloneByKey.get(nodeKeyFor(state, type, visibility)) ?? type;
+  }
+  switch (type.kind) {
+    case "array":
+    case "dict": {
+      const projectedValueType = projectTypeReferences(state, type.valueType, visibility);
+      return projectedValueType === type.valueType
+        ? type
+        : { ...type, valueType: projectedValueType };
+    }
+    case "nullable": {
+      const projectedType = projectTypeReferences(state, type.type, visibility);
+      return projectedType === type.type ? type : { ...type, type: projectedType };
+    }
+    case "tuple": {
+      const projectedValueTypes = type.valueTypes.map((valueType) =>
+        projectTypeReferences(state, valueType, visibility),
+      );
+      return projectedValueTypes.every((valueType, index) => valueType === type.valueTypes[index])
+        ? type
+        : { ...type, valueTypes: projectedValueTypes };
+    }
+    case "union": {
+      const projectedVariantTypes = type.variantTypes.map((variantType) =>
+        projectTypeReferences(state, variantType, visibility),
+      );
+      return projectedVariantTypes.every(
+        (variantType, index) => variantType === type.variantTypes[index],
+      )
+        ? type
+        : { ...type, variantTypes: projectedVariantTypes };
+    }
+  }
+  return type;
+}
+
+/**
+ * Repoints client-method parameters and their HTTP payload representation to
+ * projected models.
+ */
+function repointMethodBody(state: SplitState, method: SdkServiceMethod<SdkHttpOperation>): void {
+  const operation = method.operation;
+  const bodyParam = operation?.bodyParam;
+  if (!bodyParam) {
+    return;
+  }
+
+  const visibility = resolveRequestVisibility(
+    state.context.program,
+    operation.__raw.operation,
+    operation.verb,
+  );
+
+  for (const segment of bodyParam.methodParameterSegments) {
+    const methodParam = segment[0];
+    if (!methodParam) {
+      continue;
+    }
+
+    const originalType = methodParam.type;
+    const projectedType = projectTypeReferences(state, originalType, visibility);
+    if (projectedType === originalType) {
+      // The write view is identical to the read model (collapse).
+      continue;
+    }
+
+    methodParam.type = projectedType;
+
+    if (originalType === bodyParam.type) {
+      // A non-spread body uses the method parameter model as the payload model.
+      bodyParam.type = projectedType;
+    } else if (bodyParam.type.kind === "model") {
+      // A spread body uses a synthesized wrapper serialized property by property.
+      for (const bodyProperty of bodyParam.type.properties) {
+        if (bodyProperty.type === originalType) {
+          bodyProperty.type = projectedType;
+        }
+      }
+    }
+  }
+}

package/src/transform/transform-client-options.ts

@@ -57,6 +57,8 @@ function extractClientOptions(
   const ignoreNullableOnOptional = getIgnoreNullableOnOptional(emitterOptions);
   const wrapNonModelReturn = getWrapNonModelReturn(emitterOptions);
   const isMultiService = (dpgContext.allServiceNamespaces?.length ?? 0) > 1;
+  const experimentalSplitModelsByVisibility =
+    emitterOptions["experimental-split-models-by-visibility"] === true;
 
   return {
     ...credentialInfo,
@@ -85,6 +87,7 @@ function extractClientOptions(
     enableStorageCompat,
     treatUnknownAsRecord,
     generateReactNativeTarget,
+    experimentalSplitModelsByVisibility,
   };
 }