@checkdigit/eslint-plugin 7.18.0-PR.143-3aac → 7.18.0-PR.143-1cc5

package/dist-types/athena/visitor.d.ts

@@ -47,6 +47,8 @@ export declare function isJoin(node: unknown): node is Join;
 export declare function isBaseFrom(node: unknown): node is BaseFrom;
 export declare function hasArrayIndex(node: ColumnRefItem): node is ColumnRefWithIndex;
 export declare function walk(node: unknown, visitor: VisitorMap): void;
+/** Return true if the expression contains a lambda (`->`) subexpression. */
+export declare function containsLambda(expr: unknown): boolean;
 /** Collect all column_ref nodes within an expression subtree. */
 export declare function extractColumnRefs(expr: unknown): ColumnRefItem[];
 /** Return the path string from the first json_extract_scalar / json_extract call found. */

package/package.json

@@ -1 +1 @@
-{"name":"@checkdigit/eslint-plugin","version":"7.18.0-PR.143-3aac","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"]}},"wallaby":{"env":{"params":{"runner":"--experimental-vm-modules"}}}}
+{"name":"@checkdigit/eslint-plugin","version":"7.18.0-PR.143-1cc5","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"]}},"wallaby":{"env":{"params":{"runner":"--experimental-vm-modules"}}}}

package/src/athena/athena.ts

@@ -1,5 +1,7 @@
 // athena/athena.ts
 
