[eslint] add rule for validating cross-boundary imports (#137116)

packages/kbn-repo-source-classifier/BUILD.bazel

@@ -0,0 +1,119 @@
+load("@npm//@bazel/typescript:index.bzl", "ts_config")
+load("@build_bazel_rules_nodejs//:index.bzl", "js_library")
+load("//src/dev/bazel:index.bzl", "jsts_transpiler", "pkg_npm", "pkg_npm_types", "ts_project")
+
+PKG_DIRNAME = "kbn-repo-source-classifier"
+PKG_REQUIRE_NAME = "@kbn/repo-source-classifier"
+
+SOURCE_FILES = glob(
+  [
+    "src/**/*.ts",
+  ],
+  exclude = [
+    "**/*.test.*",
+    "**/*.stories.*",
+  ],
+)
+
+SRCS = SOURCE_FILES
+
+filegroup(
+  name = "srcs",
+  srcs = SRCS,
+)
+
+NPM_MODULE_EXTRA_FILES = [
+  "package.json",
+]
+
+# In this array place runtime dependencies, including other packages and NPM packages
+# which must be available for this code to run.
+#
+#  To reference other packages use:
+#    "//repo/relative/path/to/package"
+#    eg. "//packages/kbn-utils"
+#
+#  To reference a NPM package use:
+#    "@npm//name-of-package"
+#    eg. "@npm//lodash"
+RUNTIME_DEPS = [
+]
+
+# In this array place dependencies necessary to build the types, which will include the
+# :npm_module_types target of other packages and packages from NPM, including @types/*
+# packages.
+#
+#  To reference the types for another package use:
+#    "//repo/relative/path/to/package:npm_module_types"
+#    eg. "//packages/kbn-utils:npm_module_types"
+#
+#  References to NPM packages work the same as RUNTIME_DEPS
+TYPES_DEPS = [
+  "@npm//@types/node",
+  "@npm//@types/jest",
+  "@npm//normalize-path",
+  "//packages/kbn-import-resolver:npm_module_types",
+  "//packages/kbn-utils:npm_module_types",
+]
+
+jsts_transpiler(
+  name = "target_node",
+  srcs = SRCS,
+  build_pkg_name = package_name(),
+)
+
+ts_config(
+  name = "tsconfig",
+  src = "tsconfig.json",
+  deps = [
+    "//:tsconfig.base.json",
+    "//:tsconfig.bazel.json",
+  ],
+)
+
+ts_project(
+  name = "tsc_types",
+  args = ['--pretty'],
+  srcs = SRCS,
+  deps = TYPES_DEPS,
+  declaration = True,
+  declaration_map = True,
+  emit_declaration_only = True,
+  out_dir = "target_types",
+  root_dir = "src",
+  tsconfig = ":tsconfig",
+)
+
+js_library(
+  name = PKG_DIRNAME,
+  srcs = NPM_MODULE_EXTRA_FILES,
+  deps = RUNTIME_DEPS + [":target_node"],
+  package_name = PKG_REQUIRE_NAME,
+  visibility = ["//visibility:public"],
+)
+
+pkg_npm(
+  name = "npm_module",
+  deps = [":" + PKG_DIRNAME],
+)
+
+filegroup(
+  name = "build",
+  srcs = [":npm_module"],
+  visibility = ["//visibility:public"],
+)
+
+pkg_npm_types(
+  name = "npm_module_types",
+  srcs = SRCS,
+  deps = [":tsc_types"],
+  package_name = PKG_REQUIRE_NAME,
+  tsconfig = ":tsconfig",
+  visibility = ["//visibility:public"],
+)
+
+filegroup(
+  name = "build_types",
+  srcs = [":npm_module_types"],
+  visibility = ["//visibility:public"],
+)

packages/kbn-repo-source-classifier/README.mdx

@@ -0,0 +1,31 @@
+---
+id: kibDevDocsOpsRepoSourceClassifier
+slug: /kibana-dev-docs/ops/repo-source-classifier
+title: "@kbn/repo-source-classifier"
+description: 'The tool which classifies source files into categories'
+date: 2022-07-25
+tags: ['kibana', 'dev', 'contributor', 'operations', 'packages', 'scripts']
+---
+
+This package exposes a class which can be used to efficiently classify all of the files in the repository into one of the following groups:
+
+- `server package`: plugin code in the root `server/` directory, eventually this will include packages of type `server-plugin` or `server-shared`
+ - `browser package`: plugin code in the root `public/` directory (and a few others in specific plugins), eventually this will include packages of type `browser-plugin` or `browser-shared`
+ - `common packages`: includes any existing package, plugin code in root `common/` directories, (and a few others in specific plugins), Eventually this will include `common-shared` packages
+ - `tests or mocks`: code that is loaded by jest/storybook, and mocks/helpers intended for use by that code. These files usually live along side package code but will have a separate dependency tree and are pieces of code which should never end up in the product.
+ - `static`: static files, currently any .json file or things loaded via `raw-loader` in browser code
+ - `tooling`: scripts, config files for tools like eslint, webpack, etc. 
+ - `non-package`: code that lives outside of packages/plugins or doesn't fit into other more specific categories. Once the package project is complete this category should be limited to just `@kbn/pm`
+
+This is a map of types to the types they are allowed to import:
+ - `non-package`: `non-package`, `server package`, `browser package`, `common package` or `static`
+ - `server package`: `common package`, `server package`, or `static`
+ - `browser package`: `common package`, `browser package`, or `static`
+ - `common package`: `common package` or`static`
+ - `static`: static files are not allowed to have dependencies
+ - `tests or mocks`: anything
+ - `tooling`: anything
+
+The `RepoSourceClassifier` class implements several caches to make these lookups as efficient as possible in ESLint when all imports across the entire repository are validated. This cache lasts for the lifetime of the class and to invalidate the cache the object should just be discarded and a new instance created.
+
+A CLI is provided for inspecting the results of the classifier, check out `node scripts/classify_source --help` for more information about usage.

packages/kbn-repo-source-classifier/jest.config.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+module.exports = {
+  preset: '@kbn/test/jest_node',
+  rootDir: '../..',
+  roots: ['<rootDir>/packages/kbn-repo-source-classifier'],
+};

packages/kbn-repo-source-classifier/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@kbn/repo-source-classifier",
+  "private": true,
+  "version": "1.0.0",
+  "main": "./target_node/index.js",
+  "license": "SSPL-1.0 OR Elastic License 2.0",
+  "kibana": {
+    "devOnly": true
+  }
+}

