@kensio/yulin 1.20.15 → 1.20.17

package/docs/cli/README.md

@@ -0,0 +1,284 @@
+# AWS CLI
+
+The real `aws` CLI reaches a served simulated environment over a local endpoint URL, and twenty of
+Yulin's twenty-five SDK-facing services answer it.
+
+[Serving on localhost](https://yulinsim.dev/serve/) is the reference for what each service serves. This page
+covers the way in from a shell.
+
+## An endpoint and a key to sign with
+
+Serving binds a simulated environment to a port. A served request runs as whoever signed it, and the
+access key to sign the first one comes from simulated IAM in the process that built the environment:
+
+```typescript sim-cli-endpoint
+/**
+ * Serving a simulated environment for the aws CLI to reach.
+ */
+
+import {
+  CreateAccessKeyCommand,
+  CreateUserCommand,
+  PutUserPolicyCommand,
+} from "@aws-sdk/client-iam";
+import { SimAws } from "@kensio/yulin";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const simIam = simAws.iam();
+
+await simIam.createUser(new CreateUserCommand({ UserName: "Operator" }));
+await simIam.putUserPolicy(
+  new PutUserPolicyCommand({
+    UserName: "Operator",
+    PolicyName: "Everything",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: { Effect: "Allow", Action: "*", Resource: "*" },
+    }),
+  }),
+);
+const created = await simIam.createAccessKey(
+  new CreateAccessKeyCommand({ UserName: "Operator" }),
+);
+
+const srv = await serveSimAws({ simAws, port: 8787 });
+
+// Paste these into the shell the CLI runs in.
+console.log(`export AWS_ENDPOINT_URL=http://localhost:${srv.port}`);
+console.log(`export AWS_ACCESS_KEY_ID=${created.AccessKey.AccessKeyId}`);
+console.log(
+  `export AWS_SECRET_ACCESS_KEY=${created.AccessKey.SecretAccessKey}`,
+);
+console.log(`export AWS_DEFAULT_REGION=${simAws.defaultRegionName}`);
+```
+
+Pin the port when the URL has to stay the same between runs. Without one the server takes whatever
+is free.
+
+## Configuring the CLI
+
+Four environment variables are the whole configuration:
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:8787
+export AWS_ACCESS_KEY_ID=AKIAVEXOWARWMKBOA0MP
+export AWS_SECRET_ACCESS_KEY=RzIvKRp1sd5yXfEifA1twsUTd4GlHL5JpzvECpox
+export AWS_DEFAULT_REGION=us-east-1
+```
+
+`sts get-caller-identity` is the call to check the wiring with. It reports the principal behind the
+key that signed the request:
+
+```bash
+aws sts get-caller-identity
+{
+    "UserId": "AIDARNFLISEC7SCUNSDY",
+    "Account": "888888888888",
+    "Arn": "arn:aws:iam::888888888888:user/Operator"
+}
+```
+
+The credentials have to come from simulated IAM. Any other key is refused with `403 Forbidden`, and
+an unsigned request reaches nothing.
+
+A Region is required, as it is against real AWS. Changing it moves the CLI between simulated
+Regions, and a Queue created under `eu-west-2` is invisible to `AWS_DEFAULT_REGION=us-east-1`.
+
+### A named profile instead
+
+A profile in the CLI's own config file carries the same four values. The simulation then stays out
+of the ambient environment:
+
+```ini
+[profile sim]
+region = us-east-1
+endpoint_url = http://localhost:8787
+aws_access_key_id = AKIAVEXOWARWMKBOA0MP
+aws_secret_access_key = RzIvKRp1sd5yXfEifA1twsUTd4GlHL5JpzvECpox
+```
+
+`aws --profile sim sts get-caller-identity` then reaches the simulation while a bare `aws` still
+goes to real AWS. The profile has to carry credentials of its own. Once `--profile` is given the CLI
+stops reading `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` from the environment.
+
+`role_arn` and `source_profile` work too. The CLI assumes the simulated Role for itself and signs
+with the session it gets back:
+
+```ini
+[profile reader]
+region = us-east-1
+endpoint_url = http://localhost:8787
+role_arn = arn:aws:iam::888888888888:role/Reader
+source_profile = sim
+```
+
+## Building the rest of the identities from the shell
+
+Only the first key has to come from the process that built the simulation. `aws iam` builds
+everything after it:
+
+```bash
+aws iam create-user --user-name shopper
+aws iam put-user-policy --user-name shopper --policy-name read-buckets \
+  --policy-document '{"Version":"2012-10-17","Statement":{"Effect":"Allow","Action":"s3:ListAllMyBuckets","Resource":"*"}}'
+aws iam create-access-key --user-name shopper
+```
+
+`create-access-key` answers with the secret once. Signing with the new key reports the new User, and
+simulated IAM authorizes every request against the policy it was given:
+
+```bash
+aws s3api create-bucket --bucket nope
+
+aws: [ERROR]: An error occurred (AccessDenied) when calling the CreateBucket operation: User:
+arn:aws:iam::888888888888:user/shopper is not authorized to perform: s3:CreateBucket on resource:
+arn:aws:s3:::nope
+```
+
+`aws sts assume-role` answers with temporary credentials. Export the three values it returns and the
+rest of the session runs as the Role:
+
+```bash
+aws sts assume-role --role-arn arn:aws:iam::888888888888:role/Reader --role-session-name probe
+export AWS_ACCESS_KEY_ID=ASIAKBEUIHDMON9VBZXF
+export AWS_SECRET_ACCESS_KEY=jm2N56vfVtLgJEo11OtbIXbgnJBgxpUMrszPrQdl
+export AWS_SESSION_TOKEN=11568oBDksY9czECUMiAWk9tzmvG7zlQNjtLI1WmhZFS...
+```
+
+The expiry is stamped from the simulation's own clock, and
+[advancing it](https://yulinsim.dev/time/) past the expiry stops the session authenticating.
+
+## What answers
+
+Twenty simulated services answer the endpoint. S3, STS, IAM, ELBv2, SNS, CloudFormation and Lambda,
+along with the AWS JSON protocol services: DynamoDB, DynamoDB Streams, SQS, Cognito Identity
+Provider, EventBridge, ECS, SSM, ACM, CloudWatch, CloudWatch Logs, KMS, Secrets Manager and
+Rekognition.
+
+A quick tour of the ones a shell reaches for most:
+
+```bash
+aws s3 cp ./index.html s3://widgets/index.html
+aws s3 sync ./site s3://widgets/site/
+aws dynamodb put-item --table-name widgets --item '{"id":{"S":"w1"}}'
+aws sqs create-queue --queue-name orders
+aws ssm get-parameter --name /shop/url --query 'Parameter.Value' --output text
+aws secretsmanager get-secret-value --secret-id shop/db --query SecretString --output text
+aws logs describe-log-groups --query 'logGroups[].logGroupName' --output text
+```
+
+`--query`, `--output text` and the rest of the CLI's own machinery work throughout, because they run
+client-side over an ordinary AWS response.
+
+[The serve docs](https://yulinsim.dev/serve/#which-services-answer) list the operations each service
+implements. Anything outside those lists is refused as `NotImplemented`.
+
+## CLI traps
+
+Each of these is CLI behaviour, and each catches people out against real AWS too. They are collected
+here because a simulated endpoint is often where someone meets them first.
+
+### `--payload` needs `--cli-binary-format`
+
+CLI v2 reads `--payload` as base64 by default:
+
+```bash
+aws lambda invoke --function-name orders --payload '{"id":1}' out.json
+
+aws: [ERROR]: Invalid base64: "{"id":1}"
+```
+
+Pass `--cli-binary-format raw-in-base64-out` and the same call runs the function:
+
+```bash
+aws lambda invoke --function-name orders --payload '{"id":1}' \
+  --cli-binary-format raw-in-base64-out out.json
+cat out.json
+```
+
+`--invocation-type Event` answers `202` and runs the handler on the background scheduler. A script
+reading what the function did waits on `simAws.backgroundTasksComplete()` first.
+
+### S3 addressing style
+
+The CLI needs nothing here. Its default `auto` style sends path-style requests to a custom endpoint,
+which is what this endpoint routes. An SDK client is the one that needs `forcePathStyle: true`.
+
+Forcing `addressing_style = virtual` in the config file breaks it. The Bucket moves into a hostname
+the endpoint has no route for, and `list-objects-v2` comes back empty while `head-object` comes back
+`404`.
+
+### `aws cloudformation deploy` uses change sets
+
+`deploy` is a CLI-side wrapper over `CreateChangeSet`, and simulated CloudFormation implements four
+operations that do not include it:
+
+```bash
+aws cloudformation deploy --stack-name site --template-file template.json
+
+aws: [ERROR]: An error occurred (NotImplemented) when calling the CreateChangeSet operation:
+Simulated CloudFormation does not serve CreateChangeSet
+```
+
+`create-stack` and `describe-stacks` do work. A deployment starts in the background and
+`create-stack` is answered before the Resources exist, as real CloudFormation answers it.
+
+### Presigning needs the S3 service hostname
+
+`aws s3 presign` signs whatever endpoint the CLI is configured with, and a URL built over the
+general endpoint has no Bucket in it for the endpoint to route on. Point the one command at
+simulated S3's own hostname on the served port:
+
+```bash
+aws --endpoint-url http://s3.us-east-1.sim-aws.localhost:8787 s3 presign s3://widgets/one.txt
+```
+
+The URL that comes back is fetchable by anything, including `curl` and a browser. The same hostname
+serves [presigned URLs built by the SDK](https://yulinsim.dev/services/s3/#presigned-urls).
+
+### A bad key looks like an XML parse failure
+
+STS, IAM and ELBv2 speak the AWS Query protocol and expect an XML body. The endpoint answers a
+rejected signature as JSON. The CLI reports the body it could not parse:
+
+```bash
+aws sts get-caller-identity
+
+aws: [ERROR]: Unable to parse response (not well-formed (invalid token): line 1, column 0), invalid
+XML received. Further retries may succeed:
+b'{"Message":"Forbidden"}'
+```
+
+`Forbidden` in the quoted body is the real answer. The other seventeen services report the same
+rejection as a plain `403`.
+
+## Limitations
+
+- Five services are refused with `501 Not Implemented`. Route 53 and CloudFront speak REST-XML, and
+  API Gateway v2, SES v2 and EventBridge Scheduler speak REST-JSON. Every one of them is reachable
+  in process through `SimAws` and through [SDK interception](https://yulinsim.dev/sdk/). Simulated ECR is
+  refused the same way and has no AWS API surface at all, since its images are registered in
+  process.
+- An operation a served service has not implemented is refused as `NotImplemented`. That is a
+  separate answer from the protocol refusal above. `aws iam list-users` reports
+  `Simulated IAM does not serve ListUsers`, and `aws lambda list-functions` names the path it
+  arrived at.
+- `aws cloudwatch get-metric-statistics` and `aws cloudwatch get-metric-data` fail with
+  `TypeError: time.getTime is not a function`. The JSON protocol carries a timestamp as epoch
+  seconds and the endpoint hands that number to the simulation where a `Date` is expected. Both
+  reads work in process and through SDK interception. `put-metric-data` and `list-metrics` are
+  unaffected.
+- `aws s3 cp` and `aws s3 sync` corrupt a **download** above the CLI's 8MB threshold
+  ([#717](https://github.com/KensioSoftware/yulin/issues/717)). The CLI splits
+  the download into ranged GETs, simulated S3 ignores `Range` and returns the whole Object for each
+  one, and the parts land on top of each other. A 12MB Object arrives as a 20MB file. Uploads above
+  the threshold are fine, and so is any download under it. Two ways round it, both verified.
+  `aws s3api get-object` issues one unranged GET. Raising the threshold in the config file keeps
+  `aws s3 cp` on a single GET too.
+
+  ```ini
+  [profile sim]
+  s3 =
+    multipart_threshold = 5GB
+  ```

package/docs/factories/README.md

@@ -0,0 +1,140 @@
+# Event factories
+
+A handler is invoked with an event, and a test of a handler has to produce one. The events AWS
+delivers are large, most of each one is fields the handler never reads, and the two or three the
+test is about are buried in them. Written out by hand, that literal is copied between files and
+drifts.
+
+Yulin exports [`@kensio/part-factory`](https://partfactory.dev/) factories for those event shapes. A
+test made with one says what the request or the message was and leaves the rest of the event alone.
+They are ordinary factories, made in-process, and they need no `SimAws` instance and no simulated
+service running. A handler test that runs without a simulator is who they are for. A test that does want
+one (a Function URL served over HTTP, a queue with a real event source mapping) gets its events from
+the simulator, and these factories make the same shapes that simulator delivers.
+
+## What is exported
+
+| Factory                                                                       | Import                       | Event                               |
+| ----------------------------------------------------------------------------- | ---------------------------- | ----------------------------------- |
+| `lambdaFunctionUrlEventFactory`                                               | `@kensio/yulin/lambda`       | A Lambda Function URL invocation    |
+| `lambdaSqsEventFactory`, `lambdaSqsEventRecordFactory`                        | `@kensio/yulin/lambda`       | An SQS event source mapping's batch |
+| `lambdaDynamoDbStreamEventFactory`, `lambdaDynamoDbStreamEventRecordFactory`  | `@kensio/yulin/lambda`       | A DynamoDB stream mapping's batch   |
+| `httpApiProxyEventFactory`                                                    | `@kensio/yulin/apigatewayv2` | An HTTP API `AWS_PROXY` invocation  |
+| `s3NotificationEventFactory`, `s3NotificationEventRecordFactory`              | `@kensio/yulin/s3`           | An S3 event notification            |
+| `cloudFrontViewerRequestEventFactory`, `cloudFrontViewerResponseEventFactory` | `@kensio/yulin/cloudfront`   | A CloudFront Functions event        |
+
+Each service's own documentation covers what its events mean. This page is about how the factories
+are shaped and what they have in common.
+
+## One factory per shape, and one per record
+
+An event that carries a list of records has two factories, one for a record and one for the event
+around it. The record factory makes one record, and the event factory completes as many records as
+the test asks for.
+
+```typescript factories-records-and-events
+/**
+ * Making the SQS event a batch of messages arrives in.
+ */
+
+import {
+  lambdaSqsEventFactory,
+  lambdaSqsEventRecordFactory,
+  type SimLambdaSqsEvent,
+} from "@kensio/yulin/lambda";
+
+function ordersHandler(event: SimLambdaSqsEvent): readonly string[] {
+  return event.Records.map(
+    (record) => (JSON.parse(record.body) as { orderId: string }).orderId,
+  );
+}
+
+// One record, for a test about a single message.
+const record = lambdaSqsEventRecordFactory.make({
+  body: '{"orderId":"YL-1"}',
+});
+
+// [ 'YL-1' ]
+console.log(ordersHandler({ Records: [record] }));
+
+// A batch, saying only what each message carries. Everything else about each
+// record — its message id, its receipt handle, the digest of its body — is
+// filled in as a delivered record's is.
+const event = lambdaSqsEventFactory.make({
+  Records: [{ body: '{"orderId":"YL-1"}' }, { body: '{"orderId":"YL-2"}' }],
+});
+
+// [ 'YL-1', 'YL-2' ]
+console.log(ordersHandler(event));
+```
+
+The event factory exists so a test can pass partial records like that. A `DynamicFactory` whose
+defaults hold one record would not manage it. Overrides are merged onto defaults, and merging
+replaces a list whole rather than element by element. A partial record passed that way would reach
+the handler as the only thing in those records, typed as a complete one and missing every field the
+handler reads.
+
+## Named variations
+
+Every factory here is an `ItemFactory`. A variation with a name is a `VariantFactory` around it, the
+same as for any other `part-factory` factory. That is usually the tidiest way to describe the kind
+of request or message one application receives:
+
+```typescript factories-variants
+/**
+ * Naming the variations of an event an application receives.
+ */
+
+import { VariantFactory } from "@kensio/part-factory";
+
+import { httpApiProxyEventFactory } from "@kensio/yulin/apigatewayv2";
+import { s3NotificationEventFactory } from "@kensio/yulin/s3";
+
+const signedInRequestFactory = new VariantFactory(httpApiProxyEventFactory, {
+  requestContext: {
+    authorizer: { jwt: { claims: { sub: "YL-1" }, scopes: null } },
+  },
+});
+
+const request = signedInRequestFactory.make({ rawPath: "/account" });
+
+// GET /account YL-1
+console.log(
+  request.routeKey,
+  request.requestContext.authorizer?.jwt?.claims["sub"],
+);
+
+const objectRemovedFactory = new VariantFactory(s3NotificationEventFactory, {
+  Records: [{ eventName: "ObjectRemoved:Delete" }],
+});
+
+const removal = objectRemovedFactory.make();
+
+// ObjectRemoved:Delete undefined
+console.log(
+  removal.Records[0]?.eventName,
+  // A removal reports no size, because the Object is gone.
+  removal.Records[0]?.s3.object.size,
+);
+```
+
+## Events that agree with themselves
+
+A real AWS event says the same thing in more than one field, and those copies are where a
+hand-written literal goes wrong. It asks for `/user/status` and leaves the request context saying
+`/`, or gives an SQS record the digest of some other body, or reports a DynamoDB insert on a record
+that carries an old image.
+
+Each factory's defaults are computed from the overrides, so supplying either copy settles the other.
+What that covers is listed in each factory's own documentation, and in outline it is:
+
+- **Function URL and HTTP API events** — the path, the query, the route key, the endpoint's id,
+  hostname and `host` header, the caller's user agent and address, and the invocation time
+- **SQS records** — the digest of the body, and the Region of the queue ARN
+- **DynamoDB stream records** — the images the reported change would carry, the view type naming
+  the images that are there, and the Region of the stream ARN
+- **S3 notification records** — the ARN of the Bucket named, and whether the Object still exists to
+  have a size and an eTag
+
+Overriding both copies of one of those with different values is still allowed. A test that wants an
+event no real invocation would produce is entitled to one. It just has to ask for it twice.

package/docs/lint/README.md

@@ -0,0 +1,176 @@
+# Linting CFF JS2
+
+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.
+
+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.
+
+## 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.
+
+```typescript cff-js2-eslint-config
+/**
+ * An ESLint config that lints CloudFront Function files as JS2.
+ */
+
+import eslint from "@eslint/js";
+import { defineConfig } from "eslint/config";
+
+import { cloudFrontFunctionsJs2 } from "@kensio/yulin/eslint";
+
+export default defineConfig(
+  eslint.configs.recommended,
+
+  // Applies only to **/*.cff.js, so it goes after the configs it relaxes.
+  ...cloudFrontFunctionsJs2,
+);
+```
+
+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.
+
+`eslint` and `typescript-eslint` are optional peer dependencies, needed only if 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.
+
+```json
+{
+  "extends": ["./node_modules/@kensio/yulin/cffjs2.oxlintrc.json"],
+  "rules": {
+    "no-console": "error"
+  }
+}
+```
+
+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.
+
+The plugin is loaded through Oxlint's JS plugin support, which needs Oxlint 1.77 or later.
+
+## What is reported
+
+Each restriction is its own rule, under the `cff-js2` name in both linters.
+
+| Rule                            | What it refuses                                          |
+| ------------------------------- | -------------------------------------------------------- |
+| `cff-js2/no-import`             | `import` declarations, apart from `cloudfront`           |
+| `cff-js2/only-handler-export`   | Any export other than `export function handler(...)`     |
+| `cff-js2/only-built-in-require` | Requiring anything but `querystring`, `crypto`, `buffer` |
+| `cff-js2/no-class`              | Class declarations and expressions                       |
+| `cff-js2/no-generator`          | Generators and `yield`                                   |
+| `cff-js2/no-destructuring`      | Object and array destructuring                           |
+| `cff-js2/no-spread`             | Spread syntax, but not rest parameters                   |
+| `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.
+
+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.
+
+## What is not reported
+
+These all work in JS2 and no rule here objects to them:
+
+- Template literals, including interpolation and nesting
+- Arrow functions and rest parameters
+- `const` and `let`
+- `async` and `await`
+- `Promise`, including `all`, `allSettled`, `any` and `race`
+- `Buffer`, and `require` of `querystring`, `crypto` or `buffer`
+- `import cf from "cloudfront"`, which a Function needs for `cf.kvs()` and
+  `cf.updateRequestOrigin()`
+- `String.prototype.replaceAll`, `atob`, `btoa` and numeric separators
+
+## Turning one restriction off
+
+Rules are individual. A restriction you disagree with can be switched off on its own. In ESLint:
+
+```typescript cff-js2-eslint-relax
+/**
+ * Allowing class syntax in CloudFront Function files.
+ */
+
+import { defineConfig } from "eslint/config";
+
+import { cloudFrontFunctionsJs2 } from "@kensio/yulin/eslint";
+
+export default defineConfig(...cloudFrontFunctionsJs2, {
+  files: ["**/*.cff.js"],
+  rules: {
+    "cff-js2/no-class": "off",
+  },
+});
+```
+
+In Oxlint, the same thing goes in an `overrides` entry after the `extends`:
+
+```json
+{
+  "extends": ["./node_modules/@kensio/yulin/cffjs2.oxlintrc.json"],
+  "overrides": [
+    {
+      "files": ["**/*.cff.js"],
+      "rules": {
+        "cff-js2/no-class": "off"
+      }
+    }
+  ]
+}
+```
+
+## 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
+
+## 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.