@typespec/spector 0.1.0-alpha.0

package/src/lib/decorators.ts

@@ -0,0 +1,225 @@
+import {
+  $service,
+  Enum,
+  getNamespaceFullName,
+  getTypeName,
+  Interface,
+  listServices,
+  Model,
+  Namespace,
+  Operation,
+  Program,
+} from "@typespec/compiler";
+import {
+  $route,
+  $server,
+  getOperationVerb,
+  getRoutePath,
+  getServers,
+  HttpVerb,
+} from "@typespec/http";
+import { $versioned } from "@typespec/versioning";
+import {
+  ScenarioDecorator,
+  ScenarioDocDecorator,
+  ScenarioServiceDecorator,
+} from "../../generated-defs/TypeSpec.Spector.js";
+import { SpectorStateKeys } from "./lib.js";
+
+export const $scenario: ScenarioDecorator = (context, target, name?) => {
+  context.program.stateMap(SpectorStateKeys.Scenario).set(target, name ?? target.name);
+};
+
+export const $scenarioDoc: ScenarioDocDecorator = (context, target, doc, formatArgs?) => {
+  const formattedDoc = formatArgs ? replaceTemplatedStringFromProperties(doc, formatArgs) : doc;
+  context.program.stateMap(SpectorStateKeys.ScenarioDoc).set(target, formattedDoc);
+};
+
+export const $scenarioService: ScenarioServiceDecorator = (context, target, route, options?) => {
+  const properties = new Map().set("title", {
+    type: { kind: "String", value: getNamespaceFullName(target).replace(/\./g, "") },
+  });
+
+  context.program.stateSet(SpectorStateKeys.ScenarioService).add(target);
+
+  const versions = options ? (options as Model).properties.get("versioned")?.type : null;
+  if (versions) {
+    context.call($versioned, target, versions as Enum);
+  }
+  context.call($service, target, {
+    kind: "Model",
+    properties,
+    decorators: [],
+    projections: [],
+    name: "Service",
+    derivedModels: [],
+    projectionsByName: [],
+  } as any);
+  context.call($server, target, "http://localhost:3000", "TestServer endpoint");
+  context.call($route, target, route);
+};
+
+export function getScenarioDoc(
+  program: Program,
+  target: Operation | Interface | Namespace,
+): string | undefined {
+  return program.stateMap(SpectorStateKeys.ScenarioDoc).get(target);
+}
+
+function replaceTemplatedStringFromProperties(formatString: string, formatArgs: Model) {
+  return formatString.replace(/{(\w+)}/g, (_, propName) => {
+    const type = formatArgs.properties.get(propName)?.type;
+    if (type === undefined) {
+      return "";
+    }
+    return "value" in type ? String(type.value) : getTypeName(type);
+  });
+}
+
+export interface Scenario {
+  name: string;
+  scenarioDoc: string;
+  target: Operation | Interface | Namespace;
+  endpoints: ScenarioEndpoint[];
+}
+
+export interface ScenarioEndpoint {
+  verb: HttpVerb;
+  path: string;
+  target: Operation;
+}
+
+export function listScenarios(program: Program): Scenario[] {
+  return listScenarioIn(program, program.getGlobalNamespaceType());
+}
+
+export function getScenarioEndpoints(
+  program: Program,
+  target: Namespace | Interface | Operation,
+): ScenarioEndpoint[] {
+  switch (target.kind) {
+    case "Namespace":
+      return [
+        ...[...target.namespaces.values()].flatMap((x) => getScenarioEndpoints(program, x)),
+        ...[...target.interfaces.values()].flatMap((x) => getScenarioEndpoints(program, x)),
+        ...[...target.operations.values()].flatMap((x) => getScenarioEndpoints(program, x)),
+      ];
+    case "Interface":
+      return [...target.operations.values()].flatMap((x) => getScenarioEndpoints(program, x));
+    case "Operation":
+      return [
+        {
+          verb: getOperationVerb(program, target) ?? "get",
+          path: getOperationRoute(program, target),
+          target,
+        },
+      ];
+  }
+}
+
+function getRouteSegments(program: Program, target: Operation | Interface | Namespace): string[] {
+  const route = getRoutePath(program, target)?.path;
+  const seg = route ? [route] : [];
+  switch (target.kind) {
+    case "Namespace":
+      return target.namespace ? [...getRouteSegments(program, target.namespace), ...seg] : seg;
+    case "Interface":
+      return target.namespace ? [...getRouteSegments(program, target.namespace), ...seg] : seg;
+
+    case "Operation":
+      return target.interface
+        ? [...getRouteSegments(program, target.interface), ...seg]
+        : target.namespace
+          ? [...getRouteSegments(program, target.namespace), ...seg]
+          : seg;
+  }
+}
+
+function getOperationRoute(program: Program, target: Operation): string {
+  const template = getRouteSegmentFromServer(program);
+  const segments = getRouteSegments(program, target);
+  return (
+    (template
+      ? template.endsWith("/") || segments.length === 0
+        ? template
+        : template + "/"
+      : "/") + segments.map((x) => (x.startsWith("/") ? x.substring(1) : x)).join("/")
+  );
+}
+
+function getRouteSegmentFromServer(program: Program): string | undefined {
+  const serviceNs = listServices(program)[0]?.type;
+  const server = getServers(program, serviceNs);
+  if (server && server.length === 1) {
+    if (server[0].url.indexOf("localhost:3000") > -1) {
+      return server[0].url.split("localhost:3000")[1];
+    } else if (server[0].url.indexOf("{endpoint}") > -1) {
+      return server[0].url.split("{endpoint}")[1];
+    } else {
+      return server[0].url;
+    }
+  }
+  return undefined;
+}
+
+export function listScenarioIn(
+  program: Program,
+  target: Namespace | Interface | Operation,
+): Scenario[] {
+  const scenarioName = getScenarioName(program, target);
+  if (scenarioName) {
+    return [
+      {
+        target,
+        scenarioDoc: getScenarioDoc(program, target)!, /// `onValidate` validate against this happening
+        name: scenarioName,
+        endpoints: getScenarioEndpoints(program, target),
+      },
+    ];
+  }
+  switch (target.kind) {
+    case "Namespace":
+      return [
+        ...[...target.namespaces.values()].flatMap((x) => listScenarioIn(program, x)),
+        ...[...target.interfaces.values()].flatMap((x) => listScenarioIn(program, x)),
+        ...[...target.operations.values()].flatMap((x) => listScenarioIn(program, x)),
+      ];
+    case "Interface":
+      return [...target.operations.values()].flatMap((x) => listScenarioIn(program, x));
+    case "Operation":
+      return [];
+  }
+}
+
+function resolveScenarioName(target: Operation | Interface | Namespace, name: string): string {
+  const names = [name];
+
+  let current: Operation | Interface | Namespace | undefined = target;
+  while (true) {
+    current =
+      current.kind === "Operation" && current.interface ? current.interface : current.namespace;
+    if (
+      current === undefined ||
+      (current.kind === "Namespace" && (current.name === "" || current.name === "_Specs_"))
+    ) {
+      break;
+    }
+    names.unshift(current.name);
+  }
+  return names.join("_");
+}
+
+export function isScenario(program: Program, target: Operation | Interface | Namespace): boolean {
+  return program.stateMap(SpectorStateKeys.Scenario).has(target);
+}
+
+export function getScenarioName(
+  program: Program,
+  target: Operation | Interface | Namespace,
+): string | undefined {
+  const name = program.stateMap(SpectorStateKeys.Scenario).get(target);
+  if (name === undefined) {
+    return undefined;
+  }
+  return resolveScenarioName(target, name);
+}