packages/kbn-repo-source-classifier/src/config.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+// file names which indicate that the file is a testing file
+export const RANDOM_TEST_FILE_NAMES = new Set([
+  'jest_setup',
+  'test_data',
+  'test_helper',
+  'test_helpers',
+  'stubs',
+  'test_utils',
+  'test_utilities',
+  'rtl_helpers',
+  'enzyme_helpers',
+  'fixtures',
+  'testbed',
+]);
+
+// tags are found in filenames after a `.`, like `name.tag.ts`
+export const TEST_TAG = new Set([
+  'test',
+  'mock',
+  'mocks',
+  'stories',
+  'story',
+  'stub',
+  'fixture',
+  'story_decorators',
+  'test_helpers',
+]);
+
+// directories where test specific files are assumed to live, any file in a directory with these names is assumed to be test related
+export const TEST_DIR = new Set([
+  'cypress',
+  'test',
+  'tests',
+  'testing',
+  'mock',
+  'mocks',
+  '__jest__',
+  '__mock__',
+  '__test__',
+  '__mocks__',
+  '__stories__',
+  '__fixtures__',
+  '__snapshots__',
+  'stub',
+  'e2e',
+  'ftr_e2e',
+  'storybook',
+  '.storybook',
+  'integration_tests',
+  ...RANDOM_TEST_FILE_NAMES,
+]);

packages/kbn-repo-source-classifier/src/index.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export type { ModuleType } from './module_type';
+export { RepoSourceClassifier } from './repo_source_classifier';

packages/kbn-repo-source-classifier/src/module_id.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { ModuleType } from './module_type';
+import { PkgInfo } from './pkg_info';
+
+export interface ModuleId {
+  /** Type of the module */
+  type: ModuleType;
+  /** repo relative path to the module's source file */
+  repoRel: string;
+  /** info about the package the source file is within, in the case the file is found within a package */
+  pkgInfo?: PkgInfo;
+}

packages/kbn-repo-source-classifier/src/module_type.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export type ModuleType =
+  | 'non-package'
+  | 'tests or mocks'
+  | 'static'
+  | 'tooling'
+  | 'server package'
+  | 'browser package'
+  | 'common package';

