@suss/contract-appsync 0.0.1

package/dist/index.js

@@ -0,0 +1,717 @@
+// src/index.ts
+import fs from "fs";
+import path2 from "path";
+import YAML from "yaml";
+
+// src/refs.ts
+function resolveLogicalRef(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value === null || typeof value !== "object") {
+    return null;
+  }
+  const obj = value;
+  const ref = obj.Ref;
+  if (typeof ref === "string") {
+    return ref;
+  }
+  const getAtt = obj["Fn::GetAtt"];
+  if (Array.isArray(getAtt) && getAtt.length > 0 && typeof getAtt[0] === "string") {
+    return getAtt[0];
+  }
+  return null;
+}
+function stringField(value) {
+  return typeof value === "string" ? value : null;
+}
+function asRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+
+// src/sam.ts
+var RESOLVER_ROOT_TYPES = ["Query", "Mutation", "Subscription"];
+var DATA_SOURCE_CATEGORIES = {
+  Lambdas: "lambda",
+  DynamoDb: "dynamodb",
+  DynamoDBs: "dynamodb",
+  OpenSearch: "opensearch",
+  ElasticSearch: "elasticsearch",
+  Http: "http",
+  EventBridge: "eventbridge",
+  RelationalDatabase: "relational",
+  RelationalDatabases: "relational",
+  None: "none"
+};
+function readServerlessGraphQLApis(resources) {
+  const out = {
+    apis: [],
+    resolvers: [],
+    functions: [],
+    dataSources: []
+  };
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    if (resource?.Type !== "AWS::Serverless::GraphQLApi") {
+      continue;
+    }
+    readOne(logicalId, resource.Properties ?? {}, out);
+  }
+  return out;
+}
+function readOne(apiLogicalId, props, out) {
+  out.apis.push({
+    logicalId: apiLogicalId,
+    name: stringField(props.Name),
+    schemaSource: readSchemaSource(props),
+    authenticationType: readAuthType(props.Auth)
+  });
+  out.dataSources.push(...readDataSources(apiLogicalId, props.DataSources));
+  out.functions.push(...readFunctions(apiLogicalId, props.Functions));
+  out.resolvers.push(...readResolvers(apiLogicalId, props.Resolvers));
+}
+function readSchemaSource(props) {
+  const inline = stringField(props.SchemaInline);
+  if (inline !== null) {
+    return { kind: "inline", sdl: inline };
+  }
+  const location = stringField(props.SchemaUri);
+  if (location !== null) {
+    return { kind: "location", location };
+  }
+  return { kind: "absent" };
+}
+function readAuthType(auth) {
+  const record = asRecord(auth);
+  return record === null ? null : stringField(record.Type);
+}
+function readDataSources(apiLogicalId, raw) {
+  const dataSources = asRecord(raw);
+  if (dataSources === null) {
+    return [];
+  }
+  const out = [];
+  for (const [category, entriesRaw] of Object.entries(dataSources)) {
+    const type = DATA_SOURCE_CATEGORIES[category] ?? "unknown";
+    const entries = asRecord(entriesRaw);
+    if (entries === null) {
+      continue;
+    }
+    for (const [name, defRaw] of Object.entries(entries)) {
+      const def = asRecord(defRaw);
+      out.push({
+        logicalId: dataSourceId(apiLogicalId, name),
+        apiLogicalId,
+        type,
+        lambdaFunctionLogicalId: type === "lambda" && def !== null ? resolveLogicalRef(def.FunctionArn) : null
+      });
+    }
+  }
+  return out;
+}
+function readFunctions(apiLogicalId, raw) {
+  const functions = asRecord(raw);
+  if (functions === null) {
+    return [];
+  }
+  const out = [];
+  for (const [name, defRaw] of Object.entries(functions)) {
+    const def = asRecord(defRaw) ?? {};
+    out.push({
+      logicalId: functionId(apiLogicalId, name),
+      apiLogicalId,
+      name,
+      dataSourceLogicalId: referencedDataSourceId(apiLogicalId, def.DataSource),
+      codeUri: stringField(def.CodeUri),
+      runtime: readRuntime(def.Runtime)
+    });
+  }
+  return out;
+}
+function readResolvers(apiLogicalId, raw) {
+  const byType = asRecord(raw);
+  if (byType === null) {
+    return [];
+  }
+  const out = [];
+  for (const typeName of RESOLVER_ROOT_TYPES) {
+    const fields = asRecord(byType[typeName]);
+    if (fields === null) {
+      continue;
+    }
+    for (const [fieldName, defRaw] of Object.entries(fields)) {
+      const def = asRecord(defRaw) ?? {};
+      out.push(buildResolver(apiLogicalId, typeName, fieldName, def));
+    }
+  }
+  return out;
+}
+function buildResolver(apiLogicalId, typeName, fieldName, def) {
+  const pipeline = readPipeline(apiLogicalId, def.Pipeline);
+  const isPipeline = pipeline.length > 0;
+  return {
+    logicalId: `${apiLogicalId}${typeName}${fieldName}Resolver`,
+    apiLogicalId,
+    typeName,
+    fieldName,
+    dataSourceLogicalId: isPipeline ? null : referencedDataSourceId(apiLogicalId, def.DataSource),
+    kind: isPipeline ? "PIPELINE" : "UNIT",
+    pipelineFunctionLogicalIds: pipeline,
+    codeUri: stringField(def.CodeUri),
+    runtime: readRuntime(def.Runtime)
+  };
+}
+function readPipeline(apiLogicalId, raw) {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const out = [];
+  for (const entry of raw) {
+    const name = stringField(entry) ?? resolveLogicalRef(entry);
+    if (name !== null) {
+      out.push(functionId(apiLogicalId, name));
+    }
+  }
+  return out;
+}
+function readRuntime(raw) {
+  const record = asRecord(raw);
+  return record === null ? null : stringField(record.Name);
+}
+function referencedDataSourceId(apiLogicalId, raw) {
+  const name = stringField(raw);
+  return name === null ? null : dataSourceId(apiLogicalId, name);
+}
+function dataSourceId(apiLogicalId, name) {
+  return `${apiLogicalId}${name}`;
+}
+function functionId(apiLogicalId, name) {
+  return `${apiLogicalId}${name}`;
+}
+
+// src/cfn.ts
+function readAppSyncFromCfn(template) {
+  const resources = template.Resources ?? {};
+  const raw = {
+    apis: collectApis(resources),
+    resolvers: collectResolvers(resources),
+    functions: collectFunctions(resources),
+    dataSources: collectDataSources(resources)
+  };
+  const sam = readServerlessGraphQLApis(resources);
+  return {
+    apis: [...raw.apis, ...sam.apis],
+    resolvers: [...raw.resolvers, ...sam.resolvers],
+    functions: [...raw.functions, ...sam.functions],
+    dataSources: [...raw.dataSources, ...sam.dataSources]
+  };
+}
+function collectApis(resources) {
+  const apis = [];
+  const schemaByApi = indexSchemasByApi(resources);
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    if (resource?.Type !== "AWS::AppSync::GraphQLApi") {
+      continue;
+    }
+    const props = resource.Properties ?? {};
+    apis.push({
+      logicalId,
+      name: stringField(props.Name),
+      schemaSource: schemaByApi.get(logicalId) ?? { kind: "absent" },
+      authenticationType: stringField(props.AuthenticationType)
+    });
+  }
+  return apis;
+}
+function indexSchemasByApi(resources) {
+  const out = /* @__PURE__ */ new Map();
+  for (const resource of Object.values(resources)) {
+    if (resource?.Type !== "AWS::AppSync::GraphQLSchema") {
+      continue;
+    }
+    const props = resource.Properties ?? {};
+    const apiRef = resolveLogicalRef(props.ApiId);
+    if (apiRef === null) {
+      continue;
+    }
+    const inline = stringField(props.Definition);
+    if (inline !== null) {
+      out.set(apiRef, { kind: "inline", sdl: inline });
+      continue;
+    }
+    const location = stringField(props.DefinitionS3Location);
+    if (location !== null) {
+      out.set(apiRef, { kind: "location", location });
+    }
+  }
+  return out;
+}
+function collectResolvers(resources) {
+  const out = [];
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    if (resource?.Type !== "AWS::AppSync::Resolver") {
+      continue;
+    }
+    const props = resource.Properties ?? {};
+    const typeName = stringField(props.TypeName);
+    const fieldName = stringField(props.FieldName);
+    if (typeName === null || fieldName === null) {
+      continue;
+    }
+    out.push({
+      logicalId,
+      apiLogicalId: resolveLogicalRef(props.ApiId),
+      typeName,
+      fieldName,
+      dataSourceLogicalId: resolveLogicalRef(props.DataSourceName),
+      kind: resolverKind(stringField(props.Kind)),
+      pipelineFunctionLogicalIds: pipelineFunctionIds(props.PipelineConfig),
+      codeUri: null,
+      runtime: null
+    });
+  }
+  return out;
+}
+function pipelineFunctionIds(pipelineConfig) {
+  const config = asRecord(pipelineConfig);
+  if (config === null) {
+    return [];
+  }
+  const functions = config.Functions;
+  if (!Array.isArray(functions)) {
+    return [];
+  }
+  const out = [];
+  for (const entry of functions) {
+    const ref = resolveLogicalRef(entry);
+    if (ref !== null) {
+      out.push(ref);
+    }
+  }
+  return out;
+}
+function collectFunctions(resources) {
+  const out = [];
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    if (resource?.Type !== "AWS::AppSync::FunctionConfiguration") {
+      continue;
+    }
+    const props = resource.Properties ?? {};
+    out.push({
+      logicalId,
+      apiLogicalId: resolveLogicalRef(props.ApiId),
+      name: stringField(props.Name),
+      dataSourceLogicalId: resolveLogicalRef(props.DataSourceName),
+      codeUri: null,
+      runtime: null
+    });
+  }
+  return out;
+}
+function collectDataSources(resources) {
+  const out = [];
+  for (const [logicalId, resource] of Object.entries(resources)) {
+    if (resource?.Type !== "AWS::AppSync::DataSource") {
+      continue;
+    }
+    const props = resource.Properties ?? {};
+    const lambdaConfig = asRecord(props.LambdaConfig);
+    out.push({
+      logicalId,
+      apiLogicalId: resolveLogicalRef(props.ApiId),
+      type: dataSourceType(stringField(props.Type)),
+      lambdaFunctionLogicalId: lambdaConfig === null ? null : resolveLogicalRef(lambdaConfig.LambdaFunctionArn)
+    });
+  }
+  return out;
+}
+var DATA_SOURCE_TYPES = {
+  AWS_LAMBDA: "lambda",
+  AMAZON_DYNAMODB: "dynamodb",
+  AMAZON_ELASTICSEARCH: "elasticsearch",
+  AMAZON_OPENSEARCH_SERVICE: "opensearch",
+  HTTP: "http",
+  RELATIONAL_DATABASE: "relational",
+  AMAZON_EVENTBRIDGE: "eventbridge",
+  NONE: "none"
+};
+function dataSourceType(raw) {
+  if (raw === null) {
+    return "unknown";
+  }
+  return DATA_SOURCE_TYPES[raw] ?? "unknown";
+}
+function resolverKind(raw) {
+  if (raw === "PIPELINE") {
+    return "PIPELINE";
+  }
+  if (raw === "UNIT" || raw === null) {
+    return "UNIT";
+  }
+  return "UNKNOWN";
+}
+
+// src/schema.ts
+import {
+  Kind,
+  parse
+} from "graphql";
+function schemaKey(typeName, fieldName) {
+  return `${typeName}.${fieldName}`;
+}
+function parseSchema(sdl) {
+  const index = /* @__PURE__ */ new Map();
+  const doc = safeParse(sdl);
+  if (doc === null) {
+    return index;
+  }
+  for (const def of doc.definitions) {
+    if (def.kind !== Kind.OBJECT_TYPE_DEFINITION && def.kind !== Kind.OBJECT_TYPE_EXTENSION && def.kind !== Kind.INTERFACE_TYPE_DEFINITION) {
+      continue;
+    }
+    const typeName = def.name.value;
+    for (const field of def.fields ?? []) {
+      const info = describeField(typeName, field);
+      index.set(schemaKey(typeName, info.fieldName), info);
+    }
+  }
+  return index;
+}
+function safeParse(sdl) {
+  try {
+    return parse(sdl);
+  } catch {
+    return null;
+  }
+}
+function describeField(typeName, field) {
+  return {
+    typeName,
+    fieldName: field.name.value,
+    returnShape: typeReference(sourceOfType(field.type)),
+    args: (field.arguments ?? []).map((arg) => ({
+      name: arg.name.value,
+      shape: typeReference(sourceOfType(arg.type)),
+      required: isNonNull(arg.type)
+    }))
+  };
+}
+function sourceOfType(node) {
+  if (node.kind === Kind.NON_NULL_TYPE) {
+    return `${sourceOfType(node.type)}!`;
+  }
+  if (node.kind === Kind.LIST_TYPE) {
+    return `[${sourceOfType(node.type)}]`;
+  }
+  return node.name.value;
+}
+function isNonNull(node) {
+  return node.kind === Kind.NON_NULL_TYPE;
+}
+function typeReference(name) {
+  return { type: "ref", name };
+}
+
+// src/schemaSource.ts
+import path from "path";
+import { loadSdlFile } from "@suss/contract-graphql";
+var REMOTE_SCHEME = /^(s3|https?):\/\//i;
+function resolveSchemaSource(raw, baseDir) {
+  if (raw.kind === "inline") {
+    return { status: "inline", sdl: raw.sdl };
+  }
+  if (raw.kind === "absent") {
+    return { status: "absent" };
+  }
+  return resolveLocation(raw.location, baseDir);
+}
+function resolveLocation(location, baseDir) {
+  if (REMOTE_SCHEME.test(location)) {
+    return { status: "unresolved", location, reason: "remote" };
+  }
+  const resolvedPath = toLocalPath(location, baseDir);
+  if (resolvedPath === null) {
+    return { status: "unresolved", location, reason: "no-base-dir" };
+  }
+  const sdl = loadSdlFile(resolvedPath);
+  if (sdl === null) {
+    return { status: "unresolved", location, reason: "not-found" };
+  }
+  return { status: "external-file", sdl, location };
+}
+function toLocalPath(location, baseDir) {
+  if (path.isAbsolute(location)) {
+    return location;
+  }
+  if (baseDir === null) {
+    return null;
+  }
+  return path.resolve(baseDir, location);
+}
+function resolvedSdl(resolved) {
+  if (resolved.status === "inline" || resolved.status === "external-file") {
+    return resolved.sdl;
+  }
+  return null;
+}
+
+// src/summaryBuilder.ts
+import { graphqlResolverBinding } from "@suss/behavioral-ir";
+function buildResolverSummaries(config, resolvedByApi, schemasByApi, options = {}) {
+  const sourceFile = options.source ?? "appsync";
+  const indexes = {
+    apiById: byLogicalId(config.apis),
+    functionById: byLogicalId(config.functions),
+    dataSourceById: byLogicalId(config.dataSources)
+  };
+  return config.resolvers.map(
+    (resolver) => buildOne(resolver, indexes, resolvedByApi, schemasByApi, sourceFile)
+  );
+}
+function byLogicalId(items) {
+  const out = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    out.set(item.logicalId, item);
+  }
+  return out;
+}
+function buildOne(resolver, indexes, resolvedByApi, schemasByApi, sourceFile) {
+  const api = resolver.apiLogicalId === null ? null : indexes.apiById.get(resolver.apiLogicalId) ?? null;
+  const resolved = resolver.apiLogicalId === null ? null : resolvedByApi.get(resolver.apiLogicalId) ?? null;
+  const schema = resolver.apiLogicalId === null ? null : schemasByApi.get(resolver.apiLogicalId) ?? null;
+  const field = schema?.get(schemaKey(resolver.typeName, resolver.fieldName)) ?? null;
+  const ownerKey = `${resolver.typeName}.${resolver.fieldName}`;
+  const schemaSdl = resolved === null ? null : resolvedSdl(resolved);
+  return {
+    kind: "resolver",
+    location: {
+      file: `${sourceFile}:${resolver.logicalId}`,
+      range: { start: 0, end: 0 },
+      exportName: null
+    },
+    identity: {
+      name: ownerKey,
+      exportPath: null,
+      boundaryBinding: graphqlResolverBinding({
+        // AppSync is invoked over HTTPS-to-AWS. Keeping transport
+        // explicit here matches the aws-apigateway reader's posture
+        // and leaves room for a future AWS-SDK-direct transport
+        // ("aws-sdk") once Lambda-invoke semantics land.
+        transport: "aws-https",
+        recognition: "appsync",
+        typeName: resolver.typeName,
+        fieldName: resolver.fieldName
+      })
+    },
+    inputs: buildInputs(field),
+    transitions: buildTransitions(ownerKey, resolver, field),
+    gaps: [],
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      appsync: buildAppsyncMetadata(resolver, api, resolved, field, indexes),
+      // Surface the resolved SDL so the checker can resolve nested
+      // selections against this resolver's return type. Repeated across
+      // every resolver from the same API by design — each summary
+      // travels independently; keeping the SDL on-hand is simpler than
+      // cross-summary schema lookup, and the checker caches parses
+      // per-SDL.
+      ...schemaSdl !== null ? { graphql: { schemaSdl } } : {}
+    }
+  };
+}
+function buildAppsyncMetadata(resolver, api, resolved, field, indexes) {
+  const pipelineFunctions = resolver.pipelineFunctionLogicalIds.map(
+    (logicalId) => pipelineFunctionMeta(logicalId, indexes)
+  );
+  return {
+    apiLogicalId: resolver.apiLogicalId,
+    apiName: api?.name ?? null,
+    dataSourceLogicalId: resolver.dataSourceLogicalId,
+    // Lambda behind this resolver's own data source (UNIT resolvers).
+    // PIPELINE resolvers attribute per-function below; their top-level
+    // data source is null, so this is null too.
+    lambdaFunctionLogicalId: lambdaBehind(
+      resolver.dataSourceLogicalId,
+      indexes
+    ),
+    kind: resolver.kind,
+    authenticationType: api?.authenticationType ?? null,
+    // SAM JS/VTL resolver code location + runtime (null for raw
+    // AWS::AppSync::Resolver resources).
+    codeUri: resolver.codeUri,
+    runtime: resolver.runtime,
+    // Distinguish "schema said X" from "we didn't see a schema at all"
+    // (field-level), and record how the SDL itself was obtained
+    // (source-level) so a genuinely-remote schema is never silent.
+    schemaMatched: field !== null,
+    schemaSource: schemaSourceMetadata(resolved),
+    // For PIPELINE resolvers, surface the ordered function chain so
+    // downstream tools can show the dispatch path. Empty for UNIT
+    // resolvers; empty with `kind: "PIPELINE"` means the Functions
+    // array was dynamically-referenced and we couldn't resolve it.
+    ...pipelineFunctions.length > 0 ? { pipelineFunctions } : {}
+  };
+}
+function pipelineFunctionMeta(logicalId, indexes) {
+  const fn = indexes.functionById.get(logicalId) ?? null;
+  return {
+    logicalId,
+    name: fn?.name ?? null,
+    dataSourceLogicalId: fn?.dataSourceLogicalId ?? null,
+    lambdaFunctionLogicalId: lambdaBehind(
+      fn?.dataSourceLogicalId ?? null,
+      indexes
+    ),
+    codeUri: fn?.codeUri ?? null,
+    runtime: fn?.runtime ?? null
+  };
+}
+function lambdaBehind(dataSourceLogicalId, indexes) {
+  if (dataSourceLogicalId === null) {
+    return null;
+  }
+  return indexes.dataSourceById.get(dataSourceLogicalId)?.lambdaFunctionLogicalId ?? null;
+}
+function schemaSourceMetadata(resolved) {
+  if (resolved === null || resolved.status === "absent") {
+    return { status: "absent" };
+  }
+  if (resolved.status === "inline") {
+    return { status: "inline" };
+  }
+  if (resolved.status === "external-file") {
+    return { status: "external-file", location: resolved.location };
+  }
+  return {
+    status: "unresolved",
+    location: resolved.location,
+    reason: resolved.reason
+  };
+}
+function buildInputs(field) {
+  if (field === null) {
+    return [];
+  }
+  return field.args.map((arg, index) => ({
+    type: "parameter",
+    name: arg.name,
+    position: index,
+    role: "args",
+    shape: arg.shape
+  }));
+}
+function buildTransitions(ownerKey, resolver, field) {
+  const returnShape = field?.returnShape ?? { type: "unknown" };
+  const successSource = field !== null ? "aws::appsync::resolver.success" : "aws::appsync::resolver.success-no-schema";
+  return [
+    {
+      id: `${ownerKey}:return:success`,
+      conditions: [],
+      output: { type: "return", value: returnShape },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: true,
+      confidence: { source: "derived", level: "high" },
+      metadata: {
+        source: successSource,
+        resolverKind: resolver.kind
+      }
+    },
+    {
+      id: `${ownerKey}:throw:error`,
+      conditions: [
+        {
+          type: "opaque",
+          sourceText: "aws:appsync:resolver-error",
+          reason: "externalFunction"
+        }
+      ],
+      output: {
+        type: "throw",
+        exceptionType: null,
+        message: null
+      },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: false,
+      confidence: { source: "derived", level: "medium" },
+      metadata: {
+        source: "aws::appsync::resolver.error-path"
+      }
+    }
+  ];
+}
+
+// src/index.ts
+function appsyncToSummaries(template, options = {}) {
+  const config = readAppSyncFromCfn(template);
+  const baseDir = options.baseDir ?? null;
+  const resolvedByApi = resolveSchemas(config, baseDir);
+  const schemasByApi = indexSchemas(resolvedByApi);
+  return buildResolverSummaries(config, resolvedByApi, schemasByApi, {
+    ...options.source !== void 0 ? { source: options.source } : {}
+  });
+}
+function resolveSchemas(config, baseDir) {
+  const out = /* @__PURE__ */ new Map();
+  for (const api of config.apis) {
+    out.set(api.logicalId, resolveSchemaSource(api.schemaSource, baseDir));
+  }
+  return out;
+}
+function indexSchemas(resolvedByApi) {
+  const out = /* @__PURE__ */ new Map();
+  for (const [logicalId, resolved] of resolvedByApi) {
+    if (resolved.status === "inline" || resolved.status === "external-file") {
+      out.set(logicalId, parseSchema(resolved.sdl));
+    }
+  }
+  return out;
+}
+function appsyncFileToSummaries(filePath, options = {}) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const template = parseTemplate(filePath, raw);
+  return appsyncToSummaries(template, {
+    source: options.source ?? path2.relative(process.cwd(), filePath),
+    baseDir: options.baseDir ?? path2.dirname(filePath)
+  });
+}
+var CLOUDFORMATION_YAML_TAGS = [
+  { tag: "!Ref", resolve: (value) => ({ Ref: value }) },
+  {
+    tag: "!GetAtt",
+    resolve: (value) => ({
+      "Fn::GetAtt": value.includes(".") ? value.split(".") : [value]
+    })
+  },
+  ...[
+    "!Sub",
+    "!Join",
+    "!Select",
+    "!Split",
+    "!FindInMap",
+    "!ImportValue",
+    "!Base64",
+    "!Cidr",
+    "!If",
+    "!Not",
+    "!And",
+    "!Or",
+    "!Equals"
+  ].map((tag) => ({ tag, resolve: (value) => value }))
+];
+function parseTemplate(filePath, raw) {
+  const ext = path2.extname(filePath).toLowerCase();
+  if (ext === ".json") {
+    return JSON.parse(raw);
+  }
+  return YAML.parse(raw, {
+    customTags: CLOUDFORMATION_YAML_TAGS
+  });
+}
+export {
+  appsyncFileToSummaries,
+  appsyncToSummaries
+};