@n8n/scan-community-package 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@n8n/scan-community-package",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Static code analyser for n8n community packages",
   "license": "SEE LICENSE IN LICENSE.md",
   "bin": "scanner/cli.mjs",
@@ -14,13 +14,15 @@
     "fast-glob": "3.2.12",
     "axios": "1.18.0",
     "@typescript-eslint/parser": "^8.35.0",
+    "eslint-plugin-n8n-nodes-base": "^1.16.7",
     "semver": "7.7.3",
+    "typescript": "6.0.2",
     "tmp": "0.2.4",
-    "@n8n/eslint-plugin-community-nodes": "0.23.0"
+    "@n8n/eslint-plugin-community-nodes": "0.24.0"
   },
   "devDependencies": {
     "vitest": "^4.1.9",
-    "@n8n/vitest-config": "1.16.0"
+    "@n8n/vitest-config": "1.17.0"
   },
   "homepage": "https://n8n.io",
   "author": {

package/scanner/scanner.mjs

@@ -117,29 +117,88 @@ const downloadAndExtractPackage = async (packageName, version) => {
 	}
 };
 
-export const analyzePackage = async (packageDir) => {
+/**
+ * Builds the flat ESLint config the scanner lints packages with. Exported so
+ * tests can assert the external `eslint-plugin-n8n-nodes-base` plugin and its
+ * rulesets are wired in, independent of ESLint execution.
+ */
+export const buildScanConfig = async () => {
 	const { n8nCommunityNodesPlugin } = await import('@n8n/eslint-plugin-community-nodes');
 	const tsParser = await import('@typescript-eslint/parser');
+	const n8nNodesPlugin = (await import('eslint-plugin-n8n-nodes-base')).default;
+
+	const parser = tsParser.default ?? tsParser;
+
+	return defineConfig(
+		n8nCommunityNodesPlugin.configs.recommended,
+		{
+			rules: { 'no-console': 'error' },
+		},
+		// Register the full `eslint-plugin-n8n-nodes-base` plugin and apply its
+		// three rulesets so the scan gate enforces the same rules as
+		// `n8n-node lint` (see node-cli/src/configs/eslint.ts). The off-overrides
+		// below are kept identical. Scoping differs on purpose: `n8n-node lint`
+		// runs at dev-time on `nodes/**` / `credentials/**` `.ts` sources, but
+		// published tarballs ship compiled output under `dist/` (e.g.
+		// `dist/nodes/Foo/Foo.node.js` + `.d.ts`). We match `nodes`/`credentials`
+		// dirs at any depth and target `.ts`/`.d.ts` only — the AST-walking rules
+		// resolve against the type-preserving `.d.ts`. Compiled `.js` is
+		// deliberately excluded: the description AST is buried in a constructor
+		// there so the rules no-op, and file-shape rules like
+		// node-filename-against-convention would false-positive on the `.js`
+		// extension (that check is meaningful only against `.ts` sources at
+		// dev-time). Without the `dist/`-aware glob these rules never run at the
+		// gate at all.
+		{ plugins: { 'n8n-nodes-base': n8nNodesPlugin } },
+		{
+			files: ['package.json'],
+			rules: { ...n8nNodesPlugin.configs.community.rules },
+		},
+		{
+			files: ['**/credentials/**/*.ts'],
+			rules: {
+				...n8nNodesPlugin.configs.credentials.rules,
+				// Not valid for community nodes
+				'n8n-nodes-base/cred-class-field-documentation-url-miscased': 'off',
+				// @n8n/eslint-plugin-community-nodes credential-password-field rule is more accurate
+				'n8n-nodes-base/cred-class-field-type-options-password-missing': 'off',
+			},
+		},
+		{
+			files: ['**/nodes/**/*.ts'],
+			rules: {
+				...n8nNodesPlugin.configs.nodes.rules,
+				// Inputs and outputs can be enum instead of string "main"
+				'n8n-nodes-base/node-class-description-inputs-wrong-regular-node': 'off',
+				'n8n-nodes-base/node-class-description-outputs-wrong': 'off',
+				// Sometimes the 3rd party API does have a maximum limit, so maxValue is valid
+				'n8n-nodes-base/node-param-type-options-max-value-present': 'off',
+			},
+		},
+		// JSON files (notably `package.json`) are not parseable by ESLint's
+		// default JS parser, so register the TypeScript parser for them. The
+		// community-nodes rules that gate on `package.json` walk a TSESTree
+		// `ObjectExpression` AST, which `@typescript-eslint/parser` produces
+		// when given a top-level JSON object literal.
+		{
+			files: ['**/*.json'],
+			languageOptions: { parser },
+		},
+		// The external `nodes`/`credentials` rulesets walk a TSESTree AST, so
+		// TS sources (when present in the tarball) need the TS parser too.
+		{
+			files: ['**/*.ts'],
+			languageOptions: { parser },
+		},
+	);
+};
 
+export const analyzePackage = async (packageDir) => {
 	const eslint = new ESLint({
 		cwd: packageDir,
 		allowInlineConfig: false,
 		overrideConfigFile: true,
-		overrideConfig: defineConfig(
-			n8nCommunityNodesPlugin.configs.recommended,
-			{
-				rules: { 'no-console': 'error' },
-			},
-			// JSON files (notably `package.json`) are not parseable by ESLint's
-			// default JS parser, so register the TypeScript parser for them. The
-			// community-nodes rules that gate on `package.json` walk a TSESTree
-			// `ObjectExpression` AST, which `@typescript-eslint/parser` produces
-			// when given a top-level JSON object literal.
-			{
-				files: ['**/*.json'],
-				languageOptions: { parser: tsParser.default ?? tsParser },
-			},
-		),
+		overrideConfig: await buildScanConfig(),
 	});
 
 	try {
@@ -147,7 +206,7 @@ export const analyzePackage = async (packageDir) => {
 		// such as `no-overrides-field`, `valid-peer-dependencies`, and
 		// `package-name-convention` only run against `package.json`. Without
 		// it the scanner silently skips every package.json-based rule.
-		const filesToLint = glob.sync(['**/*.js', '**/*.json'], {
+		const filesToLint = glob.sync(['**/*.js', '**/*.ts', '**/*.json'], {
 			cwd: packageDir,
 			absolute: true,
 			ignore: ['node_modules/**', '**/package-lock.json'],

package/scanner/scanner.test.mjs

@@ -3,7 +3,7 @@ import path from 'path';
 import os from 'os';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
-import { analyzePackage } from './scanner.mjs';
+import { analyzePackage, buildScanConfig } from './scanner.mjs';
 
 /**
  * Build a temporary package directory on disk so we can hand it to
@@ -23,6 +23,56 @@ function makeFixturePackage(files) {
 	return dir;
 }
 
+describe('buildScanConfig', () => {
+	// CE-1606: the scan gate must register the external eslint-plugin-n8n-nodes-base
+	// and apply all three rulesets, mirroring `n8n-node lint`. Assert on the
+	// resolved config rather than on rule execution: under vitest the external
+	// plugin resolves a different @typescript-eslint parser instance than the one
+	// it was compiled against, so its AST-walking rules silently no-op in-process
+	// (they run correctly when the scanner is invoked via `node`, as the CLI does).
+	it('registers the external n8n-nodes-base plugin', async () => {
+		const config = await buildScanConfig();
+		const pluginBlock = config.find((block) => block.plugins?.['n8n-nodes-base']);
+
+		expect(pluginBlock).toBeDefined();
+		expect(pluginBlock.plugins['n8n-nodes-base'].configs).toHaveProperty('community');
+		expect(pluginBlock.plugins['n8n-nodes-base'].configs).toHaveProperty('credentials');
+		expect(pluginBlock.plugins['n8n-nodes-base'].configs).toHaveProperty('nodes');
+	});
+
+	it('applies each external ruleset with the correct file scoping', async () => {
+		const config = await buildScanConfig();
+		const ruleBlockFor = (glob) =>
+			config.find(
+				(block) =>
+					block.files?.includes(glob) &&
+					Object.keys(block.rules ?? {}).some((r) => r.startsWith('n8n-nodes-base/')),
+			);
+
+		// community ruleset → package.json
+		expect(ruleBlockFor('package.json')).toBeDefined();
+		// credentials ruleset → credentials dir at any depth (incl. dist/)
+		expect(ruleBlockFor('**/credentials/**/*.ts')).toBeDefined();
+		// nodes ruleset → nodes dir at any depth (incl. dist/)
+		expect(ruleBlockFor('**/nodes/**/*.ts')).toBeDefined();
+	});
+
+	it('carries over the same off-overrides node-cli applies', async () => {
+		const config = await buildScanConfig();
+		const rules = Object.assign({}, ...config.map((block) => block.rules ?? {}));
+
+		for (const rule of [
+			'n8n-nodes-base/cred-class-field-documentation-url-miscased',
+			'n8n-nodes-base/cred-class-field-type-options-password-missing',
+			'n8n-nodes-base/node-class-description-inputs-wrong-regular-node',
+			'n8n-nodes-base/node-class-description-outputs-wrong',
+			'n8n-nodes-base/node-param-type-options-max-value-present',
+		]) {
+			expect(rules[rule]).toBe('off');
+		}
+	});
+});
+
 describe('analyzePackage', () => {
 	let fixtureDir;
 
@@ -56,8 +106,12 @@ describe('analyzePackage', () => {
 			'package.json': {
 				name: 'n8n-nodes-fixture',
 				version: '1.0.0',
+				description: 'A fixture community node package',
+				license: 'MIT',
+				author: { name: 'Test Author', email: 'test@example.com' },
 				keywords: ['n8n-community-node-package'],
 				peerDependencies: { 'n8n-workflow': '*' },
+				n8n: { n8nNodesApiVersion: 1, nodes: ['dist/nodes/Foo/Foo.node.js'] },
 			},
 			'index.js': "module.exports = {};\n",
 		});
@@ -85,6 +139,42 @@ describe('analyzePackage', () => {
 		expect(result.details).toContain('no-forbidden-lifecycle-scripts');
 	});
 
+	// A well-formed node package's compiled sources must not trip the external
+	// node rules — those rules can't see enough in `.d.ts`/`.js` output to fire,
+	// so scanning must not produce false positives on legitimate packages.
+	it('does not false-positive on a well-formed node package layout (CE-1606)', async () => {
+		fixtureDir = makeFixturePackage({
+			'package.json': {
+				name: 'n8n-nodes-fixture',
+				version: '1.0.0',
+				description: 'A fixture community node package',
+				license: 'MIT',
+				author: { name: 'Test Author', email: 'test@example.com' },
+				keywords: ['n8n-community-node-package'],
+				peerDependencies: { 'n8n-workflow': '*' },
+				n8n: { n8nNodesApiVersion: 1, nodes: ['dist/nodes/Foo/Foo.node.js'] },
+			},
+			'dist/nodes/Foo/Foo.node.d.ts': `export declare class Foo {
+    description: {
+        displayName: string;
+        name: string;
+        properties: {
+            displayName: string;
+            name: string;
+            type: string;
+            default: string;
+        }[];
+    };
+}
+`,
+			'dist/nodes/Foo/Foo.node.js': "\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.Foo = void 0;\nclass Foo {}\nexports.Foo = Foo;\n",
+		});
+
+		const result = await analyzePackage(fixtureDir);
+
+		expect(result.passed).toBe(true);
+	});
+
 	it('returns passed when the package contains no lintable files', async () => {
 		fixtureDir = makeFixturePackage({
 			'README.md': '# empty package\n',