gurkencheck 0.0.9 → 0.1.0

package/dist/formatters/sarif.js

@@ -8,24 +8,41 @@
  * See https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
  */
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ALWAYS_ON_RULES } from '../gherkin/parse.js';
+import { BUILT_IN_RULES } from '../rules/index.js';
 import { version } from '../version.js';
 const SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
 const SARIF_VERSION = '2.1.0';
 const DOCUMENTATION = 'https://sebs.github.io/gurkencheck/';
+/** The rules with a page on the documentation site. */
+const DOCUMENTED_RULES = new Set([
+    ...BUILT_IN_RULES.map((rule) => rule.name),
+    ...ALWAYS_ON_RULES,
+]);
 /** SARIF's levels, which happen to line up with ours. */
 const LEVEL = { error: 'error', warning: 'warning' };
 function levelOf(error) {
     return LEVEL[error.severity ?? 'error'];
 }
 /**
- * Paths relative to the working directory, with forward slashes.
+ * Paths relative to the working directory, with forward slashes, as a URI.
  *
  * Code scanning matches a result to a file in the repository by this URI, so
  * an absolute path from whichever machine ran the linter would match nothing.
+ * It is a URI rather than a path, so each segment is percent-encoded: a `#`
+ * in a file name would otherwise start a fragment, and `%20` read as a space.
+ *
+ * A file outside the working directory is not in the repository as code
+ * scanning sees it, so a relative `../` path would match nothing either; it
+ * gets an absolute `file:` URI, which at least names the file exactly.
  */
 function uriFor(filePath, cwd) {
     const relative = path.relative(cwd, filePath);
-    return relative.split(path.sep).join('/');
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return pathToFileURL(path.resolve(cwd, filePath)).href;
+    }
+    return relative.split(path.sep).map(encodeURIComponent).join('/');
 }
 function toResult(result, error, cwd) {
     const physicalLocation = {
@@ -63,12 +80,14 @@ export function toSarif(results, cwd = process.cwd()) {
                         name: 'gurkencheck',
                         informationUri: DOCUMENTATION,
                         version: version(),
-                        rules: ruleIds.map((id) => ({
-                            id,
-                            helpUri: `${DOCUMENTATION}rules/${id}.html`,
-                        })),
+                        // Only the rules documented on the site get a link: one to a
+                        // custom rule's page, or to unexpected-error's, would be a 404.
+                        rules: ruleIds.map((id) => DOCUMENTED_RULES.has(id) ? { id, helpUri: `${DOCUMENTATION}rules/${id}.html` } : { id }),
                     },
                 },
+                // Columns count characters, as the Gherkin parser does, not the
+                // UTF-16 units some tools assume.
+                columnKind: 'unicodeCodePoints',
                 results: findings,
             },
         ],
@@ -78,4 +97,3 @@ export function toSarif(results, cwd = process.cwd()) {
 export function printResults(results) {
     console.log(JSON.stringify(toSarif(results), null, 2));
 }
-//# sourceMappingURL=sarif.js.map

package/dist/formatters/stylish.d.ts

@@ -9,4 +9,3 @@ export declare function startRun(): FormatterRun;
  * stops the linter running is written to stderr instead.
  */
 export declare function printResults(results: readonly FileResult[]): void;
-//# sourceMappingURL=stylish.d.ts.map

package/dist/formatters/stylish.js

@@ -94,4 +94,3 @@ export function printResults(results) {
         console.log('\n');
     }
 }
-//# sourceMappingURL=stylish.js.map

package/dist/formatters/tap.d.ts

@@ -25,4 +25,3 @@ export declare function startRun(): FormatterRun;
 export declare function format(results: readonly FileResult[]): string;
 /** Writes the TAP stream to stdout. */
 export declare function printResults(results: readonly FileResult[]): void;
-//# sourceMappingURL=tap.d.ts.map

package/dist/formatters/tap.js

