@typespec/spector 0.1.0-alpha.9 → 0.1.0-dev.0

package/src/actions/upload-scenario-manifest.ts

@@ -7,37 +7,48 @@ import { computeScenarioManifest } from "../coverage/scenario-manifest.js";
 import { logger } from "../logger.js";
 
 export interface UploadScenarioManifestConfig {
-  scenariosPaths: string[];
+  scenariosPath: string;
   storageAccountName: string;
-  setNames: string[];
   containerName: string;
+  manifestName: string;
+  override?: boolean;
 }
 
 export async function uploadScenarioManifest({
-  scenariosPaths,
+  scenariosPath,
   storageAccountName,
-  setNames,
   containerName,
+  manifestName,
+  override = false,
 }: UploadScenarioManifestConfig) {
-  const manifests = [];
-  for (let idx = 0; idx < scenariosPaths.length; idx++) {
-    const path = resolve(process.cwd(), scenariosPaths[idx]);
-    logger.info(`Computing scenario manifest for ${path}`);
-    const [manifest, diagnostics] = await computeScenarioManifest(path, setNames[idx]);
-    if (manifest === undefined || diagnostics.length > 0) {
-      process.exit(-1);
-    }
-    manifests.push(manifest);
+  const path = resolve(process.cwd(), scenariosPath);
+  logger.info(`Computing scenario manifest for ${path}`);
+  const [manifest, diagnostics] = await computeScenarioManifest(path);
+  if (manifest === undefined || diagnostics.length > 0) {
+    process.exit(-1);
   }
-  await writeFile("manifest.json", JSON.stringify(manifests, null, 2));
+  await writeFile("manifest.json", JSON.stringify(manifest, null, 2));
   const client = new SpecCoverageClient(storageAccountName, {
     credential: new AzureCliCredential(),
     containerName,
   });
   await client.createIfNotExists();
-  await client.manifest.upload(manifests);
+  if (override) {
+    await client.manifest.upload(manifestName, manifest);
+    logger.info(
+      `${pc.green("✓")} Scenario manifest uploaded to ${storageAccountName} storage account.`,
+    );
+  } else {
+    const result = await client.manifest.uploadIfVersionNew(manifestName, manifest);
 
-  logger.info(
-    `${pc.green("✓")} Scenario manifest uploaded to ${storageAccountName} storage account.`,
-  );
+    if (result === "uploaded") {
+      logger.info(
+        `${pc.green("✓")} Scenario manifest new version uploaded to ${storageAccountName} storage account.`,
+      );
+    } else {
+      logger.info(
+        `${pc.white("-")} Existing scenario manifest in ${storageAccountName} storage account is up to date. No upload needed.`,
+      );
+    }
+  }
 }

package/src/actions/validate-mock-apis.ts

@@ -41,7 +41,7 @@ export async function validateMockApis({
     );
 
     if (programDiagnostics.length > 0) {
-      specCompiler.logDiagnostics(programDiagnostics, { log: logger.error });
+      specCompiler.logDiagnostics(programDiagnostics, specCompiler.NodeHost.logSink);
       diagnostics.reportDiagnostic({
         message: `Scenario ${name} is invalid.`,
       });

package/src/app/app.ts

@@ -1,4 +1,13 @@
-import { MockApiDefinition, MockRequest, RequestExt, ScenarioMockApi } from "@typespec/spec-api";
+import {
+  expandDyns,
+  MockApiDefinition,
+  MockBody,
+  MockMultipartBody,
+  MockRequest,
+  RequestExt,
+  ResolverConfig,
+  ScenarioMockApi,
+} from "@typespec/spec-api";
 import { ScenariosMetadata } from "@typespec/spec-coverage-sdk";
 import { Response, Router } from "express";
 import { getScenarioMetadata } from "../coverage/common.js";
@@ -19,6 +28,7 @@ export class MockApiApp {
   private router = Router();
   private server: MockApiServer;
   private coverageTracker: CoverageTracker;
+  private resolverConfig!: ResolverConfig;
 
   constructor(private config: ApiMockAppConfig) {
     this.server = new MockApiServer({ port: config.port });
@@ -54,79 +64,77 @@ export class MockApiApp {
     });
 
     this.server.use("/", this.router);
-    this.server.start();
+    // Getting the resolved port as setting 0 in the config will have express resolve on of the available ports
+    const port = await this.server.start();
+    this.resolverConfig = {
+      baseUrl: `http://localhost:${port}`,
+    };
   }
 
   private registerScenario(name: string, scenario: ScenarioMockApi) {
     for (const endpoint of scenario.apis) {
-      if (endpoint.kind !== "MockApiDefinition") {
-        this.router.route(endpoint.uri)[endpoint.method]((req: RequestExt, res: Response) => {
-          processRequest(
-            this.coverageTracker,
-            name,
-            endpoint.uri,
-            req,
-            res,
-            endpoint.handler,
-          ).catch((e) => {
-            logger.error("Unexpected request error", e);
-            res.status(500).end();
-          });
-        });
-      } else {
-        if (!endpoint.handler) {
-          endpoint.handler = createHandler(endpoint);
-        }
-        this.router.route(endpoint.uri)[endpoint.method]((req: RequestExt, res: Response) => {
-          processRequest(
-            this.coverageTracker,
-            name,
-            endpoint.uri,
-            req,
-            res,
-            endpoint.handler!,
-          ).catch((e) => {
-            logger.error("Unexpected request error", e);
-            res.status(500).end();
-          });
-        });
+      if (!endpoint.handler) {
+        endpoint.handler = createHandler(endpoint, this.resolverConfig);
       }
+      this.router.route(endpoint.uri)[endpoint.method]((req: RequestExt, res: Response) => {
+        processRequest(
+          this.coverageTracker,
+          name,
+          endpoint.uri,
+          req,
+          res,
+          endpoint.handler!,
+          this.resolverConfig,
+        ).catch((e) => {
+          logger.error("Unexpected request error", e);
+          res.status(500).end();
+        });
+      });
     }
   }
 }
 
-function isObject(value: any): boolean {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function validateBody(
+  req: MockRequest,
+  body: MockBody | MockMultipartBody,
+  config: ResolverConfig,
+) {
+  if ("kind" in body) {
+    // custom handler for now.
+  } else {
+    if (Buffer.isBuffer(body.rawContent)) {
+      req.expect.rawBodyEquals(body.rawContent);
+    } else {
+      const raw =
+        typeof body.rawContent === "string" ? body.rawContent : body.rawContent?.serialize(config);
+      switch (body.contentType) {
+        case "application/json":
+          req.expect.coercedBodyEquals(JSON.parse(raw as any));
+          break;
+        case "application/xml":
+          req.expect.xmlBodyEquals(
+            (raw as any).replace(`<?xml version='1.0' encoding='UTF-8'?>`, ""),
+          );
+          break;
+        default:
+          req.expect.rawBodyEquals(raw);
+      }
+    }
+  }
 }
 
-function createHandler(apiDefinition: MockApiDefinition) {
+function createHandler(apiDefinition: MockApiDefinition, config: ResolverConfig) {
   return (req: MockRequest) => {
+    const body = apiDefinition.request?.body;
     // Validate body if present in the request
-    if (apiDefinition.request.body) {
-      if (
-        apiDefinition.request.headers &&
-        apiDefinition.request.headers["Content-Type"] === "application/xml"
-      ) {
-        req.expect.xmlBodyEquals(
-          apiDefinition.request.body.rawContent.replace(
-            `<?xml version='1.0' encoding='UTF-8'?>`,
-            "",
-          ),
-        );
-      } else {
-        if (isObject(apiDefinition.request.body)) {
-          Object.entries(apiDefinition.request.body).forEach(([key, value]) => {
-            req.expect.deepEqual(req.body[key], value);
-          });
-        } else {
-          req.expect.coercedBodyEquals(apiDefinition.request.body);
-        }
-      }
+    if (body) {
+      validateBody(req, body, config);
     }
 
     // Validate headers if present in the request
-    if (apiDefinition.request.headers) {
-      Object.entries(apiDefinition.request.headers).forEach(([key, value]) => {
+    if (apiDefinition.request?.headers) {
+      const headers = expandDyns(apiDefinition.request.headers, config);
+      Object.entries(headers).forEach(([key, value]) => {
         if (key.toLowerCase() !== "content-type") {
           if (Array.isArray(value)) {
             req.expect.deepEqual(req.headers[key], value);
@@ -137,21 +145,12 @@ function createHandler(apiDefinition: MockApiDefinition) {
       });
     }
 
-    // Validate query params if present in the request
-    if (apiDefinition.request.params) {
-      Object.entries(apiDefinition.request.params).forEach(([key, value]) => {
-        if (!req.query[key]) {
-          if (Array.isArray(value)) {
-            req.expect.deepEqual(req.params[key], value);
-          } else {
-            req.expect.deepEqual(req.params[key], String(value));
-          }
+    if (apiDefinition.request?.query) {
+      Object.entries(apiDefinition.request.query).forEach(([key, value]) => {
+        if (Array.isArray(value)) {
+          req.expect.deepEqual(req.query[key], value);
         } else {
-          if (Array.isArray(value)) {
-            req.expect.deepEqual(req.query[key], value);
-          } else {
-            req.expect.containsQueryParam(key, String(value));
-          }
+          req.expect.containsQueryParam(key, String(value));
         }
       });
     }

package/src/app/request-processor.ts

@@ -1,8 +1,10 @@
 import {
+  expandDyns,
   MockRequest,
   MockRequestHandler,
   MockResponse,
   RequestExt,
+  ResolverConfig,
   ValidationError,
 } from "@typespec/spec-api";
 import { Response } from "express";
@@ -17,6 +19,7 @@ export async function processRequest(
   request: RequestExt,
   response: Response,
   func: MockRequestHandler,
+  resolverConfig: ResolverConfig,
 ): Promise<void> {
   const mockRequest = new MockRequest(request);
   const mockResponse = await callHandler(mockRequest, response, func);
@@ -25,18 +28,27 @@ export async function processRequest(
   }
 
   await coverageTracker.trackEndpointResponse(scenarioName, scenarioUri, mockResponse);
-  processResponse(response, mockResponse);
+  processResponse(response, mockResponse, resolverConfig);
 }
 
-const processResponse = (response: Response, mockResponse: MockResponse) => {
+const processResponse = (
+  response: Response,
+  mockResponse: MockResponse,
+  resolverConfig: ResolverConfig,
+) => {
   response.status(mockResponse.status);
 
   if (mockResponse.headers) {
-    response.set(mockResponse.headers);
+    response.set(expandDyns(mockResponse.headers, resolverConfig));
   }
 
   if (mockResponse.body) {
-    response.contentType(mockResponse.body.contentType).send(mockResponse.body.rawContent);
+    const raw =
+      typeof mockResponse.body.rawContent === "string" ||
+      Buffer.isBuffer(mockResponse.body.rawContent)
+        ? mockResponse.body.rawContent
+        : mockResponse.body.rawContent?.serialize(resolverConfig);
+    response.contentType(mockResponse.body.contentType).send(raw);
   }
 
   response.end();

package/src/cli/cli.ts

@@ -167,7 +167,7 @@ async function main() {
       },
     )
     .command(
-      "server-test <scenariosPaths..>",
+      "knock <scenariosPaths..>",
       "Executes the test cases against the service",
       (cmd) => {
         return cmd
@@ -181,23 +181,18 @@ async function main() {
             description: "Path to the server",
             type: "string",
           })
-          .option("runSingleScenario", {
-            description: "Single Scenario Case to run",
+          .option("filter", {
+            description: "Glob filter of scenario to run",
             type: "string",
           })
-          .option("runScenariosFromFile", {
-            description: "File that has the Scenarios to run",
-            type: "string",
-          })
-          .demandOption("scenariosPaths", "serverBasePath");
+          .demandOption("scenariosPaths");
       },
       async (args) => {
         for (const scenariosPath of args.scenariosPaths) {
           logger.info(`Executing server tests for scenarios at ${scenariosPath}`);
           await serverTest(scenariosPath, {
             baseUrl: args.baseUrl,
-            runSingleScenario: args.runSingleScenario,
-            runScenariosFromFile: args.runScenariosFromFile,
+            filter: args.filter,
           });
         }
       },
@@ -278,20 +273,13 @@ async function main() {
       },
     )
     .command(
-      "upload-manifest <scenariosPaths..>",
+      "upload-manifest <scenariosPath>",
       "Upload the scenario manifest. DO NOT CALL in generator.",
       (cmd) => {
         return cmd
-          .positional("scenariosPaths", {
+          .positional("scenariosPath", {
             description: "Path to the scenarios and mock apis",
             type: "string",
-            array: true,
-            demandOption: true,
-          })
-          .option("setName", {
-            type: "string",
-            description: "Set used to generate the manifest.",
-            array: true,
             demandOption: true,
           })
           .option("storageAccountName", {
@@ -303,14 +291,26 @@ async function main() {
             description: "Name of the Container",
             demandOption: true,
           })
+          .option("manifestName", {
+            type: "string",
+            description:
+              "Name of the manifest(will be located at manifests/<manifestName>.json in the container).",
+            demandOption: true,
+          })
+          .option("override", {
+            type: "boolean",
+            description: "Override existing manifest with the same version.",
+            default: false,
+          })
           .demandOption("storageAccountName");
       },
       async (args) => {
         await uploadScenarioManifest({
-          scenariosPaths: args.scenariosPaths,
+          scenariosPath: args.scenariosPath,
           storageAccountName: args.storageAccountName,
-          setNames: args.setName,
           containerName: args.containerName,
+          manifestName: args.manifestName,
+          override: args.override,
         });
       },
     )

package/src/config/config.ts

@@ -1,5 +1,5 @@
 import { readFile } from "fs/promises";
-import yaml from "js-yaml";
+import yaml from "yaml";
 import { Diagnostic } from "../utils/diagnostic-reporter.js";
 import { SpecConfigJsonSchema } from "./config-schema.js";
 import { SchemaValidator } from "./schema-validator.js";
@@ -9,7 +9,7 @@ const validator = new SchemaValidator(SpecConfigJsonSchema);
 
 export async function loadSpecConfig(path: string): Promise<[SpecConfig, Diagnostic[]]> {
   const content = await readFile(path);
-  const config: any = yaml.load(content.toString(), { filename: path });
+  const config: any = yaml.parse(content.toString());
   const diagnostics = validator.validate(config, path);
   return [config, diagnostics];
 }

package/src/coverage/coverage-tracker.ts

@@ -1,4 +1,4 @@
-import { Fail, KeyedMockResponse, MockResponse, PassByKeyScenario, PassByServiceKeyScenario, ScenarioMockApi } from "@typespec/spec-api";
+import { Fail, KeyedMockResponse, MockResponse, PassByKeyScenario,  ScenarioMockApi } from "@typespec/spec-api";
 import { logger } from "../logger.js";
 import { CoverageReport, ScenariosMetadata, ScenarioStatus } from "@typespec/spec-coverage-sdk";
 import { writeFileSync } from "fs";
@@ -106,7 +106,7 @@ export class CoverageTracker {
       return "pass";
     }
 
-    function checkByKeys(scenario: PassByKeyScenario | PassByServiceKeyScenario) {
+    function checkByKeys(scenario: PassByKeyScenario) {
       for (const endpoint of scenario.apis) {
         const hits = scenarioHits?.get(endpoint.uri);
         if (hits === undefined) {

package/src/coverage/scenario-manifest.ts

@@ -1,14 +1,13 @@
 import { loadScenarios } from "../scenarios-resolver.js";
 import { Diagnostic } from "../utils/diagnostic-reporter.js";
-import { getCommit, getPackageJson } from "../utils/misc-utils.js";
+import { getCommit, getPackageJson, type SpectorPackageJson } from "../utils/misc-utils.js";
 import { ScenarioLocation, ScenarioManifest } from "@typespec/spec-coverage-sdk";
-import { getSourceLocation, normalizePath } from "@typespec/compiler";
+import { getSourceLocation, normalizePath, PackageJson } from "@typespec/compiler";
 import { relative } from "path";
 import type { Scenario } from "../lib/decorators.js";
 
 export async function computeScenarioManifest(
   scenariosPath: string,
-  setName: string
 ): Promise<[ScenarioManifest | undefined, readonly Diagnostic[]]> {
   const [scenarios, diagnostics] = await loadScenarios(scenariosPath);
   if (diagnostics.length > 0) {
@@ -17,19 +16,31 @@ export async function computeScenarioManifest(
 
   const commit = getCommit(scenariosPath);
   const pkg = await getPackageJson(scenariosPath);
-  return [createScenarioManifest(scenariosPath, pkg?.version ?? "?", commit, scenarios, setName), []];
+  return [createScenarioManifest(scenariosPath, pkg, commit, scenarios), []];
 }
 
+function getRepo(pkg: PackageJson): string | undefined {
+  const repository = pkg.repository;
+  const gitUrl = typeof repository === "string" ? repository : repository?.url;
+  if (!gitUrl) {
+    return undefined;
+  }
+  // Parse git+https://github.com/org/repo.git to https://github.com/org/repo
+  return gitUrl.replace(/^git\+/, "").replace(/\.git$/, "");
+}
 export function createScenarioManifest(
   scenariosPath: string,
-  version: string,
+  pkg: SpectorPackageJson | undefined,
   commit: string,
   scenarios: Scenario[],
-  setName: string
 ): ScenarioManifest {
   const sortedScenarios = [...scenarios].sort((a, b) => a.name.localeCompare(b.name));
   return {
-    version,
+    version: pkg?.version ?? "?",
+    repo: pkg && getRepo(pkg),
+    sourceUrl: pkg?.spector?.sourceUrl,
+    packageName: pkg?.name,
+    displayName: pkg && ("displayName" in pkg ? pkg.displayName as string : undefined),
     commit,
     scenarios: sortedScenarios.map(({ name, scenarioDoc, target }) => {
       const tspLocation = getSourceLocation(target);
@@ -40,6 +51,5 @@ export function createScenarioManifest(
       };
       return { name, scenarioDoc, location };
     }),
-    setName
   };
 }

package/src/logger.ts

@@ -1,10 +1,41 @@
-import winston from "winston";
+/* eslint-disable no-console */
+import pc from "picocolors";
 
-export const logger = winston.createLogger({
+const levels = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 30,
+};
+
+type Level = keyof typeof levels;
+const levelDisplay: Record<Level, string> = {
+  debug: pc.blue("debug"),
+  info: pc.green("info"),
+  warn: pc.yellow("warn"),
+  error: pc.red("error"),
+};
+
+interface Logger {
+  level: Level;
+  debug: (message: string, ...data: unknown[]) => void;
+  info: (message: string, ...data: unknown[]) => void;
+  warn: (message: string, ...data: unknown[]) => void;
+  error: (message: string, ...data: unknown[]) => void;
+}
+
+export const logger: Logger = {
   level: "info",
-  transports: [
-    new winston.transports.Console({
-      format: winston.format.combine(winston.format.colorize(), winston.format.simple()),
-    }),
-  ],
-});
+  debug: log("debug"),
+  info: log("info"),
+  warn: log("warn"),
+  error: log("error"),
+};
+
+function log(level: Level) {
+  return (message: string, ...data: unknown[]) => {
+    if (levels[level] >= levels[logger.level]) {
+      console.log(levelDisplay[level], message, ...data);
+    }
+  };
+}

package/src/scenarios-resolver.ts

@@ -1,4 +1,4 @@
-import { Operation } from "@typespec/compiler";
+import type { Operation } from "@typespec/compiler";
 import { isSharedRoute } from "@typespec/http";
 import { ScenarioMockApi } from "@typespec/spec-api";
 import { dirname, join, relative, resolve } from "path";

package/src/server/server.ts

@@ -75,25 +75,39 @@ export class MockApiServer {
         verify: rawBinaryBodySaver,
       }),
     );
-    this.app.use(multer().any());
+    this.app.use(multer().any() as any);
   }
 
   public use(route: string, ...handlers: RequestHandler[]): void {
     this.app.use(route, ...handlers);
   }
 
-  public start(): void {
+  public start(): Promise<number> {
     this.app.use(errorHandler);
 
-    const server = this.app.listen(this.config.port, () => {
-      logger.info(`Started server on ${getAddress(server)}`);
+    return new Promise((resolve, reject) => {
+      const server = this.app.listen(this.config.port, () => {
+        const resolvedPort = getPort(server);
+        if (!resolvedPort) {
+          logger.error("Failed to resolve port");
+          reject(new Error("Failed to resolve port"));
+          return;
+        }
+        logger.info(`Started server on ${resolvedPort}`);
+        resolve(resolvedPort);
+      });
+
+      server.on("error", (err) => {
+        logger.error("Error starting server", err);
+        reject(err);
+      });
     });
   }
 }
 
 export type ServerRequestHandler = (request: RequestExt, response: Response) => void;
 
-const getAddress = (server: Server): string => {
+const getPort = (server: Server): number | undefined | null => {
   const address = server?.address();
-  return typeof address === "string" ? "pipe " + address : "port " + address?.port;
+  return typeof address === "string" ? null : address?.port;
 };

package/src/utils/misc-utils.ts

@@ -1,3 +1,4 @@
+import type { PackageJson } from "@typespec/compiler";
 import { execSync } from "child_process";
 import { readFile, stat } from "fs/promises";
 import { dirname, join } from "path";
@@ -10,7 +11,7 @@ export async function ensureScenariosPathExists(scenariosPath: string) {
       throw new Error(`Scenarios path ${scenariosPath} is not a directory.`);
     }
   } catch (e) {
-    throw new Error(`Scenarios path ${scenariosPath} doesn't exists.`);
+    throw new Error(`Scenarios path ${scenariosPath} doesn't exist.`, { cause: e });
   }
 }
 
@@ -18,9 +19,10 @@ export function getCommit(path: string): string {
   return execSync("git rev-parse HEAD", { cwd: path }).toString().trim();
 }
 
-export interface PackageJson {
-  name: string;
-  version: string;
+export interface SpectorPackageJson extends PackageJson {
+  spector?: {
+    sourceUrl?: string;
+  };
 }
 
 export async function getPackageJson(path: string): Promise<PackageJson | undefined> {