package/src/lib/index.ts

@@ -0,0 +1,18 @@
+export {
+  $scenario,
+  $scenarioDoc,
+  $scenarioService,
+  Scenario,
+  ScenarioEndpoint,
+  getScenarioDoc,
+  getScenarioEndpoints,
+  getScenarioName,
+  isScenario,
+  listScenarioIn,
+  listScenarios,
+} from "./decorators.js";
+export { $lib, reportDiagnostic } from "./lib.js";
+export { $onValidate } from "./validate.js";
+
+/** @internal */
+export { $decorators } from "./tsp-index.js";

package/src/lib/lib.ts

@@ -0,0 +1,33 @@
+import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
+
+export const $lib = createTypeSpecLibrary({
+  name: "@typespec/spector",
+  diagnostics: {
+    "category-invalid": {
+      severity: "error",
+      messages: {
+        default: paramMessage`Category "${"category"}" is not one of the allowed category. Use ${"allowed"}. See https://github.com/Azure/cadl-ranch/blob/main/docs/decorators.md#category`,
+      },
+    },
+
+    "missing-scenario": {
+      severity: "warning",
+      messages: {
+        default: `Operation doesn't belong to a scenario. Use @scenario(name?: string) to mark it as a scenario. See https://github.com/Azure/cadl-ranch/blob/main/docs/decorators.md#scenario`,
+      },
+    },
+    "missing-scenario-doc": {
+      severity: "warning",
+      messages: {
+        default: `Operation is missing a scenario doc. Use @scenarioDoc to provide the name of the scenario. See https://github.com/Azure/cadl-ranch/blob/main/docs/decorators.md#scenariodoc`,
+      },
+    },
+  },
+  state: {
+    Scenario: { description: "Mark a scenario to be executed" },
+    ScenarioDoc: { description: "Mark a scenario documentation" },
+    ScenarioService: { description: "Mark a scenario service to be executed" },
+  },
+});
+
+export const { reportDiagnostic, createStateSymbol, stateKeys: SpectorStateKeys } = $lib;

