@code-pushup/eslint-plugin 0.1.1 → 0.3.0

package/README.md

@@ -35,6 +35,8 @@ Detected ESLint rules are mapped to Code PushUp audits. Audit reports are calcul
    Remember that Code PushUp only collects and uploads the results, it doesn't fail if errors are found.
    So you can be more strict than in most linter setups, the idea is to set aspirational goals and track your progress.
 
+   > 💡 We recommend extending our own [`@code-pushup/eslint-config`](https://www.npmjs.com/package/@code-pushup/eslint-config). 😇
+
 4. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.js`).
 
    Pass in the path to your ESLint config file, along with glob patterns for which files you wish to target (relative to `process.cwd()`).
@@ -51,6 +53,34 @@ Detected ESLint rules are mapped to Code PushUp audits. Audit reports are calcul
    };
    ```
 
+   If you're using an Nx monorepo, additional helper functions are provided to simplify your configuration:
+
+   - If you wish to combine all projects in your workspace into one report, use the `eslintConfigFromNxProjects` helper:
+
+     ```js
+     import eslintPlugin, { eslintConfigFromNxProjects } from '@code-pushup/eslint-plugin';
+
+     export default {
+       plugins: [
+         // ...
+         await eslintPlugin(await eslintConfigFromNxProjects()),
+       ],
+     };
+     ```
+
+   - If you wish to target a specific project along with other projects it depends on, use the `eslintConfigFromNxProject` helper and pass in in your project name:
+
+     ```js
+     import eslintPlugin, { eslintConfigFromNxProject } from '@code-pushup/eslint-plugin';
+
+     export default {
+       plugins: [
+         // ...
+         await eslintPlugin(await eslintConfigFromNxProject('<PROJECT-NAME>')),
+       ],
+     };
+     ```
+
 5. (Optional) Reference audits (or groups) which you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
 
    Assign weights based on what influence each ESLint rule should have on the overall category score (assign weight 0 to only include as extra info, without influencing category score).

package/bin.js

@@ -9,6 +9,11 @@ import { z as z2 } from "zod";
 import { z } from "zod";
 import { MATERIAL_ICONS } from "@code-pushup/portal-client";
 
+// packages/models/src/lib/implementation/limits.ts
+var MAX_SLUG_LENGTH = 128;
+var MAX_TITLE_LENGTH = 256;
+var MAX_DESCRIPTION_LENGTH = 65536;
+
 // packages/models/src/lib/implementation/utils.ts
 var slugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var filenameRegex = /^(?!.*[ \\/:*?"<>|]).+$/;
@@ -44,12 +49,12 @@ function executionMetaSchema(options = {
 function slugSchema(description = "Unique ID (human-readable, URL-safe)") {
   return z.string({ description }).regex(slugRegex, {
     message: "The slug has to follow the pattern [0-9a-z] followed by multiple optional groups of -[0-9a-z]. e.g. my-slug"
-  }).max(128, {
-    message: "slug can be max 128 characters long"
+  }).max(MAX_SLUG_LENGTH, {
+    message: `slug can be max ${MAX_SLUG_LENGTH} characters long`
   });
 }
 function descriptionSchema(description = "Description (markdown)") {
-  return z.string({ description }).max(65536).optional();
+  return z.string({ description }).max(MAX_DESCRIPTION_LENGTH).optional();
 }
 function docsUrlSchema(description = "Documentation site") {
   return urlSchema(description).optional().or(z.string().max(0));
@@ -58,7 +63,7 @@ function urlSchema(description) {
   return z.string({ description }).url();
 }
 function titleSchema(description = "Descriptive name") {
-  return z.string({ description }).max(256);
+  return z.string({ description }).max(MAX_TITLE_LENGTH);
 }
 function metaSchema(options) {
   const {
@@ -550,13 +555,6 @@ function pluralizeToken(token, times = 0) {
 }
 
 // packages/utils/src/lib/file-system.ts
-function toUnixPath(path, options) {
-  const unixPath = path.replace(/\\/g, "/");
-  if (options?.toRelative) {
-    return unixPath.replace(process.cwd().replace(/\\/g, "/") + "/", "");
-  }
-  return unixPath;
-}
 async function readTextFile(path) {
   const buffer = await readFile(path);
   return buffer.toString();
@@ -565,6 +563,13 @@ async function readJsonFile(path) {
   const text = await readTextFile(path);
   return JSON.parse(text);
 }
+function toUnixPath(path, options) {
+  const unixPath = path.replace(/\\/g, "/");
+  if (options?.toRelative) {
+    return unixPath.replace(process.cwd().replace(/\\/g, "/") + "/", "");
+  }
+  return unixPath;
+}
 function pluginWorkDir(slug) {
   return join("node_modules", ".code-pushup", slug);
 }

package/index.js

@@ -1,11 +1,11 @@
 // packages/plugin-eslint/src/lib/eslint-plugin.ts
-import { mkdir, writeFile } from "fs/promises";
+import { mkdir as mkdir2, writeFile } from "fs/promises";
 import { dirname as dirname2, join as join3 } from "path";
 import { fileURLToPath } from "url";
 
 // packages/plugin-eslint/package.json
 var name = "@code-pushup/eslint-plugin";
-var version = "0.1.1";
+var version = "0.3.0";
 
 // packages/plugin-eslint/src/lib/config.ts
 import { z } from "zod";
@@ -31,6 +31,11 @@ import { z as z3 } from "zod";
 import { z as z2 } from "zod";
 import { MATERIAL_ICONS } from "@code-pushup/portal-client";
 
+// packages/models/src/lib/implementation/limits.ts
+var MAX_SLUG_LENGTH = 128;
+var MAX_TITLE_LENGTH = 256;
+var MAX_DESCRIPTION_LENGTH = 65536;
+
 // packages/models/src/lib/implementation/utils.ts
 var slugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var filenameRegex = /^(?!.*[ \\/:*?"<>|]).+$/;
@@ -66,12 +71,12 @@ function executionMetaSchema(options = {
 function slugSchema(description = "Unique ID (human-readable, URL-safe)") {
   return z2.string({ description }).regex(slugRegex, {
     message: "The slug has to follow the pattern [0-9a-z] followed by multiple optional groups of -[0-9a-z]. e.g. my-slug"
-  }).max(128, {
-    message: "slug can be max 128 characters long"
+  }).max(MAX_SLUG_LENGTH, {
+    message: `slug can be max ${MAX_SLUG_LENGTH} characters long`
   });
 }
 function descriptionSchema(description = "Description (markdown)") {
-  return z2.string({ description }).max(65536).optional();
+  return z2.string({ description }).max(MAX_DESCRIPTION_LENGTH).optional();
 }
 function docsUrlSchema(description = "Documentation site") {
   return urlSchema(description).optional().or(z2.string().max(0));
@@ -80,7 +85,7 @@ function urlSchema(description) {
   return z2.string({ description }).url();
 }
 function titleSchema(description = "Descriptive name") {
-  return z2.string({ description }).max(256);
+  return z2.string({ description }).max(MAX_TITLE_LENGTH);
 }
 function metaSchema(options) {
   const {
@@ -551,14 +556,36 @@ var reportSchema = packageVersionSchema({
 // packages/utils/src/lib/file-system.ts
 import { bundleRequire } from "bundle-require";
 import chalk from "chalk";
+import { mkdir, readFile, readdir, stat } from "fs/promises";
 import { join } from "path";
 
 // packages/utils/src/lib/formatting.ts
 function slugify(text) {
   return text.trim().toLowerCase().replace(/\s+|\//g, "-").replace(/[^a-z0-9-]/g, "");
 }
+function truncateText(text, maxChars) {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  const ellipsis = "...";
+  return text.slice(0, maxChars - ellipsis.length) + ellipsis;
+}
+function truncateTitle(text) {
+  return truncateText(text, MAX_TITLE_LENGTH);
+}
+function truncateDescription(text) {
+  return truncateText(text, MAX_DESCRIPTION_LENGTH);
+}
 
 // packages/utils/src/lib/file-system.ts
+async function fileExists(path) {
+  try {
+    const stats = await stat(path);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
 function pluginWorkDir(slug) {
   return join("node_modules", ".code-pushup", slug);
 }
@@ -781,8 +808,8 @@ function ruleToAudit({ ruleId, meta, options }) {
   ];
   return {
     slug: ruleIdToSlug(ruleId, options),
-    title: meta.docs?.description ?? name2,
-    description: lines.join("\n\n"),
+    title: truncateTitle(meta.docs?.description ?? name2),
+    description: truncateDescription(lines.join("\n\n")),
     ...meta.docs?.url && {
       docsUrl: meta.docs.url
     }
@@ -840,7 +867,7 @@ async function eslintPlugin(config) {
   const eslint = setupESLint(eslintrc);
   const { audits, groups } = await listAuditsAndGroups(eslint, patterns);
   if (typeof eslintrc !== "string") {
-    await mkdir(dirname2(ESLINTRC_PATH), { recursive: true });
+    await mkdir2(dirname2(ESLINTRC_PATH), { recursive: true });
     await writeFile(ESLINTRC_PATH, JSON.stringify(eslintrc));
   }
   const eslintrcPath = typeof eslintrc === "string" ? eslintrc : ESLINTRC_PATH;
@@ -853,7 +880,7 @@ async function eslintPlugin(config) {
     title: "ESLint",
     icon: "eslint",
     description: "Official Code PushUp ESLint plugin",
-    // TODO: docsUrl (package README, once published)
+    docsUrl: "https://www.npmjs.com/package/@code-pushup/eslint-plugin",
     packageName: name,
     version,
     audits,
@@ -867,8 +894,101 @@ async function eslintPlugin(config) {
   };
 }
 
+// packages/plugin-eslint/src/lib/nx/utils.ts
+import { join as join4 } from "node:path";
+async function findCodePushupEslintrc(project) {
+  const name2 = "code-pushup.eslintrc";
+  const extensions = ["json", "js", "cjs", "yml", "yaml"];
+  for (const ext of extensions) {
+    const filename = `./${project.root}/${name2}.${ext}`;
+    if (await fileExists(join4(process.cwd(), filename))) {
+      return filename;
+    }
+  }
+  return null;
+}
+function getLintFilePatterns(project) {
+  const options = project.targets?.["lint"]?.options;
+  return options?.lintFilePatterns == null ? [] : toArray(options.lintFilePatterns);
+}
+function getEslintConfig(project) {
+  const options = project.targets?.["lint"]?.options;
+  return options?.eslintConfig ?? `./${project.root}/.eslintrc.json`;
+}
+
+// packages/plugin-eslint/src/lib/nx/projects-to-config.ts
+async function nxProjectsToConfig(projectGraph, predicate = () => true) {
+  const { readProjectsConfigurationFromProjectGraph } = await import("@nx/devkit");
+  const projectsConfiguration = readProjectsConfigurationFromProjectGraph(projectGraph);
+  const projects = Object.values(projectsConfiguration.projects).filter((project) => "lint" in (project.targets ?? {})).filter(predicate).sort((a, b) => a.root.localeCompare(b.root));
+  const eslintConfig = {
+    root: true,
+    overrides: await Promise.all(
+      projects.map(async (project) => ({
+        files: getLintFilePatterns(project),
+        extends: await findCodePushupEslintrc(project) ?? getEslintConfig(project)
+      }))
+    )
+  };
+  const patterns = projects.flatMap((project) => [
+    ...getLintFilePatterns(project),
+    // HACK: ESLint.calculateConfigForFile won't find rules included only for subsets of *.ts when globs used
+    // so we explicitly provide additional patterns used by @code-pushup/eslint-config to ensure those rules are included
+    // this workaround won't be necessary once flat configs are stable (much easier to find all rules)
+    `${project.sourceRoot}/*.spec.ts`,
+    // jest/* and vitest/* rules
+    `${project.sourceRoot}/*.cy.ts`,
+    // cypress/* rules
+    `${project.sourceRoot}/*.stories.ts`,
+    // storybook/* rules
+    `${project.sourceRoot}/.storybook/main.ts`
+    // storybook/no-uninstalled-addons rule
+  ]);
+  return {
+    eslintrc: eslintConfig,
+    patterns
+  };
+}
+
+// packages/plugin-eslint/src/lib/nx/find-all-projects.ts
+async function eslintConfigFromNxProjects() {
+  const { createProjectGraphAsync } = await import("@nx/devkit");
+  const projectGraph = await createProjectGraphAsync({ exitOnError: false });
+  return nxProjectsToConfig(projectGraph);
+}
+
+// packages/plugin-eslint/src/lib/nx/traverse-graph.ts
+function findAllDependencies(entry, projectGraph) {
+  const results = /* @__PURE__ */ new Set();
+  const queue = [entry];
+  while (queue.length > 0) {
+    const source = queue.shift();
+    const dependencies = projectGraph.dependencies[source];
+    for (const { target } of dependencies ?? []) {
+      if (!results.has(target) && target !== entry) {
+        results.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return results;
+}
+
+// packages/plugin-eslint/src/lib/nx/find-project-with-deps.ts
+async function eslintConfigFromNxProject(projectName) {
+  const { createProjectGraphAsync } = await import("@nx/devkit");
+  const projectGraph = await createProjectGraphAsync({ exitOnError: false });
+  const dependencies = findAllDependencies(projectName, projectGraph);
+  return nxProjectsToConfig(
+    projectGraph,
+    (project) => !!project.name && (project.name === projectName || dependencies.has(project.name))
+  );
+}
+
 // packages/plugin-eslint/src/index.ts
 var src_default = eslintPlugin;
 export {
-  src_default as default
+  src_default as default,
+  eslintConfigFromNxProject,
+  eslintConfigFromNxProjects
 };

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@code-pushup/eslint-plugin",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "dependencies": {
     "@code-pushup/utils": "*",
+    "@code-pushup/models": "*",
     "eslint": "~8.46.0",
-    "zod": "^3.22.4",
-    "@code-pushup/models": "*"
+    "zod": "^3.22.4"
+  },
+  "peerDependencies": {
+    "@nx/devkit": "^17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nx/devkit": {
+      "optional": true
+    }
   },
   "type": "module",
   "main": "./index.js",

package/src/index.d.ts

@@ -1,3 +1,4 @@
 import { eslintPlugin } from './lib/eslint-plugin';
 export default eslintPlugin;
 export type { ESLintPluginConfig } from './lib/config';
+export { eslintConfigFromNxProject, eslintConfigFromNxProjects, } from './lib/nx';

package/src/lib/nx/find-all-projects.d.ts

@@ -0,0 +1,23 @@
+import type { ESLintPluginConfig } from '../config';
+/**
+ * Finds all Nx projects in workspace and converts their lint configurations to Code PushUp ESLint plugin parameters.
+ *
+ * Use when you wish to automatically include every Nx project in a single Code PushUp project.
+ * If you prefer to only include a subset of your Nx monorepo, refer to {@link eslintConfigFromNxProject} instead.
+ *
+ * @example
+ * import eslintPlugin, {
+ *   eslintConfigFromNxProjects,
+ * } from '@code-pushup/eslint-plugin';
+ *
+ * export default {
+ *   plugins: [
+ *     await eslintPlugin(
+ *       await eslintConfigFromNxProjects()
+ *     )
+ *   ]
+ * }
+ *
+ * @returns ESLint config and patterns, intended to be passed to {@link eslintPlugin}
+ */
+export declare function eslintConfigFromNxProjects(): Promise<ESLintPluginConfig>;

package/src/lib/nx/find-project-with-deps.d.ts

@@ -0,0 +1,26 @@
+import type { ESLintPluginConfig } from '../config';
+/**
+ * Accepts a target Nx projects, finds projects it depends on, and converts lint configurations to Code PushUp ESLint plugin parameters.
+ *
+ * Use when you wish to include a targetted subset of your Nx monorepo in your Code PushUp project.
+ * If you prefer to include all Nx projects, refer to {@link eslintConfigFromNxProjects} instead.
+ *
+ * @example
+ * import eslintPlugin, {
+ *   eslintConfigFromNxProject,
+ * } from '@code-pushup/eslint-plugin';
+ *
+ * const projectName = 'backoffice'; // <-- name from project.json
+ *
+ * export default {
+ *   plugins: [
+ *     await eslintPlugin(
+ *       await eslintConfigFromNxProject(projectName)
+ *     )
+ *   ]
+ * }
+ *
+ * @param projectName Nx project serving as main entry point
+ * @returns ESLint config and patterns, intended to be passed to {@link eslintPlugin}
+ */
+export declare function eslintConfigFromNxProject(projectName: string): Promise<ESLintPluginConfig>;

package/src/lib/nx/index.d.ts

@@ -0,0 +1,2 @@
+export { eslintConfigFromNxProjects } from './find-all-projects';
+export { eslintConfigFromNxProject } from './find-project-with-deps';

package/src/lib/nx/projects-to-config.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectConfiguration, ProjectGraph } from '@nx/devkit';
+import type { ESLintPluginConfig } from '../config';
+export declare function nxProjectsToConfig(projectGraph: ProjectGraph, predicate?: (project: ProjectConfiguration) => boolean): Promise<ESLintPluginConfig>;

package/src/lib/nx/traverse-graph.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectGraph } from '@nx/devkit';
+export declare function findAllDependencies(entry: string, projectGraph: ProjectGraph): ReadonlySet<string>;

package/src/lib/nx/utils.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectConfiguration } from '@nx/devkit';
+export declare function findCodePushupEslintrc(project: ProjectConfiguration): Promise<string | null>;
+export declare function getLintFilePatterns(project: ProjectConfiguration): string[];
+export declare function getEslintConfig(project: ProjectConfiguration): string;