packages/kbn-repo-source-classifier/src/pkg_info.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export interface PkgInfo {
+  /** id of the package this file is from */
+  pkgId: string;
+  /** Relative path to a file within a package directory */
+  rel: string;
+  /** Absolute path to the package directory */
+  pkgDir: string;
+}

packages/kbn-repo-source-classifier/src/repo_path.ts

@@ -0,0 +1,102 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import Path from 'path';
+
+import { REPO_ROOT } from '@kbn/utils';
+import { ImportResolver } from '@kbn/import-resolver';
+import normalizePath from 'normalize-path';
+
+import { PkgInfo } from './pkg_info';
+
+const getNormal = Path.sep === '/' ? (path: string) => path : normalizePath;
+
+/**
+ * A wraper around an absolute path in the repository. We create this object and bind it
+ * to a specific ImportResolver primarily so that we can use it as a key in WeakMap instances
+ * and make analysis as efficient as possible.
+ *
+ * Instead of managing many caches in a stateful class somewhere we instead write memoized
+ * functions which use weakmaps that are key'd off of a RepoPath instance. RepoPath instances
+ * are then cached by the overall classifier, and that instance can then be cached by
+ * the tool running analysis on the repository
+ */
+export class RepoPath {
+  constructor(public readonly absolute: string, public readonly resolver: ImportResolver) {}
+
+  private extname: string | undefined;
+  /** Get the extention for this path */
+  getExtname() {
+    if (this.extname === undefined) {
+      this.extname = Path.extname(this.absolute);
+    }
+
+    return this.extname;
+  }
+
+  private filename: string | undefined;
+  /** Get the filename, without the extension, for this path */
+  getFilename() {
+    if (this.filename === undefined) {
+      this.filename = Path.basename(this.absolute, this.getExtname());
+    }
+
+    return this.filename;
+  }
+
+  private repoRel: string | undefined;
+  /** get and cache the repo-relative version of the path */
+  getRepoRel() {
+    if (this.repoRel === undefined) {
+      this.repoRel = getNormal(Path.relative(REPO_ROOT, this.absolute));
+    }
+
+    return this.repoRel;
+  }
+
+  private segs: string[] | undefined;
+  /** get and cache the path segments from the repo-realtive versions of this path */
+  getSegs() {
+    if (this.segs === undefined) {
+      this.segs = Path.dirname(this.getRepoRel()).split('/');
+    }
+
+    return this.segs;
+  }
+
+  private pkgInfo: PkgInfo | null | undefined;
+  /** get and cache the package info for a path */
+  getPkgInfo() {
+    if (this.pkgInfo === undefined) {
+      const pkgId = this.resolver.getPackageIdForPath(this.absolute);
+      if (!pkgId) {
+        this.pkgInfo = null;
+      } else {
+        const pkgDir = this.resolver.getAbsolutePackageDir(pkgId);
+        if (!pkgDir) {
+          throw new Error(`unable to get package directory for package [${pkgId}]`);
+        }
+
+        const rel = getNormal(Path.relative(pkgDir, this.absolute));
+        if (rel.startsWith(`../`)) {
+          throw new Error(
+            `path [${this.getRepoRel()}] does not apear to be within package [${pkgId}]`
+          );
+        }
+
+        this.pkgInfo = {
+          pkgDir,
+          pkgId,
+          rel,
+        };
+      }
+    }
+
+    return this.pkgInfo;
+  }
+}

packages/kbn-repo-source-classifier/src/repo_source_classifier.ts

