@suss/extractor 0.0.1

package/dist/index.js

@@ -0,0 +1,282 @@
+// src/index.ts
+import { createHash } from "crypto";
+
+// src/packHelpers.ts
+function httpRouteDiscovery(opts) {
+  const kind = opts.kind ?? "handler";
+  return opts.importNames.map((importName) => ({
+    kind,
+    match: {
+      type: "registrationCall",
+      importModule: opts.importModule,
+      importName,
+      registrationChain: [...opts.methods]
+    },
+    bindingExtraction: {
+      method: { type: "fromRegistration", position: "methodName" },
+      path: { type: "fromRegistration", position: 0 }
+    },
+    requiresImport: [opts.importModule]
+  }));
+}
+
+// src/index.ts
+var DEFAULT_OPTIONS = { gapHandling: "permissive" };
+function makeTransitionId(functionName, branch) {
+  const { terminal } = branch;
+  const statusKey = terminal.statusCode === null ? "none" : terminal.statusCode.type === "literal" ? String(terminal.statusCode.value) : `dyn:${terminal.statusCode.sourceText}`;
+  const conditionSig = branch.conditions.map((c) => `${c.polarity}:${c.sourceText}`).join(";");
+  const conditionHash = createHash("sha1").update(conditionSig).digest("hex").slice(0, 7);
+  return `${functionName}:${terminal.kind}:${statusKey}:${conditionHash}`;
+}
+function assembleSummary(raw, options = DEFAULT_OPTIONS) {
+  const transitions = raw.branches.map((branch) => {
+    const conditions = branch.conditions.map(
+      rawConditionToPredicate
+    );
+    const transition = {
+      id: makeTransitionId(raw.identity.name, branch),
+      conditions,
+      output: terminalToOutput(branch.terminal),
+      effects: [
+        ...branch.effects.map(effectToIR),
+        ...branch.extraEffects ?? []
+      ],
+      location: branch.location,
+      isDefault: branch.isDefault
+    };
+    if (branch.expectedInput != null) {
+      transition.expectedInput = branch.expectedInput;
+    }
+    return transition;
+  });
+  const gaps = detectGaps(raw, transitions, options);
+  const confidence = assessConfidence(raw);
+  const inputs = raw.parameters.map(paramToInput);
+  const metadata = buildMetadata(raw);
+  return {
+    kind: raw.identity.kind,
+    location: {
+      file: raw.identity.file,
+      range: raw.identity.range,
+      exportName: raw.identity.exportName
+    },
+    identity: {
+      name: raw.identity.name,
+      exportPath: raw.identity.exportPath,
+      boundaryBinding: raw.boundaryBinding ?? null
+    },
+    inputs,
+    transitions,
+    gaps,
+    confidence,
+    ...metadata !== null ? { metadata } : {}
+  };
+}
+function buildMetadata(raw) {
+  const metadata = {};
+  const http = buildHttpMetadata(raw);
+  if (http !== null) {
+    metadata.http = http;
+  }
+  const graphql = buildGraphqlMetadata(raw);
+  if (graphql !== null) {
+    metadata.graphql = graphql;
+  }
+  return Object.keys(metadata).length > 0 ? metadata : null;
+}
+function buildHttpMetadata(raw) {
+  const http = {};
+  if (raw.declaredContract !== null) {
+    http.declaredContract = raw.declaredContract;
+  }
+  if (raw.bodyAccessors !== void 0 && raw.bodyAccessors.length > 0) {
+    http.bodyAccessors = raw.bodyAccessors;
+  }
+  if (raw.statusAccessors !== void 0 && raw.statusAccessors.length > 0) {
+    http.statusAccessors = raw.statusAccessors;
+  }
+  return Object.keys(http).length > 0 ? http : null;
+}
+function buildGraphqlMetadata(raw) {
+  const graphql = {};
+  if (raw.graphqlDocument !== void 0) {
+    graphql.document = raw.graphqlDocument;
+  }
+  if (raw.graphqlSchemaSdl !== void 0) {
+    graphql.schemaSdl = raw.graphqlSchemaSdl;
+  }
+  if (raw.graphqlDeclaredContract !== void 0) {
+    graphql.declaredContract = raw.graphqlDeclaredContract;
+  }
+  if (raw.graphqlUnresolvedDocument !== void 0) {
+    graphql.unresolvedDocument = raw.graphqlUnresolvedDocument;
+  }
+  return Object.keys(graphql).length > 0 ? graphql : null;
+}
+function detectGaps(raw, transitions, options) {
+  if (options.gapHandling === "silent") {
+    return [];
+  }
+  const gaps = [];
+  if (raw.declaredContract) {
+    const producedStatuses = new Set(
+      transitions.flatMap((t) => {
+        if (t.output.type !== "response") {
+          return [];
+        }
+        const sc = t.output.statusCode;
+        if (sc?.type === "literal") {
+          return [sc.value];
+        }
+        return [];
+      })
+    );
+    const declaredStatuses = new Set(
+      raw.declaredContract.responses.map((r) => r.statusCode)
+    );
+    for (const declared of declaredStatuses) {
+      if (!producedStatuses.has(declared)) {
+        gaps.push({
+          type: "unhandledCase",
+          conditions: [],
+          consequence: "frameworkDefault",
+          description: `Declared response ${declared} is never produced by the handler`
+        });
+      }
+    }
+    for (const produced of producedStatuses) {
+      if (!declaredStatuses.has(produced)) {
+        gaps.push({
+          type: "unhandledCase",
+          conditions: [],
+          consequence: "unknown",
+          description: `Handler produces status ${produced} which is not declared in the ${raw.declaredContract.framework} contract`
+        });
+      }
+    }
+  }
+  return gaps;
+}
+function assessConfidence(raw) {
+  let total = 0;
+  let opaque = 0;
+  for (const branch of raw.branches) {
+    for (const condition of branch.conditions) {
+      total++;
+      if (!condition.structured || condition.structured.type === "opaque") {
+        opaque++;
+      }
+    }
+  }
+  const ratio = total === 0 ? 0 : opaque / total;
+  const level = ratio === 0 ? "high" : ratio < 0.5 ? "medium" : "low";
+  return { source: "inferred_static", level };
+}
+function bodyToShape(body) {
+  if (!body) {
+    return null;
+  }
+  if (body.shape !== null) {
+    return body.shape;
+  }
+  if (body.typeText) {
+    return { type: "ref", name: body.typeText };
+  }
+  return null;
+}
+var terminalConverters = {
+  response: (t) => {
+    const statusCode = t.statusCode ? t.statusCode.type === "literal" ? { type: "literal", value: t.statusCode.value } : { type: "unresolved", sourceText: t.statusCode.sourceText } : null;
+    const body = bodyToShape(t.body);
+    return { type: "response", statusCode, body, headers: {} };
+  },
+  throw: (t) => {
+    if (t.statusCode) {
+      const statusCode = t.statusCode.type === "literal" ? { type: "literal", value: t.statusCode.value } : { type: "unresolved", sourceText: t.statusCode.sourceText };
+      return {
+        type: "response",
+        statusCode,
+        body: bodyToShape(t.body),
+        headers: {}
+      };
+    }
+    return {
+      type: "throw",
+      exceptionType: t.exceptionType,
+      message: t.message
+    };
+  },
+  render: (t) => ({
+    type: "render",
+    component: t.component ?? "unknown",
+    ...t.renderTree !== null ? { root: t.renderTree } : {}
+  }),
+  delegate: (t) => ({
+    type: "delegate",
+    to: t.delegateTarget ?? "unknown"
+  }),
+  emit: (t) => ({
+    type: "emit",
+    event: t.emitEvent ?? "unknown"
+  }),
+  return: (t) => ({
+    type: "return",
+    value: bodyToShape(t.body)
+  }),
+  void: (_t) => ({ type: "void" })
+};
+function terminalToOutput(terminal) {
+  return terminalConverters[terminal.kind](terminal);
+}
+function rawConditionToPredicate(c) {
+  const pred = c.structured !== null ? c.structured : {
+    type: "opaque",
+    sourceText: c.sourceText,
+    reason: "complexExpression"
+  };
+  return c.polarity === "negative" ? { type: "negation", operand: pred } : pred;
+}
+var effectConverters = {
+  mutation: (e) => ({
+    type: "mutation",
+    target: e.target,
+    operation: e.operation
+  }),
+  invocation: (e) => {
+    const invocation = {
+      type: "invocation",
+      callee: e.callee,
+      args: e.args,
+      async: e.async
+    };
+    if (e.preconditions !== void 0 && e.preconditions.length > 0) {
+      invocation.preconditions = e.preconditions.map(rawConditionToPredicate);
+    }
+    return invocation;
+  },
+  emission: (e) => ({ type: "emission", event: e.event }),
+  stateChange: (e) => ({ type: "stateChange", variable: e.variable })
+};
+function effectToIR(effect) {
+  return effectConverters[effect.type](effect);
+}
+function paramToInput(param) {
+  return {
+    type: "parameter",
+    name: param.name,
+    position: param.position,
+    role: param.role,
+    shape: param.typeText ? { type: "ref", name: param.typeText } : null
+  };
+}
+export {
+  assembleSummary,
+  assessConfidence,
+  detectGaps,
+  effectToIR,
+  httpRouteDiscovery,
+  makeTransitionId,
+  paramToInput,
+  terminalToOutput
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@suss/extractor",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Framework-agnostic extraction pipeline that turns raw extractions into suss behavioral summaries.",
+  "keywords": [
+    "suss",
+    "behavioral-summary",
+    "static-analysis",
+    "extraction",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/extractor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/extractor"
+  },
+  "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.0.1"
+  },
+  "devDependencies": {
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}