@suss/recognize 0.11.0

package/dist/chain-DTSij2Mn.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The operations a chain performs at one call site, and what a language
+ * adapter has to be able to work out for it.
+ *
+ * A chain is data, so something has to turn "did this module declare
+ * the method" into a yes or no about a particular program. That is the
+ * adapter's job, and this interface is the whole of what a chain asks
+ * for. An adapter implements it once and every declared pack runs
+ * there, which is what lets one pack drive several languages.
+ *
+ * Nothing here mentions a syntax tree. A link that needs the tree goes
+ * through `@suss/recognize/ast`, a separate import so that reaching for
+ * it shows up in a diff and in the pack health report.
+ */
+/**
+ * How a pack pins down the receiver a call is on.
+ *
+ * The migration plan for #542 lists four more: `factoryMade` (`app =
+ * express()`), `imported`, `anchored` (a chain read from its anchor
+ * call), `inherits` (a Ruby or Python receiver matched by ancestry) and
+ * `global` (`process.env`, bare `fetch`). Each arrives as a member here
+ * with an entry in every adapter's dispatch table. The README beside
+ * this file says which starts are not receiver-shaped at all.
+ */
+type ReceiverOrigin = DeclaredBy | ConstructedFrom;
+/**
+ * A receiver whose method one of these modules declared.
+ *
+ * This is the origin for a client the source never spells out. `const
+ * redis = await this.getClient()` says nothing about ioredis, and the
+ * declaration behind `redis.get` says everything.
+ */
+interface DeclaredBy {
+    readonly origin: "declaredBy";
+    /** The modules whose declarations settle the call. */
+    readonly importedFrom: readonly string[];
+}
+/**
+ * A client made from a module's export, however the program caches it.
+ * Asked of the receiver itself, so it still works where the method is untyped
+ * and `declaredBy` finds nothing to read.
+ */
+interface ConstructedFrom {
+    readonly origin: "constructed";
+    /** The modules whose export the client was made from. */
+    readonly importedFrom: readonly string[];
+}
+/**
+ * A receiver whose method one of these modules declared. Pass every
+ * module that ships the same client, the way three packages all speak
+ * one wire protocol.
+ */
+declare function declaredBy(...importedFrom: readonly string[]): DeclaredBy;
+/** A client made from one of these modules' exports. */
+declare function constructedFrom(...importedFrom: readonly string[]): ConstructedFrom;
+/**
+ * What a reader gives back for a name nothing in the source settles.
+ * `"nothing"` gives null, `"reference"` gives the value to go and ask
+ * about instead.
+ */
+type UnsettledName = "nothing" | "reference";
+/**
+ * One call site, as the questions a chain asks about it.
+ *
+ * An adapter builds one of these per call and hands it to the
+ * recognizer through its context. Every member is about the call in
+ * hand, so there is no node to pass around and no place for a pack to
+ * reach past what it declared.
+ */
+interface CallOps {
+    /** Which method the call reaches for, spelled as the source spells it. */
+    method(): string | null;
+    /** Whether the receiver came from where the origin says. */
+    receiverIsFrom(origin: ReceiverOrigin): boolean;
+    /** How many arguments the call passes. */
+    argumentCount(): number;
+    /** The name the argument in this position gives. */
+    nameAt(index: number, unsettled: UnsettledName): string | null;
+    /** The callee, as the source writes it. */
+    calleeText(): string;
+}
+/**
+ * The property an adapter puts its ops on, in the context it hands a
+ * recognizer. A context without it belongs to an adapter that has not
+ * implemented the ops, and a declared pack matches nothing there.
+ */
+interface OpsCarrier {
+    ops?: CallOps;
+}
+/** The ops in a recognizer context, or null when the adapter has none. */
+declare function opsIn(ctx: unknown): CallOps | null;
+
+/**
+ * The spine every pack shares, as a chain of links.
+ *
+ * A pack does four jobs, and all four start the same way: match the
+ * receiver, match the method, read the arguments, then yield. What
+ * differs is the ending. Recognition yields effects, discovery yields a
+ * unit, a terminal yields a response write, and a claimed callback
+ * yields a sub-unit. Only the effects ending is built; the others are
+ * further members of `Ending` with an entry in the compile table.
+ *
+ * A link's answer is data wherever it can be. A link given a function
+ * instead is code, that link alone, and pack health says which ones.
+ */
+
+/** A link whose answer a pack wrote as code rather than as data. */
+interface LinkFunction<A extends unknown[], R> {
+    (...args: A): R;
+    /** Set when the function was built through `@suss/recognize/ast`. */
+    readonly reachesAst?: boolean;
+}
+/**
+ * What a match starts from.
+ *
+ * Most of what the shipped packs match starts from a receiver, and none
+ * of what discovery matches does: an exported name, a file path, a
+ * decorator, a parameter's type, a template file beside the module and
+ * a function's return type each start somewhere else. So the start is
+ * its own axis, and a receiver origin is one value on it.
+ */
+type MatchStart = FromReceiver;
+/** A match that starts from the receiver a call is on. */
+interface FromReceiver {
+    readonly starts: "receiver";
+    readonly origin: ReceiverOrigin;
+}
+/** Where the match begins. */
+interface StartLink {
+    readonly asks: "start";
+    readonly at: MatchStart;
+}
+/** Which methods count, and what each one does. */
+interface MethodsLink<TMeaning> {
+    readonly asks: "methods";
+    readonly table: Readonly<Record<string, TMeaning>>;
+    /**
+     * Whether two spellings of one method name are the same method. One
+     * client library lower-cases where another camel-cases, and both are
+     * sending the same command.
+     */
+    readonly ignoringCase: boolean;
+}
+/**
+ * Which container a call's selector belongs to.
+ *
+ * The call in hand comes second so that a rule written over the
+ * selector alone, which is most of them, ignores it. A rule that has to
+ * read the syntax tree goes through `astLink`, which is what puts the
+ * call to use.
+ */
+interface ContainerLink {
+    readonly asks: "container";
+    readonly from: LinkFunction<[readonly string[], CallOps], string | null>;
+}
+/** One question in a chain, and the answer the pack gave for it. */
+type Link<TMeaning> = StartLink | MethodsLink<TMeaning> | ContainerLink;
+/** Which argument or arguments say what a call reached. */
+type ArgumentPick = {
+    readonly at: number;
+} | {
+    readonly from: number;
+};
+/** What one method of a storage client does. */
+interface StorageMethod {
+    readonly kind: "read" | "write";
+    /** Which argument or arguments say what the call reached. */
+    readonly selector?: ArgumentPick;
+    /** Which argument says which field inside it, when the method takes one. */
+    readonly fields?: ArgumentPick;
+}
+/** What a chain produces when every link matches. */
+type Ending = StorageEnding;
+/** A storage access: one call, one thing it read or wrote. */
+interface StorageEnding {
+    readonly yields: "storageAccess";
+    /** The store, in the words OpenTelemetry's semantic conventions use. */
+    readonly system: string;
+    /** The wire, when it differs from the store's own name. */
+    readonly transport?: string;
+    /** Which of the store's namespaces the call reached. */
+    readonly scope: string;
+    /** What a reader gives back for a name nothing in the source settles. */
+    readonly unsettledName: "nothing" | "reference";
+}
+/**
+ * A pack's declaration for one kind of call: the links, the ending, and
+ * a line of code it matches.
+ */
+interface Chain<TMeaning = StorageMethod> {
+    readonly links: readonly Link<TMeaning>[];
+    readonly ending: Ending;
+    /** A line of code this matches, which the pack's tests run. */
+    readonly example: string | null;
+}
+
+export { type ArgumentPick as A, type CallOps as C, type DeclaredBy as D, type Ending as E, type FromReceiver as F, type LinkFunction as L, type MatchStart as M, type OpsCarrier as O, type ReceiverOrigin as R, type StorageMethod as S, type UnsettledName as U, type Chain as a, type ConstructedFrom as b, type ContainerLink as c, type Link as d, type MethodsLink as e, type StartLink as f, type StorageEnding as g, constructedFrom as h, declaredBy as i, opsIn as o };

package/dist/index.cjs

@@ -0,0 +1,266 @@
+"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, {
+  compile: () => compile,
+  constructedFrom: () => constructedFrom,
+  declaredBy: () => declaredBy,
+  examplesMissing: () => examplesMissing,
+  opsIn: () => opsIn,
+  pack: () => pack,
+  runExamples: () => runExamples,
+  storageCalls: () => storageCalls
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/compile.ts
+var import_behavioral_ir = require("@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: (0, import_behavioral_ir.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 module2 of link.at.origin.importedFrom) {
+        modules.add(module2);
+      }
+    }
+  }
+  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 })
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compile,
+  constructedFrom,
+  declaredBy,
+  examplesMissing,
+  opsIn,
+  pack,
+  runExamples,
+  storageCalls
+});

package/dist/index.d.cts

@@ -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.cjs';
+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.cjs';
+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 };