+/* eslint-disable max-lines */
+
 /*
  * Copyright (c) 2021-2026 Check Digit, LLC
  *
@@ -14,7 +16,7 @@ import { AST_NODE_TYPES, ESLintUtils, type TSESTree } from '@typescript-eslint/u
 import type { SchemaObject } from 'ajv/dist/2020';
 
 import { parse } from '../peggy/athena-peggy.ts';
-import type { AST, From, Select, With } from './types';
+import type { AST, BaseFrom, From, Select, With } from './types';
 import { matchApi } from './api-matcher.ts';
 import { locateApi } from './api-locator.ts';
 import {
@@ -26,6 +28,7 @@ import {
 } from './context.ts';
 import { buildServiceTables } from './service-table.ts';
 import {
+  containsLambda,
   extractBracketAccessorPath,
   extractColumnRefs,
   extractJsonExtractCalls,
@@ -141,6 +144,23 @@ function fromClauseItems(select: Select): From[] {
 // Pass 1 — Resolve FROM clause: service tables → ctx.tables + ctx.aliases
 // ---------------------------------------------------------------------------
 
+function resolveServiceTable(select: Select, item: BaseFrom, ctx: VisitContext): void {
+  const { table: tableName } = item;
+  try {
+    const apiSchemas = getApiSchemas(tableName, ctx);
+    if (apiSchemas.length === 0) {
+      throw new AthenaError(ATHENA_ERROR, `service not found: "${tableName}" (no swagger schema located)`, item);
+    }
+    const operations = matchApi(select, item, apiSchemas) ?? [];
+    ctx.tables.set(tableName, buildServiceTables(tableName, operations));
+  } catch (error) {
+    if (error instanceof AthenaError) {
+      throw error;
+    }
+    throw new AthenaError(ATHENA_ERROR, error instanceof Error ? error.message : String(error), item);
+  }
+}
+
 function resolveFromClause(select: Select, ctx: VisitContext): void {
   for (const item of fromClauseItems(select)) {
     if (isUnnestFrom(item)) {
@@ -153,9 +173,7 @@ function resolveFromClause(select: Select, ctx: VisitContext): void {
         ctx.aliases.set(alias, tableName);
       }
       if (!ctx.tables.has(tableName)) {
-        const apiSchemas = getApiSchemas(tableName, ctx);
-        const operations = matchApi(select, item, apiSchemas) ?? [];
-        ctx.tables.set(tableName, buildServiceTables(tableName, operations));
+        resolveServiceTable(select, item, ctx);
       }
       continue;
     }
@@ -174,11 +192,7 @@ function resolveFromClause(select: Select, ctx: VisitContext): void {
       continue; // already resolved (CTE or duplicate)
     }
 
-    // Service table: locate + match API schemas from disk.
-    // matchApi throws when no operation matches, so operations is always defined here.
-    const apiSchemas = getApiSchemas(tableName, ctx);
-    const operations = matchApi(select, item, apiSchemas) ?? [];
-    ctx.tables.set(tableName, buildServiceTables(tableName, operations));
+    resolveServiceTable(select, item, ctx);
   }
 }
 
@@ -278,6 +292,28 @@ function expandWildcard(referencedTables: ResolvedTable[], columns: Map<string,
   }
 }
 
+// If every resolved column shares the same object schema, return a hint listing its top-level
+// properties. Returns '' when schemas differ across matched operations or the schema isn't an object.
+function schemaPropertyHint(resolvedColumns: ResolvedColumn[]): string {
+  if (resolvedColumns.length === 0) {
+    return '';
+  }
+  const first = JSON.stringify(resolvedColumns[0]?.schema);
+  if (!resolvedColumns.every((col) => JSON.stringify(col.schema) === first)) {
+    return '';
+  }
+  const schema = resolvedColumns[0]?.schema;
+  if (schema?.type !== 'object') {
+    return '';
+  }
+  const properties = schema.properties;
+  if (properties === undefined) {
+    return '';
+  }
+  const propNames = Object.keys(properties);
+  return propNames.length > 0 ? `; available properties: ${propNames.join(', ')}` : '';
+}
+
 function resolveSchemaAtPath(
   colRef: string,
   propertyAccessor: string,
@@ -295,7 +331,11 @@ function resolveSchemaAtPath(
   log('extracted schemas', extractedSchemas);
 
   if (extractedSchemas.length === 0) {
-    throw new AthenaError(ATHENA_ERROR, `property not found ${colRef} - ${propertyAccessor}`, ast);
+    throw new AthenaError(
+      ATHENA_ERROR,
+      `property not found ${colRef} - ${propertyAccessor}${schemaPropertyHint(resolvedColumns)}`,
+      ast,
+    );
   }
   return extractedSchemas;
 }
@@ -321,6 +361,41 @@ function navigateSchemaPath(
 // Pass 2 — Resolve SELECT columns → Map<name, ResolvedColumn[]>
 // ---------------------------------------------------------------------------
 
+/** Resolve a column by name against `referencedTables`, throwing if not found. */
+function lookupColumnOrThrow(
+  colRef: string,
+  ref: object,
+  referencedTables: ResolvedTable[],
+  ctx: VisitContext,
+): ResolvedColumn[] {
+  const resolvedColumns = referencedTables.flatMap((table) => table.columns.get(colRef) ?? []);
+  if (resolvedColumns.length === 0) {
+    const tableNames = [...ctx.tables.keys()].join(', ');
+    const availableCols = [...new Set(referencedTables.flatMap((table) => [...table.columns.keys()]))].join(', ');
+    throw new AthenaError(
+      ATHENA_ERROR,
+      `can't found column ${colRef} in tables: ${tableNames}; available columns: ${availableCols}`,
+      ref,
+    );
+  }
+  return resolvedColumns;
+}
+
+/** Check all column_refs in `ast` exist in scope. Skips lambda expressions (lambda params look like column_refs). */
+function checkColumnRefsExist(ast: unknown, allTables: ResolvedTable[], ctx: VisitContext): void {
+  if (containsLambda(ast)) {
+    return;
+  }
+  for (const ref of extractColumnRefs(ast)) {
+    const colRef = typeof ref.column === 'string' ? ref.column : undefined;
+    if (colRef === undefined || colRef === '*') {
+      continue;
+    }
+    const tableRef = ref.table ?? undefined;
+    lookupColumnOrThrow(colRef, ref, tableRef !== undefined ? lookupTables(tableRef, ctx) : allTables, ctx);
+  }
+}
+
 /** Validate all json_extract / json_extract_scalar paths in a complex column expression. */
 function validateComplexColumnExpression(columnAST: unknown, allTables: ResolvedTable[], ctx: VisitContext): void {
   for (const { ref, path, fnNode } of extractJsonExtractCalls(columnAST)) {
@@ -361,12 +436,7 @@ function resolveSingleColumnRef(
 
   const withFunctions = hasFunctionCalls(columnAST);
   const colName = columnAlias ?? (withFunctions ? indexedName : colRef);
-  const resolvedColumns = referencedTables.flatMap((table) => table.columns.get(colRef) ?? []);
-
-  if (resolvedColumns.length === 0) {
-    const tableNames = [...ctx.tables.keys()].join(', ');
-    throw new AthenaError(ATHENA_ERROR, `can't found column ${colRef} in tables: ${tableNames}`, columnAST as object);
-  }
+  const resolvedColumns = lookupColumnOrThrow(colRef, ref, referencedTables, ctx);
 
   const propertyAccessor = extractJsonExtractPath(columnAST) ?? extractBracketAccessorPath(columnAST);
   if (propertyAccessor !== undefined) {
@@ -392,6 +462,7 @@ function resolveSelectColumns(select: Select, ctx: VisitContext): Map<string, Re
     const columnRefs = extractColumnRefs(columnAST);
 
     if (columnRefs.length !== 1) {
+      checkColumnRefsExist(columnAST, allTables, ctx);
       validateComplexColumnExpression(columnAST, allTables, ctx);
       resolveDefaultSchemaColumn(columnAlias, indexedName, columnAST, columns);
       continue;
@@ -499,21 +570,33 @@ const rule: ESLintUtils.RuleModule<typeof SYNTEXT_ERROR | typeof ATHENA_ERROR> =
         return;
       }
 
+      const sqlMapping = buildSqlMapping(sqlNode);
       let ast: AST;
       try {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         ({ ast } = parse(sql, { includeLocations: true }));
       } catch (error) {
-        log('error checking Athena AST', { error, sql });
-        context.report({
-          node: sqlNode,
-          messageId: SYNTEXT_ERROR,
-          data: { errorMessage: JSON.stringify(error, undefined, 2), sql },
-        });
+        log('error parsing Athena SQL', { error, sql });
+        const pegLoc = (error as { location?: { start: { offset: number }; end: { offset: number } } }).location;
+        if (pegLoc !== undefined) {
+          const sourceText = context.sourceCode.getText();
+          context.report({
+            loc: {
+              start: offsetToLoc(sourceText, sqlOffsetToSource(pegLoc.start.offset, sqlMapping)),
+              end: offsetToLoc(sourceText, sqlOffsetToSource(pegLoc.end.offset, sqlMapping)),
+            },
+            messageId: SYNTEXT_ERROR,
+            data: { errorMessage: (error as Error).message },
+          });
+        } else {
+          context.report({
+            node: sqlNode,
+            messageId: SYNTEXT_ERROR,
+            data: { errorMessage: (error as Error).message },
+          });
+        }
         return;
       }
-
-      const sqlMapping = buildSqlMapping(sqlNode);
       const athenaCtx = createRootContext();
       try {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
@@ -573,3 +656,5 @@ const rule: ESLintUtils.RuleModule<typeof SYNTEXT_ERROR | typeof ATHENA_ERROR> =
 });
 
 export default rule;
+
+/* eslint-enable max-lines */

package/src/athena/visitor.ts

@@ -264,6 +264,19 @@ export function walk(node: unknown, visitor: VisitorMap): void {
 // Convenience extractors — replace ad-hoc JSONPath queries.
 // -------------------------------------------------------------------
 
+/** Return true if the expression contains a lambda (`->`) subexpression. */
+export function containsLambda(expr: unknown): boolean {
+  let found = false;
+  walkExpr(expr, {
+    visitBinary(node) {
+      if (node.operator === '->') {
+        found = true;
+      }
+    },
+  });
+  return found;
+}
+
 /** Collect all column_ref nodes within an expression subtree. */
 export function extractColumnRefs(expr: unknown): ColumnRefItem[] {
   const refs: ColumnRefItem[] = [];

package/src/peggy/athena-peggy.ts

@@ -1553,12 +1553,13 @@ function peg$parse(input: any, options: any): any {
   var peg$f107 = function (t, alias) {
     if (t.type === 'var') {
       t.as = alias;
-      return t;
+      return { ...t, ...getLocationObject() };
     } else {
       return {
         db: t.db,
         table: t.table,
         as: alias,
+        ...getLocationObject(),
       };
     }
   };
@@ -2035,6 +2036,7 @@ function peg$parse(input: any, options: any): any {
       table: tbl[3],
       column: col[3],
       collate: ce && ce[1],
+      ...getLocationObject(),
     };
   };
   var peg$f187 = function (tbl, col, ce) {
@@ -2044,6 +2046,7 @@ function peg$parse(input: any, options: any): any {
       table: tbl,
       column: col,
       collate: ce && ce[1],
+      ...getLocationObject(),
     };
   };
   var peg$f188 = function (col, ce) {
@@ -2053,6 +2056,7 @@ function peg$parse(input: any, options: any): any {
       table: null,
       column: col,
       collate: ce && ce[1],
+      ...getLocationObject(),
     };
   };
   var peg$f189 = function (head, tail) {

package/src/peggy/athena.peggy

@@ -1239,12 +1239,13 @@ table_base
   / t:table_name __ alias:alias_clause? {
       if (t.type === 'var') {
         t.as = alias;
-        return t;
+        return { ...t, ...getLocationObject() };
       } else {
         return {
           db: t.db,
           table: t.table,
-          as: alias
+          as: alias,
+          ...getLocationObject(),
         };
       }
     }
@@ -1906,6 +1907,7 @@ column_ref
         table: tbl[3],
         column: col[3],
         collate: ce && ce[1],
+        ...getLocationObject(),
       };
     }
   / tbl:ident __ DOT __ col:column ce:(__ collate_expr)? {
@@ -1915,6 +1917,7 @@ column_ref
         table: tbl,
         column: col,
         collate: ce && ce[1],
+        ...getLocationObject(),
       };
     }
   / col:column ce:(__ collate_expr)? {
@@ -1924,6 +1927,7 @@ column_ref
         table: null,
         column: col,
         collate: ce && ce[1],
+        ...getLocationObject(),
       };
     }