package/src/lib/tsp-index.ts

@@ -0,0 +1,12 @@
+import type { TypeSpecSpectorDecorators } from "../../generated-defs/TypeSpec.Spector.js";
+import { $scenario, $scenarioDoc, $scenarioService } from "./decorators.js";
+export { $lib } from "./lib.js";
+
+/** @internal */
+export const $decorators = {
+  "TypeSpec.Spector": {
+    scenario: $scenario,
+    scenarioDoc: $scenarioDoc,
+    scenarioService: $scenarioService,
+  } satisfies TypeSpecSpectorDecorators,
+};

package/src/lib/validate.ts

@@ -0,0 +1,55 @@
+import {
+  Interface,
+  isDeclaredInNamespace,
+  isTemplateDeclaration,
+  listServices,
+  Namespace,
+  navigateProgram,
+  Operation,
+  Program,
+} from "@typespec/compiler";
+import { getScenarioDoc, getScenarioName } from "./decorators.js";
+import { reportDiagnostic } from "./lib.js";
+
+export function $onValidate(program: Program) {
+  const services = listServices(program);
+  navigateProgram(program, {
+    operation: (operation) => {
+      if (
+        (operation.interface && isTemplateDeclaration(operation.interface)) ||
+        isTemplateDeclaration(operation)
+      ) {
+        return;
+      }
+      //  If the scenario is not defined in one of the scenario service then we can ignore it.
+      if (!services.some((x) => isDeclaredInNamespace(operation, x.type))) {
+        return;
+      }
+      const scenarioType = checkIsInScenario(program, operation);
+      if (!scenarioType) {
+        reportDiagnostic(program, { code: "missing-scenario", target: operation });
+      } else {
+        const doc = getScenarioDoc(program, scenarioType);
+        if (doc === undefined) {
+          reportDiagnostic(program, { code: "missing-scenario-doc", target: scenarioType });
+        }
+      }
+    },
+  });
+}
+
+function checkIsInScenario(
+  program: Program,
+  type: Operation | Interface | Namespace,
+): Operation | Interface | Namespace | undefined {
+  if (getScenarioName(program, type)) {
+    return type;
+  }
+  if (type.kind === "Operation" && type.interface) {
+    return checkIsInScenario(program, type.interface);
+  }
+  if (type.namespace === undefined) {
+    return undefined;
+  }
+  return checkIsInScenario(program, type.namespace);
+}

package/src/logger.ts

