refactor: Add lines-around-comment rule

alan-agius4 · alan-agius4 · commit 743188ba6265 · 2024-09-11T12:10:54.000+02:00
I often struggle with spacing around block comments, so I've decided to add the `lines-around-comment` lint rule to help manage this. For more details, see the https://eslint.style/rules/js/lines-around-comment
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -33,8 +33,24 @@
     "project": "tsconfig.json",
     "sourceType": "module"
   },
-  "plugins": ["eslint-plugin-import", "header", "@typescript-eslint"],
+  "plugins": ["@stylistic", "@typescript-eslint", "eslint-plugin-import", "header"],
   "rules": {
+    "@stylistic/lines-around-comment": [
+      "error",
+      {
+        "allowArrayStart": true,
+        "allowBlockStart": true,
+        "allowClassStart": true,
+        "allowEnumStart": true,
+        "allowInterfaceStart": true,
+        "allowModuleStart": true,
+        "allowObjectStart": true,
+        "allowTypeStart": true,
+        "beforeBlockComment": true,
+        "ignorePattern": "@license"
+      }
+    ],
+    "@stylistic/spaced-comment": ["error", "always"],
     "@typescript-eslint/consistent-type-assertions": "error",
     "@typescript-eslint/no-explicit-any": "error",
     "@typescript-eslint/no-non-null-assertion": "error",
diff --git a/package.json b/package.json
@@ -90,6 +90,7 @@
     "@listr2/prompt-adapter-inquirer": "2.0.15",
     "@rollup/plugin-commonjs": "^26.0.0",
     "@rollup/plugin-node-resolve": "^13.0.5",
+    "@stylistic/eslint-plugin": "^2.8.0",
     "@types/babel__core": "7.20.5",
     "@types/browser-sync": "^2.27.0",
     "@types/express": "^4.16.0",
diff --git a/packages/angular/build/src/builders/dev-server/vite-server.ts b/packages/angular/build/src/builders/dev-server/vite-server.ts
@@ -709,6 +709,7 @@ function getDepOptimizationConfig({
 }
 
 const nodeJsBuiltinModules = new Set(builtinModules);
+
 /** Remove any Node.js builtin modules to avoid Vite's prebundling from processing them as files. */
 function removeNodeJsBuiltinModules(value: string): boolean {
   return !nodeJsBuiltinModules.has(value);
diff --git a/packages/angular/build/src/tools/esbuild/angular/compiler-plugin.ts b/packages/angular/build/src/tools/esbuild/angular/compiler-plugin.ts
@@ -39,6 +39,7 @@ export interface CompilerPluginOptions {
   sourcemap: boolean | 'external';
   tsconfig: string;
   jit?: boolean;
+
   /** Skip TypeScript compilation setup. This is useful to re-use the TypeScript compilation from another plugin. */
   noopTypeScriptCompilation?: boolean;
   advancedOptimizations?: boolean;
diff --git a/packages/angular/build/src/tools/esbuild/i18n-inliner-worker.ts b/packages/angular/build/src/tools/esbuild/i18n-inliner-worker.ts
@@ -22,10 +22,12 @@ interface InlineRequest {
    * during Worker initialization.
    */
   filename: string;
+
   /**
    * The locale specifier that should be used during the inlining process of the file.
    */
   locale: string;
+
   /**
    * The translation messages for the locale that should be used during the inlining process of the file.
    */
diff --git a/packages/angular/build/src/tools/esbuild/stylesheets/css-inline-fonts-plugin.ts b/packages/angular/build/src/tools/esbuild/stylesheets/css-inline-fonts-plugin.ts
@@ -18,6 +18,7 @@ import { LoadResultCache, createCachedLoad } from '../load-result-cache';
 export interface CssInlineFontsPluginOptions {
   /** Disk cache normalized options */
   cacheOptions?: NormalizedCachedOptions;
+
   /** Load results cache. */
   cache?: LoadResultCache;
 }
diff --git a/packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-plugin-factory.ts b/packages/angular/build/src/tools/esbuild/stylesheets/stylesheet-plugin-factory.ts
@@ -190,6 +190,7 @@ export class StylesheetPluginFactory {
   }
 
   private initPostcssCallCount = 0;
+
   /**
    * This method should not be called directly.
    * Use {@link setupPostcss} instead.
diff --git a/packages/angular/build/src/tools/esbuild/virtual-module-plugin.ts b/packages/angular/build/src/tools/esbuild/virtual-module-plugin.ts
@@ -16,17 +16,22 @@ import { LoadResultCache, createCachedLoad } from './load-result-cache';
 export interface VirtualModulePluginOptions {
   /** Namespace. Example: `angular:polyfills`. */
   namespace: string;
+
   /** If the generated module should be marked as external. */
   external?: boolean;
+
   /** Method to transform the onResolve path. */
   transformPath?: (path: string) => string;
+
   /** Method to provide the module content. */
   loadContent: (
     args: OnLoadArgs,
     build: PluginBuild,
   ) => ReturnType<Parameters<PluginBuild['onLoad']>[1]>;
+
   /** Restrict to only entry points. Defaults to `true`. */
   entryPointOnly?: boolean;
+
   /** Load results cache. */
   cache?: LoadResultCache;
 }
diff --git a/packages/angular/build/src/tools/esbuild/wasm-plugin.ts b/packages/angular/build/src/tools/esbuild/wasm-plugin.ts
@@ -21,6 +21,7 @@ import { LoadResultCache, createCachedLoad } from './load-result-cache';
 export interface WasmPluginOptions {
   /** Allow generation of async (proposal compliant) WASM imports. This requires zoneless to enable async/await. */
   allowAsync?: boolean;
+
   /** Load results cache. */
   cache?: LoadResultCache;
 }
diff --git a/packages/angular/build/src/tools/sass/sass-service.ts b/packages/angular/build/src/tools/sass/sass-service.ts
@@ -52,6 +52,7 @@ export interface SerializableVersion {
 export interface SerializableDeprecation extends Omit<Deprecation, 'obsoleteIn' | 'deprecatedIn'> {
   /** The version this deprecation first became active in. */
   deprecatedIn: SerializableVersion | null;
+
   /** The version this deprecation became obsolete in. */
   obsoleteIn: SerializableVersion | null;
 }
diff --git a/packages/angular/build/src/tools/sass/worker.ts b/packages/angular/build/src/tools/sass/worker.ts
@@ -35,21 +35,25 @@ interface RenderRequestMessage {
    * The contents to compile.
    */
   source: string;
+
   /**
    * The Sass options to provide to the `dart-sass` compile function.
    */
   options: Omit<StringOptions<'sync'>, 'url'> & { url: string };
+
   /**
    * Indicates the request has a custom importer function on the main thread.
    */
   importerChannel?: {
     port: MessagePort;
     signal: Int32Array;
   };
+
   /**
    * Indicates the request has a custom logger for warning messages.
    */
   hasLogger: boolean;
+
   /**
    * Indicates paths within url() CSS functions should be rebased.
    */
diff --git a/packages/angular/build/src/utils/index-file/augment-index-html.ts b/packages/angular/build/src/utils/index-file/augment-index-html.ts
@@ -24,20 +24,25 @@ export interface AugmentIndexHtmlOptions {
   baseHref?: string;
   deployUrl?: string;
   sri: boolean;
+
   /** crossorigin attribute setting of elements that provide CORS support */
   crossOrigin?: CrossOriginValue;
+
   /*
    * Files emitted by the build.
    */
   files: FileInfo[];
+
   /*
    * Function that loads a file used.
    * This allows us to use different routines within the IndexHtmlWebpackPlugin and
    * when used without this plugin.
    */
   loadOutputFile: LoadOutputFileFunctionType;
+
   /** Used to sort the inseration of files in the HTML file */
   entrypoints: Entrypoint[];
+
   /** Used to set the document default locale */
   lang?: string;
   hints?: { url: string; mode: string; as?: string }[];
diff --git a/packages/angular/build/src/utils/index-file/valid-self-closing-tags.ts b/packages/angular/build/src/utils/index-file/valid-self-closing-tags.ts
@@ -22,6 +22,7 @@ export const VALID_SELF_CLOSING_TAGS = new Set([
   'source',
   'track',
   'wbr',
+
   /** SVG tags */
   'circle',
   'ellipse',
@@ -45,6 +46,7 @@ export const VALID_SELF_CLOSING_TAGS = new Set([
   'symbol',
   'use',
   'view',
+
   /** MathML tags */
   'mspace',
   'mphantom',
diff --git a/packages/angular/build/src/utils/normalize-cache.ts b/packages/angular/build/src/utils/normalize-cache.ts
@@ -14,8 +14,10 @@ const VERSION = '0.0.0-PLACEHOLDER';
 export interface NormalizedCachedOptions {
   /** Whether disk cache is enabled. */
   enabled: boolean;
+
   /** Disk cache path. Example: `/.angular/cache/v12.0.0`. */
   path: string;
+
   /** Disk cache base path. Example: `/.angular/cache`. */
   basePath: string;
 }
diff --git a/packages/angular/cli/src/command-builder/command-module.ts b/packages/angular/cli/src/command-builder/command-module.ts
@@ -33,8 +33,10 @@ export type Options<T> = { [key in keyof T as CamelCaseKey<key>]: T[key] };
 export enum CommandScope {
   /** Command can only run inside an Angular workspace. */
   In,
+
   /** Command can only run outside an Angular workspace. */
   Out,
+
   /** Command can run inside and outside an Angular workspace. */
   Both,
 }
@@ -46,6 +48,7 @@ export interface CommandContext {
   globalConfiguration: AngularWorkspace;
   logger: logging.Logger;
   packageManager: PackageManagerUtils;
+
   /** Arguments parsed in free-from without parser configuration. */
   args: {
     positional: string[];
@@ -63,10 +66,13 @@ export interface CommandModuleImplementation<T extends {} = {}>
   extends Omit<YargsCommandModule<{}, T>, 'builder' | 'handler'> {
   /** Scope in which the command can be executed in. */
   scope: CommandScope;
+
   /** Path used to load the long description for the command in JSON help text. */
   longDescriptionPath?: string;
+
   /** Object declaring the options the command accepts, or a function accepting and returning a yargs instance. */
   builder(argv: Argv): Promise<Argv<T>> | Argv<T>;
+
   /** A function which will be passed the parsed argv. */
   run(options: Options<T> & OtherOptions): Promise<number | void> | number | void;
 }
diff --git a/packages/angular/cli/src/commands/update/cli.ts b/packages/angular/cli/src/commands/update/cli.ts
@@ -901,6 +901,7 @@ export default class UpdateCommandModule extends CommandModule<UpdateCommandArgs
 
     return success ? 0 : 1;
   }
+
   /**
    * @return Whether or not the commit was successful.
    */
diff --git a/packages/angular/ssr/node/src/common-engine/common-engine.ts b/packages/angular/ssr/node/src/common-engine/common-engine.ts
@@ -23,25 +23,30 @@ const SSG_MARKER_REGEXP = /ng-server-context=["']\w*\|?ssg\|?\w*["']/;
 export interface CommonEngineOptions {
   /** A method that when invoked returns a promise that returns an `ApplicationRef` instance once resolved or an NgModule. */
   bootstrap?: Type<{}> | (() => Promise<ApplicationRef>);
+
   /** A set of platform level providers for all requests. */
   providers?: StaticProvider[];
+
   /** Enable request performance profiling data collection and printing the results in the server console. */
   enablePerformanceProfiler?: boolean;
 }
 
 export interface CommonEngineRenderOptions {
   /** A method that when invoked returns a promise that returns an `ApplicationRef` instance once resolved or an NgModule. */
   bootstrap?: Type<{}> | (() => Promise<ApplicationRef>);
+
   /** A set of platform level providers for the current request. */
   providers?: StaticProvider[];
   url?: string;
   document?: string;
   documentFilePath?: string;
+
   /**
    * Reduce render blocking requests by inlining critical CSS.
    * Defaults to true.
    */
   inlineCriticalCss?: boolean;
+
   /**
    * Base path location of index file.
    * Defaults to the 'documentFilePath' dirname when not provided.
diff --git a/packages/angular/ssr/src/routes/ng-routes.ts b/packages/angular/ssr/src/routes/ng-routes.ts
@@ -92,10 +92,13 @@ interface RouteResult {
 async function* traverseRoutesConfig(options: {
   /** The array of route configurations to process. */
   routes: Route[];
+
   /** The Angular compiler used to compile route modules. */
   compiler: Compiler;
+
   /** The parent injector for lazy-loaded modules. */
   parentInjector: Injector;
+
   /** The parent route path to prefix child routes. */
   parentRoute: string;
 }): AsyncIterableIterator<RouteResult> {
diff --git a/packages/angular/ssr/src/routes/route-config.ts b/packages/angular/ssr/src/routes/route-config.ts
@@ -83,6 +83,7 @@ export interface ServerRouteSSG extends Omit<ServerRouteCommon, 'status'> {
    * Defaults to `SSGFallback.SSR` if not provided.
    */
   fallback?: SSGFallback;
+
   /**
    * A function that returns a Promise resolving to an array of objects, each representing a route path with URL parameters.
    * This function runs in the injector context, allowing access to Angular services and dependencies.
diff --git a/packages/angular_devkit/architect/src/jobs/api.ts b/packages/angular_devkit/architect/src/jobs/api.ts
@@ -275,20 +275,24 @@ export enum JobState {
    * The job was queued and is waiting to start.
    */
   Queued = 'queued',
+
   /**
    * The job description was found, its dependencies (see "Synchronizing and Dependencies")
    * are done running, and the job's argument is validated and the job's code will be executed.
    */
   Ready = 'ready',
+
   /**
    * The job has been started. The job implementation is expected to send this as soon as its
    * work is starting.
    */
   Started = 'started',
+
   /**
    * The job has ended and is done running.
    */
   Ended = 'ended',
+
   /**
    * An error occured and the job stopped because of internal state.
    */
diff --git a/packages/angular_devkit/build_angular/src/builders/app-shell/render-worker.ts b/packages/angular_devkit/build_angular/src/builders/app-shell/render-worker.ts
@@ -44,10 +44,12 @@ interface RenderRequest {
    * The path to the server bundle that should be loaded and rendered.
    */
   serverBundlePath: string;
+
   /**
    * The existing HTML document as a string that will be augmented with the rendered application.
    */
   document: string;
+
   /**
    * An optional URL path that represents the Angular route that should be rendered.
    */
diff --git a/packages/angular_devkit/build_angular/src/tools/webpack/plugins/javascript-optimizer-worker.ts b/packages/angular_devkit/build_angular/src/tools/webpack/plugins/javascript-optimizer-worker.ts
@@ -22,10 +22,12 @@ export interface OptimizeRequestOptions {
    * * terser pure_getters option is enabled
    */
   advanced?: boolean;
+
   /**
    * Specifies the string tokens that should be replaced with a defined value.
    */
   define?: Record<string, string>;
+
   /**
    * Controls whether class, function, and variable names should be left intact
    * throughout the output code.
@@ -37,15 +39,18 @@ export interface OptimizeRequestOptions {
    * Within the CLI, this option is linked to the license extraction functionality.
    */
   removeLicenses?: boolean;
+
   /**
    * Controls whether source maps should be generated.
    */
   sourcemap?: boolean;
+
   /**
    * Specifies the list of supported esbuild targets.
    * @see: https://esbuild.github.io/api/#target
    */
   target?: string[];
+
   /**
    * Controls whether esbuild should only use the WASM-variant instead of trying to
    * use the native variant. Some platforms may not support the native-variant and
@@ -71,10 +76,12 @@ interface OptimizeRequest {
      * The name of the JavaScript asset (typically the filename).
      */
     name: string;
+
     /**
      * The source content of the JavaScript asset.
      */
     code: string;
+
     /**
      * The source map of the JavaScript asset, if available.
      * This map is merged with all intermediate source maps during optimization.
diff --git a/packages/angular_devkit/build_angular/src/tools/webpack/plugins/postcss-cli-resources.ts b/packages/angular_devkit/build_angular/src/tools/webpack/plugins/postcss-cli-resources.ts
@@ -30,6 +30,7 @@ export interface PostcssCliResourcesOptions {
   deployUrl?: string;
   resourcesOutputPath?: string;
   rebaseRootRelative?: boolean;
+
   /** CSS is extracted to a `.css` or is embedded in a `.js` file. */
   extracted?: boolean;
   filename: (resourcePath: string) => string;
diff --git a/packages/angular_devkit/build_angular/src/utils/normalize-cache.ts b/packages/angular_devkit/build_angular/src/utils/normalize-cache.ts
@@ -14,8 +14,10 @@ const VERSION = '0.0.0-PLACEHOLDER';
 export interface NormalizedCachedOptions {
   /** Whether disk cache is enabled. */
   enabled: boolean;
+
   /** Disk cache path. Example: `/.angular/cache/v12.0.0`. */
   path: string;
+
   /** Disk cache base path. Example: `/.angular/cache`. */
   basePath: string;
 }
diff --git a/packages/schematics/angular/utility/dependency.ts b/packages/schematics/angular/utility/dependency.ts
diff --git a/packages/schematics/angular/utility/workspace-models.ts b/packages/schematics/angular/utility/workspace-models.ts
diff --git a/scripts/build-packages-dist.mts b/scripts/build-packages-dist.mts
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -709,6 +709,7 @@ function getDepOptimizationConfig({`
`709`	`709`	`}`
`710`	`710`
`711`	`711`	`const nodeJsBuiltinModules = new Set(builtinModules);`
	`712`	`+`
`712`	`713`	`/** Remove any Node.js builtin modules to avoid Vite's prebundling from processing them as files. */`
`713`	`714`	`function removeNodeJsBuiltinModules(value: string): boolean {`
`714`	`715`	`return !nodeJsBuiltinModules.has(value);`
Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@ import { LoadResultCache, createCachedLoad } from '../load-result-cache';`
`18`	`18`	`export interface CssInlineFontsPluginOptions {`
`19`	`19`	`/** Disk cache normalized options */`
`20`	`20`	`cacheOptions?: NormalizedCachedOptions;`
	`21`	`+`
`21`	`22`	`/** Load results cache. */`
`22`	`23`	`cache?: LoadResultCache;`
`23`	`24`	`}`
Original file line number	Diff line number	Diff line change
`@@ -190,6 +190,7 @@ export class StylesheetPluginFactory {`
`190`	`190`	`}`
`191`	`191`
`192`	`192`	`private initPostcssCallCount = 0;`
	`193`	`+`
`193`	`194`	`/**`
`194`	`195`	`* This method should not be called directly.`
`195`	`196`	`* Use {@link setupPostcss} instead.`
Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,7 @@ import { LoadResultCache, createCachedLoad } from './load-result-cache';`
`21`	`21`	`export interface WasmPluginOptions {`
`22`	`22`	`/** Allow generation of async (proposal compliant) WASM imports. This requires zoneless to enable async/await. */`
`23`	`23`	`allowAsync?: boolean;`
	`24`	`+`
`24`	`25`	`/** Load results cache. */`
`25`	`26`	`cache?: LoadResultCache;`
`26`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -52,6 +52,7 @@ export interface SerializableVersion {`
`52`	`52`	`export interface SerializableDeprecation extends Omit<Deprecation, 'obsoleteIn' \| 'deprecatedIn'> {`
`53`	`53`	`/** The version this deprecation first became active in. */`
`54`	`54`	`deprecatedIn: SerializableVersion \| null;`
	`55`	`+`
`55`	`56`	`/** The version this deprecation became obsolete in. */`
`56`	`57`	`obsoleteIn: SerializableVersion \| null;`
`57`	`58`	`}`