@@ -0,0 +1,192 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { ImportResolver } from '@kbn/import-resolver';
+import { ModuleId } from './module_id';
+import { ModuleType } from './module_type';
+import { RANDOM_TEST_FILE_NAMES, TEST_DIR, TEST_TAG } from './config';
+import { RepoPath } from './repo_path';
+
+export class RepoSourceClassifier {
+  constructor(private readonly resolver: ImportResolver) {}
+
+  private repoPaths = new Map<string, RepoPath>();
+  private ids = new Map<RepoPath, ModuleId>();
+
+  /**
+   * Get the cached repo path instance
+   */
+  private getRepoPath(path: string) {
+    const cached = this.repoPaths.get(path);
+
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const rp = new RepoPath(path, this.resolver);
+    this.repoPaths.set(path, rp);
+    return rp;
+  }
+
+  /**
+   * Is this a "test" file?
+   */
+  private isTestFile(path: RepoPath) {
+    const name = path.getFilename();
+
+    if (name.startsWith('mock_') || RANDOM_TEST_FILE_NAMES.has(name)) {
+      return true;
+    }
+
+    if (name.startsWith('_')) {
+      for (const tag of TEST_TAG) {
+        if (name.includes(tag)) {
+          return true;
+        }
+      }
+    }
+
+    const tag = name.split('.').at(-1);
+    if (tag && TEST_TAG.has(tag)) {
+      return true;
+    }
+
+    for (const seg of path.getSegs()) {
+      if (TEST_DIR.has(seg)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Is this a tooling file?
+   */
+  private isToolingFile(path: RepoPath) {
+    const segs = path.getSegs();
+    if (
+      segs.includes('scripts') &&
+      !path.getRepoRel().startsWith('src/plugins/data/server/scripts/')
+    ) {
+      return true;
+    }
+
+    if (path.getFilename() === 'webpack.config' && path.getPkgInfo()?.pkgId !== '@kbn/optimizer') {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Apply canvas specific rules
+   * @param root the root dir within the canvas plugin
+   * @param dirs the directories after the root dir
+   * @returns a type, or undefined if the file should be classified as a standard file
+   */
+  private classifyCanvas(root: string, dirs: string[]): ModuleType | undefined {
+    if (root === 'canvas_plugin_src') {
+      if (dirs[0] === 'expression_types') {
+        return 'common package';
+      }
+
+      const subRoot = dirs.slice(0, 2).join('/');
+      if (subRoot === 'functions/external' || subRoot === 'functions/server') {
+        return 'server package';
+      }
+
+      return 'browser package';
+    }
+
+    if (root === 'i18n') {
+      return 'common package';
+    }
+
+    if (root === 'shareable_runtime') {
+      return 'non-package';
+    }
+
+    if (root === 'tasks') {
+      return 'tests or mocks';
+    }
+  }
+
+  /**
+   * Determine the "type" of a file
+   */
+  private getType(path: RepoPath): ModuleType {
+    if (path.getExtname() === '.json') {
+      return 'static';
+    }
+
+    if (this.isTestFile(path)) {
+      return 'tests or mocks';
+    }
+
+    if (this.isToolingFile(path)) {
+      return 'tooling';
+    }
+
+    const pkgInfo = path.getPkgInfo();
+    if (!pkgInfo) {
+      return 'non-package';
+    }
+
+    const { pkgId, rel } = pkgInfo;
+    const pkgIdWords = new Set(pkgId.split(/\W+/));
+    // treat any package with "mocks" or "storybook" in the ID as a test-specific package
+    if (pkgIdWords.has('mocks') || pkgIdWords.has('storybook') || pkgIdWords.has('test')) {
+      return 'tests or mocks';
+    }
+
+    if (path.resolver.isBazelPackage(pkgId)) {
+      return 'common package';
+    }
+
+    const [root, ...dirs] = rel.split('/');
+
+    if (pkgId === '@kbn/core' && root === 'types') {
+      return 'common package';
+    }
+
+    if (pkgId === '@kbn/canvas-plugin') {
+      const type = this.classifyCanvas(root, dirs);
+      if (type) {
+        return type;
+      }
+    }
+
+    if (root === 'public' || root === 'static') {
+      return 'browser package';
+    }
+
+    if (root === 'server') {
+      return 'server package';
+    }
+
+    return 'common package';
+  }
+
+  classify(absolute: string) {
+    const path = this.getRepoPath(absolute);
+    const cached = this.ids.get(path);
+
+    if (cached) {
+      return cached;
+    }
+
+    const id: ModuleId = {
+      type: this.getType(path),
+      repoRel: path.getRepoRel(),
+      pkgInfo: path.getPkgInfo() ?? undefined,
+    };
+    this.ids.set(path, id);
+    return id;
+  }
+}

packages/kbn-repo-source-classifier/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.bazel.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "target_types",
+    "rootDir": "src",
+    "stripInternal": false,
+    "types": [
+      "jest",
+      "node"
+    ]
+  },
+  "include": [
+    "src/**/*"
+  ]
+}