@suss/contract-wrangler 0.33.0 → 0.34.0

package/README.md

@@ -1,12 +1,12 @@
 # @suss/contract-wrangler
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Reads a Cloudflare `wrangler.toml` (or `wrangler.jsonc`) and says what the Worker it deploys is given.
+This package reads a Cloudflare `wrangler.toml` (or `wrangler.jsonc`) and records what the Worker it deploys is given.
 
 ## What this package is
 
-A contract source. `suss contract --from wrangler services/api` reads the document and emits the declared side of four boundaries:
+A contract source. `suss contract --from wrangler services/api` reads the document and records the declared side of four boundaries:
 
 ```toml
 name = "greeting-router"
@@ -31,39 +31,39 @@ queue = "greeting-events"
 | `[[queues.producers]]`, `[[queues.consumers]]` | one channel each, on `cloudflare-queues` |
 | `[env.<name>]` | the same Worker deployed again, with the top-level document as its default |
 
-A store's container is the binding name, `SESSIONS`, because that is what an access in the Worker spells (`env.SESSIONS.get(...)`), and `@suss/framework-cloudflare-workers` records the same name on the code side, so the storage check pairs the two. The resource's own name, the KV namespace id or the bucket name, goes on the summary as `physicalTable`, the same split a Prisma model has between the model and the table it maps to.
+A store's container is the binding name, `SESSIONS`, because that is what an access in the Worker uses (`env.SESSIONS.get(...)`). `@suss/framework-cloudflare-workers` records the same name on the code side, so the storage check pairs the two. The resource's own name, meaning the KV namespace id or the bucket name, goes on the summary as `physicalTable`. A Prisma model splits the same way, between the model name and the table it maps to.
 
-Binding names are also listed on the runtime-config contract, beside the `[vars]` names: a binding is a property of the same `env` object, so a Worker that reads `env.AUDIT_KV` without a binding block for it gets the same finding as a read of a variable nobody set.
+Binding names are also listed on the runtime-config contract, next to the `[vars]` names. A binding is a property of the same `env` object, so a Worker that reads `env.AUDIT_KV` with no binding block for it gets the same finding as a read of a variable nobody set.
 
-## The values, not only the names
+## Variable values
 
-A runtime-config contract usually records which variables a runtime supplies, and that is enough to say whether code reads one nobody set. A Worker needs more, because it addresses its stores through a variable:
+A runtime-config contract usually records which variables a runtime supplies, and that is enough to tell whether code reads one nobody set. A Worker needs more, because it addresses its stores through a variable:
 
 ```ts
 await dynamoRequest(env, aws, "Query", { TableName: env.EDITION_TABLE });
 ```
 
-Nothing at that call site says which table. The container comes out as `{EDITION_TABLE}`, which pairs with nothing until something says what the variable is. `[vars]` says it, so the summary keeps the values under `metadata.runtimeContract.envVarValues`, and the storage check grounds the access through the runtime that runs it.
+Nothing at that call site shows which table. The container comes out as `{EDITION_TABLE}`, which does not pair with anything until something gives the variable's value. `[vars]` gives it, so the summary keeps the values under `metadata.runtimeContract.envVarValues`, and the storage check grounds the access through the runtime that runs it.
 
-A value the document does not state stays out. A secret is set with `wrangler secret put` or by the deployment's own tooling, never in the file, so the reader has nothing to record and the container stays unresolved.
+A value the document does not set is left out. A secret is set with `wrangler secret put` or by the deployment's own tooling, and never in the file, so the reader has nothing to record and the container stays unresolved.
 
 ## Environments
 
-`[env.staging]` deploys the same Worker again under its own name, `greeting-router-staging` unless the block gives a `name`. Each one gets its own summary.
+`[env.staging]` deploys the same Worker again under its own name, which is `greeting-router-staging` unless the block sets a `name`. Each environment gets its own summary.
 
-Wrangler replaces a whole block rather than merging it, so an environment that declares `[env.staging.vars]` supplies those variables and none of the top-level ones. A variable that comes through untouched is recorded as `globals`, which is the same provenance a SAM `Globals` section gets, and the checker judges it once for the document instead of once per deployment.
+Wrangler replaces a whole block instead of merging it, so an environment that declares `[env.staging.vars]` gets those variables and none of the top-level ones. A variable that comes through unchanged is recorded as `globals`, the same provenance a SAM `Globals` section gets, and the checker judges it once for the document instead of once per deployment.
 
 ## Code scope
 
-The Worker's code is the directory the document is in, and `main` says which file it enters. `main` often points at a bundle a build step writes rather than at source; an entry that matches no file leaves the directory in charge, which is what places the code either way.
+The Worker's code is the directory the document is in, and `main` gives the entry file. `main` often points at a bundle that a build step writes, outside the source. If the entry matches no file, the directory alone decides the code scope, so the code is placed correctly either way.
 
 ## Out of scope for now
 
-- **Durable Object and service bindings.** `[[durable_objects.bindings]]` and `[[services]]` are boundaries between two Workers, and pairing them needs both sides of a deployment suss does not read yet.
-- **Routes.** `routes` says which hostnames reach the Worker. The code side states no path, so a declared route would pair with nothing.
-- **Cron expressions.** `[triggers] crons` says when a Worker runs, not what it exchanges.
-- **`.dev.vars`.** It is local development configuration, and it is not what a deployment supplies.
+- **Durable Object and service bindings.** `[[durable_objects.bindings]]` and `[[services]]` are boundaries between two Workers, and pairing them needs both sides of a deployment, which suss does not read yet.
+- **Routes.** `routes` lists the hostnames that reach the Worker. The code side does not state a path, so a declared route would not pair with anything.
+- **Cron expressions.** `[triggers] crons` sets when a Worker runs, and says nothing about what it exchanges.
+- **`.dev.vars`.** It is configuration for local development, and a deployment does not supply it.
 
 ## Where it fits in suss
 
-Depends on `@suss/behavioral-ir` and `@suss/ir-core` for the bindings it writes. `@suss/framework-cloudflare-workers` reads the code side: the triggers the Worker serves and the variables it reads. The storage check in `@suss/checker` pairs a store this reader declares, or one a Terraform module declares, against the accesses that reach it.
+The package depends on `@suss/behavioral-ir` and `@suss/ir-core` for the bindings it writes. `@suss/framework-cloudflare-workers` reads the code side: the triggers the Worker serves and the variables it reads. The storage check in `@suss/checker` pairs a store this reader declares, or one a Terraform module declares, with the accesses that reach it.

package/dist/index.cjs

@@ -98,8 +98,8 @@ function storeSummary(store, entry, context) {
         recognition: RECOGNITION,
         storageSystem: store.storageSystem,
         scope: "default",
-        // The binding name is what an access in the Worker spells, so
-        // it is the name the storage check pairs on.
+        // An access in the Worker uses the binding name, so the storage
+        // check has to pair on it.
         container: boundAs ?? resourceName,
         accessPath: null
       })
@@ -164,9 +164,9 @@ function queueSide(entries, side, context) {
       continue;
     }
     summaries.push({
-      // A producer block declares a queue the Worker sends to, which is
-      // a channel rather than a unit that runs, so it is a library. A
-      // consumer block says this Worker drains that queue.
+      // A producer block declares a queue the Worker sends to. Nothing
+      // runs there, so it is a library. A consumer block means this
+      // Worker drains the queue.
       kind: side === "consumers" ? "consumer" : "library",
       location: {
         file: context.sourceFile,

package/dist/index.d.cts

@@ -3,15 +3,14 @@ import { BehavioralSummary } from '@suss/behavioral-ir';
 /**
  * Finding and parsing a Wrangler configuration document.
  *
- * Wrangler accepts the same configuration in two spellings, TOML and
- * JSONC, and prefers the JSON one where a project has both. This module
- * settles which file a path means and hands back the parsed object; the
- * shape of what is in it is `translate.ts`'s problem.
+ * Wrangler accepts the same configuration as TOML or JSONC, and uses the
+ * JSON file when a project has both. This module picks the file for a
+ * path and returns the parsed object. It does not check the object's
+ * contents beyond it being an object.
  */
 /**
- * The names Wrangler looks for, in the order it prefers them. Wrangler
- * defines the list, so a project that spells its file otherwise passes
- * the path to that file outright.
+ * The file names Wrangler looks for, in its order of preference. A
+ * project whose file has another name passes that file's path directly.
  */
 declare const CONFIGURATION_FILE_NAMES: string[];
 /** Whether a file is one Wrangler would read as a Worker's configuration. */
@@ -44,24 +43,22 @@ type DocumentLocation = {
     kind: "missing";
 };
 /**
- * The configuration file a path means. A path may be the file itself or
- * the directory a Worker lives in, since that is where a person points
- * when they mean the Worker rather than one of its two spellings.
+ * Finds the configuration file for a path. The path may be the file
+ * itself or the Worker's directory, which is searched in Wrangler's
+ * order of preference.
  */
 declare function locateConfigurationFile(target: string): DocumentLocation;
-/** The document a file contains, read by whichever parser its suffix asks for. */
+/** Parses a configuration file as TOML or JSONC, chosen by its extension. */
 declare function loadConfigurationDocument(file: string): WranglerDocument;
 
 /**
  * The stores and queues a Worker is bound to, as boundary summaries.
  *
- * Every binding block in a Wrangler document has the same two halves:
- * `binding`, the name the code reads it under, and a key giving the
- * resource's own name. The code says the first, the deployment declares
- * the second, so a summary keeps both: the container is the binding
- * name, which is what an access in the Worker spells (`env.SESSIONS`),
- * and `physicalTable` is the resource's own name, the same split a
- * Prisma model has between the model and the table it maps to.
+ * Every binding block in a Wrangler document has two parts: `binding`,
+ * the name the code reads the resource under, and a key with the
+ * resource's own name. Code only ever uses the first (`env.SESSIONS`),
+ * so the binding name becomes the container the storage check pairs
+ * on, and the resource's own name goes on `physicalTable`.
  */
 
 /** The manifest language recorded on every binding this reader writes. */
@@ -71,14 +68,15 @@ declare const RECOGNITION = "wrangler";
  * The configuration contract a Wrangler document declares.
  *
  * A Worker reads its variables off the second argument to every
- * trigger, so the channel is the same one a Node process reads through
- * `process.env`, and the summary is the same shape the CloudFormation
- * reader writes for a Lambda: a runtime-config provider, one per
- * deployment, keyed on the deployable unit.
+ * trigger. That is the same channel a Node process reads through
+ * `process.env`, so the summary follows what the CloudFormation reader
+ * writes for a Lambda: one runtime-config provider per deployment, keyed
+ * on the deployable unit.
  *
- * The values go on it as well as the names. A Worker addresses a store
- * through a variable rather than by name, `TableName: env.EDITION_TABLE`,
- * so the value is what says which store the access reaches.
+ * The summary records variable values as well as names. A Worker
+ * addresses a store through a variable, as in
+ * `TableName: env.EDITION_TABLE`, so only the value shows which store
+ * the access reaches.
  */
 
 /** One Worker as deployed: an environment's document over the default one. */
@@ -89,7 +87,7 @@ interface Deployment {
     environment: string | null;
     /** The environment's document with the top-level one behind it. */
     merged: WranglerDocument;
-    /** Which variables the top-level document supplied rather than this one. */
+    /** The variables and bindings this environment takes from the top level. */
     inherited: Set<string>;
 }
 /**
@@ -104,14 +102,12 @@ declare function environmentDocuments(document: WranglerDocument): Deployment[];
  * @suss/contract-wrangler: behavioral summaries from a Wrangler
  * configuration document.
  *
- * A `wrangler.toml` deploys a working Worker, and before this reader
- * existed suss saw none of it: no deployable unit, no configuration
- * contract, no stores and no queues. `name` and `main` give the unit
- * and the code it runs, `vars` gives the configuration, the three
- * binding blocks give stores, `queues` gives the channels it sends on
- * and drains, and each `env.<name>` deploys the same Worker again with
- * the top-level document as its default. The README says how each half
- * pairs.
+ * `name` and `main` give the deployable unit and the code it runs.
+ * `vars` gives its configuration, the three binding blocks give its
+ * stores, and `queues` gives the channels it sends on and drains. Each
+ * `env.<name>` deploys the same Worker again, with the top-level
+ * document as its default. The README describes how each summary pairs
+ * with the code side.
  */
 
 interface WranglerToSummariesOptions {
@@ -128,7 +124,10 @@ declare function wranglerToSummaries(document: WranglerDocument, options: {
     source: string;
     codeScope: string;
 }): BehavioralSummary[];
-/** The path may be the document itself or the directory the Worker is in. */
+/**
+ * Reads a Wrangler document and returns its summaries. The path may be
+ * the document itself or the directory the Worker is in.
+ */
 declare function wranglerFileToSummaries(target: string, options?: WranglerToSummariesOptions): BehavioralSummary[];
 
 export { CONFIGURATION_FILE_NAMES, type DocumentLocation, RECOGNITION, type WranglerDocument, type WranglerRecord, type WranglerToSummariesOptions, environmentDocuments, isConfigurationFile, loadConfigurationDocument, locateConfigurationFile, wranglerFileToSummaries, wranglerToSummaries };

package/dist/index.d.ts

@@ -3,15 +3,14 @@ import { BehavioralSummary } from '@suss/behavioral-ir';
 /**
  * Finding and parsing a Wrangler configuration document.
  *
- * Wrangler accepts the same configuration in two spellings, TOML and
- * JSONC, and prefers the JSON one where a project has both. This module
- * settles which file a path means and hands back the parsed object; the
- * shape of what is in it is `translate.ts`'s problem.
+ * Wrangler accepts the same configuration as TOML or JSONC, and uses the
+ * JSON file when a project has both. This module picks the file for a
+ * path and returns the parsed object. It does not check the object's
+ * contents beyond it being an object.
  */
 /**
- * The names Wrangler looks for, in the order it prefers them. Wrangler
- * defines the list, so a project that spells its file otherwise passes
- * the path to that file outright.
+ * The file names Wrangler looks for, in its order of preference. A
+ * project whose file has another name passes that file's path directly.
  */
 declare const CONFIGURATION_FILE_NAMES: string[];
 /** Whether a file is one Wrangler would read as a Worker's configuration. */
@@ -44,24 +43,22 @@ type DocumentLocation = {
     kind: "missing";
 };
 /**
- * The configuration file a path means. A path may be the file itself or
- * the directory a Worker lives in, since that is where a person points
- * when they mean the Worker rather than one of its two spellings.
+ * Finds the configuration file for a path. The path may be the file
+ * itself or the Worker's directory, which is searched in Wrangler's
+ * order of preference.
  */
 declare function locateConfigurationFile(target: string): DocumentLocation;
-/** The document a file contains, read by whichever parser its suffix asks for. */
+/** Parses a configuration file as TOML or JSONC, chosen by its extension. */
 declare function loadConfigurationDocument(file: string): WranglerDocument;
 
 /**
  * The stores and queues a Worker is bound to, as boundary summaries.
  *
- * Every binding block in a Wrangler document has the same two halves:
- * `binding`, the name the code reads it under, and a key giving the
- * resource's own name. The code says the first, the deployment declares
- * the second, so a summary keeps both: the container is the binding
- * name, which is what an access in the Worker spells (`env.SESSIONS`),
- * and `physicalTable` is the resource's own name, the same split a
- * Prisma model has between the model and the table it maps to.
+ * Every binding block in a Wrangler document has two parts: `binding`,
+ * the name the code reads the resource under, and a key with the
+ * resource's own name. Code only ever uses the first (`env.SESSIONS`),
+ * so the binding name becomes the container the storage check pairs
+ * on, and the resource's own name goes on `physicalTable`.
  */
 
 /** The manifest language recorded on every binding this reader writes. */
@@ -71,14 +68,15 @@ declare const RECOGNITION = "wrangler";
  * The configuration contract a Wrangler document declares.
  *
  * A Worker reads its variables off the second argument to every
- * trigger, so the channel is the same one a Node process reads through
- * `process.env`, and the summary is the same shape the CloudFormation
- * reader writes for a Lambda: a runtime-config provider, one per
- * deployment, keyed on the deployable unit.
+ * trigger. That is the same channel a Node process reads through
+ * `process.env`, so the summary follows what the CloudFormation reader
+ * writes for a Lambda: one runtime-config provider per deployment, keyed
+ * on the deployable unit.
  *
- * The values go on it as well as the names. A Worker addresses a store
- * through a variable rather than by name, `TableName: env.EDITION_TABLE`,
- * so the value is what says which store the access reaches.
+ * The summary records variable values as well as names. A Worker
+ * addresses a store through a variable, as in
+ * `TableName: env.EDITION_TABLE`, so only the value shows which store
+ * the access reaches.
  */
 
 /** One Worker as deployed: an environment's document over the default one. */
@@ -89,7 +87,7 @@ interface Deployment {
     environment: string | null;
     /** The environment's document with the top-level one behind it. */
     merged: WranglerDocument;
-    /** Which variables the top-level document supplied rather than this one. */
+    /** The variables and bindings this environment takes from the top level. */
     inherited: Set<string>;
 }
 /**
@@ -104,14 +102,12 @@ declare function environmentDocuments(document: WranglerDocument): Deployment[];
  * @suss/contract-wrangler: behavioral summaries from a Wrangler
  * configuration document.
  *
- * A `wrangler.toml` deploys a working Worker, and before this reader
- * existed suss saw none of it: no deployable unit, no configuration
- * contract, no stores and no queues. `name` and `main` give the unit
- * and the code it runs, `vars` gives the configuration, the three
- * binding blocks give stores, `queues` gives the channels it sends on
- * and drains, and each `env.<name>` deploys the same Worker again with
- * the top-level document as its default. The README says how each half
- * pairs.
+ * `name` and `main` give the deployable unit and the code it runs.
+ * `vars` gives its configuration, the three binding blocks give its
+ * stores, and `queues` gives the channels it sends on and drains. Each
+ * `env.<name>` deploys the same Worker again, with the top-level
+ * document as its default. The README describes how each summary pairs
+ * with the code side.
  */
 
 interface WranglerToSummariesOptions {
@@ -128,7 +124,10 @@ declare function wranglerToSummaries(document: WranglerDocument, options: {
     source: string;
     codeScope: string;
 }): BehavioralSummary[];
-/** The path may be the document itself or the directory the Worker is in. */
+/**
+ * Reads a Wrangler document and returns its summaries. The path may be
+ * the document itself or the directory the Worker is in.
+ */
 declare function wranglerFileToSummaries(target: string, options?: WranglerToSummariesOptions): BehavioralSummary[];
 
 export { CONFIGURATION_FILE_NAMES, type DocumentLocation, RECOGNITION, type WranglerDocument, type WranglerRecord, type WranglerToSummariesOptions, environmentDocuments, isConfigurationFile, loadConfigurationDocument, locateConfigurationFile, wranglerFileToSummaries, wranglerToSummaries };

package/dist/index.js

@@ -57,8 +57,8 @@ function storeSummary(store, entry, context) {
         recognition: RECOGNITION,
         storageSystem: store.storageSystem,
         scope: "default",
-        // The binding name is what an access in the Worker spells, so
-        // it is the name the storage check pairs on.
+        // An access in the Worker uses the binding name, so the storage
+        // check has to pair on it.
         container: boundAs ?? resourceName,
         accessPath: null
       })
@@ -123,9 +123,9 @@ function queueSide(entries, side, context) {
       continue;
     }
     summaries.push({
-      // A producer block declares a queue the Worker sends to, which is
-      // a channel rather than a unit that runs, so it is a library. A
-      // consumer block says this Worker drains that queue.
+      // A producer block declares a queue the Worker sends to. Nothing
+      // runs there, so it is a library. A consumer block means this
+      // Worker drains the queue.
       kind: side === "consumers" ? "consumer" : "library",
       location: {
         file: context.sourceFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-wrangler",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "Read a Cloudflare wrangler.toml or wrangler.jsonc and check the bindings it declares against the Worker code that uses them.",
   "keywords": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/wrangler#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -47,8 +47,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.33.0",
-    "@suss/ir-core": "0.33.0",
+    "@suss/behavioral-ir": "0.34.0",
+    "@suss/ir-core": "0.34.0",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.4.2"
   },