@checkdigit/eslint-plugin 7.18.0-PR.143-b6d4 → 7.18.0-PR.143-c222

package/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2021-2024 Check Digit, LLC
+Copyright (c) 2021-2026 Check Digit, LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1 +1 @@
-{"name":"@checkdigit/eslint-plugin","version":"7.18.0-PR.143-b6d4","description":"Check Digit eslint plugins","keywords":["eslint","eslintplugin"],"homepage":"https://github.com/checkdigit/eslint-plugin#readme","bugs":{"url":"https://github.com/checkdigit/eslint-plugin/issues"},"repository":{"type":"git","url":"https://github.com/checkdigit/eslint-plugin"},"license":"MIT","author":"Check Digit, LLC","sideEffects":false,"type":"module","exports":{".":{"types":"./dist-types/index.d.ts","import":"./dist-mjs/index.mjs","default":"./dist-mjs/index.mjs"}},"files":["src","dist-types","dist-mjs","!src/**/test/**","!src/**/*.test.ts","!src/**/*.spec.ts","!dist-types/**/test/**","!dist-types/**/*.test.d.ts","!dist-types/**/*.spec.d.ts","!dist-mjs/**/test/**","!dist-mjs/**/*.test.mjs","!dist-mjs/**/*.spec.mjs","SECURITY.md"],"scripts":{"build:dist-mjs":"rimraf dist-mjs && npx builder --type=module --sourceMap --outDir=dist-mjs && node dist-mjs/index.mjs","build:dist-types":"rimraf dist-types && npx builder --type=types --outDir=dist-types","ci:compile":"tsc --noEmit","ci:coverage":"NODE_OPTIONS=\"--disable-warning ExperimentalWarning --experimental-vm-modules\" jest --coverage=true","ci:lint":"npm run lint","ci:style":"npm run prettier","ci:test":"NODE_OPTIONS=\"--disable-warning ExperimentalWarning --experimental-vm-modules\" jest --coverage=false","lint":"eslint --max-warnings 0 .","lint:fix":"eslint --max-warnings 0 --fix .","peggy":"for file in ./src/peggy/*.peggy; do peggy \"$file\" --format es --output \"${file%.peggy}-peggy.ts\"; done","peggy-watch":"for file in ./src/peggy/*.peggy; do peggy \"$file\" --format=es --watch --output=\"${file%.peggy}-peggy.ts\"; done","prepare":"","prepublishOnly":"npm run build:dist-types && npm run build:dist-mjs","prettier":"prettier --ignore-path .gitignore --list-different .","prettier:fix":"prettier --ignore-path .gitignore --write .","test":"npm run ci:compile && npm run ci:test && npm run ci:lint && npm run ci:style"},"prettier":"@checkdigit/prettier-config","jest":{"preset":"@checkdigit/jest-config"},"dependencies":{"@apidevtools/json-schema-ref-parser":"^15.3.5","@typescript-eslint/type-utils":"^8.60.1","@typescript-eslint/utils":"^8.60.1","ajv":"^8.20.0","debug":"^4.4.3","glob":"^13.0.6","http-status-codes":"^2.3.0","js-yaml":"^4.2.0","json-pointer":"^0.6.2","jsonpath-plus":"^10.4.0","ts-api-utils":"^2.5.0"},"devDependencies":{"@checkdigit/jest-config":"^6.0.2","@checkdigit/prettier-config":"^6.1.0","@checkdigit/typescript-config":"10.0.0","@eslint/js":"^9.37.0","@types/debug":"^4.1.13","@types/eslint":"^9.6.1","@types/eslint-config-prettier":"^6.11.3","@types/js-yaml":"^4.0.9","@types/json-pointer":"^1.0.34","@typescript-eslint/parser":"^8.60.1","@typescript-eslint/rule-tester":"^8.60.1","eslint":"^9.37.0","eslint-config-prettier":"^10.1.8","eslint-import-resolver-typescript":"^4.4.5","eslint-plugin-eslint-plugin":"^6.4.0","eslint-plugin-import":"^2.32.0","eslint-plugin-no-only-tests":"^3.4.0","eslint-plugin-no-secrets":"^2.3.3","eslint-plugin-node":"^11.1.0","eslint-plugin-sonarjs":"^1.0.4","openapi-types":"^12.1.3","peggy":"^4.2.0","rimraf":"^6.1.3","typescript-eslint":"^8.60.1"},"peerDependencies":{"eslint":">=9 <10"},"engines":{"node":">=22.18"},"service":{"api":{"root":"src","endpoints":["api/v1"]}}}
+{"name":"@checkdigit/eslint-plugin","version":"7.18.0-PR.143-c222","description":"Check Digit eslint plugins","keywords":["eslint","eslintplugin"],"homepage":"https://github.com/checkdigit/eslint-plugin#readme","bugs":{"url":"https://github.com/checkdigit/eslint-plugin/issues"},"repository":{"type":"git","url":"https://github.com/checkdigit/eslint-plugin"},"license":"MIT","author":"Check Digit, LLC","sideEffects":false,"type":"module","exports":{".":{"types":"./dist-types/index.d.ts","import":"./dist-mjs/index.mjs","default":"./dist-mjs/index.mjs"}},"files":["src","dist-types","dist-mjs","!src/**/test/**","!src/**/*.test.ts","!src/**/*.spec.ts","!dist-types/**/test/**","!dist-types/**/*.test.d.ts","!dist-types/**/*.spec.d.ts","!dist-mjs/**/test/**","!dist-mjs/**/*.test.mjs","!dist-mjs/**/*.spec.mjs","SECURITY.md"],"scripts":{"build:dist-mjs":"rimraf dist-mjs && npx builder --type=module --sourceMap --outDir=dist-mjs && node dist-mjs/index.mjs","build:dist-types":"rimraf dist-types && npx builder --type=types --outDir=dist-types","ci:compile":"tsc --noEmit","ci:coverage":"NODE_OPTIONS=\"--disable-warning ExperimentalWarning --experimental-vm-modules\" jest --coverage=true","ci:lint":"npm run lint","ci:style":"npm run prettier","ci:test":"NODE_OPTIONS=\"--disable-warning ExperimentalWarning --experimental-vm-modules\" jest --coverage=false","lint":"eslint --max-warnings 0 .","lint:fix":"eslint --max-warnings 0 --fix .","peggy":"for file in ./src/peggy/*.peggy; do peggy \"$file\" --format es --output \"${file%.peggy}-peggy.ts\"; done","peggy-watch":"for file in ./src/peggy/*.peggy; do peggy \"$file\" --format=es --watch --output=\"${file%.peggy}-peggy.ts\"; done","prepare":"","prepublishOnly":"npm run build:dist-types && npm run build:dist-mjs","prettier":"prettier --ignore-path .gitignore --list-different .","prettier:fix":"prettier --ignore-path .gitignore --write .","test":"npm run ci:compile && npm run ci:test && npm run ci:lint && npm run ci:style"},"prettier":"@checkdigit/prettier-config","jest":{"preset":"@checkdigit/jest-config"},"dependencies":{"@apidevtools/json-schema-ref-parser":"^15.3.5","@typescript-eslint/type-utils":"^8.60.1","@typescript-eslint/utils":"^8.60.1","ajv":"^8.20.0","debug":"^4.4.3","glob":"^13.0.6","http-status-codes":"^2.3.0","js-yaml":"^4.2.0","json-pointer":"^0.6.2","jsonpath-plus":"^10.4.0","ts-api-utils":"^2.5.0"},"devDependencies":{"@checkdigit/jest-config":"^6.0.2","@checkdigit/prettier-config":"^6.1.0","@checkdigit/typescript-config":"10.0.0","@eslint/js":"^9.37.0","@types/debug":"^4.1.13","@types/eslint":"^9.6.1","@types/eslint-config-prettier":"^6.11.3","@types/js-yaml":"^4.0.9","@types/json-pointer":"^1.0.34","@typescript-eslint/parser":"^8.60.1","@typescript-eslint/rule-tester":"^8.60.1","eslint":"^9.37.0","eslint-config-prettier":"^10.1.8","eslint-import-resolver-typescript":"^4.4.5","eslint-plugin-eslint-plugin":"^6.4.0","eslint-plugin-import":"^2.32.0","eslint-plugin-no-only-tests":"^3.4.0","eslint-plugin-no-secrets":"^2.3.3","eslint-plugin-node":"^11.1.0","eslint-plugin-sonarjs":"^1.0.4","openapi-types":"^12.1.3","peggy":"^4.2.0","rimraf":"^6.1.3","typescript-eslint":"^8.60.1"},"peerDependencies":{"eslint":">=9 <10"},"engines":{"node":">=24.14.1"},"service":{"api":{"root":"src","endpoints":["api/v1"]}}}

