markuplint 5.3.0 → 5.5.0

package/lib/cli/main.js

@@ -0,0 +1,171 @@
+/**
+ * @module cli/main
+ *
+ * The CLI run itself. `index.ts` is the entry point and owns the process boundary
+ * (the exit code and why `process.exit()` is not used); this module is separate so a spec
+ * can call `main()` without starting the process.
+ */
+import { text } from 'node:stream/consumers';
+import { isFatalError } from '@markuplint/shared';
+import { verbosely } from '../debug.js';
+import { cli } from './bootstrap.js';
+import { command } from './command.js';
+import { initialize } from './init/index.js';
+import { search } from './search/index.js';
+/** The operand that means standard input. */
+const STDIN_OPERAND = '-';
+/**
+ * Runs the CLI and resolves to its exit code.
+ *
+ * Every branch returns a number: a branch that forgets to leaves `undefined`,
+ * and the `process.exitCode` that `output.ts` set (1) would leak out.
+ */
+export async function main() {
+    // Same condition as meow's automatic handling: the flag has to be the only argument.
+    const isSoleArgument = cli.input.length === 0 && process.argv.length === 3;
+    if (cli.flags.v || (isSoleArgument && cli.flags.version === true)) {
+        return showVersion();
+    }
+    if (cli.flags.h || (isSoleArgument && cli.flags.help === true)) {
+        return showHelp(0);
+    }
+    if (cli.flags.verbose) {
+        verbosely();
+    }
+    if (cli.flags.init) {
+        try {
+            await initialize();
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            process.stderr.write(error + '\n');
+            return 1;
+        }
+        return 0;
+    }
+    if (cli.flags.createRule) {
+        process.stderr.write("Use to run 'npx @markuplint/create-rule' instead of 'markuplint --create-rule'.\n");
+        return 1;
+    }
+    const files = cli.input;
+    if (files.includes(STDIN_OPERAND)) {
+        const fileFlags = givenFileFlags();
+        if (files.length > 1 || fileFlags.length > 0) {
+            const conflicts = files.length > 1 ? ['file paths', ...fileFlags] : fileFlags;
+            process.stderr.write(`The \`${STDIN_OPERAND}\` operand (standard input) cannot be combined with ${conflicts.join(', ')}.\n`);
+            return 1;
+        }
+        const stdin = await readStdin();
+        if (stdin === null) {
+            return 1;
+        }
+        // An empty input is an empty source, as `markuplint empty.html` is.
+        return lintStdin(stdin);
+    }
+    if (files.length > 0) {
+        if (cli.flags.search) {
+            try {
+                await search(files, cli.flags, cli.flags.search);
+            }
+            catch (error) {
+                if (isFatalError(error)) {
+                    throw error;
+                }
+                process.stderr.write(error + '\n');
+                return 1;
+            }
+            return 0;
+        }
+        return lint(files, cli.flags);
+    }
+    if (usePipe()) {
+        const fileFlags = givenFileFlags();
+        if (fileFlags.length > 0) {
+            process.stderr.write(`Standard input cannot be combined with ${fileFlags.join(', ')}.\n`);
+            return 1;
+        }
+        const stdin = await readStdin();
+        if (stdin === null) {
+            return 1;
+        }
+        if (!stdin) {
+            // result is empty
+            return showHelp(1);
+        }
+        return lintStdin(stdin);
+    }
+    // No arguments
+    return showHelp(1);
+}
+/**
+ * The options that act on a file that are given, by their names: `--fix` writes the fixed source
+ * to it (with nothing to write to, it created a file named `<AnonymousFile>`, #4560), `--search`
+ * and the suppressions options report or record by file. The standard input has none, so both
+ * ways of reading it (the `-` operand and the no-operand pipe) reject them, and name them in the
+ * message, from this one list: an option that acts on a file is added here, and nowhere else.
+ * `--fix-dry-run` is not one: it writes nothing and prints the diff.
+ */
+function givenFileFlags() {
+    const { search, fix, suppress, suppressRule, pruneSuppressions } = cli.flags;
+    // Each is given by the condition of the code that consumes it, not by one shared test:
+    // `--search` is a search when it is not empty (the file branch below tests it so), and
+    // `--suppress-rule` turns the suppressions mode on when it is set at all (`command.ts`).
+    const given = [
+        ['--search', Boolean(search)],
+        ['--fix', Boolean(fix)],
+        ['--suppress', Boolean(suppress)],
+        ['--suppress-rule', suppressRule != null],
+        ['--prune-suppressions', Boolean(pruneSuppressions)],
+    ];
+    return given.filter(([, isGiven]) => isGiven).map(([name]) => name);
+}
+function usePipe() {
+    return !process.stdin.isTTY && process.stdout.isTTY;
+}
+/**
+ * Reports a read failure on stderr and returns `null` instead of throwing,
+ * so the caller can return the exit code.
+ */
+async function readStdin() {
+    try {
+        return await text(process.stdin);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        process.stderr.write(error + '\n');
+        return null;
+    }
+}
+function lintStdin(sourceCode) {
+    return lint([{ sourceCode }], { ...cli.flags, ignoreExt: true });
+}
+/**
+ * Runs `command()` and resolves to its exit code. A failure that is not fatal is reported on
+ * stderr with exit code 1, whatever the input is (file paths or the standard input).
+ */
+async function lint(...args) {
+    try {
+        return (await command(...args)) ? 1 : 0;
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        process.stderr.write(error + '\n');
+        return 1;
+    }
+}
+/** Prints what meow's `showVersion()` printed (`console.log` of the version). */
+function showVersion() {
+    process.stdout.write(cli.pkg.version + '\n');
+    return 0;
+}
+/** Prints what meow's `showHelp()` printed (`console.log` of the help, which ends with a newline). */
+function showHelp(exitCode) {
+    process.stdout.write(cli.help + '\n');
+    return exitCode;
+}

