@angular-eslint/test-utils 17.5.3-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 James Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @angular-eslint/test-utils
+
+Please see https://github.com/angular-eslint/angular-eslint for full usage instructions and guidance.
+
+The `@angular-eslint/test-utils` package is a set of testing utility functions and types which are used across the `@angular-eslint` packages and are helpful when testing your own custom ESLint rules for Angular workspaces.

package/dist/convert-annotated-source-to-failure-case.d.ts

@@ -0,0 +1,62 @@
+import type { TSESLint } from '@typescript-eslint/utils';
+/**
+ * When leveraging the convertAnnotatedSourceToFailureCase() utility, the
+ * following characters are eligible to be used in the source code of expected
+ * failure cases within ESLint unit tests in order to provide an easy way to
+ * annotate where one or more ESLint errors are expected to occur within that
+ * source.
+ *
+ * See the convertAnnotatedSourceToFailureCase() utility itself for more details.
+ */
+export declare const SPECIAL_UNDERLINE_CHARS: readonly ["~", "^", "#", "%", "¶", "*", "¨", "@"];
+type MultipleErrorOptions<TMessageIds extends string> = BaseErrorOptions & {
+    readonly messages: readonly (Message<TMessageIds> & {
+        readonly char: (typeof SPECIAL_UNDERLINE_CHARS)[number];
+    })[];
+};
+type BaseErrorOptions = {
+    readonly description: string;
+    readonly annotatedSource: string;
+    readonly options?: readonly unknown[];
+    readonly annotatedOutput?: string;
+    readonly annotatedOutputs?: readonly string[];
+    readonly filename?: string;
+    readonly only?: boolean;
+};
+type Message<TMessageIds extends string> = {
+    readonly messageId: TMessageIds;
+    readonly data?: Record<string, unknown>;
+    readonly suggestions?: TSESLint.SuggestionOutput<TMessageIds>[];
+};
+type SingleErrorOptions<TMessageIds extends string> = BaseErrorOptions & Message<TMessageIds>;
+/**
+ * convertAnnotatedSourceToFailureCase() provides an ergonomic way to easily write
+ * expected failure cases for ESLint rules by allowing you to directly annotate the
+ * source code for the case with one or more of the values in `SPECIAL_UNDERLINE_CHARS`.
+ *
+ * This not only makes the unit tests easier to write because of the time saved in figuring
+ * out location data in terms of lines and columns, but also far easier to read, which is
+ * arguably much more important.
+ *
+ * Here is a real-world example of using the utility:
+ *
+ * ```ts
+ *  convertAnnotatedSourceToFailureCase({
+ *    description: 'should fail when Pipe has no prefix ng',
+ *    annotatedSource: `
+ *        @Pipe({
+ *          name: 'foo-bar'
+ *                ~~~~~~~~~
+ *        })
+ *        class Test {}
+ *    `,
+ *    messageId: 'pipePrefix,
+ *    options: [{ prefixes: ['ng'] }],
+ *    data: { prefixes: '"ng"' },
+ *  }),
+ * ```
+ */
+export declare function convertAnnotatedSourceToFailureCase<TMessageIds extends string>(errorOptions: SingleErrorOptions<TMessageIds>): TSESLint.InvalidTestCase<TMessageIds, readonly unknown[]>;
+export declare function convertAnnotatedSourceToFailureCase<TMessageIds extends string>(errorOptions: MultipleErrorOptions<TMessageIds>): TSESLint.InvalidTestCase<TMessageIds, readonly unknown[]>;
+export {};
+//# sourceMappingURL=convert-annotated-source-to-failure-case.d.ts.map

package/dist/convert-annotated-source-to-failure-case.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert-annotated-source-to-failure-case.d.ts","sourceRoot":"","sources":["../src/convert-annotated-source-to-failure-case.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,mDAS1B,CAAC;AAEX,KAAK,oBAAoB,CAAC,WAAW,SAAS,MAAM,IAAI,gBAAgB,GAAG;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG;QAClD,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;KACzD,CAAC,EAAE,CAAC;CACN,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,KAAK,OAAO,CAAC,WAAW,SAAS,MAAM,IAAI;IACzC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,CAAC;CACjE,CAAC;AAEF,KAAK,kBAAkB,CAAC,WAAW,SAAS,MAAM,IAAI,gBAAgB,GACpE,OAAO,CAAC,WAAW,CAAC,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mCAAmC,CAAC,WAAW,SAAS,MAAM,EAC5E,YAAY,EAAE,kBAAkB,CAAC,WAAW,CAAC,GAC5C,QAAQ,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC;AAC7D,wBAAgB,mCAAmC,CAAC,WAAW,SAAS,MAAM,EAC5E,YAAY,EAAE,oBAAoB,CAAC,WAAW,CAAC,GAC9C,QAAQ,CAAC,eAAe,CAAC,WAAW,EAAE,SAAS,OAAO,EAAE,CAAC,CAAC"}

