@suss/recognize 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,127 @@
+import { InvocationRecognizer, PatternPack } from '@suss/extractor';
+export { DeclaredMatch, PackDeclarations, PatternPack } from '@suss/extractor';
+import { a as Chain, S as StorageMethod, L as LinkFunction, C as CallOps, R as ReceiverOrigin } from './chain-DTSij2Mn.js';
+export { A as ArgumentPick, b as ConstructedFrom, c as ContainerLink, D as DeclaredBy, E as Ending, F as FromReceiver, d as Link, M as MatchStart, e as MethodsLink, O as OpsCarrier, f as StartLink, g as StorageEnding, U as UnsettledName, h as constructedFrom, i as declaredBy, o as opsIn } from './chain-DTSij2Mn.js';
+import { Effect } from '@suss/behavioral-ir';
+
+/**
+ * Turning a chain into the recognizer hook the adapters already call.
+ *
+ * The links are guards, so the compiled hook checks the cheap one
+ * first: looking a method up in a table costs nothing, while following
+ * a receiver to the library that made it walks declarations. The chain
+ * says which questions to ask, not the order to ask them in. A link
+ * that changes what the receiver is, the way Prisma's model property
+ * does, will need that order back, and the note here is where to start.
+ */
+
+/** A chain, as the hook the adapter dispatches to on every call. */
+declare function compile(chain: Chain<StorageMethod>, recognition: string): InvocationRecognizer;
+
+/**
+ * Running the example that comes with every declaration.
+ *
+ * A pack's documentation goes stale the moment the library moves, and
+ * nothing catches it. An example that the pack's own tests compile and
+ * run against the declaration cannot: the day it stops matching, the
+ * pack fails rather than the docs quietly lying.
+ *
+ * The run itself needs a compiler, which this package does not have, so
+ * the caller passes one. A pack's test builds a small project with the
+ * client library on disk and hands back what the recognizers emitted.
+ */
+
+/** What a pack's example produced, and what the pack said it would. */
+interface RanExample {
+    /** What the declaration matches, in the pack's own words. */
+    match: string;
+    /** The line of code that came with the declaration. */
+    example: string;
+    effects: Effect[];
+}
+/** How a pack's test compiles one line and runs the pack over it. */
+type RunOverCode = (code: string) => Effect[];
+/**
+ * Every example a pack declares, run. A declaration with no example is
+ * left out, which is what the pack health check catches separately.
+ */
+declare function runExamples(pack: PatternPack, run: RunOverCode): RanExample[];
+/** The declarations a pack shipped without a line of code to run. */
+declare function examplesMissing(pack: PatternPack): string[];
+
+/**
+ * The entry point for a pack that recognizes storage calls, and the
+ * chain it builds.
+ *
+ * The entry point says what comes out rather than how, so a pack author
+ * writes `storageCalls` and never meets an `Effect`. Each method on the
+ * returned value adds one link and gives back a new chain, so a chain
+ * is finished data by the time `pack` receives it.
+ */
+
+/** What a pack says about the store its calls reach. */
+interface StorageCallsSpec {
+    /** The store, in the words OpenTelemetry's semantic conventions use. */
+    system: string;
+    /** The wire, when it differs from the store's own name. */
+    transport?: string;
+    /** Which of the store's namespaces the calls reach. Defaults to "default". */
+    scope?: string;
+    /** How the pack pins down the client its calls are on. */
+    client: ReceiverOrigin;
+    /**
+     * What a reader gives back for a name nothing settles. Defaults to
+     * "reference", which says which value to go and ask about.
+     */
+    unsettledName?: "nothing" | "reference";
+}
+/** A storage chain, and the links that can still be added to it. */
+interface StorageCalls {
+    /** Which methods count, and what each one reads or writes. */
+    methods(table: Readonly<Record<string, StorageMethod>>, options?: {
+        ignoringCase?: boolean;
+    }): StorageCalls;
+    /**
+     * Which container a call's selector belongs to. Without this the
+     * first name a call reached is the container.
+     */
+    container(from: LinkFunction<[readonly string[], CallOps], string | null>): StorageCalls;
+    /** A line of code this matches, which the pack's tests run. */
+    example(code: string): StorageCalls;
+    /** The links and the ending, as data. */
+    readonly declared: Chain<StorageMethod>;
+}
+/** A pack that recognizes calls against a store. */
+declare function storageCalls(spec: StorageCallsSpec): StorageCalls;
+
+/**
+ * Assembling declared chains into the pack the adapters load.
+ *
+ * Everything a `PatternPack` needs beyond the chains is either already
+ * in them or the same for every declared pack: the modules the client
+ * came from are the import gate, the store's wire is the protocol, and
+ * a pack of recognizers discovers nothing. What is left is the pack's
+ * own name, the languages it runs on, and the name its effects are
+ * recognized under, which is the npm package callers install.
+ */
+
+/** What a pack says about itself, beyond the calls it matches. */
+interface PackSpec {
+    /** The languages the pack runs on, as the adapters name them. */
+    languages: string[];
+    /**
+     * The name effects from this pack are recorded under, which is the
+     * npm package a user installs.
+     */
+    recognizedAs: string;
+    /**
+     * What the pack calls this build of itself. The extraction cache keys
+     * on it, so a pack that never stamps one serves an earlier build's
+     * results after an edit.
+     */
+    version?: string;
+}
+/** A pack, assembled from the calls it says it matches. */
+declare function pack(name: string, matches: readonly StorageCalls[], spec: PackSpec): PatternPack;
+
+export { CallOps, Chain, LinkFunction, type PackSpec, type RanExample, ReceiverOrigin, type RunOverCode, type StorageCalls, type StorageCallsSpec, StorageMethod, compile, examplesMissing, pack, runExamples, storageCalls };