package/lib/cli/output.js

@@ -28,6 +28,8 @@ export function output(results, options) {
     let msg = `${out.join('\n')}\n`;
     msg = options.color ? msg : stripAnsi(msg);
     // If it has errors, Write to `stderr` and failure and exit.
+    // `index.ts` overwrites this `exitCode` with the verdict `command()` returns, which is the one
+    // that counts (warnings are written here too, yet only `--no-allow-warnings` fails on them).
     if (results.violations.length > 0) {
         process.stderr.write(msg);
         process.exitCode = 1;
@@ -78,7 +80,7 @@ function createSummaryLines(summary) {
         out.push(`${logger('✖')} ${problemCount} problem${problemCount === 1 ? '' : 's'} (${problemDetail}) in ${pluralize(summary.checkedFileCount, 'file')}`, `${pluralize(summary.checkedFileCount, 'file')} checked: ${passedFileCount} passed, ${summary.failedFileCount} failed`);
     }
     if (summary.skippedFileCount > 0) {
-        out.push(`${font.yellow('⚠')} ${pluralize(summary.skippedFileCount, 'file')} skipped because --max-count was reached`);
+        out.push(`${font.yellow('⚠')} ${pluralize(summary.skippedFileCount, 'file')} not reported because --max-count was reached (violations in ${summary.skippedFileCount === 1 ? 'it' : 'them'} still count toward the exit code)`);
     }
     return out;
 }

package/lib/cli/search/index.js

@@ -13,7 +13,8 @@ export async function search(files, options, selectors) {
                 name,
                 ...createRule({
                     verify({ document }) {
-                        const nodes = document.querySelectorAll(selectors);
+                        // Every tree is searched: what is in the content of a `template` element is found too
+                        const nodes = document.deepQuerySelectorAll(selectors);
                         locations.push(...[...nodes].map(node => {
                             return {
                                 file: document.filename ?? '_NO_FILE_',

package/lib/suppressions/compute-scope.d.ts

@@ -57,7 +57,7 @@ export interface PositionedNode extends ScopedNode {
  * (the one `CSS.escape()` is specified by), in which a code point that is not an ident code point of CSS
  * Syntax is escaped, so the output is always one identifier. A NUL is written as U+FFFD, as the algorithm
  * has it, so it does not read back as NUL. A scope is a CSS selector, and CSS lets any code point be part
- * of an identifier by escaping it, "even ones that CSS uses in its syntax". So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
+ * of an identifier by escaping it, even one that CSS uses in its syntax. So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
  * `Tabs` with the class `Root`, `py-1.5` is `py-1\.5`, `hover:bg-x` is `hover\:bg-x`, `2xl:flex` is
  * `\32 xl\:flex`, and a class that ends with `:nth-of-type(2)` is no position. What this writes and what
  * {@link unescapeIdentifier} reads are one form, so a scope matches the element it was made for.
@@ -69,7 +69,12 @@ export interface PositionedNode extends ScopedNode {
  * with `:nth-of-type(n)` (`div.a:nth-of-type(2)`) never matched, and is still read as a position. A `\`
  * that such a file holds is read as CSS reads it: `\ba` is the hex escape U+00BA.
  *
+ * CSS Syntax says of an identifier:
+ *
+ * > You can include any code point at all, even ones that CSS uses in its syntax, by escaping it.
+ *
  * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export declare function serializeIdentifier(name: string): string;
 /**
@@ -104,7 +109,7 @@ export declare function splitScopeAttr(segment: string): {
  * class `a\` at the position 2, and `a\:nth-of-type(2)` is the class `a:nth-of-type(2)`. The escapes
  * are scanned from the start, as {@link splitScopeIdents} does.
  *
- * @see https://www.w3.org/TR/css-syntax-3/#escaping
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export declare function splitScopeNth(segment: string): {
     readonly base: string;

package/lib/suppressions/compute-scope.js

@@ -40,7 +40,7 @@ const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u0
  * (the one `CSS.escape()` is specified by), in which a code point that is not an ident code point of CSS
  * Syntax is escaped, so the output is always one identifier. A NUL is written as U+FFFD, as the algorithm
  * has it, so it does not read back as NUL. A scope is a CSS selector, and CSS lets any code point be part
- * of an identifier by escaping it, "even ones that CSS uses in its syntax". So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
+ * of an identifier by escaping it, even one that CSS uses in its syntax. So `Tabs.Root` (a member tag of JSX, MDX or Svelte) is `Tabs\.Root` and not the element
  * `Tabs` with the class `Root`, `py-1.5` is `py-1\.5`, `hover:bg-x` is `hover\:bg-x`, `2xl:flex` is
  * `\32 xl\:flex`, and a class that ends with `:nth-of-type(2)` is no position. What this writes and what
  * {@link unescapeIdentifier} reads are one form, so a scope matches the element it was made for.
@@ -52,7 +52,12 @@ const NON_ASCII_IDENT_CODE_POINT = /^[\u00B7\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u0
  * with `:nth-of-type(n)` (`div.a:nth-of-type(2)`) never matched, and is still read as a position. A `\`
  * that such a file holds is read as CSS reads it: `\ba` is the hex escape U+00BA.
  *
+ * CSS Syntax says of an identifier:
+ *
+ * > You can include any code point at all, even ones that CSS uses in its syntax, by escaping it.
+ *
  * @see https://drafts.csswg.org/cssom/#serialize-an-identifier
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export function serializeIdentifier(name) {
     let result = '';
@@ -187,7 +192,7 @@ export function splitScopeAttr(segment) {
  * class `a\` at the position 2, and `a\:nth-of-type(2)` is the class `a:nth-of-type(2)`. The escapes
  * are scanned from the start, as {@link splitScopeIdents} does.
  *
- * @see https://www.w3.org/TR/css-syntax-3/#escaping
+ * @see https://www.w3.org/TR/css-syntax-3/#syntax-description
  */
 export function splitScopeNth(segment) {
     // Only an unescaped `:` is looked at: an escaped one is read with its `\` before it, as one character

package/lib/suppressions/suppressions-file.d.ts

@@ -12,6 +12,11 @@ export declare function resolveSuppressionsPath(customPath?: string): string;
  * Reads and parses a suppressions JSON file.
  * Returns an empty object if the file does not exist.
  *
+ * Only the top level is checked: valid JSON that is not an object (`null`, an
+ * array, a string, a number) is not suppressions data and fails like
+ * unparsable JSON does, so that every caller gets the same readable error
+ * instead of a `TypeError` from the first `Object.keys` on it.
+ *
  * @param filePath - Absolute path to the suppressions file.
  * @returns The parsed suppressions data, or an empty object if the file does not exist.
  */

package/lib/suppressions/suppressions-file.js

@@ -20,13 +20,22 @@ export function resolveSuppressionsPath(customPath) {
  * Reads and parses a suppressions JSON file.
  * Returns an empty object if the file does not exist.
  *
+ * Only the top level is checked: valid JSON that is not an object (`null`, an
+ * array, a string, a number) is not suppressions data and fails like
+ * unparsable JSON does, so that every caller gets the same readable error
+ * instead of a `TypeError` from the first `Object.keys` on it.
+ *
  * @param filePath - Absolute path to the suppressions file.
  * @returns The parsed suppressions data, or an empty object if the file does not exist.
  */
 export async function readSuppressionsFile(filePath) {
     try {
         const content = await fs.readFile(filePath, 'utf8');
-        return JSON.parse(content);
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new Error(`Failed to parse suppressions file "${filePath}": the top level must be a JSON object`);
+        }
+        return parsed;
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markuplint",
-	"version": "5.3.0",
+	"version": "5.5.0",
 	"description": "An HTML linter for all markup developers",
 	"author": "Yusuke Hirao",
 	"license": "MIT",
@@ -33,20 +33,28 @@
 		"dev": "tsc --watch --project tsconfig.build.json",
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
+	"devDependencies": {
+		"@markuplint/astro-parser": "5.5.0",
+		"@markuplint/jsx-parser": "5.5.0",
+		"@markuplint/mdx-parser": "5.5.0",
+		"@markuplint/pretenders": "5.5.0",
+		"@markuplint/svelte-parser": "5.5.0",
+		"@markuplint/vue-parser": "5.5.0"
+	},
 	"dependencies": {
 		"@markuplint/cli-utils": "5.3.0",
-		"@markuplint/file-resolver": "5.3.0",
-		"@markuplint/html-parser": "5.3.0",
-		"@markuplint/html-spec": "5.3.0",
-		"@markuplint/i18n": "5.3.0",
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.3.0",
-		"@markuplint/ml-core": "5.3.0",
-		"@markuplint/ml-spec": "5.3.0",
-		"@markuplint/rules": "5.3.0",
-		"@markuplint/shared": "5.3.0",
+		"@markuplint/file-resolver": "5.5.0",
+		"@markuplint/html-parser": "5.5.0",
+		"@markuplint/html-spec": "5.5.0",
+		"@markuplint/i18n": "5.5.0",
+		"@markuplint/ml-ast": "5.5.0",
+		"@markuplint/ml-config": "5.5.0",
+		"@markuplint/ml-core": "5.5.0",
+		"@markuplint/ml-spec": "5.5.0",
+		"@markuplint/rules": "5.5.0",
+		"@markuplint/shared": "5.5.0",
 		"@types/debug": "^4.1.13",
-		"chokidar": "^5.0.0",
+		"chokidar": "^6.0.0",
 		"debug": "^4.4.3",
 		"meow": "^14.1.0",
 		"os-locale": "^8.0.0",
@@ -54,5 +62,33 @@
 		"strip-ansi": "^7.2.0",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
+	"peerDependencies": {
+		"@markuplint/astro-parser": "^5.4.0",
+		"@markuplint/jsx-parser": "^5.4.0",
+		"@markuplint/mdx-parser": "^5.4.0",
+		"@markuplint/pretenders": "^5.4.0",
+		"@markuplint/svelte-parser": "^5.4.0",
+		"@markuplint/vue-parser": "^5.4.0"
+	},
+	"peerDependenciesMeta": {
+		"@markuplint/astro-parser": {
+			"optional": true
+		},
+		"@markuplint/jsx-parser": {
+			"optional": true
+		},
+		"@markuplint/mdx-parser": {
+			"optional": true
+		},
+		"@markuplint/pretenders": {
+			"optional": true
+		},
+		"@markuplint/svelte-parser": {
+			"optional": true
+		},
+		"@markuplint/vue-parser": {
+			"optional": true
+		}
+	},
+	"gitHead": "fedebcfd56eaec4642e68643b2f9e10750d810e1"
 }