package/dist/convert-annotated-source-to-failure-case.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertAnnotatedSourceToFailureCase = exports.SPECIAL_UNDERLINE_CHARS = void 0;
+/**
+ * When leveraging the convertAnnotatedSourceToFailureCase() utility, the
+ * following characters are eligible to be used in the source code of expected
+ * failure cases within ESLint unit tests in order to provide an easy way to
+ * annotate where one or more ESLint errors are expected to occur within that
+ * source.
+ *
+ * See the convertAnnotatedSourceToFailureCase() utility itself for more details.
+ */
+exports.SPECIAL_UNDERLINE_CHARS = [
+    '~',
+    '^',
+    '#',
+    '%',
+    '¶',
+    '*',
+    '¨',
+    '@',
+];
+function convertAnnotatedSourceToFailureCase(errorOptions) {
+    if (errorOptions.annotatedOutput && errorOptions.annotatedOutputs) {
+        throw new Error('Only one of `annotatedOutput` and `annotatedOutputs` should be provided');
+    }
+    const messages = 'messageId' in errorOptions
+        ? [{ ...errorOptions, char: '~' }]
+        : errorOptions.messages;
+    let parsedSource = '';
+    const errors = messages.map(({ char: currentValueChar, data, messageId, suggestions }) => {
+        const otherChars = messages
+            .map(({ char }) => char)
+            .filter((char) => char !== currentValueChar);
+        const parsedForChar = parseInvalidSource(errorOptions.annotatedSource, currentValueChar, otherChars);
+        const { failure: { endPosition, startPosition }, } = parsedForChar;
+        parsedSource = parsedForChar.source;
+        if (!endPosition || !startPosition) {
+            throw Error(`Char '${currentValueChar}' has been specified in \`messages\`, however it is not present in the source of the failure case`);
+        }
+        return {
+            data,
+            messageId,
+            line: startPosition.line + 1,
+            column: startPosition.character + 1,
+            endLine: endPosition.line + 1,
+            endColumn: endPosition.character + 1,
+            suggestions,
+        };
+    });
+    return {
+        name: errorOptions.description,
+        code: parsedSource,
+        filename: errorOptions.filename,
+        options: errorOptions.options ?? [],
+        errors,
+        only: errorOptions.only ?? false,
+        output: errorOptions.annotatedOutputs
+            ? errorOptions.annotatedOutputs.map((s) => parseInvalidSource(s).source)
+            : errorOptions.annotatedOutput
+                ? parseInvalidSource(errorOptions.annotatedOutput).source
+                : null,
+    };
+}
+exports.convertAnnotatedSourceToFailureCase = convertAnnotatedSourceToFailureCase;
+function escapeRegexp(value) {
+    return value.replace(/[-/\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+/**
+ * When testing a failure, we also test to see if the linter will report the correct place where
+ * the source code doesn't match the rule.
+ *
+ * For example, if you use a private property in your template, the linter should report _where_
+ * did it happen. Because it's tedious to supply actual line/column number in the spec, we use
+ * some custom syntax with "underlining" the problematic part with tildes:
+ *
+ * ```
+ * template: '{{ foo }}'
+ *               ~~~
+ * ```
+ *
+ * When giving a spec which we expect to fail, we give it "source code" such as above, with tildes.
+ * We call this kind of source code "annotated". This source code cannot be compiled (and thus
+ * cannot be linted/tested), so we use this function to get rid of tildes, but maintain the
+ * information about where the linter is supposed to catch error.
+ *
+ * The result of the function contains "cleaned" source (`.source`) and a `.failure` object which
+ * contains the `.startPosition` and `.endPosition` of the tildes.
+ *
+ * @param source The annotated source code with tildes.
+ * @param specialChar The character to look for; in the above example that's ~.
+ * @param otherChars All other characters which should be ignored. Used when asserting multiple
+ *                   failures where there are multiple invalid characters.
+ * @returns {{source: string, failure: {message: string, startPosition: null, endPosition: any}}}
+ */
+function parseInvalidSource(source, specialChar = '~', otherChars = []) {
+    let replacedSource;
+    if (otherChars.length === 0) {
+        replacedSource = source;
+    }
+    else {
+        const patternAsStr = `[${otherChars.map(escapeRegexp).join('')}]`;
+        const pattern = RegExp(patternAsStr, 'g');
+        replacedSource = source.replace(pattern, ' ');
+    }
+    let col = 0;
+    let line = 0;
+    let lastCol = 0;
+    let lastLine = 0;
+    let startPosition;
+    for (const currentChar of replacedSource) {
+        if (currentChar === '\n') {
+            col = 0;
+            line++;
+            continue;
+        }
+        col++;
+        if (currentChar !== specialChar)
+            continue;
+        if (!startPosition) {
+            startPosition = {
+                character: col - 1,
+                line: line - 1,
+            };
+        }
+        lastCol = col;
+        lastLine = line - 1;
+    }
+    const endPosition = {
+        character: lastCol,
+        line: lastLine,
+    };
+    const newSource = replacedSource.replace(RegExp(escapeRegexp(specialChar), 'g'), '');
+    return {
+        failure: {
+            endPosition,
+            message: '',
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            startPosition: startPosition,
+        },
+        source: newSource,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './convert-annotated-source-to-failure-case';
+export * from './rule-tester';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4CAA4C,CAAC;AAC3D,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./convert-annotated-source-to-failure-case"), exports);
+__exportStar(require("./rule-tester"), exports);

package/dist/rule-tester.d.ts

@@ -0,0 +1,13 @@
+import { RuleTester as TSESLintRuleTester } from '@typescript-eslint/rule-tester';
+import type { TSESLint } from '@typescript-eslint/utils';
+declare const VALID_PARSERS: readonly ["@angular-eslint/template-parser", "@typescript-eslint/parser"];
+type RuleTesterConfig = Omit<TSESLint.RuleTesterConfig, 'parser'> & {
+    parser: (typeof VALID_PARSERS)[number];
+};
+export declare class RuleTester extends TSESLintRuleTester {
+    private filename?;
+    constructor(options: RuleTesterConfig);
+    run<TMessageIds extends string, TOptions extends readonly unknown[]>(name: string, rule: TSESLint.RuleModule<TMessageIds, TOptions>, { valid, invalid }: TSESLint.RunTests<TMessageIds, TOptions>): void;
+}
+export {};
+//# sourceMappingURL=rule-tester.d.ts.map

package/dist/rule-tester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-tester.d.ts","sourceRoot":"","sources":["../src/rule-tester.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,IAAI,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGzD,QAAA,MAAM,aAAa,2EAGT,CAAC;AAEX,KAAK,gBAAgB,GAAG,IAAI,CAAC,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,GAAG;IAClE,MAAM,EAAE,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;CACxC,CAAC;AAYF,qBAAa,UAAW,SAAQ,kBAAkB;IAChD,OAAO,CAAC,QAAQ,CAAC,CAAc;gBAKnB,OAAO,EAAE,gBAAgB;IA8B5B,GAAG,CAAC,WAAW,SAAS,MAAM,EAAE,QAAQ,SAAS,SAAS,OAAO,EAAE,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,WAAW,EAAE,QAAQ,CAAC,EAChD,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,GAC3D,IAAI;CA0BR"}

package/dist/rule-tester.js

@@ -0,0 +1,93 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuleTester = void 0;
+const rule_tester_1 = require("@typescript-eslint/rule-tester");
+const path = __importStar(require("path"));
+const VALID_PARSERS = [
+    '@angular-eslint/template-parser',
+    '@typescript-eslint/parser',
+];
+function getFixturesRootDir() {
+    return path.join(process.cwd(), 'tests/fixtures/');
+}
+function isValidParser(parser) {
+    return VALID_PARSERS.includes(parser);
+}
+class RuleTester extends rule_tester_1.RuleTester {
+    filename = '';
+    // as of eslint 6 you have to provide an absolute path to the parser
+    // but that's not as clean to type, this saves us trying to manually enforce
+    // that contributors require.resolve everything
+    constructor(options) {
+        super({
+            ...options,
+            parser: require.resolve(options.parser),
+        });
+        if (options.parserOptions?.project) {
+            this.filename = path.join(options.parserOptions?.tsconfigRootDir ?? getFixturesRootDir(), 'file.ts');
+        }
+        // make sure that the parser doesn't hold onto file handles between tests
+        // on linux (i.e. our CI env), there can be very a limited number of watch handles available
+        afterAll(() => {
+            try {
+                // instead of creating a hard dependency, just use a soft require
+                // a bit weird, but if they're using this tooling, it'll be installed
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                require(options.parser).clearCaches();
+            }
+            catch {
+                // ignored
+            }
+        });
+    }
+    // as of eslint 6 you have to provide an absolute path to the parser
+    // If you don't do that at the test level, the test will fail somewhat cryptically...
+    // This is a lot more explicit
+    run(name, rule, { valid, invalid }) {
+        const errorMessage = `Do not set the parser at the test level unless you want to use a parser other than ${VALID_PARSERS.join(', ')}`;
+        const parsedTests = {
+            valid: valid.map((test) => {
+                if (typeof test !== 'string' && isValidParser(test.parser)) {
+                    throw Error(errorMessage);
+                }
+                return typeof test === 'string'
+                    ? { code: test, filename: this.filename }
+                    : { ...test, filename: test.filename ?? this.filename };
+            }),
+            invalid: invalid.map((test) => {
+                if (isValidParser(test.parser)) {
+                    throw Error(errorMessage);
+                }
+                return {
+                    ...test,
+                    filename: test.filename ?? this.filename,
+                };
+            }),
+        };
+        super.run(name, rule, parsedTests);
+    }
+}
+exports.RuleTester = RuleTester;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@angular-eslint/test-utils",
+  "version": "17.5.3-alpha.1",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/angular-eslint/angular-eslint.git",
+    "directory": "packages/test-utils"
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "eslint": "^8.57.0 || ^9.0.0",
+    "typescript": "*"
+  },
+  "dependencies": {
+    "@typescript-eslint/rule-tester": "8.0.0-alpha.20",
+    "@typescript-eslint/utils": "8.0.0-alpha.20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "e2006e5e9c99e5a943d1a999e0efa5247d29ec24"
+}