chore: extracts (npm and GH) constraint linter into separate package (#4888)

Extraction of our package.json and GH action constraints linter to a new
separate `@kumahq` package.

Note: I got an LLM to do this, reined it in, and then heavily amended it
following my own review, please take this into account when reviewing to
make sure the original functionality remains as-is. I'm also giving this
a secondary review myself.

I also tried to make the "nested workspace" functionality we have as an
optional (not applied by default) feature (undocumented) seeing as this
feature is probably very rarely required.

---------

Signed-off-by: John Cowen <john.cowen@konghq.com>

Author: johncowen

package-lock.json

@@ -12,6 +12,9 @@ BrandiJS with token-based service registration for managing application
 dependencies.
 - **[@kumahq/data](./data)** - Vue components (`DataSource` and `DataLoader`) for
 handling external data fetching, loading states, and error handling.
+- **[@kumahq/eslint-package-constraints](./eslint-package-constraints)** - ESLint flat config for
+enforcing `package.json` and GitHub workflow version constraints across a monorepo, including
+dependency version range rules and SHA pinning for third-party actions.
 - **[@kumahq/fake-api](./fake-api)** - Utilities for loading and serving mock HTTP API
 responses with generated fake data via FakerJS for development and testing.
 - **[@kumahq/gherkin-web](./gherkin-web)** - Gherkin/Cucumber step definitions for testing web

packages/README.md

@@ -43,19 +43,18 @@
     "@cucumber/gherkin-utils": "^11.0.0",
     "@eslint/js": "^9.39.4",
     "@kumahq/gherkin-web": "*",
+    "@kumahq/eslint-package-constraints": "*",
     "@playwright/test": "^1.59.1",
     "@stylistic/eslint-plugin": "^5.10.0",
     "@stylistic/stylelint-plugin": "^5.1.0",
     "@vue/eslint-config-typescript": "^14.7.0",
     "@vue/tsconfig": "^0.9.1",
     "deepmerge": "^4.3.1",
     "esbuild": "^0.28.0",
-    "escape-string-regexp": "^4.0.0",
     "eslint": "^9.39.4",
     "eslint-import-resolver-alias": "^1.1.2",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-json-schema-validator": "^6.2.0",
     "eslint-plugin-no-unsanitized": "^4.1.5",
     "eslint-plugin-vue": "^10.9.0",
     "globals": "^17.5.0",

packages/config/package.json

@@ -1,30 +1,11 @@
 import eslint from '@eslint/js'
+import { defineConfig as packageConstraints, getNpmWorkspaceJSON } from '@kumahq/eslint-package-constraints'
 import stylistic from '@stylistic/eslint-plugin'
 import { defineConfigWithVueTs, vueTsConfigs } from '@vue/eslint-config-typescript'
-import escape from 'escape-string-regexp'
 import importPlugin from 'eslint-plugin-import'
-import jsonSchemaValidatorPlugin from 'eslint-plugin-json-schema-validator'
 import nounsanitized from 'eslint-plugin-no-unsanitized'
 import vuePlugin from 'eslint-plugin-vue'
 import globals from 'globals'
-import { execSync } from 'node:child_process'
-import { readFileSync as read } from 'node:fs'
-import { resolve, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const $config = dirname(fileURLToPath(import.meta.resolve('@kumahq/config')))
-
-const workspace = JSON.parse(
-  execSync('npm query :root').toString(),
-).at(0)
-
-const packageSchema = JSON.parse(
-  read(resolve(`${$config}/package.schema.json`), 'utf-8'),
-)
-
-const workflowSchema = JSON.parse(
-  read(resolve(`${$config}/workflow.schema.json`), 'utf-8'),
-)
 
 // Taken from https://github.com/vuejs/eslint-plugin-vue/blob/master/lib/utils/inline-non-void-elements.json.
 const INLINE_NON_VOID_ELEMENTS = [
@@ -76,39 +57,16 @@ export function createEslintConfig(
   {
     tsConfigPath = 'tsconfig.json',
     componentIgnorePatterns = [],
-    versionIgnorePatterns = {},
+    dependencyIgnorePatterns = {},
     workspaceRoot = false,
   } = {
     tsConfigPath: 'tsconfig.json',
     componentIgnorePatterns: [],
-    versionIgnorePatterns: {},
+    dependencyIgnorePatterns: {},
     workspaceRoot: false,
   },
 ) {
 
-  // amend our package.json schema depending on arguments
-  ((schema) => {
-    // 1. include any ignored version patterns
-    ['dependencies', 'devDependencies', 'peerDependencies'].forEach((item) => {
-      schema.properties[item].patternProperties = {
-        ...schema.properties[item].patternProperties,
-        ...versionIgnorePatterns[item] ?? {},
-      }
-    })
-
-    // 2. Take engines from the root of kumahq/kuma-gui and make sure
-    // any other workspace root using this linter use the same engines
-    Object.entries(workspace.engines).forEach(([key, value]) => {
-      schema.definitions[key].pattern = `^${escape(value)}$`
-    })
-
-    // 3. Any non-root package.json files shouldn't ever specify `engines`
-    if (!workspaceRoot) {
-      schema.properties.engines = {
-        not: {},
-      }
-    }
-  })(packageSchema)
 
   const vueTsConfig = defineConfigWithVueTs(
     ...vuePlugin.configs['flat/recommended'],
@@ -124,30 +82,6 @@ export function createEslintConfig(
     },
   ]
 
-  const jsonSchemaValidatorConfig = [
-    ...jsonSchemaValidatorPlugin.configs['flat/recommended'],
-    {
-      rules: {
-        'json-schema-validator/no-invalid': ['error', {
-          useSchemastoreCatalog: false,
-          mergeSchemas: true,
-          schemas: [
-            {
-              fileMatch: ['package.json'],
-              // our schema allows for ignoring individual dependencies if required
-              // see ./package.schema.json patternProperties examples
-              schema: packageSchema,
-            },
-            {
-              fileMatch: ['.github/**/*.{yaml,yml}'],
-              schema: workflowSchema,
-            },
-          ],
-        }],
-      },
-    },
-  ]
-
   const stylisticConfig = {
     plugins: {
       '@stylistic': stylistic,
@@ -181,19 +115,24 @@ export function createEslintConfig(
       '@stylistic/semi': ['error', 'never'],
     },
   }
-
+  const workspaceJSON = getNpmWorkspaceJSON()
   return [
     // when linting workspaceRoots we want to ignore
     // sub-packages which are linted separately
     workspaceRoot ? {
-      ignores: workspace.workspaces,
+      ignores: workspaceJSON.workspaces,
     } : {},
-    //
     eslint.configs.recommended,
     nounsanitized.configs.recommended,
     ...vueTsConfig,
     ...importConfig,
-    ...jsonSchemaValidatorConfig,
+    //
+    ...packageConstraints({
+      workspaceRoot,
+      dependencyIgnorePatterns,
+      workspaceJSON,
+    }),
+    //
     stylisticConfig,
     {
       languageOptions: {

packages/config/src/eslint.js

@@ -0,0 +1,25 @@
+# Please keep this file free of actual scripts
+# It should only be used for adding "non-dot" aliases and documentation
+
+SHELL := /usr/bin/env bash -o pipefail
+
+NPM_WORKSPACE_ROOT := $(shell npm prefix)
+KUMAHQ_CONFIG := $(NPM_WORKSPACE_ROOT)/$(shell cat $(NPM_WORKSPACE_ROOT)/package-lock.json | jq -r '.packages | to_entries[] | select(.value.name == "@kumahq/config") | .key')
+MK := $(KUMAHQ_CONFIG)/src/mk
+
+## make help: if you're aren't sure use `make help`
+.DEFAULT_GOAL := help
+
+include $(MK)/index.mk
+
+.PHONY: help
+help: .help ## Display this help screen
+
+.PHONY: clean
+clean: .clean ## Dev: Remove all `node_modules` recursively
+
+.PHONY: install
+install: .install ## Dev: Install all dependencies
+
+.PHONY: lint
+lint: .lint/script ## Dev: Run all lint script checks (js,ts)

packages/eslint-package-constraints/Makefile

@@ -0,0 +1,34 @@
+# eslint-package-constraints
+
+ESLint package that enforces `package.json` and GitHub workflow version
+constraints across a monorepo.
+
+## Features
+
+- Validates `package.json` files against a JSON Schema that enforces consistent
+dependency version ranges and engine requirements. Defaults to preferring carat
+versions but allows ignore rules
+- Validates `.github/**/*.{yaml,yml}` workflow files against a schema that
+enforces immutable SHA pinning for third-party actions
+- Prevents non-root packages from specifying their own `engines` field
+- Locks any "nested workspaces" to the same `node`/`npm` engine versions as the
+"root-most" workspace
+
+## Usage
+
+```js
+import { defineConfig } from '@kumahq/eslint-package-constraints'
+
+export default [
+  ...defineConfig({
+    workspaceRoot: false, // set true if linting at the monorepo root, otherwise `engines` properties are not allowed in the package.json
+    dependencyIgnorePatterns: {
+      dependencies: { // we are amending prod dependencies only (other options are `devDependencies` and `peerDependencies`)
+        '@kong-ui-public/app-layout': {
+          '$ref': '#/definitions/exactOnlyVersion', // reuse our definition to enforce only specifying an "exact version constraint"
+        },
+      },
+    },
+  }),
+]
+```

packages/eslint-package-constraints/README.md

@@ -0,0 +1,9 @@
+/** @typedef {import('eslint').Linter.Config[]} Config */
+
+import { eslint } from '@kumahq/config'
+
+const /** @type Config */ config = [
+  ...eslint({}),
+]
+
+export default config

packages/eslint-package-constraints/eslint.config.js

@@ -0,0 +1,16 @@
+{
+  "name": "@kumahq/eslint-package-constraints",
+  "version": "0.1.0",
+  "private": true,
+  "description": "ESLint flat config for enforcing package.json and workflow constraints",
+  "author": "Kong",
+  "type": "module",
+  "main": "src/index.ts",
+  "dependencies": {
+    "escape-string-regexp": "^4.0.0",
+    "eslint-plugin-json-schema-validator": "^6.2.0"
+  },
+  "devDependencies": {
+    "@kumahq/config": "*"
+  }
+}

packages/eslint-package-constraints/package.json

@@ -0,0 +1,73 @@
+import escape from 'escape-string-regexp'
+import jsonSchemaValidatorPlugin from 'eslint-plugin-json-schema-validator'
+import { execSync } from 'node:child_process'
+import { readFileSync as read } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { Linter } from 'eslint'
+
+const $dir = dirname(fileURLToPath(import.meta.url))
+
+type DependencyKey = 'dependencies' | 'devDependencies' | 'peerDependencies'
+
+type Options = {
+  workspaceRoot?: boolean
+  dependencyIgnorePatterns?: Partial<
+    Record<DependencyKey, Record<string, unknown>>
+  >
+  workspaceJSON?: Record<string, unknown>
+}
+export const getNpmWorkspaceJSON = () => JSON.parse(execSync('npm query :root').toString()).at(0)
+export const defineConfig = ({
+  workspaceRoot = false,
+  dependencyIgnorePatterns = {},
+  workspaceJSON = {},
+}: Options = {}): Linter.Config[] => {
+  const packageSchema = JSON.parse(read(resolve($dir, 'package.schema.json'), 'utf-8'))
+  const workflowSchema = JSON.parse(read(resolve($dir, 'workflow.schema.json'), 'utf-8'))
+
+  // 1. include any ignored version patterns
+  ;(['dependencies', 'devDependencies', 'peerDependencies'] as DependencyKey[]).forEach((item) => {
+    packageSchema.properties[item].patternProperties = {
+      ...packageSchema.properties[item].patternProperties,
+      ...dependencyIgnorePatterns[item] ?? {},
+    }
+  })
+
+  // 2. Take engines from the workspace root and enforce them across all packages
+  if(workspaceJSON !== null && typeof workspaceJSON === 'object' && Object.keys(workspaceJSON).length > 0) {
+    Object.entries(workspaceJSON?.engines ?? {}).forEach(([key, value]) => {
+      packageSchema.definitions[key].pattern = `^${escape(value)}$`
+    })
+  }
+
+  // 3. Any non-root package.json files shouldn't ever specify `engines`
+  if (!workspaceRoot) {
+    packageSchema.properties.engines = { not: {} }
+  }
+
+  return [
+    ...jsonSchemaValidatorPlugin.configs['flat/recommended'],
+    {
+      rules: {
+        'json-schema-validator/no-invalid': ['error', {
+          useSchemastoreCatalog: false,
+          mergeSchemas: true,
+          schemas: [
+            {
+              fileMatch: ['package.json'],
+              // our schema allows for ignoring individual dependencies if required
+              // see ./package.schema.json patternProperties examples
+              schema: packageSchema,
+            },
+            {
+              fileMatch: ['.github/**/*.{yaml,yml}'],
+              schema: workflowSchema,
+            },
+          ],
+        }],
+      },
+    },
+  ]
+}