@suss/contract-serverless 0.3.2-0

package/dist/index.js

@@ -0,0 +1,582 @@
+// src/index.ts
+import path2 from "path";
+import { nestedDocumentLabel } from "@suss/behavioral-ir";
+import {
+  cloudFormationToSummaries,
+  documentSourceLabel
+} from "@suss/contract-cloudformation";
+
+// src/document.ts
+import fs from "fs";
+import path from "path";
+import YAML from "yaml";
+import { CLOUDFORMATION_YAML_TAGS } from "@suss/manifest-aws";
+var SERVICE_FILE_NAMES = [
+  "serverless.yml",
+  "serverless.yaml",
+  "serverless.json"
+];
+var PROGRAM_SERVICE_FILE_NAMES = [
+  "serverless.ts",
+  "serverless.js"
+];
+function locateServiceFile(candidate) {
+  const resolved = path.resolve(candidate);
+  if (!fs.existsSync(resolved)) {
+    return { kind: "missing" };
+  }
+  if (fs.statSync(resolved).isFile()) {
+    return isProgram(resolved) ? { kind: "program", file: resolved } : { kind: "readable", file: resolved };
+  }
+  for (const name of SERVICE_FILE_NAMES) {
+    const file = path.join(resolved, name);
+    if (fs.existsSync(file)) {
+      return { kind: "readable", file };
+    }
+  }
+  for (const name of PROGRAM_SERVICE_FILE_NAMES) {
+    const file = path.join(resolved, name);
+    if (fs.existsSync(file)) {
+      return { kind: "program", file };
+    }
+  }
+  return { kind: "missing" };
+}
+function isProgram(file) {
+  const name = path.basename(file);
+  return PROGRAM_SERVICE_FILE_NAMES.includes(name);
+}
+function findServiceFile(candidate) {
+  const located = locateServiceFile(candidate);
+  return located.kind === "readable" ? located.file : null;
+}
+function loadServerlessDocument(servicePath) {
+  const file = findServiceFile(servicePath);
+  if (file === null) {
+    throw new Error(`Serverless service file not found: ${servicePath}`);
+  }
+  const raw = fs.readFileSync(file, "utf-8");
+  const parsed = file.endsWith(".json") ? JSON.parse(raw) : YAML.parse(raw, { customTags: CLOUDFORMATION_YAML_TAGS });
+  if (parsed === null || typeof parsed !== "object") {
+    throw new Error(`Serverless service file is not an object: ${file}`);
+  }
+  return parsed;
+}
+
+// src/events.ts
+function readString(raw, ctx) {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const resolved = ctx.resolver.resolveString(raw);
+  return resolved.kind === "resolved" ? { value: resolved.value, symbolic: false } : { value: resolved.token, symbolic: true };
+}
+function asMap(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  return raw;
+}
+function readRoute(raw, ctx) {
+  const asString = readString(raw, ctx);
+  if (asString !== null) {
+    if (asString.symbolic) {
+      return {
+        abstain: `route is written as ${asString.value}, which the document does not state`
+      };
+    }
+    const space = asString.value.trim().indexOf(" ");
+    if (space === -1) {
+      return {
+        abstain: `route "${asString.value}" names no method and path`
+      };
+    }
+    return {
+      method: asString.value.slice(0, space).trim().toUpperCase(),
+      path: withLeadingSlash(asString.value.slice(space + 1).trim())
+    };
+  }
+  const map = asMap(raw);
+  if (map === null) {
+    return { abstain: "event is neither a route string nor a map" };
+  }
+  const method = readString(map.method, ctx);
+  const path3 = readString(map.path, ctx);
+  if (method === null || path3 === null) {
+    return { abstain: "event names no method or no path" };
+  }
+  if (method.symbolic || path3.symbolic) {
+    return {
+      abstain: `route method or path is written as ${method.symbolic ? method.value : path3.value}, which the document does not state`
+    };
+  }
+  return {
+    method: method.value.toUpperCase(),
+    path: withLeadingSlash(path3.value)
+  };
+}
+function withLeadingSlash(path3) {
+  return path3.startsWith("/") ? path3 : `/${path3}`;
+}
+function readReference(raw, ctx) {
+  if (typeof raw !== "string") {
+    return raw;
+  }
+  const resolved = ctx.resolver.resolveString(raw);
+  return resolved.kind === "resolved" ? resolved.value : resolved.token;
+}
+var httpApiEvent = (raw, ctx) => {
+  const route = readRoute(raw, ctx);
+  if ("abstain" in route) {
+    return { kind: "abstained", reason: route.abstain };
+  }
+  return {
+    kind: "event",
+    event: {
+      Type: "HttpApi",
+      Properties: { Method: route.method, Path: route.path }
+    }
+  };
+};
+var httpEvent = (raw, ctx) => {
+  const route = readRoute(raw, ctx);
+  if ("abstain" in route) {
+    return { kind: "abstained", reason: route.abstain };
+  }
+  return {
+    kind: "event",
+    event: {
+      Type: "Api",
+      Properties: { Method: route.method, Path: route.path }
+    }
+  };
+};
+var sqsEvent = (raw, ctx) => {
+  const map = asMap(raw);
+  const arn = map === null ? raw : map.arn;
+  const queue = readReference(arn, ctx);
+  if (queue === void 0 || queue === null || queue === "") {
+    return { kind: "abstained", reason: "sqs event names no queue" };
+  }
+  return {
+    kind: "event",
+    event: { Type: "SQS", Properties: { Queue: queue } }
+  };
+};
+var snsEvent = (raw, ctx) => {
+  const map = asMap(raw);
+  const named = map === null ? raw : map.arn ?? map.topicName;
+  const topic = readReference(named, ctx);
+  if (topic === void 0 || topic === null || topic === "") {
+    return { kind: "abstained", reason: "sns event names no topic" };
+  }
+  const filterPolicy = map?.filterPolicy;
+  return {
+    kind: "event",
+    event: {
+      Type: "SNS",
+      Properties: {
+        Topic: topic,
+        ...filterPolicy !== void 0 ? { FilterPolicy: filterPolicy } : {}
+      }
+    }
+  };
+};
+var scheduleEvent = (raw, ctx) => {
+  const map = asMap(raw);
+  const rate = map === null ? raw : map.rate ?? map.schedule;
+  const expression = Array.isArray(rate) ? rate[0] : rate;
+  const stated = readReference(expression, ctx);
+  const enabled = map?.enabled;
+  return {
+    kind: "event",
+    event: {
+      Type: "Schedule",
+      Properties: {
+        ...typeof stated === "string" ? { Schedule: stated } : {},
+        ...typeof enabled === "boolean" ? { Enabled: enabled } : {}
+      }
+    }
+  };
+};
+var eventBridgeEvent = (raw, ctx) => {
+  const map = asMap(raw);
+  if (map === null) {
+    return { kind: "abstained", reason: "eventBridge event is not a map" };
+  }
+  if (map.schedule !== void 0 && map.pattern === void 0) {
+    return scheduleEvent({ rate: map.schedule, enabled: map.enabled }, ctx);
+  }
+  if (map.pattern === void 0) {
+    return {
+      kind: "abstained",
+      reason: "eventBridge event states neither a pattern nor a schedule"
+    };
+  }
+  const eventBus = readReference(map.eventBus, ctx);
+  return {
+    kind: "event",
+    event: {
+      Type: "EventBridgeRule",
+      Properties: {
+        Pattern: map.pattern,
+        ...eventBus !== void 0 && eventBus !== null ? { EventBusName: eventBus } : {}
+      }
+    }
+  };
+};
+var EVENT_TRANSLATIONS = {
+  httpApi: httpApiEvent,
+  http: httpEvent,
+  sqs: sqsEvent,
+  sns: snsEvent,
+  schedule: scheduleEvent,
+  eventBridge: eventBridgeEvent
+};
+
+// src/variables.ts
+var REFERENCE = /\$\{([^{}]*)\}/g;
+var FRAMEWORK_SOURCES = [
+  "self",
+  "env",
+  "opt",
+  "cf",
+  "s3",
+  "ssm",
+  "aws",
+  "param",
+  "sls",
+  "file",
+  "git"
+];
+function namesFrameworkSource(body) {
+  const source = body.trim().split(/[:(]/, 1)[0].trim();
+  return FRAMEWORK_SOURCES.includes(source);
+}
+function createVariableResolver(document) {
+  function resolveString(raw, inProgress) {
+    const value = resolveValue(raw, inProgress);
+    if (value.kind === "symbolic") {
+      return value;
+    }
+    if (typeof value.value === "string") {
+      return { kind: "resolved", value: value.value };
+    }
+    if (typeof value.value === "number" || typeof value.value === "boolean") {
+      return { kind: "resolved", value: String(value.value) };
+    }
+    return { kind: "symbolic", token: raw };
+  }
+  function resolveValue(raw, inProgress) {
+    if (typeof raw !== "string") {
+      return { kind: "resolved", value: raw };
+    }
+    if (!raw.includes("${")) {
+      return { kind: "resolved", value: raw };
+    }
+    const wholeReference = wholeReferenceBody(raw);
+    if (wholeReference !== null) {
+      return resolveReference(wholeReference, inProgress);
+    }
+    let anyUnresolved = false;
+    const substituted = raw.replace(REFERENCE, (whole, body) => {
+      const resolved = resolveReference(body, inProgress);
+      if (resolved.kind === "resolved" && (typeof resolved.value === "string" || typeof resolved.value === "number" || typeof resolved.value === "boolean")) {
+        return String(resolved.value);
+      }
+      anyUnresolved = true;
+      return whole;
+    });
+    return anyUnresolved || substituted.includes("${") ? { kind: "symbolic", token: substituted } : { kind: "resolved", value: substituted };
+  }
+  function resolveReference(body, inProgress) {
+    const { primary, fallback } = splitFallback(body);
+    if (!primary.startsWith("self:")) {
+      return { kind: "symbolic", token: primary };
+    }
+    const path3 = primary.slice("self:".length);
+    if (inProgress.has(path3)) {
+      return { kind: "symbolic", token: primary };
+    }
+    const target = documentPath(document, path3);
+    if (target !== void 0) {
+      inProgress.add(path3);
+      const resolved = resolveValue(target, inProgress);
+      inProgress.delete(path3);
+      return resolved;
+    }
+    if (fallback !== null) {
+      const literal = literalFallback(fallback);
+      if (literal !== null) {
+        return { kind: "resolved", value: literal };
+      }
+    }
+    return { kind: "symbolic", token: primary };
+  }
+  function resolveTemplateString(raw) {
+    const whole = wholeReferenceBody(raw);
+    if (whole !== null && !namesFrameworkSource(whole)) {
+      return raw;
+    }
+    const resolved = resolveValue(raw, /* @__PURE__ */ new Set());
+    return resolved.kind === "resolved" ? resolved.value : resolved.token;
+  }
+  function resolveTemplateTree(value) {
+    if (typeof value === "string") {
+      return resolveTemplateString(value);
+    }
+    if (Array.isArray(value)) {
+      return value.map(resolveTemplateTree);
+    }
+    if (value === null || typeof value !== "object") {
+      return value;
+    }
+    const out = {};
+    for (const [key, entry] of Object.entries(
+      value
+    )) {
+      out[key] = resolveTemplateTree(entry);
+    }
+    return out;
+  }
+  return {
+    resolveValue: (raw) => resolveValue(raw, /* @__PURE__ */ new Set()),
+    resolveString: (raw) => resolveString(raw, /* @__PURE__ */ new Set()),
+    resolveTemplateTree
+  };
+}
+function wholeReferenceBody(raw) {
+  const trimmed = raw.trim();
+  const match = /^\$\{([^{}]*)\}$/.exec(trimmed);
+  return match === null ? null : match[1];
+}
+function splitFallback(body) {
+  const comma = body.indexOf(",");
+  if (comma === -1) {
+    return { primary: body.trim(), fallback: null };
+  }
+  return {
+    primary: body.slice(0, comma).trim(),
+    fallback: body.slice(comma + 1).trim()
+  };
+}
+function literalFallback(fallback) {
+  const quoted = /^'([^']*)'$/.exec(fallback) ?? /^"([^"]*)"$/.exec(fallback);
+  if (quoted !== null) {
+    return quoted[1];
+  }
+  if (/^-?\d+(\.\d+)?$/.test(fallback)) {
+    return fallback;
+  }
+  return null;
+}
+function documentPath(document, path3) {
+  if (path3 === "") {
+    return void 0;
+  }
+  let current = document;
+  for (const segment of path3.split(".")) {
+    if (current === null || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
+// src/translate.ts
+var IMPLICIT_HTTP_API = "HttpApi";
+var IMPLICIT_REST_API = "RestApi";
+var IMPLICIT_API_FOR_EVENT = {
+  HttpApi: IMPLICIT_HTTP_API,
+  Api: IMPLICIT_REST_API
+};
+var IMPLICIT_API_TYPE = {
+  [IMPLICIT_HTTP_API]: "AWS::Serverless::HttpApi",
+  [IMPLICIT_REST_API]: "AWS::Serverless::Api"
+};
+function translateService(document) {
+  const resolver = createVariableResolver(document);
+  const unread = [];
+  const resources = {};
+  const implicitApis = /* @__PURE__ */ new Set();
+  if (document.plugins !== void 0) {
+    unread.push({
+      functionName: null,
+      kind: "plugins",
+      reason: "the service loads plugins, which can add, rename or rewrite functions and events; what they declare is not in this document"
+    });
+  }
+  for (const [functionName, definition] of Object.entries(
+    document.functions ?? {}
+  )) {
+    if (definition === null || typeof definition !== "object") {
+      continue;
+    }
+    const handler = resolver.resolveValue(definition.handler);
+    if (handler.kind !== "resolved" || typeof handler.value !== "string") {
+      unread.push({
+        functionName,
+        kind: "handler",
+        reason: "the function's handler is not a string this document states, so nothing names the code behind it"
+      });
+      continue;
+    }
+    const events = {};
+    const declared = Array.isArray(definition.events) ? definition.events : [];
+    for (const [index, entry] of declared.entries()) {
+      if (entry === null || typeof entry !== "object") {
+        continue;
+      }
+      for (const [kind, raw] of Object.entries(
+        entry
+      )) {
+        const translate = EVENT_TRANSLATIONS[kind];
+        if (translate === void 0) {
+          unread.push({
+            functionName,
+            kind,
+            reason: "this reader does not translate that event kind yet"
+          });
+          continue;
+        }
+        const translated = translate(raw, { resolver });
+        if (translated.kind === "abstained") {
+          unread.push({ functionName, kind, reason: translated.reason });
+          continue;
+        }
+        events[`${kind}${index}`] = translated.event;
+        const implicitApi = IMPLICIT_API_FOR_EVENT[translated.event.Type];
+        if (implicitApi !== void 0) {
+          implicitApis.add(implicitApi);
+        }
+      }
+    }
+    const runtime = statedString(resolver.resolveValue(definition.runtime));
+    resources[functionName] = {
+      Type: "AWS::Serverless::Function",
+      Properties: {
+        Handler: handler.value,
+        ...runtime !== null ? { Runtime: runtime } : {},
+        ...Object.keys(events).length > 0 ? { Events: events } : {},
+        Environment: {
+          Variables: environmentVariables(definition.environment, resolver)
+        }
+      }
+    };
+  }
+  for (const apiId of implicitApis) {
+    resources[apiId] = { Type: IMPLICIT_API_TYPE[apiId], Properties: {} };
+  }
+  return {
+    functions: {
+      Globals: providerGlobals(document, resolver),
+      Resources: resources
+    },
+    resources: rawResources(document, resolver),
+    unread
+  };
+}
+function providerGlobals(document, resolver) {
+  const provider = document.provider ?? {};
+  const runtime = statedString(resolver.resolveValue(provider.runtime));
+  return {
+    Function: {
+      CodeUri: ".",
+      ...runtime !== null ? { Runtime: runtime } : {},
+      Environment: {
+        Variables: environmentVariables(provider.environment, resolver)
+      }
+    }
+  };
+}
+function statedString(resolved) {
+  return resolved.kind === "resolved" && typeof resolved.value === "string" ? resolved.value : null;
+}
+function environmentVariables(raw, resolver) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  const out = {};
+  for (const [name, value] of Object.entries(raw)) {
+    const resolved = resolver.resolveValue(value);
+    out[name] = resolved.kind === "resolved" ? resolved.value : resolved.token;
+  }
+  return out;
+}
+function rawResources(document, resolver) {
+  const block = document.resources;
+  if (block === null || typeof block !== "object" || Array.isArray(block)) {
+    return null;
+  }
+  const declared = block.Resources;
+  if (declared === null || typeof declared !== "object") {
+    return null;
+  }
+  return {
+    Resources: resolver.resolveTemplateTree(declared)
+  };
+}
+
+// src/index.ts
+var RECOGNITION = "serverless";
+var RESOURCES_DOCUMENT = "resources";
+function serverlessToSummaries(document, options = {}) {
+  const translated = translateService(document);
+  const report = options.onUnread ?? reportUnread;
+  for (const wiring of translated.unread) {
+    report(wiring);
+  }
+  const rootLabel = options.source ?? "serverless";
+  const summaries = cloudFormationToSummaries(translated.functions, {
+    source: rootLabel,
+    recognition: RECOGNITION
+  });
+  if (translated.resources === null) {
+    return summaries;
+  }
+  return [
+    ...summaries,
+    ...cloudFormationToSummaries(translated.resources, {
+      source: nestedDocumentLabel(rootLabel, [RESOURCES_DOCUMENT]),
+      recognition: RECOGNITION
+    })
+  ];
+}
+function serverlessFileToSummaries(servicePath, options = {}) {
+  const located = locateServiceFile(servicePath);
+  if (located.kind === "missing") {
+    throw new Error(`Serverless service file not found: ${servicePath}`);
+  }
+  if (located.kind === "program") {
+    const report = options.onUnread ?? reportUnread;
+    report({
+      functionName: null,
+      kind: path2.basename(located.file),
+      reason: "a program declares this service, and a reader does not run one to find out what it says"
+    });
+    return [];
+  }
+  const document = loadServerlessDocument(located.file);
+  return serverlessToSummaries(document, {
+    ...options,
+    source: options.source ?? documentSourceLabel("serverless", located.file)
+  });
+}
+function reportUnread(wiring) {
+  const where = wiring.functionName === null ? wiring.kind : `${wiring.functionName}.${wiring.kind}`;
+  process.stderr.write(`[suss] serverless: ${where}: ${wiring.reason}
+`);
+}
+export {
+  EVENT_TRANSLATIONS,
+  PROGRAM_SERVICE_FILE_NAMES,
+  SERVICE_FILE_NAMES,
+  createVariableResolver,
+  findServiceFile,
+  loadServerlessDocument,
+  locateServiceFile,
+  serverlessFileToSummaries,
+  serverlessToSummaries,
+  translateService
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@suss/contract-serverless",
+  "version": "0.3.2-0",
+  "type": "module",
+  "description": "Generate suss behavioral summaries from Serverless Framework serverless.yml service files.",
+  "keywords": [
+    "suss",
+    "behavioral-summary",
+    "aws",
+    "serverless",
+    "serverless-framework",
+    "lambda"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/serverless#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/contract/serverless"
+  },
+  "bugs": {
+    "url": "https://github.com/nimbuscloud-ai/suss/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@suss/behavioral-ir": "0.3.2",
+    "@suss/contract-aws-apigateway": "0.3.2",
+    "@suss/contract-cloudformation": "0.3.2",
+    "@suss/ir-core": "0.3.2",
+    "@suss/manifest-aws": "0.3.2",
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}