@@ -0,0 +1,10 @@
+import winston from "winston";
+
+export const logger = winston.createLogger({
+  level: "info",
+  transports: [
+    new winston.transports.Console({
+      format: winston.format.combine(winston.format.colorize(), winston.format.simple()),
+    }),
+  ],
+});

package/src/routes/admin.ts

@@ -0,0 +1,15 @@
+import { Router } from "express";
+import { AdminUrls } from "../constants.js";
+import { logger } from "../logger.js";
+
+const router = Router();
+
+router.post(AdminUrls.stop, (_req, res) => {
+  logger.info("Received signal to stop server. Exiting...");
+  res.status(202).end();
+  setTimeout(() => {
+    process.exit(0);
+  });
+});
+
+export const adminRoutes: Router = router;

package/src/routes/index.ts

@@ -0,0 +1,7 @@
+import { Router } from "express";
+import { adminRoutes } from "./admin.js";
+
+const router = Router();
+router.use("/", adminRoutes);
+
+export const internalRouter: Router = router;

package/src/scenarios-resolver.ts

@@ -0,0 +1,209 @@
+import { Operation } from "@typespec/compiler";
+import { isSharedRoute } from "@typespec/http";
+import { ScenarioMockApi } from "@typespec/spec-api";
+import { dirname, join, relative, resolve } from "path";
+import pc from "picocolors";
+import { pathToFileURL } from "url";
+import type { Scenario } from "./lib/decorators.js";
+import { logger } from "./logger.js";
+import { importSpecExpect, importTypeSpec, importTypeSpecHttp } from "./spec-utils/index.js";
+import { findFilesFromPattern } from "./utils/file-utils.js";
+import {
+  createDiagnosticReporter,
+  Diagnostic,
+  ensureScenariosPathExists,
+  getSourceLocationStr,
+} from "./utils/index.js";
+import { normalizePath } from "./utils/path-utils.js";
+
+export interface MockApiFile {
+  path: string;
+  scenarios: Record<string, ScenarioMockApi>;
+}
+
+interface SpecScenarioFile {
+  name: string;
+  specFilePath: string;
+}
+
+export async function findScenarioSpecFiles(scenariosPath: string): Promise<SpecScenarioFile[]> {
+  await ensureScenariosPathExists(scenariosPath);
+  const normalizedScenarioPath = normalizePath(scenariosPath);
+  const pattern = [
+    `${normalizedScenarioPath}/**/client.tsp`,
+    `${normalizedScenarioPath}/**/main.tsp`,
+  ];
+  logger.debug(`Looking for scenarios in ${pattern}`);
+  const fullScenarios = await findFilesFromPattern(pattern);
+  logger.info(`Found ${fullScenarios.length} full scenarios.`);
+  const scenarioSet = new Set(fullScenarios);
+  const scenarios = fullScenarios.filter((scenario) => {
+    // Exclude main.tsp that have a client.tsp next to it, we should use that instead
+    return !(
+      normalizePath(scenario).endsWith("/main.tsp") &&
+      scenarioSet.has(normalizePath(join(dirname(scenario), "client.tsp")))
+    );
+  });
+
+  logger.info(`Found ${scenarios.length} scenarios.`);
+
+  return scenarios.map((name) => ({
+    name: normalizePath(relative(scenariosPath, name))
+      .replace("/main.tsp", "")
+      .replace("/client.tsp", ""),
+    specFilePath: normalizePath(resolve(scenariosPath, name)),
+  }));
+}
+
+export async function loadScenarios(
+  scenariosPath: string,
+): Promise<[Scenario[], readonly Diagnostic[]]> {
+  const scenarioFiles = await findScenarioSpecFiles(scenariosPath);
+  const typespecCompiler = await importTypeSpec(scenariosPath);
+  const specExpect = await importSpecExpect(scenariosPath);
+  const typespecHttp = await importTypeSpecHttp(scenariosPath);
+
+  const scenarioNames = new Map<string, Scenario[]>();
+  const endpoints = new Map<string, Operation[]>();
+  const diagnostics = createDiagnosticReporter();
+
+  for (const { name, specFilePath } of scenarioFiles) {
+    logger.debug(`Found scenario "${specFilePath}"`);
+    const program = await typespecCompiler.compile(typespecCompiler.NodeHost, specFilePath, {
+      additionalImports: ["@typespec/spector"],
+      noEmit: true,
+      warningAsError: true,
+    });
+
+    // Workaround https://github.com/Azure/cadl-azure/issues/2458
+    const programDiagnostics = program.diagnostics.filter(
+      (d) =>
+        !(
+          d.code === "@azure-tools/typespec-azure-core/casing-style" &&
+          typeof d.target === "object" &&
+          "kind" in d.target &&
+          d.target.kind === "Namespace" &&
+          d.target.name === "DPG"
+        ),
+    );
+
+    if (programDiagnostics.length > 0) {
+      for (const item of programDiagnostics) {
+        const sourceLocation = typespecCompiler.getSourceLocation(item.target);
+        diagnostics.reportDiagnostic({
+          message: `${item.message}: ${sourceLocation && getSourceLocationStr(sourceLocation)}`,
+        });
+      }
+
+      diagnostics.reportDiagnostic({
+        message: `${pc.red("✘")} Scenario ${name} is invalid.`,
+      });
+      continue;
+    }
+
+    const scenarios = specExpect.listScenarios(program);
+    logger.debug(`  ${scenarios.length} scenarios`);
+
+    for (const scenario of scenarios) {
+      const existing = scenarioNames.get(scenario.name);
+      if (existing) {
+        existing.push(scenario);
+      } else {
+        scenarioNames.set(scenario.name, [scenario]);
+      }
+    }
+
+    const service = typespecCompiler.ignoreDiagnostics(typespecHttp.getAllHttpServices(program))[0];
+    const server = typespecHttp.getServers(program, service.namespace)?.[0];
+    if (server?.url === undefined || !server?.url.includes("{")) {
+      const serverPath = server ? new URL(server.url).pathname : "";
+      for (const route of service.operations) {
+        const path = serverPath + route.path;
+        const key = `${route.verb} ${path}`;
+        const existing = endpoints.get(key);
+        if (existing) {
+          if (!isSharedRoute(program, route.operation)) {
+            existing.push(route.operation);
+          }
+        } else {
+          endpoints.set(key, [route.operation]);
+        }
+      }
+    }
+  }
+
+  for (const [name, scenarios] of scenarioNames.entries()) {
+    if (scenarios.length > 1) {
+      for (const scenario of scenarios) {
+        diagnostics.reportDiagnostic({
+          message: `Duplicate scenario name "${name}".`,
+          target: scenario.target,
+        });
+      }
+    }
+  }
+
+  for (const [path, operations] of endpoints.entries()) {
+    if (operations.length > 1) {
+      for (const operation of operations) {
+        diagnostics.reportDiagnostic({
+          message: `Duplicate endpoint path "${path}".`,
+          target: operation,
+        });
+      }
+    }
+  }
+
+  return [[...scenarioNames.values()].map((x) => x[0]), diagnostics.diagnostics];
+}
+
+export async function loadScenarioMockApiFiles(scenariosPath: string): Promise<MockApiFile[]> {
+  const pattern = normalizePath(join(scenariosPath, "../dist/**/*.js"));
+  logger.debug(`Looking for mock api files in ${pattern}`);
+  const files = await findFilesFromPattern(pattern);
+  logger.debug(`Detected ${files.length} mock api files: ${files}`);
+  const results: MockApiFile[] = [];
+  for (const file of files) {
+    const result = await import(pathToFileURL(file).href);
+    if (result.Scenarios) {
+      logger.debug(`File '${file}' contains ${Object.keys(result.Scenarios).length} scenarios.`);
+      results.push({
+        path: normalizePath(file),
+        scenarios: result.Scenarios,
+      });
+    } else {
+      logger.debug(`File '${file}' is not exporting any scenarios.`);
+    }
+  }
+  logger.info("result length: " + results.length);
+  return results;
+}
+
+export async function loadScenarioMockApis(
+  scenariosPath: string,
+): Promise<Record<string, ScenarioMockApi>> {
+  const files = await loadScenarioMockApiFiles(scenariosPath);
+  const result: Record<string, ScenarioMockApi> = {};
+
+  const duplicateTracker: Record<string, string[]> = {};
+  for (const file of files) {
+    for (const [key, scenario] of Object.entries(file.scenarios)) {
+      if (duplicateTracker[key]) {
+        duplicateTracker[key].push(file.path);
+      } else {
+        duplicateTracker[key] = [file.path];
+      }
+
+      result[key] = scenario;
+    }
+  }
+
+  for (const [key, paths] of Object.entries(duplicateTracker)) {
+    if (paths.length >= 2) {
+      logger.warn(
+        `Scenario ${key} is being defined multiple times in mockapis:\n${paths.map((x) => `    ${x}`).join("\n")}`,
+      );
+    }
+  }
+  return result;
+}

