@suss/ir-core 0.0.1

package/dist/index.cjs

@@ -0,0 +1,626 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BoundaryBindingSchema: () => BoundaryBindingSchema,
+  ConfidenceInfoSchema: () => ConfidenceInfoSchema,
+  ConfidenceLevelSchema: () => ConfidenceLevelSchema,
+  ConfidenceSourceSchema: () => ConfidenceSourceSchema,
+  FunctionCallSemanticsSchema: () => FunctionCallSemanticsSchema,
+  GraphqlOperationSemanticsSchema: () => GraphqlOperationSemanticsSchema,
+  GraphqlResolverSemanticsSchema: () => GraphqlResolverSemanticsSchema,
+  MessageBusSemanticsSchema: () => MessageBusSemanticsSchema,
+  RestSemanticsSchema: () => RestSemanticsSchema,
+  RuntimeConfigSemanticsSchema: () => RuntimeConfigSemanticsSchema,
+  SemanticsSchema: () => SemanticsSchema,
+  SourceLocationSchema: () => SourceLocationSchema,
+  StorageRelationalSemanticsSchema: () => StorageRelationalSemanticsSchema,
+  SuppressionFileSchema: () => SuppressionFileSchema,
+  SuppressionRuleSchema: () => SuppressionRuleSchema,
+  TypeShapeSchema: () => TypeShapeSchema,
+  applySuppressionsToFindings: () => applySuppressionsToFindings,
+  bodyShapesMatch: () => bodyShapesMatch,
+  boundaryKey: () => boundaryKey,
+  countsForThreshold: () => countsForThreshold,
+  functionCallBinding: () => functionCallBinding,
+  graphqlOperationBinding: () => graphqlOperationBinding,
+  graphqlResolverBinding: () => graphqlResolverBinding,
+  messageBusBinding: () => messageBusBinding,
+  normalizePath: () => normalizePath,
+  normalizeRuleBoundary: () => normalizeRuleBoundary,
+  packageExportBinding: () => packageExportBinding,
+  restBinding: () => restBinding,
+  ruleBoundaryMatchesKey: () => ruleBoundaryMatchesKey,
+  runtimeConfigBinding: () => runtimeConfigBinding,
+  storageRelationalBinding: () => storageRelationalBinding,
+  validateRule: () => validateRule
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/schemas.ts
+var import_zod = require("zod");
+var ConfidenceSourceSchema = import_zod.z.enum([
+  "inferred_static",
+  "inferred_ai",
+  "declared",
+  "derived"
+]);
+var ConfidenceLevelSchema = import_zod.z.enum(["high", "medium", "low"]);
+var ConfidenceInfoSchema = import_zod.z.object({
+  source: ConfidenceSourceSchema,
+  level: ConfidenceLevelSchema
+});
+var SourceLocationSchema = import_zod.z.object({
+  file: import_zod.z.string(),
+  range: import_zod.z.object({ start: import_zod.z.number(), end: import_zod.z.number() }),
+  exportName: import_zod.z.string().nullable()
+});
+var RestSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("rest"),
+  /** Uppercase HTTP method ("GET", "POST", …). */
+  method: import_zod.z.string(),
+  /** Normalized route path ("/users/{id}"). */
+  path: import_zod.z.string(),
+  /**
+   * Status codes the producing source explicitly declared (OpenAPI
+   * responses, CFN MethodResponses, ts-rest router statuses). Kept here
+   * so the pairing layer can still see them without unwrapping metadata.
+   * Empty / absent for inferred sources.
+   */
+  declaredResponses: import_zod.z.array(import_zod.z.number()).optional()
+});
+var FunctionCallSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("function-call"),
+  /**
+   * Optional module identifier for cross-unit references
+   * (e.g. `"./components/Button"` for a React component, or the TS
+   * module path for a bare function export). Packs that don't do
+   * cross-module pairing can leave it unset.
+   */
+  module: import_zod.z.string().optional(),
+  /** Named export within the module, when applicable. */
+  exportName: import_zod.z.string().optional(),
+  /**
+   * Package name (as written in `package.json`) when this identity
+   * refers to a public package export — e.g. `"@suss/behavioral-ir"`.
+   * Set alongside `exportPath` by packs that resolve a package's
+   * public surface (the `packageExports` discovery variant). Distinct
+   * from `module`, which is a repo-relative module path for
+   * intra-repo pairing.
+   */
+  package: import_zod.z.string().optional(),
+  /**
+   * Path to the exported binding within the package, starting with
+   * the sub-path key when one is used. Examples:
+   *   `["parseSummary"]`              — root export
+   *   `["schemas", "BoundaryBindingSchema"]` — sub-path `./schemas`
+   *
+   * The first segment is the sub-path without the leading `./`
+   * (`"."` → omitted). The last segment is the exported name.
+   */
+  exportPath: import_zod.z.array(import_zod.z.string()).optional()
+});
+var GraphqlResolverSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("graphql-resolver"),
+  /** GraphQL type the resolver attaches to: "Query", "Mutation", "Subscription", or an object-type name. */
+  typeName: import_zod.z.string(),
+  /** Field name on that type. */
+  fieldName: import_zod.z.string()
+});
+var GraphqlOperationSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("graphql-operation"),
+  /** Optional operation name — anonymous queries / mutations leave this unset. */
+  operationName: import_zod.z.string().optional(),
+  operationType: import_zod.z.enum(["query", "mutation", "subscription"])
+});
+var RuntimeConfigSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("runtime-config"),
+  deploymentTarget: import_zod.z.enum([
+    "lambda",
+    "ecs-task",
+    "container",
+    "k8s-deployment"
+  ]),
+  /**
+   * Stable identifier for the runtime instance — CFN logical resource
+   * ID for Lambda / ECS, k8s deployment name, container name.
+   */
+  instanceName: import_zod.z.string()
+});
+var StorageRelationalSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("storage-relational"),
+  storageSystem: import_zod.z.enum(["postgres", "mysql", "sqlite"]),
+  /**
+   * ORM / driver scope. Defaults to `"default"` for single-database
+   * setups; monorepos with multiple schemas use distinct values.
+   */
+  scope: import_zod.z.string(),
+  /** Table / model name as declared in the schema. */
+  table: import_zod.z.string()
+});
+var MessageBusSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("message-bus"),
+  messageBus: import_zod.z.enum(["sqs", "eventbridge", "bullmq", "kafka", "nats"]),
+  /** Stable channel identifier — CFN logical id, queue/topic name, subject pattern, `bus#detailType`. */
+  channel: import_zod.z.string()
+});
+var SemanticsSchema = import_zod.z.discriminatedUnion("name", [
+  RestSemanticsSchema,
+  FunctionCallSemanticsSchema,
+  GraphqlResolverSemanticsSchema,
+  GraphqlOperationSemanticsSchema,
+  RuntimeConfigSemanticsSchema,
+  StorageRelationalSemanticsSchema,
+  MessageBusSemanticsSchema
+]);
+var BoundaryBindingSchema = import_zod.z.object({
+  transport: import_zod.z.string(),
+  semantics: SemanticsSchema,
+  recognition: import_zod.z.string()
+});
+var TypeShapeSchema = import_zod.z.lazy(
+  () => import_zod.z.discriminatedUnion("type", [
+    import_zod.z.object({
+      type: import_zod.z.literal("record"),
+      properties: import_zod.z.record(import_zod.z.string(), TypeShapeSchema),
+      spreads: import_zod.z.array(import_zod.z.object({ sourceText: import_zod.z.string() })).optional()
+    }),
+    import_zod.z.object({ type: import_zod.z.literal("dictionary"), values: TypeShapeSchema }),
+    import_zod.z.object({ type: import_zod.z.literal("array"), items: TypeShapeSchema }),
+    import_zod.z.object({
+      type: import_zod.z.literal("literal"),
+      value: import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.boolean()]),
+      raw: import_zod.z.string().optional()
+    }),
+    import_zod.z.object({ type: import_zod.z.literal("text") }),
+    import_zod.z.object({ type: import_zod.z.literal("integer") }),
+    import_zod.z.object({ type: import_zod.z.literal("number") }),
+    import_zod.z.object({ type: import_zod.z.literal("boolean") }),
+    import_zod.z.object({ type: import_zod.z.literal("null") }),
+    import_zod.z.object({ type: import_zod.z.literal("undefined") }),
+    import_zod.z.object({
+      type: import_zod.z.literal("union"),
+      variants: import_zod.z.array(TypeShapeSchema)
+    }),
+    import_zod.z.object({ type: import_zod.z.literal("ref"), name: import_zod.z.string() }),
+    import_zod.z.object({ type: import_zod.z.literal("unknown") })
+  ])
+);
+
+// src/boundaryKey.ts
+function normalizePath(path) {
+  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  normalized = normalized.replace(
+    /\{[^}]+\}|[^{]+/g,
+    (segment) => segment.startsWith("{") ? segment : segment.toLowerCase()
+  );
+  return normalized;
+}
+function boundaryKey(binding) {
+  const semantics = binding.semantics;
+  if (semantics.name === "rest") {
+    if (semantics.method === "" || semantics.path === "") {
+      return null;
+    }
+    const method = semantics.method.toUpperCase();
+    const path = normalizePath(semantics.path);
+    return `${method} ${path}`;
+  }
+  if (semantics.name === "graphql-resolver") {
+    return `gql:${semantics.typeName}.${semantics.fieldName}`;
+  }
+  if (semantics.name === "function-call") {
+    if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
+      return `fn:${semantics.package}::${semantics.exportPath.join(".")}`;
+    }
+    return null;
+  }
+  return null;
+}
+
+// src/suppressions.ts
+var import_zod2 = require("zod");
+var SuppressionRuleSchema = import_zod2.z.object({
+  /**
+   * Finding kind to match — any behavioural or intent finding kind.
+   * Open here (this package sits below both IRs); the loader
+   * validates against the published kind enums.
+   */
+  kind: import_zod2.z.string().optional(),
+  /**
+   * Boundary as a human-readable key, e.g. "GET /pet/{petId}" or
+   * "fn:@acme/api::getUser". REST keys are normalized via the same
+   * path normalizer the checkers use, so `:id` and `{id}` compare
+   * equal.
+   */
+  boundary: import_zod2.z.string().optional(),
+  /**
+   * Consumer-side discriminators (narrowest useful match). Only
+   * meaningful for behavioural findings — a rule that specifies
+   * `consumer` never matches an intent finding, which has no
+   * consumer side.
+   */
+  consumer: import_zod2.z.object({
+    summary: import_zod2.z.string().optional(),
+    transitionId: import_zod2.z.string().optional()
+  }).optional(),
+  /**
+   * "narrow" (default): requires at least (kind + boundary) OR
+   *   (kind + consumer.transitionId) — enough to target a specific
+   *   finding class. "broad" opts in to kind-only or boundary-only
+   *   matches, which silence future regressions in that category too.
+   */
+  scope: import_zod2.z.enum(["narrow", "broad"]).default("narrow"),
+  /** Required human-written justification. */
+  reason: import_zod2.z.string().min(1),
+  /** What to do when a finding matches. */
+  effect: import_zod2.z.enum(["mark", "downgrade", "hide"]).default("mark")
+}).strict();
+var SuppressionFileSchema = import_zod2.z.object({
+  version: import_zod2.z.literal(1),
+  rules: import_zod2.z.array(SuppressionRuleSchema)
+}).strict();
+function validateRule(rule) {
+  if (rule.scope === "broad") {
+    if (rule.kind === void 0 && rule.boundary === void 0 && rule.consumer === void 0) {
+      return "broad-scope rule must constrain at least one field (kind, boundary, or consumer)";
+    }
+    return null;
+  }
+  const hasKind = rule.kind !== void 0;
+  const hasBoundary = rule.boundary !== void 0;
+  const hasConsumerTxn = rule.consumer?.transitionId !== void 0;
+  if (hasKind && (hasBoundary || hasConsumerTxn)) {
+    return null;
+  }
+  return "narrow-scope rule must specify kind AND (boundary OR consumer.transitionId); set scope: 'broad' to silence wider categories";
+}
+function normalizeRuleBoundary(raw) {
+  const trimmed = raw.trim();
+  const spaceIdx = trimmed.indexOf(" ");
+  if (spaceIdx < 0) {
+    return trimmed;
+  }
+  const method = trimmed.slice(0, spaceIdx).toUpperCase();
+  const path = trimmed.slice(spaceIdx + 1);
+  return `${method} ${normalizePath(path)}`;
+}
+function ruleBoundaryMatchesKey(ruleBoundary, key) {
+  if (key === null) {
+    return false;
+  }
+  return ruleBoundary === key || normalizeRuleBoundary(ruleBoundary) === key;
+}
+var SEVERITY_DOWNGRADE = {
+  error: "warning",
+  warning: "info",
+  info: "info"
+};
+function applyRuleToFinding(rule, finding) {
+  const common = {
+    reason: rule.reason,
+    effect: rule.effect
+  };
+  if (rule.effect === "downgrade") {
+    return {
+      ...finding,
+      severity: SEVERITY_DOWNGRADE[finding.severity],
+      suppressed: { ...common, originalSeverity: finding.severity }
+    };
+  }
+  return { ...finding, suppressed: { ...common } };
+}
+function applySuppressionsToFindings(findings, rules, matches, opts = {}) {
+  const out = [];
+  for (const f of findings) {
+    const rule = rules.find(
+      (r) => (r.kind === void 0 || r.kind === f.kind) && matches(r, f)
+    );
+    if (rule === void 0) {
+      out.push(f);
+      continue;
+    }
+    const applied = applyRuleToFinding(rule, f);
+    if (applied.suppressed?.effect === "hide" && !opts.keepHidden) {
+      continue;
+    }
+    out.push(applied);
+  }
+  return out;
+}
+function countsForThreshold(finding) {
+  if (finding.suppressed === void 0) {
+    return true;
+  }
+  return finding.suppressed.effect === "downgrade";
+}
+
+// src/typeShapeMatch.ts
+function bodyShapesMatch(actual, declared) {
+  if (actual.type === "unknown" || declared.type === "unknown") {
+    return "unknown";
+  }
+  if (actual.type === "ref" || declared.type === "ref") {
+    if (actual.type === "ref" && declared.type === "ref" && actual.name === declared.name) {
+      return "match";
+    }
+    return "unknown";
+  }
+  if (actual.type === "union") {
+    return combine(actual.variants.map((v) => bodyShapesMatch(v, declared)));
+  }
+  if (declared.type === "union") {
+    return matchAny(actual, declared.variants);
+  }
+  if (declared.type === "dictionary") {
+    if (actual.type === "dictionary") {
+      return bodyShapesMatch(actual.values, declared.values);
+    }
+    if (actual.type === "record") {
+      if (actual.spreads && actual.spreads.length > 0) {
+        return "unknown";
+      }
+      const results = Object.values(actual.properties).map(
+        (v) => bodyShapesMatch(v, declared.values)
+      );
+      return combine(results);
+    }
+    return "nomatch";
+  }
+  if (actual.type === "dictionary") {
+    return declared.type === "record" ? "unknown" : "nomatch";
+  }
+  if (declared.type === "record") {
+    if (actual.type !== "record") {
+      return "nomatch";
+    }
+    if (actual.spreads && actual.spreads.length > 0 || declared.spreads && declared.spreads.length > 0) {
+      return "unknown";
+    }
+    const results = [];
+    for (const [key, declaredValue] of Object.entries(declared.properties)) {
+      const actualValue = actual.properties[key];
+      if (actualValue === void 0) {
+        if (allowsUndefined(declaredValue)) {
+          continue;
+        }
+        return "nomatch";
+      }
+      results.push(bodyShapesMatch(actualValue, declaredValue));
+    }
+    return combine(results);
+  }
+  if (declared.type === "array") {
+    if (actual.type !== "array") {
+      return "nomatch";
+    }
+    return bodyShapesMatch(actual.items, declared.items);
+  }
+  if (declared.type === "literal") {
+    if (actual.type !== "literal") {
+      return "nomatch";
+    }
+    return actual.value === declared.value ? "match" : "nomatch";
+  }
+  if (declared.type === "text") {
+    if (actual.type === "text") {
+      return "match";
+    }
+    if (actual.type === "literal" && typeof actual.value === "string") {
+      return "match";
+    }
+    return "nomatch";
+  }
+  if (declared.type === "integer") {
+    if (actual.type === "integer") {
+      return "match";
+    }
+    if (actual.type === "literal" && typeof actual.value === "number" && Number.isInteger(actual.value)) {
+      return "match";
+    }
+    return "nomatch";
+  }
+  if (declared.type === "number") {
+    if (actual.type === "number" || actual.type === "integer") {
+      return "match";
+    }
+    if (actual.type === "literal" && typeof actual.value === "number") {
+      return "match";
+    }
+    return "nomatch";
+  }
+  if (declared.type === "boolean") {
+    if (actual.type === "boolean") {
+      return "match";
+    }
+    if (actual.type === "literal" && typeof actual.value === "boolean") {
+      return "match";
+    }
+    return "nomatch";
+  }
+  if (declared.type === "null") {
+    return actual.type === "null" ? "match" : "nomatch";
+  }
+  if (declared.type === "undefined") {
+    return actual.type === "undefined" ? "match" : "nomatch";
+  }
+  return "nomatch";
+}
+function matchAny(actual, variants) {
+  let sawUnknown = false;
+  for (const v of variants) {
+    const r = bodyShapesMatch(actual, v);
+    if (r === "match") {
+      return "match";
+    }
+    if (r === "unknown") {
+      sawUnknown = true;
+    }
+  }
+  return sawUnknown ? "unknown" : "nomatch";
+}
+function combine(results) {
+  if (results.some((r) => r === "nomatch")) {
+    return "nomatch";
+  }
+  if (results.some((r) => r === "unknown")) {
+    return "unknown";
+  }
+  return "match";
+}
+function allowsUndefined(shape) {
+  if (shape.type === "undefined") {
+    return true;
+  }
+  if (shape.type === "union") {
+    return shape.variants.some(allowsUndefined);
+  }
+  return false;
+}
+
+// src/index.ts
+function restBinding(opts) {
+  return {
+    transport: opts.transport,
+    semantics: {
+      name: "rest",
+      method: opts.method.toUpperCase(),
+      path: opts.path,
+      ...opts.declaredResponses !== void 0 ? { declaredResponses: opts.declaredResponses } : {}
+    },
+    recognition: opts.recognition
+  };
+}
+function functionCallBinding(opts) {
+  return {
+    transport: opts.transport,
+    semantics: {
+      name: "function-call",
+      ...opts.module !== void 0 ? { module: opts.module } : {},
+      ...opts.exportName !== void 0 ? { exportName: opts.exportName } : {},
+      ...opts.package !== void 0 ? { package: opts.package } : {},
+      ...opts.exportPath !== void 0 ? { exportPath: opts.exportPath } : {}
+    },
+    recognition: opts.recognition
+  };
+}
+function packageExportBinding(opts) {
+  return functionCallBinding({
+    transport: opts.transport ?? "in-process",
+    recognition: opts.recognition,
+    package: opts.packageName,
+    exportPath: opts.exportPath
+  });
+}
+function graphqlResolverBinding(opts) {
+  return {
+    transport: opts.transport,
+    semantics: {
+      name: "graphql-resolver",
+      typeName: opts.typeName,
+      fieldName: opts.fieldName
+    },
+    recognition: opts.recognition
+  };
+}
+function graphqlOperationBinding(opts) {
+  return {
+    transport: opts.transport,
+    semantics: {
+      name: "graphql-operation",
+      operationType: opts.operationType,
+      ...opts.operationName !== void 0 ? { operationName: opts.operationName } : {}
+    },
+    recognition: opts.recognition
+  };
+}
+function runtimeConfigBinding(opts) {
+  return {
+    transport: "os",
+    semantics: {
+      name: "runtime-config",
+      deploymentTarget: opts.deploymentTarget,
+      instanceName: opts.instanceName
+    },
+    recognition: opts.recognition
+  };
+}
+function storageRelationalBinding(opts) {
+  return {
+    transport: opts.storageSystem,
+    semantics: {
+      name: "storage-relational",
+      storageSystem: opts.storageSystem,
+      scope: opts.scope,
+      table: opts.table
+    },
+    recognition: opts.recognition
+  };
+}
+function messageBusBinding(opts) {
+  return {
+    transport: opts.messageBus,
+    semantics: {
+      name: "message-bus",
+      messageBus: opts.messageBus,
+      channel: opts.channel
+    },
+    recognition: opts.recognition
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BoundaryBindingSchema,
+  ConfidenceInfoSchema,
+  ConfidenceLevelSchema,
+  ConfidenceSourceSchema,
+  FunctionCallSemanticsSchema,
+  GraphqlOperationSemanticsSchema,
+  GraphqlResolverSemanticsSchema,
+  MessageBusSemanticsSchema,
+  RestSemanticsSchema,
+  RuntimeConfigSemanticsSchema,
+  SemanticsSchema,
+  SourceLocationSchema,
+  StorageRelationalSemanticsSchema,
+  SuppressionFileSchema,
+  SuppressionRuleSchema,
+  TypeShapeSchema,
+  applySuppressionsToFindings,
+  bodyShapesMatch,
+  boundaryKey,
+  countsForThreshold,
+  functionCallBinding,
+  graphqlOperationBinding,
+  graphqlResolverBinding,
+  messageBusBinding,
+  normalizePath,
+  normalizeRuleBoundary,
+  packageExportBinding,
+  restBinding,
+  ruleBoundaryMatchesKey,
+  runtimeConfigBinding,
+  storageRelationalBinding,
+  validateRule
+});