package/dist/index.js

@@ -0,0 +1,232 @@
+// src/compile.ts
+import { storageBinding } from "@suss/behavioral-ir";
+
+// src/ops.ts
+function declaredBy(...importedFrom) {
+  return { origin: "declaredBy", importedFrom };
+}
+function constructedFrom(...importedFrom) {
+  return { origin: "constructed", importedFrom };
+}
+function opsIn(ctx) {
+  const carrier = ctx;
+  return carrier?.ops ?? null;
+}
+
+// src/compile.ts
+function compile(chain, recognition) {
+  return (_call, ctx) => {
+    const ops = opsIn(ctx);
+    if (ops === null) {
+      return null;
+    }
+    const method = ops.method();
+    if (method === null) {
+      return null;
+    }
+    const meaning = meaningOf(chain, method);
+    if (meaning === null || !startsHere(chain, ops)) {
+      return null;
+    }
+    return YIELD[chain.ending.yields]({
+      ops,
+      method,
+      meaning,
+      chain,
+      recognition
+    });
+  };
+}
+function meaningOf(chain, method) {
+  const link = chain.links.find(
+    (candidate) => candidate.asks === "methods"
+  );
+  if (link === void 0) {
+    return null;
+  }
+  if (!link.ignoringCase) {
+    return link.table[method] ?? null;
+  }
+  return link.table[method.toLowerCase()] ?? null;
+}
+var START = {
+  receiver: (start, ops) => ops.receiverIsFrom(start.origin)
+};
+function startsHere(chain, ops) {
+  return chain.links.every(
+    (link) => link.asks === "start" ? START[link.at.starts](link.at, ops) : true
+  );
+}
+var YIELD = {
+  storageAccess
+};
+function storageAccess(matched) {
+  const { ops, method, meaning, chain, recognition } = matched;
+  const ending = chain.ending;
+  const selector = namesAt(ops, meaning.selector, ending.unsettledName);
+  const fields = namesAt(ops, meaning.fields, ending.unsettledName);
+  const container = containerOf(chain, selector, ops);
+  return [
+    {
+      type: "interaction",
+      binding: storageBinding({
+        recognition,
+        storageSystem: ending.system,
+        ...ending.transport === void 0 ? {} : { transport: ending.transport },
+        scope: ending.scope,
+        container,
+        accessPath: null
+      }),
+      callee: ops.calleeText(),
+      interaction: {
+        class: "storage-access",
+        kind: meaning.kind,
+        fields,
+        operation: method,
+        ...selector.length > 0 ? { selector } : {}
+      }
+    }
+  ];
+}
+function containerOf(chain, selector, ops) {
+  const link = chain.links.find(
+    (candidate) => candidate.asks === "container"
+  );
+  if (link === void 0) {
+    return selector[0] ?? null;
+  }
+  return link.from(selector, ops);
+}
+function namesAt(ops, pick, unsettled) {
+  if (pick === void 0) {
+    return [];
+  }
+  const last = "at" in pick ? pick.at + 1 : ops.argumentCount();
+  const first = "at" in pick ? pick.at : pick.from;
+  const names = [];
+  for (let index = first; index < last; index += 1) {
+    const name = ops.nameAt(index, unsettled);
+    if (name !== null) {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+// src/example.ts
+function runExamples(pack2, run) {
+  const declared = pack2.declarations?.declarations ?? [];
+  const ran = [];
+  for (const declaration of declared) {
+    if (declaration.example === null) {
+      continue;
+    }
+    ran.push({
+      match: declaration.name,
+      example: declaration.example,
+      effects: run(declaration.example)
+    });
+  }
+  return ran;
+}
+function examplesMissing(pack2) {
+  return (pack2.declarations?.declarations ?? []).filter((declaration) => declaration.example === null).map((declaration) => declaration.name);
+}
+
+// src/pack.ts
+function pack(name, matches, spec) {
+  const chains = matches.map((match) => match.declared);
+  const recognizers = chains.map(
+    (chain) => compile(chain, spec.recognizedAs)
+  );
+  return {
+    name,
+    languages: spec.languages,
+    ...spec.version === void 0 ? {} : { version: spec.version },
+    protocol: protocolOf(chains),
+    discovery: [],
+    terminals: [],
+    inputMapping: { type: "positionalParams", params: [] },
+    requiresImport: gateOf(chains),
+    invocationRecognizers: recognizers,
+    declarations: { declarations: chains.map(describe) }
+  };
+}
+function protocolOf(chains) {
+  const wires = new Set(
+    chains.map((chain) => chain.ending.transport ?? chain.ending.system)
+  );
+  const [only] = [...wires];
+  if (wires.size !== 1 || only === void 0) {
+    throw new Error(
+      `a pack reaches ${wires.size} wires (${[...wires].join(", ")}); split it into one pack per wire`
+    );
+  }
+  return only;
+}
+function gateOf(chains) {
+  const modules = /* @__PURE__ */ new Set();
+  for (const chain of chains) {
+    for (const link of chain.links) {
+      if (link.asks !== "start" || link.at.starts !== "receiver") {
+        continue;
+      }
+      for (const module of link.at.origin.importedFrom) {
+        modules.add(module);
+      }
+    }
+  }
+  return [...modules];
+}
+function describe(chain) {
+  const functions = chain.links.filter(isFunctionLink);
+  return {
+    name: chain.ending.system,
+    dataLinks: chain.links.length - functions.length,
+    functionLinks: functions.map((link) => link.asks),
+    astLinks: functions.filter((link) => link.from.reachesAst === true).map((link) => link.asks),
+    example: chain.example
+  };
+}
+function isFunctionLink(link) {
+  return link.asks === "container";
+}
+
+// src/storage.ts
+function storageCalls(spec) {
+  const ending = {
+    yields: "storageAccess",
+    system: spec.system,
+    ...spec.transport === void 0 ? {} : { transport: spec.transport },
+    scope: spec.scope ?? "default",
+    unsettledName: spec.unsettledName ?? "reference"
+  };
+  return chainFrom({
+    links: [{ asks: "start", at: { starts: "receiver", origin: spec.client } }],
+    ending,
+    example: null
+  });
+}
+function chainFrom(declared) {
+  const adding = (link) => chainFrom({ ...declared, links: [...declared.links, link] });
+  return {
+    declared,
+    methods: (table, options) => adding({
+      asks: "methods",
+      table,
+      ignoringCase: options?.ignoringCase ?? false
+    }),
+    container: (from) => adding({ asks: "container", from }),
+    example: (code) => chainFrom({ ...declared, example: code })
+  };
+}
+export {
+  compile,
+  constructedFrom,
+  declaredBy,
+  examplesMissing,
+  opsIn,
+  pack,
+  runExamples,
+  storageCalls
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@suss/recognize",
+  "version": "0.11.0",
+  "type": "module",
+  "description": "Write a pack as data: a chain of named links that any language adapter with the executor ops can run.",
+  "keywords": [
+    "suss",
+    "pattern-pack",
+    "static-analysis",
+    "recognizer"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/recognize#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/recognize"
+  },
+  "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"
+    },
+    "./ast": {
+      "types": "./dist/ast.d.ts",
+      "import": "./dist/ast.js",
+      "require": "./dist/ast.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.11.0",
+    "@suss/extractor": "0.11.0"
+  },
+  "devDependencies": {
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}