package/src/server/index.ts

@@ -0,0 +1 @@
+export * from "./server.js";

package/src/server/server.ts

@@ -0,0 +1,99 @@
+import { RequestExt } from "@typespec/spec-api";
+import bodyParser from "body-parser";
+import express, { ErrorRequestHandler, RequestHandler, Response } from "express";
+import { Server, ServerResponse } from "http";
+import morgan from "morgan";
+import multer from "multer";
+import { logger } from "../logger.js";
+import { cleanupBody } from "../utils/index.js";
+
+export interface MockApiServerConfig {
+  port: number;
+}
+
+const errorHandler: ErrorRequestHandler = (err, _req, res, _next) => {
+  logger.error("Error", err);
+
+  const errResponse = err.toJSON
+    ? err.toJSON()
+    : err instanceof Error
+      ? { name: err.name, message: err.message, stack: err.stack }
+      : err;
+
+  res.status(err.status || 500);
+  res.contentType("application/json").send(errResponse).end();
+};
+
+const rawBodySaver = (
+  req: RequestExt,
+  res: ServerResponse,
+  buf: Buffer,
+  encoding: BufferEncoding,
+) => {
+  if (buf && buf.length) {
+    req.rawBody = cleanupBody(buf.toString(encoding || "utf8"));
+  }
+};
+
+const rawBinaryBodySaver = (
+  req: RequestExt,
+  res: ServerResponse,
+  buf: Buffer,
+  encoding: BufferEncoding,
+) => {
+  if (buf && buf.length) {
+    req.rawBody = buf;
+  }
+};
+
+const loggerstream = {
+  write: (message: string) => logger.info(message),
+};
+
+export class MockApiServer {
+  private app: express.Application;
+
+  constructor(private config: MockApiServerConfig) {
+    this.app = express();
+    this.app.use(morgan("dev", { stream: loggerstream }));
+    this.app.use(bodyParser.json({ verify: rawBodySaver, strict: false }));
+    this.app.use(
+      bodyParser.json({
+        type: "application/merge-patch+json",
+        verify: rawBodySaver,
+        strict: false,
+      }),
+    );
+    this.app.use(bodyParser.urlencoded({ verify: rawBodySaver, extended: true }));
+    this.app.use(bodyParser.text({ type: "*/xml", verify: rawBodySaver }));
+    this.app.use(bodyParser.text({ type: "*/pdf", verify: rawBodySaver }));
+    this.app.use(bodyParser.text({ type: "text/plain" }));
+    this.app.use(
+      bodyParser.raw({
+        type: ["application/octet-stream", "image/png"],
+        limit: "10mb",
+        verify: rawBinaryBodySaver,
+      }),
+    );
+    this.app.use(multer().any());
+  }
+
+  public use(route: string, ...handlers: RequestHandler[]): void {
+    this.app.use(route, ...handlers);
+  }
+
+  public start(): void {
+    this.app.use(errorHandler);
+
+    const server = this.app.listen(this.config.port, () => {
+      logger.info(`Started server on ${getAddress(server)}`);
+    });
+  }
+}
+
+export type ServerRequestHandler = (request: RequestExt, response: Response) => void;
+
+const getAddress = (server: Server): string => {
+  const address = server?.address();
+  return typeof address === "string" ? "pipe " + address : "port " + address?.port;
+};