@@ -1,9 +1,42 @@
 /**
- * Quotes a scalar for YAML using single quotes, in which the only character
- * needing attention is the quote itself.
+ * Characters a single-quoted YAML scalar cannot hold as they are: anything
+ * YAML does not count as printable, and line breaks, which it would fold.
+ */
+const NEEDS_ESCAPING = /[^\t\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u;
+/**
+ * Quotes a scalar for YAML. Single quotes, in which the only character needing
+ * attention is the quote itself, unless the value holds something they cannot
+ * carry; then double quotes, which can escape anything.
  */
 function quote(value) {
-    return `'${value.split("'").join("''")}'`;
+    if (!NEEDS_ESCAPING.test(value)) {
+        return `'${value.split("'").join("''")}'`;
+    }
+    let escaped = '';
+    for (const character of value) {
+        if (character === '"' || character === '\\') {
+            escaped += `\\${character}`;
+        }
+        else if (NEEDS_ESCAPING.test(character)) {
+            const code = character.codePointAt(0);
+            escaped +=
+                code <= 0xff
+                    ? `\\x${code.toString(16).padStart(2, '0')}`
+                    : `\\u${code.toString(16).padStart(4, '0')}`;
+        }
+        else {
+            escaped += character;
+        }
+    }
+    return `"${escaped}"`;
+}
+/**
+ * Escapes a test point's description. An unescaped `#` starts a directive, so
+ * a failing file whose path holds `# TODO` or `# SKIP` would be read as one
+ * that is allowed to fail, and the run would pass.
+ */
+function description(text) {
+    return text.replace(/[\\#]/g, '\\$&');
 }
 function severityOf(error) {
     return error.severity ?? 'error';
@@ -41,7 +74,7 @@ export function startRun() {
         file(result) {
             count++;
             const status = fails(result) ? 'not ok' : 'ok';
-            return [`${status} ${count} - ${result.filePath}`, ...diagnostics(result), ''].join('\n');
+            return [`${status} ${count} - ${description(result.filePath)}`, ...diagnostics(result), ''].join('\n');
         },
         end: () => `1..${count}\n`,
     };
@@ -57,4 +90,3 @@ export function format(results) {
 export function printResults(results) {
     console.log(format(results));
 }
-//# sourceMappingURL=tap.js.map

package/dist/gherkin/dialects.d.ts

@@ -28,4 +28,3 @@ export declare function isKnownLanguage(language: string): boolean;
  * entirely in one language set it once instead of in every file.
  */
 export declare function detectLanguage(lines: readonly string[], fallback?: string): string;
-//# sourceMappingURL=dialects.d.ts.map

package/dist/gherkin/dialects.js

@@ -37,4 +37,3 @@ export function detectLanguage(lines, fallback = DEFAULT_LANGUAGE) {
     }
     return isKnownLanguage(fallback) ? fallback : DEFAULT_LANGUAGE;
 }
-//# sourceMappingURL=dialects.js.map

package/dist/gherkin/keywords.d.ts

@@ -8,10 +8,14 @@ import type { Background, Examples, Feature, Rule, Scenario, Step } from '@cucum
 /** Any node that carries a Gherkin keyword. */
 export type KeywordNode = Feature | Rule | Background | Scenario | Examples | Step;
 /** The keyword categories used across the rules. */
-export type NeutralKeyword = 'feature' | 'rule' | 'background' | 'scenario' | 'scenariooutline' | 'examples' | 'given' | 'when' | 'then' | 'and' | 'but' | '';
+export type NeutralKeyword = 'feature' | 'rule' | 'background' | 'scenario' | 'scenariooutline' | 'examples' | 'given' | 'when' | 'then' | 'and' | 'but' | 'star' | '';
 /**
  * Maps a node's localised keyword (`Szenario`) onto the language-neutral name
  * (`scenario`). Returns an empty string for keywords the dialect does not know.
+ *
+ * `*` is `star` of its own. Every dialect lists it under all five step
+ * keywords, so looking it up would say `given` - but like `And` it carries on
+ * from the step before it, which is how Cucumber reads it too.
  */
 export declare function getNeutralKeyword(node: Pick<KeywordNode, 'keyword'>, language: string | undefined): NeutralKeyword;
 /**
@@ -24,8 +28,7 @@ export declare function getNeutralKeyword(node: Pick<KeywordNode, 'keyword'>, la
  * the empty string, the same as a keyword the dialect does not know.
  */
 export declare function resolvedStepKeywords(steps: readonly Pick<Step, 'keyword'>[], language: string | undefined): NeutralKeyword[];
-/** True when the keyword is a Given/When/Then/And/But step keyword. */
+/** True when the keyword is a Given/When/Then/And/But/`*` step keyword. */
 export declare function isStepKeyword(keyword: NeutralKeyword): boolean;
 /** The display name for a node, as used in error messages. */
 export declare function getNodeType(node: Pick<KeywordNode, 'keyword'>, language: string | undefined): string;
-//# sourceMappingURL=keywords.d.ts.map

package/dist/gherkin/keywords.js

@@ -12,12 +12,19 @@ const KEYWORD_FIELDS = [
     'and',
     'but',
 ];
-const STEP_KEYWORDS = new Set(['given', 'when', 'then', 'and', 'but']);
+const STEP_KEYWORDS = new Set(['given', 'when', 'then', 'and', 'but', 'star']);
 /**
  * Maps a node's localised keyword (`Szenario`) onto the language-neutral name
  * (`scenario`). Returns an empty string for keywords the dialect does not know.
+ *
+ * `*` is `star` of its own. Every dialect lists it under all five step
+ * keywords, so looking it up would say `given` - but like `And` it carries on
+ * from the step before it, which is how Cucumber reads it too.
  */
 export function getNeutralKeyword(node, language) {
+    if (node.keyword.trim() === '*') {
+        return 'star';
+    }
     const dialect = getDialect(language);
     for (const field of KEYWORD_FIELDS) {
         if (dialect[field].includes(node.keyword)) {
@@ -39,14 +46,14 @@ export function resolvedStepKeywords(steps, language) {
     let carried = '';
     return steps.map((step) => {
         const keyword = getNeutralKeyword(step, language);
-        if (keyword === 'and' || keyword === 'but') {
+        if (keyword === 'and' || keyword === 'but' || keyword === 'star') {
             return carried;
         }
         carried = keyword;
         return keyword;
     });
 }
-/** True when the keyword is a Given/When/Then/And/But step keyword. */
+/** True when the keyword is a Given/When/Then/And/But/`*` step keyword. */
 export function isStepKeyword(keyword) {
     return STEP_KEYWORDS.has(keyword);
 }
@@ -70,4 +77,3 @@ export function getNodeType(node, language) {
             return isStepKeyword(keyword) ? 'Step' : '';
     }
 }
-//# sourceMappingURL=keywords.js.map

package/dist/gherkin/parse.d.ts

@@ -70,4 +70,3 @@ export interface ReadOptions {
  * is what the rules looking across files need.
  */
 export declare function readAndParseFiles(files: Sequence<string>, options?: ReadOptions): AsyncGenerator<ParseResult>;
-//# sourceMappingURL=parse.d.ts.map

package/dist/gherkin/parse.js

@@ -81,16 +81,26 @@ function startsWithKeyword(text, keywords) {
     return keywords.some((keyword) => text.startsWith(`${keyword.trim()}:`));
 }
 /**
- * True when a Background is already open above `line`.
+ * True when a Background is already open above `line`, in the same Feature
+ * or Rule.
  *
  * The parser rejects a second Background and a Background written below a
  * Scenario in exactly the same way, but they are different mistakes with
- * different fixes, so the lines above are checked to tell them apart.
+ * different fixes, so the lines above are checked to tell them apart. A Rule
+ * may have a Background of its own beside the Feature's, so the search stops
+ * at the Rule the line belongs to.
  */
 function hasEarlierBackground(lines, line, dialect) {
-    return lines
-        .slice(0, Math.max(0, line - 1))
-        .some((text) => startsWithKeyword(text.trim(), dialect.background));
+    for (let index = line - 2; index >= 0; index--) {
+        const text = lines[index].trim();
+        if (startsWithKeyword(text, dialect.background)) {
+            return true;
+        }
+        if (startsWithKeyword(text, dialect.rule)) {
+            return false;
+        }
+    }
+    return false;
 }
 /** The step keywords of a dialect, without the `*` wildcard, for messages. */
 function stepKeywordsFor(dialect) {
@@ -191,7 +201,10 @@ export function toLines(source) {
  * language.
  */
 export function parseFeature(relativePath, source, defaultLanguage = DEFAULT_LANGUAGE) {
-    const lines = toLines(source);
+    // A byte order mark, as some Windows editors write, is not text: left in,
+    // it is one more character at the start of line 1, and every column on
+    // that line is one out.
+    const lines = toLines(source.replace(/^\uFEFF/u, ''));
     const file = { relativePath, lines };
     const dialect = getDialect(detectLanguage(lines, defaultLanguage));
     const errors = [];
@@ -298,4 +311,3 @@ export const DEFAULT_READ_AHEAD = 16;
 export function readAndParseFiles(files, options = {}) {
     return mapWithWindow(files, options.readAhead ?? DEFAULT_READ_AHEAD, (file) => readAndParseFile(file, options.language));
 }
-//# sourceMappingURL=parse.js.map

package/dist/gherkin/traverse.d.ts

@@ -50,4 +50,3 @@ export interface TaggedNode {
  * with the ones it inherits does not have to walk the tree itself.
  */
 export declare function taggedNodesOf(feature: Feature): Generator<TaggedNode>;
-//# sourceMappingURL=traverse.d.ts.map

package/dist/gherkin/traverse.js

@@ -109,4 +109,3 @@ export function* taggedNodesOf(feature) {
         }
     }
 }
-//# sourceMappingURL=traverse.js.map

package/dist/gherkin/variables.d.ts

@@ -14,13 +14,24 @@ export interface Position {
 }
 /** Variable name -> every place it appears. */
 export type Sightings = Map<string, Position[]>;
+/** The columns one Examples table declares. */
+export interface ExamplesTable {
+    /** The line of the `Examples:` keyword. */
+    line: number;
+    columns: Set<string>;
+}
 /** What a Scenario Outline declares, and what it actually uses. */
 export interface ScenarioVariables {
     /** Column names, against the Examples header cells declaring them. */
     declared: Sightings;
+    /**
+     * Each Examples table with a header, on its own. Cucumber runs the rows of
+     * each table separately, so a variable has to be declared in every one of
+     * them, not merely in one.
+     */
+    tables: ExamplesTable[];
     /** Variable names, against every node using them. */
     used: Sightings;
 }
 /** Gathers the variables a Scenario Outline declares and the ones it uses. */
 export declare function variablesOf(scenario: Scenario): ScenarioVariables;
-//# sourceMappingURL=variables.d.ts.map

package/dist/gherkin/variables.js

@@ -1,6 +1,13 @@
 import { at } from '../util/location.js';
-/** `<name>` placeholders, as used in Scenario Outlines. */
-const VARIABLE = /<([^>]*)>/gu;
+/**
+ * `<name>` placeholders, as used in Scenario Outlines.
+ *
+ * Cucumber substitutes any column name written in angle brackets, so what
+ * counts as one here is only what could be a column name: not starting or
+ * ending with a space or `/`, and holding no quotes or `=`. Without that,
+ * `x < 5 and y > 3`, `<div class="x">` and `<br/>` would read as variables.
+ */
+const VARIABLE = /<([^<>\s"'=/](?:[^<>\n"'=]*[^<>\s"'=/])?)>/gu;
 function note(variable, position, into) {
     const seen = into.get(variable);
     if (seen === undefined) {
@@ -25,12 +32,19 @@ function collect(text, position, into) {
 export function variablesOf(scenario) {
     const declared = new Map();
     const used = new Map();
+    const tables = [];
     for (const examples of scenario.examples) {
-        for (const cell of examples.tableHeader?.cells ?? []) {
+        if (examples.tableHeader === undefined) {
+            continue;
+        }
+        const columns = new Set();
+        for (const cell of examples.tableHeader.cells) {
             if (cell.value !== '') {
                 note(cell.value, at(cell.location), declared);
+                columns.add(cell.value);
             }
         }
+        tables.push({ line: examples.location.line, columns });
     }
     collect(scenario.name, at(scenario.location), used);
     for (const step of scenario.steps) {
@@ -42,10 +56,14 @@ export function variablesOf(scenario) {
                 collect(cell.value, at(cell.location), used);
             }
         }
+        // A doc string's content starts on the line below its opening delimiter,
+        // and each line of it is reported where it is.
         if (step.docString !== undefined) {
-            collect(step.docString.content, at(step.location), used);
+            const { content, location } = step.docString;
+            content.split('\n').forEach((line, index) => {
+                collect(line, { line: location.line + 1 + index, column: location.column }, used);
+            });
         }
     }
-    return { declared, used };
+    return { declared, tables, used };
 }
-//# sourceMappingURL=variables.js.map

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * import {findFeatureFiles, lint, loadRules, readConfiguration} from 'gurkencheck';
  *
  * const rules = await loadRules();
- * const config = readConfiguration('.gurkencheckrc', rules);
+ * const config = await readConfiguration('.gurkencheckrc', rules);
  * if (config.ok) {
  *   const {files} = findFeatureFiles(['features']);
  *   const results = await lint(files, config.configuration, rules);
@@ -54,4 +54,3 @@ export type { StatsFormatOptions, StatsFormatter } from './stats/format/index.ts
 export { runStats, statsUsage } from './stats/command.ts';
 export type { Distribution, Inventory, KeywordMix, LanguageEntry, ScenarioRef, ScenarioStats, SimilarGroup, Statistics, StepEntry, StepStats, TagEntry, TagStats, UnreadableFile, } from './stats/types.ts';
 export type { Configuration, FeatureFile, FileResult, LintRule, RuleConfig, RuleError, RuleRegistry, RuleState, RunContext, RunFinding, Severity, } from './types.ts';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -5,7 +5,7 @@
  * import {findFeatureFiles, lint, loadRules, readConfiguration} from 'gurkencheck';
  *
  * const rules = await loadRules();
- * const config = readConfiguration('.gurkencheckrc', rules);
+ * const config = await readConfiguration('.gurkencheckrc', rules);
  * if (config.ok) {
  *   const {files} = findFeatureFiles(['features']);
  *   const results = await lint(files, config.configuration, rules);
@@ -38,4 +38,3 @@ export { DEFAULT_SIMILARITY, boundedEditDistance, groupSimilar } from './stats/s
 export { NUMBER_MARKER, PLACEHOLDER_MARKER, STRING_MARKER, countWords, normaliseStepText, } from './stats/normalise.js';
 export { DEFAULT_STATS_FORMAT, DEFAULT_TOP, STATS_FORMATTERS, getStatsFormatter, toJson as statisticsToJson, toMarkdown, toText, } from './stats/format/index.js';
 export { runStats, statsUsage } from './stats/command.js';
-//# sourceMappingURL=index.js.map

package/dist/linter.d.ts

@@ -48,4 +48,3 @@ export declare function countBySeverity(results: readonly FileResult[]): {
     errors: number;
     warnings: number;
 };
-//# sourceMappingURL=linter.d.ts.map

package/dist/linter.js

@@ -54,7 +54,7 @@ export async function* lintStream(files, configuration, rules, options = {}) {
         let suppressions = EMPTY_SUPPRESSIONS;
         if (errors.length === 0) {
             errors = await runEnabledRules(result.feature, result.file, configuration, rules, run);
-            suppressions = readSuppressions(result.file.lines);
+            suppressions = readSuppressions(result.file.lines, result.feature);
             if (!suppressions.isEmpty) {
                 errors = errors.filter((error) => !suppressions.isSuppressed(error));
             }
@@ -121,4 +121,3 @@ export function countBySeverity(results) {
     }
     return { errors, warnings };
 }
-//# sourceMappingURL=linter.js.map

package/dist/logger.d.ts

@@ -15,4 +15,3 @@ export declare const style: {
     /** Red for something that fails the run, yellow for something that does not. */
     severity: (severity: string, text: string) => string;
 };
-//# sourceMappingURL=logger.d.ts.map

package/dist/logger.js

@@ -29,4 +29,3 @@ export const style = {
     /** Red for something that fails the run, yellow for something that does not. */
     severity: (severity, text) => paint(severity === 'warning' ? `${ESC}33m` : `${ESC}31m`, text),
 };
-//# sourceMappingURL=logger.js.map

package/dist/main.d.ts

@@ -8,4 +8,3 @@ import type { Diagnostics } from './diagnostics.ts';
  * library leaves the console alone until you ask for it.
  */
 export declare function run(argv: readonly string[], diagnostics?: Diagnostics): Promise<number>;
-//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -29,7 +29,8 @@ function usage() {
         '                          or the path to a formatter of your own',
         `                          (default: ${DEFAULT_FORMAT})`,
         `  -c, --config <path>     configuration file (default: ${DEFAULT_CONFIG_FILE_NAME})`,
-        `  -i, --ignore <globs>    comma separated globs to skip, overriding ${DEFAULT_IGNORE_FILE_NAME}`,
+        `  -i, --ignore <globs>    comma separated globs to skip, overriding ${DEFAULT_IGNORE_FILE_NAME};`,
+        '                          may be given more than once',
         '  -r, --rulesdir <dir>    directory of custom rules; may be given more than once',
         '  -l, --language <code>   dialect for files with no "# language:" header',
         '  -w, --watch             keep running, checking again whenever a file changes',
@@ -65,7 +66,7 @@ export async function run(argv, diagnostics = SILENT) {
             options: {
                 format: { type: 'string', short: 'f' },
                 config: { type: 'string', short: 'c' },
-                ignore: { type: 'string', short: 'i' },
+                ignore: { type: 'string', short: 'i', multiple: true },
                 rulesdir: { type: 'string', short: 'r', multiple: true },
                 language: { type: 'string', short: 'l' },
                 watch: { type: 'boolean', short: 'w' },
@@ -104,16 +105,34 @@ export async function run(argv, diagnostics = SILENT) {
         });
         return EXIT_USAGE;
     }
-    const configuration = await readConfiguration(values.config, rules);
-    if (!configuration.ok) {
-        diagnostics.report({
-            level: 'error',
-            message: configuration.message,
-            details: configuration.details,
-        });
+    /**
+     * The configuration and the dialect it asks for, or `undefined` once what
+     * is wrong with them has been reported. Read again on every pass of a
+     * watch, since a change to the configuration is one of the things it
+     * checks again for.
+     */
+    const readSettings = async () => {
+        const read = await readConfiguration(values.config, rules);
+        if (!read.ok) {
+            diagnostics.report({ level: 'error', message: read.message, details: read.details });
+            return undefined;
+        }
+        const language = values.language ?? read.language;
+        if (language !== undefined && !isKnownLanguage(language)) {
+            diagnostics.report({
+                level: 'error',
+                message: `Unknown language "${language}". Use a Gherkin language code, such as "fr".`,
+            });
+            return undefined;
+        }
+        return { configuration: read.configuration, language, files: read.files };
+    };
+    let settings = await readSettings();
+    if (settings === undefined) {
         return EXIT_USAGE;
     }
-    const ignore = values.ignore?.split(',').map((pattern) => pattern.trim());
+    // Given more than once, the lists add up rather than the last one winning.
+    const ignore = values.ignore?.flatMap((list) => list.split(',').map((pattern) => pattern.trim()));
     // Files are handed over as the walk finds them, so reading and checking
     // start on the first one rather than after the last. Only the patterns are
     // checked here; the walk itself happens once per pass.
@@ -149,22 +168,32 @@ export async function run(argv, diagnostics = SILENT) {
         });
         return EXIT_USAGE;
     }
-    const language = values.language ?? configuration.language;
-    if (language !== undefined && !isKnownLanguage(language)) {
-        diagnostics.report({
-            level: 'error',
-            message: `Unknown language "${language}". Use a Gherkin language code, such as "fr".`,
-        });
-        return EXIT_USAGE;
-    }
     // Discovery is a stream, and a stream can only be read once - so a run that
     // may happen more than once is given a fresh one each time.
     const discover = () => findFeatureFileStream(positionals, ignore).files;
+    let passes = 0;
     const checkOnce = async () => {
+        if (passes++ > 0) {
+            settings = await readSettings();
+            if (settings === undefined) {
+                return EXIT_USAGE;
+            }
+        }
+        const { configuration, language } = settings;
         if (streaming !== undefined) {
-            return await runStreaming(streaming, discover(), configuration.configuration, rules, language, diagnostics);
+            return await runStreaming(streaming, discover(), configuration, rules, language, diagnostics);
+        }
+        let results;
+        try {
+            results = await lint(discover(), configuration, rules, { language });
+        }
+        catch (thrown) {
+            diagnostics.report({
+                level: 'error',
+                message: `The run failed: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+            });
+            return EXIT_USAGE;
         }
-        const results = await lint(discover(), configuration.configuration, rules, { language });
         // A formatter may print the output itself or hand it back as a string.
         let output;
         try {
@@ -186,7 +215,19 @@ export async function run(argv, diagnostics = SILENT) {
         // Watching never fails: a run that found something is the normal state of
         // affairs while you are fixing it, and the exit code is only read once,
         // when you stop.
-        return await watch(featureRoots(positionals), values.config ?? DEFAULT_CONFIG_FILE_NAME, { diagnostics, ignore: DEFAULT_IGNORED_NAMES }, checkOnce);
+        const configPath = values.config ?? DEFAULT_CONFIG_FILE_NAME;
+        return await watch(featureRoots(positionals), configPath, {
+            diagnostics,
+            ignore: DEFAULT_IGNORED_NAMES,
+            // The configuration is watched even when it does not exist yet, so
+            // writing one is noticed; the ignore file only when --ignore is not
+            // there to overrule it.
+            files: () => [
+                configPath,
+                ...(settings?.files ?? []),
+                ...(ignore === undefined ? [DEFAULT_IGNORE_FILE_NAME] : []),
+            ],
+        }, checkOnce);
     }
     return await checkOnce();
 }
@@ -202,20 +243,31 @@ async function runStreaming(streaming, files, configuration, rules, language, di
             process.stdout.write(text);
         }
     };
+    // Linting and writing take turns in one loop, so what failed is recorded
+    // rather than guessed at: a message blaming the formatter for a rule's
+    // mistake sends you looking in the wrong place.
+    let formatting = false;
+    const format = (step) => {
+        formatting = true;
+        const written = step();
+        formatting = false;
+        return written;
+    };
     let failed = false;
     try {
-        const run = streaming();
-        write(run.start?.());
+        const run = format(() => streaming());
+        write(format(() => run.start?.()));
         for await (const result of lintStream(files, configuration, rules, { language })) {
             failed ||= result.errors.some((error) => (error.severity ?? 'error') === 'error');
-            write(run.file(result));
+            write(format(() => run.file(result)));
         }
-        write(run.end?.());
+        write(format(() => run.end?.()));
     }
     catch (thrown) {
+        const reason = thrown instanceof Error ? thrown.message : String(thrown);
         diagnostics.report({
             level: 'error',
-            message: `The formatter failed: ${thrown instanceof Error ? thrown.message : String(thrown)}`,
+            message: formatting ? `The formatter failed: ${reason}` : `The run failed: ${reason}`,
         });
         return EXIT_USAGE;
     }
@@ -268,4 +320,3 @@ async function main(argv) {
 if (isMainModule()) {
     process.exitCode = await main(process.argv.slice(2));
 }
-//# sourceMappingURL=main.js.map

package/dist/presets.d.ts

@@ -8,7 +8,8 @@
  * quiet on a codebase that has never been linted.
  *
  * Rules about style - indentation, name length, which tags go where, whether
- * repeated keywords become And - are deliberately left out. They are worth
+ * repeated keywords become And, and whitespace such as trailing spaces or a
+ * new line at the end of the file - are deliberately left out. They are worth
  * switching on, but that is a decision for a team to make rather than a
  * default to inherit.
  */
@@ -16,4 +17,3 @@ import type { Configuration } from './types.ts';
 export declare const RECOMMENDED: Configuration;
 /** The presets that can be named in a configuration file. */
 export declare const PRESETS: Record<string, Configuration>;
-//# sourceMappingURL=presets.d.ts.map