package/src/athena/ATHENA.md

@@ -1,387 +0,0 @@
-# Athena Rule — Design & Implementation Reference
-
-## Purpose
-
-The `athena` ESLint rule validates AWS Athena SQL strings embedded in TypeScript source code (as template literals or string literals beginning with `SELECT` or `WITH`) against OpenAPI schemas at lint time. It catches references to non-existent response/request body properties before the query is ever run in production.
-
----
-
-## Trigger Conditions
-
-The rule is activated on:
-
-- **Template literals** — every `` `...` `` in the file is inspected; the quasis (the static parts between `${...}` interpolations) are joined and trimmed.
-- **String literals** — plain `'...'` or `"..."` strings are inspected if the value is a string type.
-
-In both cases the rule is a no-op unless the resulting string starts with `SELECT ` or `WITH ` (case-insensitive).
-
----
-
-## File Structure
-
-```
-src/athena/
-  athena.ts         Entry point: ESLint rule, SQL parse, checkAthenaAst
-  visitor.ts        VisitorMap interface, walk() dispatcher, type guards, extractors
-  context.ts        VisitContext, ResolvedTable, ResolvedColumn, context factories
-  service-table.ts  buildServiceTables() — maps MatchedOperation[] → ResolvedTable[]
-  api-locator.ts    locateApi() — finds swagger.schema.deref.json on disk
-  api-matcher.ts    matchApi() — filters OpenAPI operations by WHERE-clause conditions
-  types.ts          TypeScript types for the PEG parser AST (based on node-sql-parser)
-  athena.spec.ts    Integration tests via RuleTester
-  zzz.spec.ts       Unit tests for walk() and the extractor helpers
-  json.spec.ts      Dev scratch tests for JSONPath exploration (all skipped)
-  PLAN.md           Architecture planning document
-  ATHENA.md         This file
-```
-
----
-
-## End-to-End Data Flow
-
-```
-TypeScript source
-      │
-      │  TemplateLiteral / Literal ESLint visitor
-      ▼
-  sql: string   (quasis joined, interpolation placeholders stripped)
-      │
-      │  parse(sql, { includeLocations: true })  ← src/peggy/athena-peggy.ts
-      ▼
-  AST: Select | With[]...
-      │
-      │  checkAthenaAst(ast, ctx)
-      ▼
-  WITH items processed first (each CTE → checkSelect → ctx.tables)
-      │
-      │  checkSelect(select, ctx)
-      ▼
-  ┌────────────────────────────────────────────┐
-  │ Pass 1 — resolveFromClause                 │
-  │   BaseFrom nodes → locateApi + matchApi    │
-  │   → buildServiceTables → ctx.tables        │
-  │                                            │
-  │ UNNEST pre-pass — applyUnnestPre           │
-  │   source is a service-table column         │
-  │   → synthetic ctx.tables[name:<unnested>]  │
-  │                                            │
-  │ Pass 2 — resolveSelectColumns              │
-  │   for each SELECT column:                  │
-  │     extractColumnRefs → find ref           │
-  │     → lookup in ctx.tables                 │
-  │     → extractJsonExtractPath / bracket     │
-  │     → JSONPath into schema                 │
-  │                                            │
-  │ UNNEST post-pass — applyUnnestPost         │
-  │   source is a computed SELECT column       │
-  │                                            │
-  │ _next (UNION ALL) → recurse checkSelect    │
-  │                                            │
-  │ register result in ctx.tables[cteTableName]│
-  └────────────────────────────────────────────┘
-      │
-  AthenaError thrown → context.report(AthenaError)
-  parse error thrown → context.report(SyntextError)
-```
-
----
-
-## PEG Grammar
-
-The SQL is parsed by `src/peggy/athena.peggy`, a hand-written PEG grammar compiled to `src/peggy/athena-peggy.ts` via `npm run peggy` (`peggy --format es`). The grammar is an extension of the `node-sql-parser` grammar with Athena/Trino-specific syntax (MAP, ARRAY, TRY_CAST, UNNEST, bracket array access, etc.).
-
-The second grammar `src/peggy/athena-chat.peggy` is an experimental rewrite with a cleaner AST format; it is **not** used by the rule.
-
-The compiled parser's `parse(sql, opts)` returns `{ ast: AST | AST[] }`. When the input is a single statement the result is a single `Select` node; when there are multiple (e.g. `;`-separated) it is an array.
-
----
-
-## AST Node Shapes (relevant subset)
-
-All types are in `src/athena/types.ts`.
-
-| Shape                          | Key fields                                                                 |
-| ------------------------------ | -------------------------------------------------------------------------- |
-| `Select`                       | `type:'select'`, `with`, `columns`, `from`, `where`, `_next` (UNION chain) |
-| `With`                         | `name.value` (CTE name), `stmt.ast` (inner Select)                         |
-| `BaseFrom`                     | `table` (string), `as` (alias or null)                                     |
-| `Join` extends `BaseFrom`      | `join` (join type string), `on`                                            |
-| `TableExpr`                    | `expr.ast` (sub-Select), `as`                                              |
-| `UnnestFrom` (not in types.ts) | `type:'unnest'`, `expr` (ColumnRefItem), `as` (func_call alias)            |
-| `Column`                       | `type:'expr'`, `expr` (ExpressionValue), `as` (alias)                      |
-| `ColumnRefItem`                | `type:'column_ref'`, `table`, `column`, optionally `array_index`           |
-| `Function`                     | `type:'function'`, `name.name[0].value` (fn name), `args.value[]`          |
-| `Binary`                       | `type:'binary_expr'`, `operator`, `left`, `right`                          |
-| `Cast`                         | `type:'cast'`, `expr`, `target.dataType`                                   |
-| `Case`                         | `type:'case'`, `args[]` (when/else arms)                                   |
-
-`ColumnRefItem.array_index` is added by the parser for bracket access (`col['key']`); it is not in the TypeScript type definition and is accessed via the `ColumnRefWithIndex` interface in `visitor.ts`.
-
----
-
-## Visitor Pattern (`visitor.ts`)
-
-### `VisitorMap`
-
-An interface with optional typed hooks, one per AST node kind:
-
-```typescript
-interface VisitorMap {
-  visitSelect?(node: Select): void;
-  visitWith?(node: With): void;
-  visitBaseFrom?(node: BaseFrom): void;
-  visitJoin?(node: Join): void;
-  visitTableExpr?(node: TableExpr): void;
-  visitUnnest?(node: UnnestFrom): void;
-  visitColumn?(node: Column): void;
-  visitColumnRef?(node: ColumnRefItem): void;
-  visitFunction?(node: Function): void;
-  visitBinary?(node: Binary): void;
-  visitAggrFunc?(node: AggrFunc): void;
-  visitCast?(node: Cast): void;
-  visitCase?(node: Case): void;
-  visitExprList?(node: ExprList): void;
-  visitValue?(node: ExpressionValue): void;
-}
-```
-
-### `walk(node, visitor)`
-
-The main entry point. For a `Select` node it:
-
-1. Calls `visitSelect`
-2. Walks `with[]` items (calls `visitWith`, recurses into CTE body)
-3. Walks `from[]` items via `walkFrom`
-4. Walks `columns[]` items via `walkExpr`
-5. Walks `where` via `walkExpr`
-6. Walks `_next` (UNION) recursively via `walk`
-
-`walkFrom` dispatches to `visitUnnest`, `visitTableExpr` (+ recurses into subquery), `visitJoin`, or `visitBaseFrom` based on type guards.
-
-`walkExpr` handles expression-level nodes: `binary_expr`, `column_ref`, `function`, `aggr_func`, `cast`, `case`, `expr_list`, `expr` (column wrapper), or `visitValue` for literal/value nodes.
-
-### Type Guards
-
-All accept `unknown` input so callers don't need intermediate casts:
-
-| Guard                 | Identifies                                        |
-| --------------------- | ------------------------------------------------- |
-| `isUnnestFrom(node)`  | `type === 'unnest'`                               |
-| `isDual(node)`        | `type === 'dual'`                                 |
-| `isTableExpr(node)`   | has `expr.ast` sub-select                         |
-| `isJoin(node)`        | has `join` property, is not unnest/dual/tableExpr |
-| `isBaseFrom(node)`    | has `table` property, is none of the above        |
-| `hasArrayIndex(node)` | `ColumnRefItem` with `array_index[]`              |
-
-### Extractor Helpers
-
-These replace the ad-hoc JSONPath queries that appeared in the original monolith:
-
-| Helper                             | Returns                                                       |
-| ---------------------------------- | ------------------------------------------------------------- |
-| `extractColumnRefs(expr)`          | All `ColumnRefItem` nodes in the subtree                      |
-| `extractJsonExtractPath(expr)`     | Path arg of first `json_extract_scalar` / `json_extract` call |
-| `extractBracketAccessorPath(expr)` | `$["key"]` string from first bracket accessor (`col['key']`)  |
-| `hasFunctionCalls(expr)`           | `true` if any `function` or `aggr_func` node is present       |
-
----
-
-## Resolution Context (`context.ts`)
-
-```typescript
-interface VisitContext {
-  tables: Map<string, ResolvedTable[]>; // name → one entry per matched API operation
-  aliases: Map<string, string>; // alias → canonical table name
-  apiSchemas: Map<string, ApiSchemas[]>; // disk-read cache, shared across the whole query
-  parent?: VisitContext; // parent scope (currently stored but not queried)
-}
-```
-
-**`createRootContext()`** — creates an empty context for the top-level query.
-
-**`createChildContext(parent)`** — creates a child context that pre-populates `tables` from the parent (so CTE results defined in the `WITH` clause are visible to subsequent CTEs and the final `SELECT`). The `aliases` map is fresh (each SELECT has its own alias scope). The `apiSchemas` map is shared by reference.
-
-```typescript
-interface ResolvedTable {
-  name?: string;
-  columns: Map<string, ResolvedColumn[]>; // column name → one per matched operation
-  apiOperation?: MatchedOperation[];
-}
-
-interface ResolvedColumn {
-  name: string;
-  schema: v3.SchemaObject;
-  ast?: object; // originating AST node (for error location, future use)
-}
-```
-
----
-
-## Service Table Columns (`service-table.ts`)
-
-Every Athena service table (Kinesis stream) exposes eleven fixed top-level columns:
-
-| Column            | Schema                          |
-| ----------------- | ------------------------------- |
-| `method`          | `{ type: 'string' }`            |
-| `started`         | `{ type: 'string' }`            |
-| `ended`           | `{ type: 'string' }`            |
-| `url`             | `{ type: 'string' }`            |
-| `requestbody`     | OpenAPI request body schema     |
-| `requestheaders`  | OpenAPI request headers schema  |
-| `responsestatus`  | `{ type: 'string' }`            |
-| `responsemessage` | `{ type: 'string' }`            |
-| `responsetype`    | `{ type: 'string' }`            |
-| `responsebody`    | OpenAPI response body schema    |
-| `responseheaders` | OpenAPI response headers schema |
-
-`requestbody` / `requestheaders` come from `operation.request['properties'].body/headers`; `responsebody` / `responseheaders` from `operation.response['properties'].body/headers`. Both fall back to `{ type: 'object' }` if the field is absent.
-
-`buildServiceTables(tableName, operations)` returns one `ResolvedTable` per `MatchedOperation` (multiple operations may match, e.g. GET and POST on the same path).
-
----
-
-## API Location (`api-locator.ts`)
-
-`locateApi(serviceName)` converts a kebab-case service name (the SQL table name) to camelCase and globs for `src/services/<camelCase>/*/swagger.schema.deref.json`. All matched files are parsed and returned as `ApiSchemas[]`.
-
-The deref'd schema is used (not the raw `swagger.schema.json`) so `$ref` pointers are already inlined.
-
----
-
-## API Matching (`api-matcher.ts`)
-
-`matchApi(selectAST, tableAST, apiSchemas)` builds a set of `Matcher` functions from WHERE-clause conditions then filters all operations in `apiSchemas` against them.
-
-Current matchers (each is optional — if the WHERE clause doesn't contain the relevant condition, the matcher is skipped):
-
-| Matcher         | Condition pattern in WHERE                                       |
-| --------------- | ---------------------------------------------------------------- |
-| Method          | `method = 'GET'` / `'POST'` / etc.                               |
-| Path part count | `cardinality(split(url, '/')) = N`                               |
-| Path part value | `split(url, '/')[N] = 'value'`                                   |
-| Response status | `responsestatus = '200'` (applied post-filter on response codes) |
-
-The function throws an `Error` if no operations match (not `AthenaError` — this propagates as an unexpected error through `checkAthenaAst` and is caught as a non-`AthenaError`, reported with the raw message).
-
----
-
-## Two-Pass Column Resolution
-
-### Pass 1 — `resolveFromClause`
-
-Iterates `select.from[]`. For each `BaseFrom` item:
-
-- Registers the alias (if any) in `ctx.aliases`
-- Skips if the table name is already in `ctx.tables` (CTE reference or duplicate in comma-join)
-- Otherwise calls `locateApi` + `matchApi` + `buildServiceTables` and stores the result in `ctx.tables`
-
-JOINs (`isJoin`), UNNEST items, subqueries (`isTableExpr`), and DUAL are skipped in pass 1.
-
-### UNNEST Pre-Pass — `applyUnnestPre`
-
-`extractUnnestMappings` extracts `{ fromColumn, toColumn }` pairs from UNNEST items in `from[]`.
-
-`applyUnnestPre` then tries to resolve each mapping immediately: if the `fromColumn` exists in a service table currently in `ctx.tables`, it verifies the schema is `array`, unwraps the `.items` schema, and registers a synthetic transient table `"<ownerTable>:<unnested>"` in `ctx.tables` with a single column `toColumn` holding the item schema.
-
-Any mappings where `fromColumn` is not yet found (because it will be a computed SELECT column) are returned as `deferred`.
-
-### Pass 2 — `resolveSelectColumns`
-
-Iterates `select.columns[]`. For each column:
-
-1. **Count column refs** (`extractColumnRefs`). If 0 or > 1, fall back to `{ type: 'string' }` under the alias or `_colN` name.
-2. **Look up the single ref** in `ctx.tables` (using `ctx.aliases` to resolve table qualifiers).
-3. **Wildcard (`*`)** — expand all columns from the referenced tables into `columns`.
-4. **Resolve the column name** in each candidate table's `columns` map. Throw `AthenaError` if not found.
-5. **Check for property access**: first try `extractJsonExtractPath` (json_extract_scalar/json_extract), then `extractBracketAccessorPath` (bracket accessor). If neither, use the resolved schema directly.
-6. **Navigate into the JSON schema** using the accessor path. The path is rewritten to use double-dot (`$..`) to handle intermediate `allOf`/`anyOf`/`oneOf` wrappers. Throw `AthenaError` if the path resolves to nothing.
-
-The column name used in the result map is: alias > bare column name (no function) > `_colN` (function present, no alias).
-
-### UNNEST Post-Pass — `applyUnnestPost`
-
-Resolves the deferred UNNEST mappings against the `columns` map built in pass 2. The `fromColumn` is now a computed column; its schema must be `array`.
-
-### UNION ALL
-
-`select._next` chains the next SELECT in a UNION. After resolving the current SELECT, `checkSelect` recurses on `_next` passing the same parent context and the same `withTableName`. The column schemas from UNION branches are not currently compared against each other (this is a known gap — see PLAN.md).
-
----
-
-## CTE / WITH Handling
-
-`checkAthenaAst` iterates `select.with[]` before calling `checkSelect` on the main query. For each WITH item it calls `checkSelect(withItem.stmt.ast, ctx, withItem.name.value)`. At the end of `checkSelect`, if `withTableName` is set, the resolved columns are registered as a `ResolvedTable` in `ctx.tables` under that name.
-
-`createChildContext(parent)` copies `parent.tables` so each nested CTE can see tables defined by earlier CTEs in the same WITH clause.
-
-After processing all CTEs, `checkAthenaAst` sets `select.with = null` (mutates the AST) to avoid double-processing in the subsequent `checkSelect` call on the outer select.
-
----
-
-## Property Accessor Schema Navigation
-
-When a column expression contains a JSON path accessor, the path is converted to a JSONPath expression that navigates into the OpenAPI schema:
-
-```
-Input:   $.foo.bar
-Rewrite: $...properties.foo..properties.bar
-```
-
-The double-dot (`..`) at each segment boundary lets JSONPath skip through intermediate `allOf`, `anyOf`, `oneOf`, or `properties` wrappers that OpenAPI schemas commonly use.
-
-`JSONPath({ json: column.schema, path: adjustedPath })` is called against the resolved column's schema. If no values are returned, `AthenaError` is thrown with `property not found <colRef> - <accessor>`.
-
----
-
-## Error Reporting
-
-Two message IDs are registered on the ESLint rule:
-
-| ID             | Cause                                         |
-| -------------- | --------------------------------------------- |
-| `SyntextError` | PEG parser threw (SQL syntax error)           |
-| `AthenaError`  | `AthenaError` thrown during schema resolution |
-
-Any other `Error` (e.g. thrown by `matchApi`, `locateApi`, `assert.ok`) is caught and reported as `AthenaError` with the error's string representation, plus a `console.error` to stderr. This is a catch-all for unexpected runtime failures.
-
-Errors are thrown at the first failure encountered (not collected). Multiple errors in one query are reported as a single lint diagnostic for the template literal node.
-
----
-
-## Schema Files
-
-`src/services/<camelCaseServiceName>/<version>/swagger.schema.deref.json`
-
-Generated by:
-
-1. `src/openapi/generate-schema.ts` — reads `swagger.yml` and produces `swagger.schema.json` with typed request/response schemas keyed by `apis[path][method]`
-2. `src/openapi/deref-schema.ts` — resolves `$ref` pointers inline to produce `swagger.schema.deref.json`
-
-The `ApiSchemas` type (from `generate-schema.ts`) has shape:
-
-```typescript
-{
-  apis: Record<string, Record<string, OperationSchemas>>;
-  // apis['/path/v1']['GET'] → { request: SchemaObject, responses: { '200': SchemaObject, ... } }
-}
-```
-
----
-
-## Debug Logging
-
-Set `DEBUG=eslint-plugin:athena` (or `eslint-plugin:athena:*`) to see verbose resolution logs. Uses the `debug` npm package.
-
----
-
-## Known Limitations (as of current implementation)
-
-- Only `BaseFrom` tables are resolved in pass 1; `JOIN ... ON`, subqueries (`TableExpr`), and `DUAL` are silently ignored.
-- Multiple column refs in one SELECT column fall back to `{ type: 'string' }` without error.
-- `CAST` type information is not propagated — a `CAST(col AS ARRAY<VARCHAR>)` is still treated as the underlying column's schema.
-- `CASE` expressions always fall back to `{ type: 'string' }`.
-- UNION branches are not checked for column-count or type compatibility.
-- Multiple matched API operations for the same table produce multiple `ResolvedTable` entries but conflicts are not reported.
-- `OR` conditions in WHERE are not used by `api-matcher` for path/method matching — only AND chains are examined.
-- `ast.json` is written to disk on every linted SQL string (debug artifact, should be removed for production use).

package/src/athena/PLAN.md

@@ -1,355 +0,0 @@
-# Athena Rule — Visitor Pattern Refactor Plan
-
-## Current State
-
-`athena.ts` implements `checkAthenaAst` / `checkSelect` as a single monolithic recursive function (~270 lines, flagged with `sonarjs/cognitive-complexity`). It processes the SQL AST imperatively using JSONPath queries scattered throughout:
-
-- `$.from..[?(@ && @.table && !@.column)]` — extract table refs
-- `"$..from[?(@ && @.type === 'unnest')]"` — extract UNNEST
-- `"$..[?(@ && @.type === 'column_ref' && @.column)]"` — find column refs per selected column
-- `"$..[?(@ && @.type === 'function' && …)]…"` — find `json_extract_scalar` / `json_extract`
-- `"$..[?(@ && @.type === 'column_ref' && @.array_index)]…"` — find JSON-bracket accessors
-
-These ad-hoc JSONPath walks make the control flow hard to follow and will only get harder as new SQL constructs are added (JOINs, subqueries, CASE expressions, etc.).
-
-## What the Visitor Pattern Should Do
-
-A visitor walks the typed AST once, dispatching to typed handlers per node kind. The goal is:
-
-1. **Separation of concerns** — each handler knows exactly one AST node shape.
-2. **Typed dispatch** — no `as unknown`, no runtime `@.type === 'foo'` predicates.
-3. **Composability** — multiple passes can reuse the same visitor infrastructure.
-4. **Testability** — individual visitors can be unit-tested against small AST fixtures.
-
-## AST Node Taxonomy (from `types.ts`)
-
-The PEG grammar produces nodes that fall into these families:
-
-| Node type (`.type` field)         | Interface               | Visitor hook needed |
-| --------------------------------- | ----------------------- | ------------------- |
-| `"select"`                        | `Select`                | `visitSelect`       |
-| `"binary_expr"`                   | `Binary`                | `visitBinary`       |
-| `"column_ref"`                    | `ColumnRefItem`         | `visitColumnRef`    |
-| `"function"`                      | `Function`              | `visitFunction`     |
-| `"aggr_func"`                     | `AggrFunc`              | `visitAggrFunc`     |
-| `"cast"`                          | `Cast`                  | `visitCast`         |
-| `"case"`                          | `Case`                  | `visitCase`         |
-| `"expr_list"`                     | `ExprList`              | `visitExprList`     |
-| `"unnest"` (virtual, in `from`)   | `ColumnRefItem` subtype | `visitUnnest`       |
-| literal / value nodes             | `ValueExpr`             | `visitValue`        |
-| `BaseFrom` / `Join` / `TableExpr` | `From` union            | `visitFrom`         |
-| `With` item                       | `With`                  | `visitWith`         |
-
-`Select._next` links UNION branches; those also need traversal via `visitSelect`.
-
-## What Is Missing in `visitor.ts`
-
-The file currently has 5 lines:
-
-```ts
-export default function (ast: unknown, context: Context) {
-  if (typeof ast !== 'object' || ast === null) {
-    return;
-  }
-}
-```
-
-Everything is missing:
-
-### 1. Visitor interface / type map
-
-```ts
-// Minimal shape needed
-type VisitorMap = {
-  visitSelect?(node: Select, ctx: VisitContext): void;
-  visitWith?(node: With, ctx: VisitContext): void;
-  visitFrom?(node: From, ctx: VisitContext): void;
-  visitColumn?(node: Column, ctx: VisitContext): void;
-  visitColumnRef?(node: ColumnRefItem, ctx: VisitContext): void;
-  visitFunction?(node: Function, ctx: VisitContext): void;
-  visitBinary?(node: Binary, ctx: VisitContext): void;
-  visitValue?(node: ValueExpr, ctx: VisitContext): void;
-  // … etc.
-};
-```
-
-All hooks should be optional so callers only implement what they care about.
-
-### 2. Typed `VisitContext`
-
-`context.ts` currently defines a `Table` interface (not a context class). We need a mutable context that accumulates resolution state **per SELECT scope**:
-
-```ts
-interface VisitContext {
-  // resolved service tables keyed by name/alias
-  tables: Map<string, ResolvedTable>;
-  // columns resolved so far in this SELECT
-  columns: Map<string, ResolvedColumn[]>;
-  // alias → real-name mapping
-  aliases: Map<string, string>;
-  // schemas loaded from disk, shared across the whole query
-  apiSchemas: Map<string, ApiSchemas[]>;
-  // parent context (for CTE / subquery scoping)
-  parent?: VisitContext;
-}
-```
-
-`context.ts` and `column.ts` have started down this road but are incomplete and have incorrect imports (`.ts` extensions in import paths, broken `Context` base class usage).
-
-### 3. `visit(node, ctx)` dispatcher
-
-The core dispatcher needs to:
-
-- Accept `unknown` input (PEG output is not statically typed at boundaries)
-- Read `node.type` and call the appropriate handler
-- Recursively descend into child nodes
-
-```ts
-function visit(node: unknown, ctx: VisitContext, visitor: VisitorMap): void {
-  if (typeof node !== 'object' || node === null) return;
-  const typed = node as { type?: string };
-  switch (typed.type) {
-    case 'select':
-      return visitor.visitSelect?.(node as Select, ctx);
-    case 'binary_expr':
-      return visitor.visitBinary?.(node as Binary, ctx);
-    case 'column_ref':
-      return visitor.visitColumnRef?.(node as ColumnRefItem, ctx);
-    case 'function':
-      return visitor.visitFunction?.(node as Function, ctx);
-    // … etc.
-  }
-  // fallback: recurse into all object values
-}
-```
-
-### 4. Per-node child traversal helpers
-
-Each handler should call `visitChildren` (or per-kind helpers) to recurse. Missing helpers:
-
-- `visitSelectChildren(node: Select, ctx, visitor)` — visits `from[]`, `columns[]`, `where`, `groupby`, `_next`
-- `visitFromChildren(node: From, ctx, visitor)` — handles `BaseFrom`, `Join` (recurse into `.on`), `TableExpr` (recurse into subquery `.expr.ast`)
-- `visitBinaryChildren(node: Binary, ctx, visitor)` — visits `.left` and `.right`
-- `visitFunctionChildren(node: Function, ctx, visitor)` — visits `.args.value[]`
-
-### 5. Concrete resolution visitor for `checkSelect` logic
-
-The current `checkSelect` logic should be decomposed into a `ResolutionVisitor` that implements `VisitorMap`:
-
-- `visitWith` → calls `checkSelect` on the CTE body, registers the result in `ctx.tables`
-- `visitFrom` → resolves service table → calls `locateApi` + `matchApi` → populates `ctx.tables`
-- `visitUnnest` → maps unnested array columns
-- `visitColumnRef` inside a `SELECT` column → looks up the column in `ctx.tables`, applies property accessor, records in `ctx.columns`
-- `visitFunction` → detects `json_extract_scalar` / `json_extract`, extracts the path argument
-
-### 6. `service-table.ts` needs to be completed
-
-The file duplicates large chunks of `athena.ts` but is incomplete (references `MatchedOperation`, `ResolvedColumn`, `AthenaContext`, `log`, etc. that are not imported). It was apparently started as the extraction destination for service-table logic. Missing:
-
-- Import `MatchedOperation` from `api-matcher`
-- Import `ResolvedColumn` (define locally or re-export from `athena.ts`)
-- Import `log`, `SCHEMA_STRING`, `SCHEMA_OBJECT`
-- Export `buildServiceTable(tableAST, selectAST, apiSchemas): ServiceTable` as the single factory function
-- Remove the duplicate `checkSelect` / `checkAthenaAst` body currently pasted in
-
-### 7. `index.ts` needs its commented-out code resolved
-
-`index.ts` has the full `ServiceEndpoint` / `Service` types but all the context/resolver interfaces are commented out. Once `visitor.ts` and `service-table.ts` are solid, these should either be deleted or promoted to the proper types.
-
-### 8. `zzz.spec.ts` is a broken scratch file
-
-`zzz.spec.ts` has syntax errors (`type Table =` with no RHS, calling `visit` instead of `visitSelect`, missing `context` arg). It was clearly a scratch experiment for the visitor idea. It should either become a proper unit test of the visitor once it exists, or be deleted.
-
-## Suggested File Structure After Refactor
-
-```
-src/athena/
-  types.ts          — unchanged (PEG AST types)
-  visitor.ts        — IMPLEMENT: VisitorMap, VisitContext, visit(), visitChildren helpers
-  service-table.ts  — COMPLETE: buildServiceTable() factory, ServiceTable type
-  context.ts        — REWRITE: VisitContext (replace broken Table/Column class tree)
-  column.ts         — REWRITE: ResolvedColumn value type (not a class extending Context)
-  index.ts          — CLEAN UP: remove commented-out code once visitor types exist
-  athena.ts         — REFACTOR: replace checkSelect monolith with visitor composition
-  athena.spec.ts    — unchanged (integration tests)
-  zzz.spec.ts       — FIX or DELETE: make it a real visitor unit test
-```
-
-## Recommended Implementation Order
-
-1. **Define `VisitContext` in `context.ts`** — the mutable scope object passed through the tree.
-2. **Define `VisitorMap` and `visit()` dispatcher in `visitor.ts`** — untyped input → typed dispatch.
-3. **Add `visitSelectChildren` and other traversal helpers** — recursive descent wiring.
-4. **Refactor `service-table.ts`** — `buildServiceTable()` extracts the FROM-resolution block out of `checkSelect`.
-5. **Build `ResolutionVisitor`** — implements `VisitorMap`, accumulates `ctx.columns`, replaces current `checkSelect` body.
-6. **Wire into `athena.ts`** — `checkAthenaAst` creates a root `VisitContext`, runs `visit(ast, ctx, resolutionVisitor)`.
-7. **Fix `zzz.spec.ts`** into a real test of the visitor dispatch.
-
-## Key Design Decisions To Resolve
-
-- **One visitor pass or two?** The current code does a single forward pass (resolves tables, then processes columns). A visitor architecture could do two passes (first pass builds the table map, second pass resolves columns), which would simplify handling forward references between CTEs — but is not required yet.
-- **Array of tables vs. Map** — the current `allResolvedTables: Record<string, Table[]>` uses arrays to represent ambiguity (multiple matching API endpoints). The new `VisitContext` should preserve this, but consider whether `Map<string, ResolvedTable[]>` is cleaner.
-- **Error handling** — `AthenaError` is currently thrown and caught at the top level. With a visitor, errors should either propagate the same way, or be collected in `ctx.errors[]` so all errors in a query are reported at once.
-
----
-
-## Future Improvements — Supporting More Complex SQL
-
-The following gaps exist in the current implementation. Each item describes what SQL pattern is not yet handled, why it matters, and what work is needed.
-
-### 1. JOIN Resolution
-
-**What fails today:** `JOIN` tables (`isJoin`) are silently skipped in `resolveFromClause`. Any column from a joined table that is not also reachable through a plain `BaseFrom` causes a "can't found column" error or silently produces a wrong result.
-
-**Affected patterns:**
-
-```sql
-SELECT req.message, res.message
-FROM request_message AS req
-JOIN response_message AS res ON json_extract_scalar(res.message, '$.id') = json_extract_scalar(req.message, '$.id')
-```
-
-**Work needed:**
-
-- In `resolveFromClause`, handle `isJoin` nodes: the `Join` interface extends `BaseFrom`, so the `table` / `as` fields are available. Register the joined table in `ctx.tables` the same way as a plain `BaseFrom`.
-- Add `visitJoin` hook in `visitor.ts`'s resolution path.
-- The `ON` clause is an expression and cannot be used to narrow the API match (unlike WHERE). The join condition should be walked for column reference validation only.
-
-### 2. Subquery / Inline View Resolution (`TableExpr`)
-
-**What fails today:** `TableExpr` nodes (subqueries in the FROM clause) are skipped. Columns from subqueries cannot be resolved.
-
-**Affected patterns:**
-
-```sql
-SELECT t.url FROM (SELECT url, method FROM link) AS t
-```
-
-**Work needed:**
-
-- In `resolveFromClause`, detect `isTableExpr` items and recursively call `checkSelect` on `item.expr.ast`, capturing the resulting columns as a new `ResolvedTable` in `ctx.tables[alias]`.
-- The child SELECT needs its own `createChildContext(ctx)` so its own alias map doesn't pollute the outer scope.
-
-### 3. CAST Type Propagation
-
-**What fails today:** `CAST(expr AS type)` is walked but the target type is ignored. The column receives the schema of the inner expression, not the cast type.
-
-**Affected patterns:**
-
-```sql
-SELECT CAST(json_extract(responsebody, '$.links') AS ARRAY<VARCHAR>) AS linkages
-FROM link CROSS JOIN UNNEST(linkages) AS t(linkage)
--- linkages has schema { type:'object' } instead of { type:'array', items:{ type:'string' } }
-```
-
-This means UNNEST pre-pass correctly finds `linkages` is `array` only when the JSON schema already says so, not when it is produced by a CAST. Two tests in `athena.spec.ts` carry a `[TODO:] handle array item type extraction using schema dereferencing` comment on exactly this case.
-
-**Work needed:**
-
-- In `resolveSelectColumns`, detect that `hasFunctionCalls` found a `cast` node.
-- Use `extractCastTarget(expr)` (new helper) to get `target.dataType` (e.g. `'ARRAY'`, `'MAP'`, `'VARCHAR'`, `'JSON'`).
-- Map Athena/Trino type names to JSON Schema equivalents and substitute the schema before storing the column.
-- Extend `ColumnRefWithIndex` or add a new `CastExpr` shape to make the type accessible without `unknown` casts.
-
-### 4. CASE Expression Schema
-
-**What fails today:** A column whose expression is a `case` node has 0 `column_ref` items at the top level (each arm has refs, but the rule counts refs at the outer level). It falls into the "multiple refs → string" bucket even when all arms resolve to the same type.
-
-**Affected patterns:**
-
-```sql
-SELECT CASE WHEN method = 'GET' THEN responsebody ELSE requestbody END AS body FROM link
-```
-
-**Work needed:**
-
-- Special-case `case` nodes in pass 2: collect refs from each arm's `result`, intersect the resolved schemas, and emit that as the output schema.
-- Add `extractCaseArms(expr)` helper in `visitor.ts`.
-
-### 5. OR Conditions in API Matcher
-
-**What fails today:** `api-matcher.ts` extracts path/method conditions only from AND-chains in the WHERE clause. SQL that uses `OR` to express version-specific URL patterns is handled by the rule passing multiple matched operations — but only when the condition can be matched by each alternative independently. A disjunction like `(split(url,'/')[3]='v1' AND ...) OR (split(url,'/')[3]='v2' AND ...)` produces no match for either branch individually, so `matchApi` throws.
-
-**Affected patterns:**
-
-```sql
-WHERE method = 'PUT'
-AND (
-  (split(url, '/')[4] = 'card' AND cardinality(split(url, '/')) = 5)
-  OR
-  (split(url, '/')[4] = 'card' AND split(url, '/')[6] = 'number' AND cardinality(split(url, '/')) = 6)
-)
-```
-
-The test case `'AND/OR'` in `athena.spec.ts` is currently in the `invalid` set with a misleading error message — it is expected to be valid, but fails today.
-
-**Work needed:**
-
-- Teach `api-matcher.ts` to recognise OR-of-AND patterns: extract each AND branch as a separate matcher set, union all matched operations across branches.
-- Alternatively, fall back to "no path constraint" when an OR is detected at the top level of the WHERE, accepting a potentially larger set of matched operations.
-
-### 6. UNION Column Compatibility Check
-
-**What fails today:** UNION ALL branches are resolved independently; their column count and schemas are never compared. A UNION where one branch has a different column name or an incompatible type silently passes.
-
-**Work needed:**
-
-- After resolving `select._next`, compare the column maps (names and schemas) between the current SELECT and the next SELECT.
-- Report `AthenaError` if column counts differ or if a column in the next branch does not exist in the current branch.
-- Consider whether schema compatibility checking (e.g. `string` vs `object`) should also be enforced, or just name-level matching.
-
-### 7. Multiple Matched Operations — Conflict Reporting
-
-**What fails today:** When multiple API operations match for the same service table (e.g. two different response status codes, or GET and POST), `buildServiceTables` silently creates multiple `ResolvedTable` entries. Column resolution then collects schemas from all of them. Conflicting schemas (e.g. different response body shapes for 200 vs 204) are silently merged.
-
-**Work needed:**
-
-- After `buildServiceTables`, if `operations.length > 1`, emit a warning (not an error, since it may be intentional) listing the matched operations.
-- In `resolveSelectColumns`, when `resolvedColumns.length > 1`, check whether all schemas are identical. If not, either report a warning or fall back to `{ type: 'object' }`.
-
-### 8. Error Collection (All Errors Per Query)
-
-**What fails today:** The first `AthenaError` thrown immediately exits resolution, so only one error per SQL string is reported even if the query has multiple bad property accesses.
-
-**Work needed:**
-
-- Add `errors: AthenaError[]` to `VisitContext`.
-- Replace `throw new AthenaError(...)` with `ctx.errors.push(...); continue` in pass 2.
-- After `checkAthenaAst` returns, report each collected error as a separate `context.report(...)` call (or a single report with all messages joined).
-
-### 9. Remove `ast.json` Debug Write
-
-**What fails today (non-functional):** `athena.ts` writes `ast.json` to disk on every linted SQL string:
-
-```typescript
-fs.writeFileSync('ast.json', JSON.stringify(ast, undefined, 2));
-```
-
-This is a development artifact. In production it creates a file in the working directory on every lint run and makes the rule non-deterministic in parallel lint runs.
-
-**Work needed:** Delete the `fs.writeFileSync` call and the `import fs from 'node:fs'` import. If debug AST output is needed, gate it behind `DEBUG=eslint-plugin:athena` using the `log` function already available.
-
-### 10. Error Location in Reports
-
-**What fails today:** The rule reports errors at the template literal node level (the whole `` `...` `` span). `ResolvedColumn.ast` stores the originating column AST node with `loc` information, but this is never used.
-
-**Work needed:**
-
-- The PEG parser already attaches `loc: { start: { line, column, offset }, end: {...} }` to AST nodes (when `includeLocations: true`).
-- Map `loc` back to ESLint's `TSESTree.SourceLocation` and use `context.report({ loc: ... })` to pinpoint the exact column expression that failed rather than the whole template literal.
-- The helper `getErrorLocation(ast)` previously existed in the old `athena.ts` (removed in the refactor) as a reference implementation.
-
-### 11. `parameters` CTE Pattern — FROM-less SELECT
-
-**What fails today:** CTEs with no FROM clause (e.g. `SELECT '' AS p_from, '' AS p_to`) produce a `Select` with `from: null`. These currently pass through `resolveFromClause` without registering any table, and then `resolveSelectColumns` tries to iterate zero tables. Because the columns are literal strings (0 `column_ref`s), they fall into the "no column references → use string default" branch and pass. However if someone writes `SELECT p_from FROM parameters` in a later CTE, the `parameters` table is looked up and resolved correctly because `checkSelect` registers its output in `ctx.tables` regardless. **This case already works**, but it is worth documenting explicitly and adding a dedicated test case to guard against regressions.
-
-### 12. Quoted Table Names
-
-**What fails today (partially):** Table names enclosed in double quotes (e.g. `FROM "payment-card"`) are parsed by the PEG grammar but the quotes are preserved in the `table` field: `table: '"payment-card"'`. `locateApi` then looks for a service named `"payment-card"` including the quotes, which fails to match the camelCase folder name `paymentCard`.
-
-The test case `'SELECT with FROM - table name with double quotes'` is currently in the valid set, which suggests the quoted-table fallback path (no matching service → no error) is silently accepted. If schemas exist for `payment-card`, the rule would fail to find them.
-
-**Work needed:**
-
-- Strip leading/trailing `"` or `'` from `tableName` before calling `locateApi` in `resolveFromClause`.
-- Add a test case that actually has schemas for a quoted-name service and verifies column resolution succeeds.