@kensio/yulin 1.21.6 → 1.21.8

package/docs/lint/README.md

@@ -1,24 +1,17 @@
-# Linting CFF JS2
+# Lint CloudFront Functions code
 
-CloudFront Functions run JS2, ECMAScript 5.1 with a named subset of ES 6 to 12 on top, rather than
-a current JavaScript engine. A class or a `for...of` is a syntax error, and CloudFront refuses the
-code when you upload it. A call to `fetch` parses, and then fails at the edge, where that global is
-absent and there is no network to reach. Both are a long way from where the code was written, and
-Yulin publishes lint configs that refuse the same things in the editor.
+Yulin provides ESLint and Oxlint configs for the CloudFront Functions JavaScript 2.0 runtime. Both
+configs apply to `**/*.cff.js`, the filename pattern used by
+[simulated CloudFront](https://yulinsim.dev/services/cloudfront/ "Simulated CloudFront usage docs").
 
-The configs apply to `**/*.cff.js` files. That is the naming
-[sim CloudFront](https://yulinsim.dev/services/cloudfront/ "Simulated CloudFront usage docs") already uses for
-CloudFront Function source.
-
-Every restriction comes from the runtime's
-[own feature list](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-javascript-runtime-20.html),
-an allow-list, and anything outside it is unsupported. None of it is house style. A rule
-banning syntax JS2 accepts would send you away from code that works.
+The runtime is ECMAScript 5.1 with selected features from ES 6 to 12. The lint rules follow AWS's
+[runtime feature list](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-javascript-runtime-20.html).
+They report unsupported syntax and globals before CloudFront rejects the function.
 
 ## Setting it up with ESLint
 
-`@kensio/yulin/eslint` exports a flat config to spread into your own. It restricts itself to
-`**/*.cff.js`. The rest of your config still applies everywhere else.
+`@kensio/yulin/eslint` exports a flat config. Spread it into your config after any general rules it
+needs to override:
 
 ```typescript cff-js2-eslint-config
 /**
@@ -38,18 +31,15 @@ export default defineConfig(
 );
 ```
 
-It goes after any config whose rules it needs to turn off. That is a short list. `const`, `let`,
-template literals, arrow functions, rest parameters and `async`/`await` all work in JS2, and the
-rules asking for them stay on. Only `object-shorthand` is switched off, because shorthand property
-names are ES 6 literal syntax the runtime lacks.
+The config keeps rules for syntax that JS2 supports, including `const`, `let`, template literals,
+arrow functions, rest parameters, and `async`/`await`. It switches off `object-shorthand` because
+JS2 does not support shorthand property names.
 
-`eslint` and `typescript-eslint` are optional peer dependencies, needed only if you use this export.
+Install the optional `eslint` and `typescript-eslint` peer dependencies when you use this export.
 
 ## Setting it up with Oxlint
 
-`@kensio/yulin/oxlint` ships the same rules as an Oxlint config fragment to extend. The rules
-themselves are one plugin loaded by both linters. The two configs report the same things in the same
-places.
+Extend Yulin's generated Oxlint config by its path in `node_modules`:
 
 ```json
 {
@@ -60,16 +50,14 @@ places.
 }
 ```
 
-Oxlint's `extends` takes a file path rather than a package name. The path into `node_modules` is
-written out in full. The file sits in the package root. A build that moves what it emits under
-`dist/` leaves the path alone. The fragment brings its own `overrides` entry scoped to `**/*.cff.js`
-and the JS plugin the rules live in, and leaves every other file to your own rules.
+Oxlint's `extends` setting takes a file path. The fragment loads Yulin's JavaScript plugin and scopes
+its rules to `**/*.cff.js`. Your own rules continue to apply to other files.
 
-The plugin is loaded through Oxlint's JS plugin support, which needs Oxlint 1.77 or later.
+This config requires Oxlint 1.77 or later because it uses JavaScript plugin support.
 
 ## What is reported
 
-Each restriction is its own rule, under the `cff-js2` name in both linters.
+Both configs load the same rules under the `cff-js2` name:
 
 | Rule                            | What it refuses                                          |
 | ------------------------------- | -------------------------------------------------------- |
@@ -83,20 +71,16 @@ Each restriction is its own rule, under the `cff-js2` name in both linters.
 | `cff-js2/no-for-of`             | `for...of`, in favour of an index-based loop             |
 | `cff-js2/no-unavailable-global` | Globals the runtime does not have, such as `fetch`       |
 
-`cff-js2/no-unavailable-global` covers three groups. `fetch`, `XMLHttpRequest` and `WebSocket` need
-a network the runtime lacks. `process` needs Node.js. `setTimeout`, `setInterval`, `setImmediate`
-and `clearTimeout` need an event loop a Function never gets. The rule resolves names through scope
-rather than matching them as text, and a local variable named `fetch` or a property named
-`event.fetch` is left alone. Each report says why the global is missing, because `fetch` being
-absent for want of a network and `setTimeout` for want of an event loop call for different rewrites.
+`cff-js2/no-unavailable-global` reports browser network APIs such as `fetch`, Node.js globals such as
+`process`, and timer functions such as `setTimeout`. It resolves variables through JavaScript scope.
+A local variable named `fetch` and a property such as `event.fetch` are allowed.
 
-Alongside these, both configs turn on `no-eval`, `no-new-func` and `no-implied-eval`, which the
-runtime refuses outright. They also set `no-unused-vars` to leave `handler` alone, since it is the
-entry point CloudFront calls.
+The configs also enable `no-eval`, `no-new-func`, and `no-implied-eval`. Their `no-unused-vars`
+setting ignores the exported `handler` function because CloudFront calls it as the entry point.
 
-## What is not reported
+## Supported JS2 syntax
 
-These all work in JS2 and no rule here objects to them:
+The configs allow these JS2 features:
 
 - Template literals, including interpolation and nesting
 - Arrow functions and rest parameters
@@ -110,7 +94,7 @@ These all work in JS2 and no rule here objects to them:
 
 ## Turning one restriction off
 
-Rules are individual. A restriction you disagree with can be switched off on its own. In ESLint:
+You can switch off one restriction without disabling the rest. For ESLint:
 
 ```typescript cff-js2-eslint-relax
 /**
@@ -129,7 +113,7 @@ export default defineConfig(...cloudFrontFunctionsJs2, {
 });
 ```
 
-In Oxlint, the same thing goes in an `overrides` entry after the `extends`:
+For Oxlint, add an `overrides` entry after `extends`:
 
 ```json
 {
@@ -147,30 +131,20 @@ In Oxlint, the same thing goes in an `overrides` entry after the `extends`:
 
 ## Available functionality
 
-- A flat ESLint config at `@kensio/yulin/eslint`, exported as `cloudFrontFunctionsJs2`
-- An Oxlint config fragment at `cffjs2.oxlintrc.json` in the package root, with the object it is
-  generated from exported as `cloudFrontFunctionsJs2Oxlint` from `@kensio/yulin/oxlint`
-- Nine `cff-js2` rules, one per restriction, shared by both linters
-- Scoping to `**/*.cff.js`, leaving a repository's own rules untouched elsewhere
+- `@kensio/yulin/eslint` exports the `cloudFrontFunctionsJs2` flat config.
+- `cffjs2.oxlintrc.json` in the package root contains the Oxlint config. The source object is exported
+  as `cloudFrontFunctionsJs2Oxlint` from `@kensio/yulin/oxlint`.
+- Both configs enable nine `cff-js2` rules and scope them to `**/*.cff.js`.
 
 ## Limitations
 
-Where the configs knowingly stop short:
-
-- **`async` arguments and closures are not checked.** JS2 supports `async` and `await`, but not
-  `async` arguments or closures, and `await` only inside an `async` function. Where the runtime's
-  wording stops short of saying exactly which forms those are, no rule guesses at it. A Function can
-  pass the lint and still be refused for one.
-- **The list of unavailable globals is the useful part of one, not all of it.** It names what test
-  code and Node habits reach for. A global outside that list goes unreported, even if JS2 lacks it.
-- **The rules are syntactic.** Nothing here knows CloudFront's size limit on Function code or its CPU
-  budget. A Function that passes the lint can still be refused at publication for being too large or
-  too slow. No rule checks which methods of a supported built-in you call either, and the runtime
-  supports only some of them.
-- **Only the `cff-js2` rules are shared between the linters.** ESLint and Oxlint each bring their own
-  built-in rules, and their own defaults for which are on. A `.cff.js` file linted by both may pick
-  up findings from one that the other lacks.
-- **Oxlint's JS plugin support is in alpha.** It is what loads these rules into Oxlint, and its API
-  is still moving upstream.
-- **The Oxlint fragment is extended by path.** Oxlint has no package-name resolution in `extends`.
-  The written-out path into `node_modules` depends on your installer's layout.
+- The rules do not check the JS2 restrictions on `async` arguments and closures. They also do not
+  check that `await` appears only inside an `async` function.
+- `cff-js2/no-unavailable-global` covers common browser, Node.js, and timer globals. Other globals
+  missing from JS2 may go unreported.
+- The rules do not check CloudFront's function size or CPU limits. They also do not validate every
+  method on each supported built-in.
+- ESLint and Oxlint have different built-in rules. Only the `cff-js2` rules are shared.
+- Oxlint's JavaScript plugin support is in alpha and may change upstream.
+- Oxlint resolves the config through its path in `node_modules`. That path depends on the package
+  manager's installation layout.

package/docs/non-aws-dependencies/README.md

@@ -1,33 +1,20 @@
-# Non-AWS dependencies
+# Use non-AWS dependencies
 
-Most applications talk to something other than AWS, such as a Redis or a Postgres. This page covers
-what happens to those when the application runs under Yulin.
+Yulin leaves databases, caches, and other non-AWS dependencies under your control.
 
-## Two kinds of dependency
+## Pass connection details through environment variables
 
-A simulated Lambda function and a simulated ECS container both run your own code in the same Node.js
-process as the test. Everything that code talks to falls into one of two categories.
+A simulated Lambda function or ECS container runs in the same Node.js process as your test. AWS
+SDK calls can stay inside Yulin through [SDK interception](https://yulinsim.dev/sdk/). Calls to
+other libraries work normally.
 
-Simulated AWS services are handled by Yulin. A DynamoDB call reaches an in-memory table and an S3
-call reaches an in-memory bucket, with no network involved. [AWS SDK interception](https://yulinsim.dev/sdk/)
-is how an ordinary SDK client in the code under test gets there.
-
-Everything else is yours to provide, and connects the way it normally would. Yulin leaves it alone
-entirely, with no simulation and no interception. Code that opens a Redis connection opens a real
-one, to whatever address it was given.
-
-## Pointing the code at your own dependency
-
-A deployed Lambda function or ECS container reads its connection details from environment variables.
-The simulated ones do the same. A function's `Environment.Variables` and a container definition's
-`environment` are visible through `process.env` while the code runs, so pointing the application
-somewhere else means setting the value it already reads. No Yulin feature is involved, and the code
-under test stays as it is.
+Configure those libraries through the same environment variables that you use in production. For
+example, a deployed function could receive an ElastiCache URL while a test receives a localhost
+URL:
 
 ```typescript non-aws-dependency-lambda
 /**
- * Pointing a simulated Lambda function at a dependency Yulin does not
- * simulate, alongside one it does.
+ * Giving a simulated Lambda function the address of an external dependency.
  */
 
 import { CreateFunctionCommand, InvokeCommand } from "@aws-sdk/client-lambda";
@@ -44,17 +31,12 @@ await lambda.createFunction(
     Role: "arn:aws:iam::111111111111:role/RatesRole",
     Environment: {
       Variables: {
-        // Simulated by Yulin, reached with no network involved.
         TABLE_NAME: "rates",
-        // Yours. A deployment points this at ElastiCache. A test points it
-        // at whatever it wants the code to talk to instead.
         CACHE_URL: "redis://127.0.0.1:6379",
       },
     },
     Code: {
       ZipFile: makeLambdaZipFileInput(() => ({
-        // Building a Redis client from the second value involves nothing of
-        // Yulin's. It is an ordinary environment variable read.
         tableName: process.env["TABLE_NAME"],
         cacheUrl: process.env["CACHE_URL"],
       })),
@@ -66,141 +48,56 @@ const output = await lambda.invoke(
   new InvokeCommand({ FunctionName: "rates" }),
 );
 
-if (output.Payload === undefined) throw new Error("No invoke Payload");
-// {"tableName":"rates","cacheUrl":"redis://127.0.0.1:6379"}
+if (output.Payload === undefined) throw new Error("No invoke payload");
+
 console.log(Buffer.from(output.Payload).toString());
+// {"tableName":"rates","cacheUrl":"redis://127.0.0.1:6379"}
 ```
 
-What that address points at is up to the test. A Redis running on localhost, one the test suite
-starts in a container, or a stand-in the test defines itself all work, because the application is
-doing what it always does with the value it is given.
-
-## A container reading from both
+`TABLE_NAME` identifies a simulated AWS resource. `CACHE_URL` points to a dependency supplied by
+the test. That dependency could be a local process, a test container, or an in-process
+implementation of the interface your application uses.
 
-The worked example below runs one simulated ECS container that writes to a simulated DynamoDB table
-and reads from a cache of its own. The two categories sit next to each other in the same handler and
-are configured the same way, through the container definition's `environment`.
+## Configure an ECS container in the same way
 
-The cache here is a stand-in defined by the example, and it works with no server running. A real
-client built from `CACHE_URL` would go in the same place.
+An ECS container binding reads the container definition's `environment` entries through
+`process.env` while its handler runs:
 
 ```typescript non-aws-dependency-ecs
 /**
- * A simulated ECS container writing to a simulated DynamoDB table and reading
- * from a cache of its own.
+ * Passing a cache URL to a simulated ECS container.
  */
 
-import {
-  CreateTableCommand,
-  DynamoDBClient,
-  GetItemCommand,
-  PutItemCommand,
-} from "@aws-sdk/client-dynamodb";
 import {
   CreateClusterCommand,
   RegisterTaskDefinitionCommand,
   RunTaskCommand,
 } from "@aws-sdk/client-ecs";
-import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
 
-import { SimSdk } from "@kensio/yulin/sdk";
-
-/**
- * Where the worker reads exchange rates from.
- *
- * A deployment builds a Redis client from the URL. This example stands one in,
- * so nothing has to be running for it to work.
- */
-class RateCache {
-  constructor(private readonly url: string) {}
-
-  rate(currency: string): Promise<string> {
-    console.log(`reading ${currency} from ${this.url}`);
-    // reading GBP from redis://127.0.0.1:6379
-    return Promise.resolve("1.27");
-  }
-}
+import { SimAws } from "@kensio/yulin";
 
-using simSdk = new SimSdk();
-const { simAws } = simSdk;
+const simAws = new SimAws();
 const ecs = simAws.ecs();
-
-simSdk.intercept(DynamoDBClient);
-
-await simAws.dynamoDb().createTable(
-  new CreateTableCommand({
-    TableName: "rates",
-    KeySchema: [{ AttributeName: "currency", KeyType: "HASH" }],
-    AttributeDefinitions: [{ AttributeName: "currency", AttributeType: "S" }],
-    BillingMode: "PAY_PER_REQUEST",
-  }),
-);
-
-const taskRole = await simAws.iam().createRole(
-  new CreateRoleCommand({
-    RoleName: "RatesTaskRole",
-    AssumeRolePolicyDocument: JSON.stringify({
-      Version: "2012-10-17",
-      Statement: {
-        Effect: "Allow",
-        Principal: { Service: "ecs-tasks.amazonaws.com" },
-        Action: "sts:AssumeRole",
-      },
-    }),
-  }),
-);
-
-await simAws.iam().putRolePolicy(
-  new PutRolePolicyCommand({
-    RoleName: "RatesTaskRole",
-    PolicyName: "WriteRates",
-    PolicyDocument: JSON.stringify({
-      Version: "2012-10-17",
-      Statement: {
-        Effect: "Allow",
-        Action: "dynamodb:PutItem",
-        Resource:
-          `arn:aws:dynamodb:${simAws.defaultRegionName}:` +
-          `${simAws.defaultAccountId}:table/rates`,
-      },
-    }),
-  }),
-);
+const connections: string[] = [];
 
 await ecs.createCluster(new CreateClusterCommand({}));
 
 ecs.bindContainer({
   family: "rates-worker",
   containerName: "app",
-  run: async () => {
-    // Both reads happen inside the handler, so they see the container's own
-    // variables rather than the test process's.
-    const cache = new RateCache(process.env["CACHE_URL"] ?? "");
-    const rate = await cache.rate("GBP");
-
-    await new DynamoDBClient({}).send(
-      new PutItemCommand({
-        TableName: process.env["TABLE_NAME"],
-        Item: { currency: { S: "GBP" }, rate: { S: rate } },
-      }),
-    );
+  run: () => {
+    connections.push(process.env["CACHE_URL"] ?? "");
   },
 });
 
 await ecs.registerTaskDefinition(
   new RegisterTaskDefinitionCommand({
     family: "rates-worker",
-    taskRoleArn: taskRole.Role.Arn,
     containerDefinitions: [
       {
         name: "app",
         image: "rates-worker:1",
-        environment: [
-          // Simulated by Yulin, reached with no network involved.
-          { name: "TABLE_NAME", value: "rates" },
-          // Yours, connected to the way it normally would be.
-          { name: "CACHE_URL", value: "redis://127.0.0.1:6379" },
-        ],
+        environment: [{ name: "CACHE_URL", value: "redis://127.0.0.1:6379" }],
       },
     ],
   }),
@@ -209,53 +106,60 @@ await ecs.registerTaskDefinition(
 await ecs.runTask(new RunTaskCommand({ taskDefinition: "rates-worker" }));
 await simAws.backgroundTasksComplete();
 
-const stored = await simAws.dynamoDb().getItem(
-  new GetItemCommand({
-    TableName: "rates",
-    Key: { currency: { S: "GBP" } },
-  }),
-);
-
-console.log(stored.Item?.["rate"]?.S); // "1.27"
+console.log(connections); // ["redis://127.0.0.1:6379"]
 ```
 
-The DynamoDB write is authorized as the task role, in the same way it would be in a deployment. The
-cache read passes through no authorization at all, because IAM has no part in it.
+The host environment remains available unless the container overrides a variable. ECS task
+overrides and simulated Secrets Manager or SSM values are also applied before the handler runs.
+See the [ECS guide](https://yulinsim.dev/services/ecs/) for the full precedence rules.
 
-## Sidecar containers are not started
+## Run the dependency yourself
 
-A task definition sometimes declares the dependency itself as a second container, such as a Redis
-running next to the application in the same task. Yulin never looks inside a container image, and
-the only thing it can run is JavaScript or TypeScript in its own process. An image holding a Redis
-server is beyond it.
+Your test or development script starts and stops the server named by a connection string.
 
-The container is stored and reported back as declared, and it is recorded as not simulated when the
-task runs, with a reason saying so. An application expecting it has to be given something else to
-talk to. Set the variable holding the address to something that answers, whether that is a Redis you
-run yourself or a stand-in, in the same way as for any other dependency of your own.
+This also applies to ECS sidecars. Yulin stores every container definition, but it only runs a
+container that has a JavaScript or TypeScript binding. It cannot run a Redis or database image. An
+unbound sidecar is recorded as unsimulated when the task runs.
 
-## Reads happen inside the handler
+Point the application container at a dependency that is available to the host process. A localhost
+address often works because the simulated container runs in that process, without a separate
+container network.
 
-Handler code gets the function's or the container's variables while it runs, and reads the host
-process environment otherwise. A read at module scope, as in `const url = process.env.CACHE_URL` at
-the top of a file, happens when the test imports that file rather than when the code runs. It sees
-the host value.
+## Read environment variables while the handler runs
 
-That matters here because a connection is often built at module scope. Read inside the handler, or
-build the client there, to get the configured value. Sim Lambda warns on the console when the
-difference changes what the code sees, which is covered under
-[environment variables](https://yulinsim.dev/services/lambda/#environment-variables) on the simulated Lambda
-page. Zip code running in the vm runtime is unaffected, because it is imported during an invocation.
+Referenced Lambda handlers and ECS bindings come from modules already imported by the test. A
+module-level read happens during that import:
 
-## Limitations
+```typescript
+const cacheUrl = process.env["CACHE_URL"];
+```
+
+That value comes from the host environment. Read the variable inside the handler when it must come
+from the simulated function or container configuration:
+
+```typescript
+async function handler(): Promise<void> {
+  const cacheUrl = process.env["CACHE_URL"];
+  // Build or call the dependency here.
+}
+```
 
-Current documented limitations:
+Simulated Lambda prints a warning when a declared value conflicts with a value that module-level
+code could have read. Lambda code loaded from a zip archive is imported during its first invocation
+and sees the function environment at module scope.
+
+## Available functionality
+
+- Lambda `Environment.Variables` are applied during an invocation.
+- ECS container `environment`, `secrets`, and task overrides are applied during a container run.
+- Host environment variables remain available for names left out of the workload configuration.
+- AWS SDK interception continues to work from code that also uses external dependencies.
+
+## Limitations
 
-- Everything outside the simulated AWS services is yours to run and to tear down. Yulin starts none
-  of it.
-- A dependency declared as a sidecar container in an ECS task definition is not started, because
-  Yulin never runs a container image.
-- A connection built at module scope reads the host environment rather than the function's or the
-  container's, since the value is read before anything runs.
-- There is no interception point for a non-AWS dependency. The way to send the code somewhere else
-  is the environment variable it already reads, or an injection point in the code itself.
+- Yulin does not create, start, reset, or stop non-AWS dependencies.
+- Unbound ECS sidecar images are stored but never run.
+- Referenced handlers and container bindings read the host value when they access `process.env` at
+  module scope.
+- Yulin has no interception API for non-AWS clients. Configure the client through your application's
+  existing environment variables or dependency injection point.