cspell 8.4.0 → 8.5.0

package/README.md

@@ -150,6 +150,8 @@ Options:
   --file-list <path or stdin>  Specify a list of files to be spell checked. The
                                list is filtered against the glob file patterns.
                                Note: the format is 1 file path per line.
+  --file [file...]             Specify files to spell check. They are filtered
+                               by the [globs...].
   --no-issues                  Do not show the spelling errors.
   --no-progress                Turn off progress messages
   --no-summary                 Turn off summary message in console.
@@ -202,6 +204,13 @@ More Examples:
     cspell . --reporter ./<path>/reporter.cjs
         Use a custom reporter. See API for details.
 
+    cspell "*.md" --exclude CHANGELOG.md --files README.md CHANGELOG.md
+        Spell check only check "README.md" but NOT "CHANGELOG.md".
+
+    cspell "/*.md" --no-must-find-files --files $FILES
+        Only spell check the "/*.md" files in $FILES,
+        where $FILES is a shell variable that contains the list of files.
+
 References:
     https://cspell.org
     https://github.com/streetsidesoftware/cspell

package/dist/esm/commandLint.js

@@ -37,15 +37,20 @@ More Examples:
     cspell . --reporter ./<path>/reporter.cjs
         Use a custom reporter. See API for details.
 
+    cspell "*.md" --exclude CHANGELOG.md --files README.md CHANGELOG.md
+        Spell check only check "README.md" but NOT "CHANGELOG.md".
+
+    cspell "/*.md" --no-must-find-files --files $FILES
+        Only spell check the "/*.md" files in $FILES,
+        where $FILES is a shell variable that contains the list of files.
+
 References:
     https://cspell.org
     https://github.com/streetsidesoftware/cspell
 `;
 function collect(value, previous) {
-    if (!previous) {
-        return [value];
-    }
-    return previous.concat([value]);
+    const values = Array.isArray(value) ? value : [value];
+    return previous ? [...previous, ...values] : values;
 }
 export function commandLint(prog) {
     const spellCheckCommand = prog.command('lint', { isDefault: true });
@@ -55,42 +60,51 @@ export function commandLint(prog) {
         .option('-v, --verbose', 'Display more information about the files being checked and the configuration.')
         .option('--locale <locale>', 'Set language locales. i.e. "en,fr" for English and French, or "en-GB" for British English.')
         .option('--language-id <language>', 'Force programming language for unknown extensions. i.e. "php" or "scala"')
-        .addOption(new CommanderOption('--languageId <language>', 'Force programming language for unknown extensions. i.e. "php" or "scala"').hideHelp())
+        .addOption(crOpt('--languageId <language>', 'Force programming language for unknown extensions. i.e. "php" or "scala"').hideHelp())
         .option('--words-only', 'Only output the words not found in the dictionaries.')
-        .addOption(new CommanderOption('--wordsOnly', 'Only output the words not found in the dictionaries.').hideHelp())
+        .addOption(crOpt('--wordsOnly', 'Only output the words not found in the dictionaries.').hideHelp())
         .option('-u, --unique', 'Only output the first instance of a word not found in the dictionaries.')
         .option('-e, --exclude <glob>', 'Exclude files matching the glob pattern. This option can be used multiple times to add multiple globs. ', collect)
+        // .option('--include <glob>', 'Include files matching the glob pattern. This option can be used multiple times.', collect)
         .option('--file-list <path or stdin>', 'Specify a list of files to be spell checked.' +
         ' The list is filtered against the glob file patterns.' +
         ' Note: the format is 1 file path per line.', collect)
+        .option('--file [file...]', 'Specify files to spell check. They are filtered by the [globs...].', collect)
+        .addOption(crOpt('--files [file...]', 'Files to spell check.', collect).hideHelp())
         .option('--no-issues', 'Do not show the spelling errors.')
         .option('--no-progress', 'Turn off progress messages')
         .option('--no-summary', 'Turn off summary message in console.')
         .option('-s, --silent', 'Silent mode, suppress error messages.')
         .option('--no-exit-code', 'Do not return an exit code if issues are found.')
-        .addOption(new CommanderOption('--quiet', 'Only show spelling issues or errors.').implies({
+        .addOption(crOpt('--quiet', 'Only show spelling issues or errors.').implies({
         summary: false,
         progress: false,
     }))
         .option('--fail-fast', 'Exit after first file with an issue or error.')
-        .addOption(new CommanderOption('--no-fail-fast', 'Process all files even if there is an error.').hideHelp())
+        .addOption(crOpt('--no-fail-fast', 'Process all files even if there is an error.').hideHelp())
         .option('-r, --root <root folder>', 'Root directory, defaults to current directory.')
-        .addOption(new CommanderOption('--relative', 'Issues are displayed relative to the root.').default(true).hideHelp())
+        .addOption(crOpt('--relative', 'Issues are displayed relative to the root.').default(true).hideHelp())
         .option('--no-relative', 'Issues are displayed with absolute path instead of relative to the root.')
         .option('--show-context', 'Show the surrounding text around an issue.')
         .option('--show-suggestions', 'Show spelling suggestions.')
-        .addOption(new CommanderOption('--no-show-suggestions', 'Do not show spelling suggestions or fixes.').default(undefined))
-        .addOption(new CommanderOption('--must-find-files', 'Error if no files are found.').default(true).hideHelp())
+        .addOption(crOpt('--no-show-suggestions', 'Do not show spelling suggestions or fixes.').default(undefined))
+        .addOption(crOpt('--must-find-files', 'Error if no files are found.').default(true).hideHelp())
         .option('--no-must-find-files', 'Do not error if no files are found.')
+        // The --filter-files option is still under design review.
+        // .option('--filter-files', 'Use the `files` configuration to filter files found.')
+        // .option(
+        //     '--no-filter-files',
+        //     'Do NOT use the `files` configuration to filter files (Only applies to --files options).',
+        // )
         // The following options are planned features
         // .option('-w, --watch', 'Watch for any changes to the matching files and report any errors')
         // .option('--force', 'Force the exit value to always be 0')
-        .addOption(new CommanderOption('--legacy', 'Legacy output').hideHelp())
-        .addOption(new CommanderOption('--local <local>', 'Deprecated -- Use: --locale').hideHelp())
+        .addOption(crOpt('--legacy', 'Legacy output').hideHelp())
+        .addOption(crOpt('--local <local>', 'Deprecated -- Use: --locale').hideHelp())
         .option('--cache', 'Use cache to only check changed files.')
         .option('--no-cache', 'Do not use cache.')
         .option('--cache-reset', 'Reset the cache file.')
-        .addOption(new CommanderOption('--cache-strategy <strategy>', 'Strategy to use for detecting changed files.').choices([
+        .addOption(crOpt('--cache-strategy <strategy>', 'Strategy to use for detecting changed files.').choices([
         'metadata',
         'content',
     ]))
@@ -103,26 +117,31 @@ export function commandLint(prog) {
         .option('--no-validate-directives', 'Do not validate in-document CSpell directives.')
         .option('--no-color', 'Turn off color.')
         .option('--color', 'Force color.')
-        .addOption(new CommanderOption('--default-configuration', 'Load the default configuration and dictionaries.').hideHelp())
-        .addOption(new CommanderOption('--no-default-configuration', 'Do not load the default configuration and dictionaries.'))
+        .addOption(crOpt('--default-configuration', 'Load the default configuration and dictionaries.').hideHelp())
+        .addOption(crOpt('--no-default-configuration', 'Do not load the default configuration and dictionaries.'))
         .option('--debug', 'Output information useful for debugging cspell.json files.')
         .option('--reporter <module|path>', 'Specify one or more reporters to use.', collect)
-        .addOption(new CommanderOption('--skip-validation', 'Collect and process documents, but do not spell check.')
+        .addOption(crOpt('--skip-validation', 'Collect and process documents, but do not spell check.')
         .implies({ cache: false })
         .hideHelp())
-        .addOption(new CommanderOption('--issues-summary-report', 'Output a summary of issues found.').hideHelp())
+        .addOption(crOpt('--issues-summary-report', 'Output a summary of issues found.').hideHelp())
+        // Planned options
+        // .option('--dictionary <dictionary name>', 'Enable a dictionary by name.', collect)
+        // .option('--no-dictionary <dictionary name>', 'Disable a dictionary by name.', collect)
+        // .option('--import', 'Import a configuration file.', collect)
         .usage(usage)
         .addHelpText('after', advanced)
         .arguments('[globs...]')
         .action(async (fileGlobs, options) => {
+        // console.error('lint: %o', { fileGlobs, options });
         const useExitCode = options.exitCode ?? true;
         if (options.skipValidation) {
             options.cache = false;
         }
         App.parseApplicationFeatureFlags(options.flag);
-        const { mustFindFiles, fileList } = options;
+        const { mustFindFiles, fileList, files, file } = options;
         const result = await App.lint(fileGlobs, options);
-        if (!fileGlobs.length && !result.files && !result.errors && !fileList) {
+        if (!fileGlobs.length && !result.files && !result.errors && !fileList && !files?.length && !file?.length) {
             spellCheckCommand.outputHelp();
             throw new CheckFailed('outputHelp', 1);
         }
@@ -137,4 +156,22 @@ export function commandLint(prog) {
     });
     return spellCheckCommand;
 }
+/**
+ * Create Option - a helper function to create a commander option.
+ * @param name - the name of the option
+ * @param description - the description of the option
+ * @param parseArg - optional function to parse the argument
+ * @param defaultValue - optional default value
+ * @returns CommanderOption
+ */
+function crOpt(name, description, parseArg, defaultValue) {
+    const option = new CommanderOption(name, description);
+    if (parseArg) {
+        option.argParser(parseArg);
+    }
+    if (defaultValue !== undefined) {
+        option.default(defaultValue);
+    }
+    return option;
+}
 //# sourceMappingURL=commandLint.js.map

package/dist/esm/commandLint.mjs

@@ -37,15 +37,20 @@ More Examples:
     cspell . --reporter ./<path>/reporter.cjs
         Use a custom reporter. See API for details.
 
+    cspell "*.md" --exclude CHANGELOG.md --files README.md CHANGELOG.md
+        Spell check only check "README.md" but NOT "CHANGELOG.md".
+
+    cspell "/*.md" --no-must-find-files --files $FILES
+        Only spell check the "/*.md" files in $FILES,
+        where $FILES is a shell variable that contains the list of files.
+
 References:
     https://cspell.org
     https://github.com/streetsidesoftware/cspell
 `;
 function collect(value, previous) {
-    if (!previous) {
-        return [value];
-    }
-    return previous.concat([value]);
+    const values = Array.isArray(value) ? value : [value];
+    return previous ? [...previous, ...values] : values;
 }
 export function commandLint(prog) {
     const spellCheckCommand = prog.command('lint', { isDefault: true });
@@ -55,42 +60,51 @@ export function commandLint(prog) {
         .option('-v, --verbose', 'Display more information about the files being checked and the configuration.')
         .option('--locale <locale>', 'Set language locales. i.e. "en,fr" for English and French, or "en-GB" for British English.')
         .option('--language-id <language>', 'Force programming language for unknown extensions. i.e. "php" or "scala"')
-        .addOption(new CommanderOption('--languageId <language>', 'Force programming language for unknown extensions. i.e. "php" or "scala"').hideHelp())
+        .addOption(crOpt('--languageId <language>', 'Force programming language for unknown extensions. i.e. "php" or "scala"').hideHelp())
         .option('--words-only', 'Only output the words not found in the dictionaries.')
-        .addOption(new CommanderOption('--wordsOnly', 'Only output the words not found in the dictionaries.').hideHelp())
+        .addOption(crOpt('--wordsOnly', 'Only output the words not found in the dictionaries.').hideHelp())
         .option('-u, --unique', 'Only output the first instance of a word not found in the dictionaries.')
         .option('-e, --exclude <glob>', 'Exclude files matching the glob pattern. This option can be used multiple times to add multiple globs. ', collect)
+        // .option('--include <glob>', 'Include files matching the glob pattern. This option can be used multiple times.', collect)
         .option('--file-list <path or stdin>', 'Specify a list of files to be spell checked.' +
         ' The list is filtered against the glob file patterns.' +
         ' Note: the format is 1 file path per line.', collect)
+        .option('--file [file...]', 'Specify files to spell check. They are filtered by the [globs...].', collect)
+        .addOption(crOpt('--files [file...]', 'Files to spell check.', collect).hideHelp())
         .option('--no-issues', 'Do not show the spelling errors.')
         .option('--no-progress', 'Turn off progress messages')
         .option('--no-summary', 'Turn off summary message in console.')
         .option('-s, --silent', 'Silent mode, suppress error messages.')
         .option('--no-exit-code', 'Do not return an exit code if issues are found.')
-        .addOption(new CommanderOption('--quiet', 'Only show spelling issues or errors.').implies({
+        .addOption(crOpt('--quiet', 'Only show spelling issues or errors.').implies({
         summary: false,
         progress: false,
     }))
         .option('--fail-fast', 'Exit after first file with an issue or error.')
-        .addOption(new CommanderOption('--no-fail-fast', 'Process all files even if there is an error.').hideHelp())
+        .addOption(crOpt('--no-fail-fast', 'Process all files even if there is an error.').hideHelp())
         .option('-r, --root <root folder>', 'Root directory, defaults to current directory.')
-        .addOption(new CommanderOption('--relative', 'Issues are displayed relative to the root.').default(true).hideHelp())
+        .addOption(crOpt('--relative', 'Issues are displayed relative to the root.').default(true).hideHelp())
         .option('--no-relative', 'Issues are displayed with absolute path instead of relative to the root.')
         .option('--show-context', 'Show the surrounding text around an issue.')
         .option('--show-suggestions', 'Show spelling suggestions.')
-        .addOption(new CommanderOption('--no-show-suggestions', 'Do not show spelling suggestions or fixes.').default(undefined))
-        .addOption(new CommanderOption('--must-find-files', 'Error if no files are found.').default(true).hideHelp())
+        .addOption(crOpt('--no-show-suggestions', 'Do not show spelling suggestions or fixes.').default(undefined))
+        .addOption(crOpt('--must-find-files', 'Error if no files are found.').default(true).hideHelp())
         .option('--no-must-find-files', 'Do not error if no files are found.')
+        // The --filter-files option is still under design review.
+        // .option('--filter-files', 'Use the `files` configuration to filter files found.')
+        // .option(
+        //     '--no-filter-files',
+        //     'Do NOT use the `files` configuration to filter files (Only applies to --files options).',
+        // )
         // The following options are planned features
         // .option('-w, --watch', 'Watch for any changes to the matching files and report any errors')
         // .option('--force', 'Force the exit value to always be 0')
-        .addOption(new CommanderOption('--legacy', 'Legacy output').hideHelp())
-        .addOption(new CommanderOption('--local <local>', 'Deprecated -- Use: --locale').hideHelp())
+        .addOption(crOpt('--legacy', 'Legacy output').hideHelp())
+        .addOption(crOpt('--local <local>', 'Deprecated -- Use: --locale').hideHelp())
         .option('--cache', 'Use cache to only check changed files.')
         .option('--no-cache', 'Do not use cache.')
         .option('--cache-reset', 'Reset the cache file.')
-        .addOption(new CommanderOption('--cache-strategy <strategy>', 'Strategy to use for detecting changed files.').choices([
+        .addOption(crOpt('--cache-strategy <strategy>', 'Strategy to use for detecting changed files.').choices([
         'metadata',
         'content',
     ]))
@@ -103,26 +117,31 @@ export function commandLint(prog) {
         .option('--no-validate-directives', 'Do not validate in-document CSpell directives.')
         .option('--no-color', 'Turn off color.')
         .option('--color', 'Force color.')
-        .addOption(new CommanderOption('--default-configuration', 'Load the default configuration and dictionaries.').hideHelp())
-        .addOption(new CommanderOption('--no-default-configuration', 'Do not load the default configuration and dictionaries.'))
+        .addOption(crOpt('--default-configuration', 'Load the default configuration and dictionaries.').hideHelp())
+        .addOption(crOpt('--no-default-configuration', 'Do not load the default configuration and dictionaries.'))
         .option('--debug', 'Output information useful for debugging cspell.json files.')
         .option('--reporter <module|path>', 'Specify one or more reporters to use.', collect)
-        .addOption(new CommanderOption('--skip-validation', 'Collect and process documents, but do not spell check.')
+        .addOption(crOpt('--skip-validation', 'Collect and process documents, but do not spell check.')
         .implies({ cache: false })
         .hideHelp())
-        .addOption(new CommanderOption('--issues-summary-report', 'Output a summary of issues found.').hideHelp())
+        .addOption(crOpt('--issues-summary-report', 'Output a summary of issues found.').hideHelp())
+        // Planned options
+        // .option('--dictionary <dictionary name>', 'Enable a dictionary by name.', collect)
+        // .option('--no-dictionary <dictionary name>', 'Disable a dictionary by name.', collect)
+        // .option('--import', 'Import a configuration file.', collect)
         .usage(usage)
         .addHelpText('after', advanced)
         .arguments('[globs...]')
         .action(async (fileGlobs, options) => {
+        // console.error('lint: %o', { fileGlobs, options });
         const useExitCode = options.exitCode ?? true;
         if (options.skipValidation) {
             options.cache = false;
         }
         App.parseApplicationFeatureFlags(options.flag);
-        const { mustFindFiles, fileList } = options;
+        const { mustFindFiles, fileList, files, file } = options;
         const result = await App.lint(fileGlobs, options);
-        if (!fileGlobs.length && !result.files && !result.errors && !fileList) {
+        if (!fileGlobs.length && !result.files && !result.errors && !fileList && !files?.length && !file?.length) {
             spellCheckCommand.outputHelp();
             throw new CheckFailed('outputHelp', 1);
         }
@@ -137,4 +156,22 @@ export function commandLint(prog) {
     });
     return spellCheckCommand;
 }
+/**
+ * Create Option - a helper function to create a commander option.
+ * @param name - the name of the option
+ * @param description - the description of the option
+ * @param parseArg - optional function to parse the argument
+ * @param defaultValue - optional default value
+ * @returns CommanderOption
+ */
+function crOpt(name, description, parseArg, defaultValue) {
+    const option = new CommanderOption(name, description);
+    if (parseArg) {
+        option.argParser(parseArg);
+    }
+    if (defaultValue !== undefined) {
+        option.default(defaultValue);
+    }
+    return option;
+}
 //# sourceMappingURL=commandLint.mjs.map

package/dist/esm/lint/LintRequest.d.mts

@@ -4,6 +4,7 @@ import type { GlobSrcInfo } from '../util/glob.mjs';
 import type { FinalizedReporter } from '../util/reporters.mjs';
 interface Deprecated {
     fileLists?: LinterOptions['fileList'];
+    local?: LinterOptions['locale'];
 }
 export declare class LintRequest {
     readonly fileGlobs: string[];
@@ -17,6 +18,7 @@ export declare class LintRequest {
     readonly showContext: number;
     readonly enableGlobDot: boolean | undefined;
     readonly fileLists: string[];
+    readonly files: string[] | undefined;
     constructor(fileGlobs: string[], options: LinterOptions & Deprecated, reporter: FinalizedReporter);
 }
 export {};

package/dist/esm/lint/LintRequest.d.ts

@@ -4,6 +4,7 @@ import type { GlobSrcInfo } from '../util/glob.js';
 import type { FinalizedReporter } from '../util/reporters.js';
 interface Deprecated {
     fileLists?: LinterOptions['fileList'];
+    local?: LinterOptions['locale'];
 }
 export declare class LintRequest {
     readonly fileGlobs: string[];
@@ -17,6 +18,7 @@ export declare class LintRequest {
     readonly showContext: number;
     readonly enableGlobDot: boolean | undefined;
     readonly fileLists: string[];
+    readonly files: string[] | undefined;
     constructor(fileGlobs: string[], options: LinterOptions & Deprecated, reporter: FinalizedReporter);
 }
 export {};

package/dist/esm/lint/LintRequest.js

@@ -13,6 +13,7 @@ export class LintRequest {
     showContext;
     enableGlobDot;
     fileLists;
+    files;
     constructor(fileGlobs, options, reporter) {
         this.fileGlobs = fileGlobs;
         this.options = options;
@@ -20,13 +21,27 @@ export class LintRequest {
         this.root = path.resolve(options.root || process.cwd());
         this.configFile = options.config;
         this.excludes = calcExcludeGlobInfo(this.root, options.exclude);
-        this.locale = options.locale || '';
+        this.locale = options.locale ?? options.local ?? '';
         this.enableGlobDot = options.dot;
         // this.uniqueFilter = options.unique ? util.uniqueFilterFnGenerator((issue: Issue) => issue.text) : () => true;
         this.uniqueFilter = () => true;
         this.showContext =
             options.showContext === true ? defaultContextRange : options.showContext ? options.showContext : 0;
         this.fileLists = (options.fileList ?? options.fileLists) || [];
+        this.files = mergeFiles(options.file, options.files);
     }
 }
+function mergeFiles(a, b) {
+    const files = merge(a, b);
+    if (!files)
+        return undefined;
+    return [...new Set(files.flatMap((a) => a.split('\n').map((a) => a.trim())).filter((a) => !!a))];
+}
+function merge(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return [...a, ...b];
+}
 //# sourceMappingURL=LintRequest.js.map

package/dist/esm/lint/LintRequest.mjs

@@ -13,6 +13,7 @@ export class LintRequest {
     showContext;
     enableGlobDot;
     fileLists;
+    files;
     constructor(fileGlobs, options, reporter) {
         this.fileGlobs = fileGlobs;
         this.options = options;
@@ -20,13 +21,27 @@ export class LintRequest {
         this.root = path.resolve(options.root || process.cwd());
         this.configFile = options.config;
         this.excludes = calcExcludeGlobInfo(this.root, options.exclude);
-        this.locale = options.locale || '';
+        this.locale = options.locale ?? options.local ?? '';
         this.enableGlobDot = options.dot;
         // this.uniqueFilter = options.unique ? util.uniqueFilterFnGenerator((issue: Issue) => issue.text) : () => true;
         this.uniqueFilter = () => true;
         this.showContext =
             options.showContext === true ? defaultContextRange : options.showContext ? options.showContext : 0;
         this.fileLists = (options.fileList ?? options.fileLists) || [];
+        this.files = mergeFiles(options.file, options.files);
     }
 }
+function mergeFiles(a, b) {
+    const files = merge(a, b);
+    if (!files)
+        return undefined;
+    return [...new Set(files.flatMap((a) => a.split('\n').map((a) => a.trim())).filter((a) => !!a))];
+}
+function merge(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return [...a, ...b];
+}
 //# sourceMappingURL=LintRequest.mjs.map

package/dist/esm/lint/lint.js

@@ -1,4 +1,4 @@
-import { isAsyncIterable, operators, opFilter, pipeAsync, pipeSync } from '@cspell/cspell-pipe';
+import { isAsyncIterable, operators, opFilter, pipeAsync } from '@cspell/cspell-pipe';
 import { opMap, pipe } from '@cspell/cspell-pipe/sync';
 import { MessageTypes } from '@cspell/cspell-types';
 import chalk from 'chalk';
@@ -12,7 +12,7 @@ import { npmPackage } from '../../lib/pkgInfo.cjs';
 import { getFeatureFlags } from '../featureFlags/index.js';
 import { calcCacheSettings, createCache } from '../util/cache/index.js';
 import { CheckFailed, toApplicationError, toError } from '../util/errors.js';
-import { fileInfoToDocument, filenameToUri, findFiles, isBinaryFile, isNotDir, readConfig, readFileInfo, readFileListFiles, } from '../util/fileHelper.js';
+import { fileInfoToDocument, filenameToUri, findFiles, isBinaryFile, isFile, isNotDir, readConfig, readFileInfo, readFileListFiles, resolveFilename, } from '../util/fileHelper.js';
 import { buildGlobMatcher, extractGlobsFromMatcher, extractPatterns, normalizeFileOrGlobsToRoot, normalizeGlobsToRoot, } from '../util/glob.js';
 import { prefetchIterable } from '../util/prefetch.js';
 import { loadReporters, mergeReporters } from '../util/reporters.js';
@@ -288,7 +288,7 @@ export async function runLint(cfg) {
         const globInfo = await determineGlobs(configInfo, cfg);
         const { fileGlobs, excludeGlobs } = globInfo;
         const hasFileLists = !!cfg.fileLists.length;
-        if (!fileGlobs.length && !hasFileLists) {
+        if (!fileGlobs.length && !hasFileLists && !cfg.files?.length) {
             // Nothing to do.
             return runResult();
         }
@@ -339,7 +339,7 @@ async function determineGlobs(configInfo, cfg) {
     const gitignoreRoots = cfg.options.gitignoreRoot ?? configInfo.config.gitignoreRoot;
     const gitIgnore = useGitignore ? await generateGitIgnore(gitignoreRoots) : undefined;
     const cliGlobs = cfg.fileGlobs;
-    const allGlobs = cliGlobs.length ? cliGlobs : configInfo.config.files || [];
+    const allGlobs = (cliGlobs.length && cliGlobs) || (cfg.options.filterFiles !== false && configInfo.config.files) || [];
     const combinedGlobs = await normalizeFileOrGlobsToRoot(allGlobs, cfg.root);
     const cliExcludeGlobs = extractPatterns(cfg.excludes).map((p) => p.glob);
     const normalizedExcludes = normalizeGlobsToRoot(cliExcludeGlobs, cfg.root, true);
@@ -370,14 +370,19 @@ async function determineFilesToCheck(configInfo, cfg, reporter, globInfo) {
         if (enableGlobDot !== undefined) {
             globOptions.dot = enableGlobDot;
         }
-        const filterFiles = opFilter(filterFilesFn(globMatcher));
-        const foundFiles = await (hasFileLists
-            ? useFileLists(fileLists, allGlobs, root, enableGlobDot)
-            : findFiles(fileGlobs, globOptions));
+        const opFilterExcludedFiles = opFilter(filterOutExcludedFilesFn(globMatcher));
+        const includeFilter = createIncludeFileFilterFn(allGlobs, root, enableGlobDot);
+        const rawCliFiles = cfg.files?.map((file) => resolveFilename(file, root)).filter(includeFilter);
+        const cliFiles = cfg.options.mustFindFiles
+            ? rawCliFiles
+            : rawCliFiles && pipeAsync(rawCliFiles, opFilterAsync(isFile));
+        const foundFiles = hasFileLists
+            ? concatAsyncIterables(cliFiles, await useFileLists(fileLists, includeFilter))
+            : cliFiles || (await findFiles(fileGlobs, globOptions));
         const filtered = gitIgnore ? await gitIgnore.filterOutIgnored(foundFiles) : foundFiles;
         const files = isAsyncIterable(filtered)
-            ? pipeAsync(filtered, filterFiles)
-            : [...pipeSync(filtered, filterFiles)];
+            ? pipeAsync(filtered, opFilterExcludedFiles)
+            : [...pipe(filtered, opFilterExcludedFiles)];
         return files;
     }
     function isExcluded(filename, globMatcherExclude) {
@@ -393,7 +398,7 @@ async function determineFilesToCheck(configInfo, cfg, reporter, globInfo) {
         }
         return r.matched;
     }
-    function filterFilesFn(globMatcherExclude) {
+    function filterOutExcludedFilesFn(globMatcherExclude) {
         const patterns = globMatcherExclude.patterns;
         const excludeInfo = patterns
             .map(extractGlobSource)
@@ -475,15 +480,27 @@ async function generateGitIgnore(roots) {
     }
     return new GitIgnore(root?.map((p) => path.resolve(p)));
 }
-async function useFileLists(fileListFiles, includeGlobPatterns, root, dot) {
-    includeGlobPatterns = includeGlobPatterns.length ? includeGlobPatterns : ['**'];
+async function useFileLists(fileListFiles, filterFiles) {
+    const files = readFileListFiles(fileListFiles);
+    return pipeAsync(files, opFilter(filterFiles), opFilterAsync(isNotDir));
+}
+function createIncludeFileFilterFn(includeGlobPatterns, root, dot) {
+    if (!includeGlobPatterns?.length) {
+        return () => true;
+    }
+    const patterns = includeGlobPatterns.map((g) => (g === '.' ? '/**' : g));
     const options = { root, mode: 'include' };
     if (dot !== undefined) {
         options.dot = dot;
     }
-    const globMatcher = new GlobMatcher(includeGlobPatterns, options);
-    const filterFiles = (file) => globMatcher.match(file);
-    const files = readFileListFiles(fileListFiles);
-    return pipeAsync(files, opFilter(filterFiles), opFilterAsync(isNotDir));
+    const globMatcher = new GlobMatcher(patterns, options);
+    return (file) => globMatcher.match(file);
+}
+async function* concatAsyncIterables(...iterables) {
+    for (const iter of iterables) {
+        if (!iter)
+            continue;
+        yield* iter;
+    }
 }
 //# sourceMappingURL=lint.js.map

package/dist/esm/lint/lint.mjs

@@ -1,4 +1,4 @@
-import { isAsyncIterable, operators, opFilter, pipeAsync, pipeSync } from '@cspell/cspell-pipe';
+import { isAsyncIterable, operators, opFilter, pipeAsync } from '@cspell/cspell-pipe';
 import { opMap, pipe } from '@cspell/cspell-pipe/sync';
 import { MessageTypes } from '@cspell/cspell-types';
 import chalk from 'chalk';
@@ -12,7 +12,7 @@ import { npmPackage } from '../../lib/pkgInfo.cjs';
 import { getFeatureFlags } from '../featureFlags/index.mjs';
 import { calcCacheSettings, createCache } from '../util/cache/index.mjs';
 import { CheckFailed, toApplicationError, toError } from '../util/errors.mjs';
-import { fileInfoToDocument, filenameToUri, findFiles, isBinaryFile, isNotDir, readConfig, readFileInfo, readFileListFiles, } from '../util/fileHelper.mjs';
+import { fileInfoToDocument, filenameToUri, findFiles, isBinaryFile, isFile, isNotDir, readConfig, readFileInfo, readFileListFiles, resolveFilename, } from '../util/fileHelper.mjs';
 import { buildGlobMatcher, extractGlobsFromMatcher, extractPatterns, normalizeFileOrGlobsToRoot, normalizeGlobsToRoot, } from '../util/glob.mjs';
 import { prefetchIterable } from '../util/prefetch.mjs';
 import { loadReporters, mergeReporters } from '../util/reporters.mjs';
@@ -288,7 +288,7 @@ export async function runLint(cfg) {
         const globInfo = await determineGlobs(configInfo, cfg);
         const { fileGlobs, excludeGlobs } = globInfo;
         const hasFileLists = !!cfg.fileLists.length;
-        if (!fileGlobs.length && !hasFileLists) {
+        if (!fileGlobs.length && !hasFileLists && !cfg.files?.length) {
             // Nothing to do.
             return runResult();
         }
@@ -339,7 +339,7 @@ async function determineGlobs(configInfo, cfg) {
     const gitignoreRoots = cfg.options.gitignoreRoot ?? configInfo.config.gitignoreRoot;
     const gitIgnore = useGitignore ? await generateGitIgnore(gitignoreRoots) : undefined;
     const cliGlobs = cfg.fileGlobs;
-    const allGlobs = cliGlobs.length ? cliGlobs : configInfo.config.files || [];
+    const allGlobs = (cliGlobs.length && cliGlobs) || (cfg.options.filterFiles !== false && configInfo.config.files) || [];
     const combinedGlobs = await normalizeFileOrGlobsToRoot(allGlobs, cfg.root);
     const cliExcludeGlobs = extractPatterns(cfg.excludes).map((p) => p.glob);
     const normalizedExcludes = normalizeGlobsToRoot(cliExcludeGlobs, cfg.root, true);
@@ -370,14 +370,19 @@ async function determineFilesToCheck(configInfo, cfg, reporter, globInfo) {
         if (enableGlobDot !== undefined) {
             globOptions.dot = enableGlobDot;
         }
-        const filterFiles = opFilter(filterFilesFn(globMatcher));
-        const foundFiles = await (hasFileLists
-            ? useFileLists(fileLists, allGlobs, root, enableGlobDot)
-            : findFiles(fileGlobs, globOptions));
+        const opFilterExcludedFiles = opFilter(filterOutExcludedFilesFn(globMatcher));
+        const includeFilter = createIncludeFileFilterFn(allGlobs, root, enableGlobDot);
+        const rawCliFiles = cfg.files?.map((file) => resolveFilename(file, root)).filter(includeFilter);
+        const cliFiles = cfg.options.mustFindFiles
+            ? rawCliFiles
+            : rawCliFiles && pipeAsync(rawCliFiles, opFilterAsync(isFile));
+        const foundFiles = hasFileLists
+            ? concatAsyncIterables(cliFiles, await useFileLists(fileLists, includeFilter))
+            : cliFiles || (await findFiles(fileGlobs, globOptions));
         const filtered = gitIgnore ? await gitIgnore.filterOutIgnored(foundFiles) : foundFiles;
         const files = isAsyncIterable(filtered)
-            ? pipeAsync(filtered, filterFiles)
-            : [...pipeSync(filtered, filterFiles)];
+            ? pipeAsync(filtered, opFilterExcludedFiles)
+            : [...pipe(filtered, opFilterExcludedFiles)];
         return files;
     }
     function isExcluded(filename, globMatcherExclude) {
@@ -393,7 +398,7 @@ async function determineFilesToCheck(configInfo, cfg, reporter, globInfo) {
         }
         return r.matched;
     }
-    function filterFilesFn(globMatcherExclude) {
+    function filterOutExcludedFilesFn(globMatcherExclude) {
         const patterns = globMatcherExclude.patterns;
         const excludeInfo = patterns
             .map(extractGlobSource)
@@ -475,15 +480,27 @@ async function generateGitIgnore(roots) {
     }
     return new GitIgnore(root?.map((p) => path.resolve(p)));
 }
-async function useFileLists(fileListFiles, includeGlobPatterns, root, dot) {
-    includeGlobPatterns = includeGlobPatterns.length ? includeGlobPatterns : ['**'];
+async function useFileLists(fileListFiles, filterFiles) {
+    const files = readFileListFiles(fileListFiles);
+    return pipeAsync(files, opFilter(filterFiles), opFilterAsync(isNotDir));
+}
+function createIncludeFileFilterFn(includeGlobPatterns, root, dot) {
+    if (!includeGlobPatterns?.length) {
+        return () => true;
+    }
+    const patterns = includeGlobPatterns.map((g) => (g === '.' ? '/**' : g));
     const options = { root, mode: 'include' };
     if (dot !== undefined) {
         options.dot = dot;
     }
-    const globMatcher = new GlobMatcher(includeGlobPatterns, options);
-    const filterFiles = (file) => globMatcher.match(file);
-    const files = readFileListFiles(fileListFiles);
-    return pipeAsync(files, opFilter(filterFiles), opFilterAsync(isNotDir));
+    const globMatcher = new GlobMatcher(patterns, options);
+    return (file) => globMatcher.match(file);
+}
+async function* concatAsyncIterables(...iterables) {
+    for (const iter of iterables) {
+        if (!iter)
+            continue;
+        yield* iter;
+    }
 }
 //# sourceMappingURL=lint.mjs.map

package/dist/esm/options.d.mts

@@ -52,8 +52,24 @@ export interface LinterOptions extends BaseOptions, Omit<CacheOptions, 'version'
      * List of files that contains the paths to files to be spell checked.
      * The files in the lists will be filtered against the glob patterns.
      * - an entry of `stdin` means to read the file list from **`stdin`**
+     * The resulting files are filtered against the `files` globs found in the configuration.
      */
     fileList?: string[] | undefined;
+    /**
+     * List of file paths to spell check. These can be relative or absolute
+     * paths, but not Globs. Relative paths are relative to {@link LinterOptions.root}.
+     * The files are combined with the file paths read from {@link LinterOptions.fileList}.
+     * These files are filtered against the `files` globs found in the configuration.
+     */
+    files?: string[] | undefined;
+    /**
+     * Alias of {@link LinterOptions.files}.
+     */
+    file?: string[] | undefined;
+    /**
+     * Use the `files` configuration to filter the files found.
+     */
+    filterFiles?: boolean | undefined;
     /**
      * Files must be found and processed otherwise it is considered an error.
      */

package/dist/esm/options.d.ts

@@ -52,8 +52,24 @@ export interface LinterOptions extends BaseOptions, Omit<CacheOptions, 'version'
      * List of files that contains the paths to files to be spell checked.
      * The files in the lists will be filtered against the glob patterns.
      * - an entry of `stdin` means to read the file list from **`stdin`**
+     * The resulting files are filtered against the `files` globs found in the configuration.
      */
     fileList?: string[] | undefined;
+    /**
+     * List of file paths to spell check. These can be relative or absolute
+     * paths, but not Globs. Relative paths are relative to {@link LinterOptions.root}.
+     * The files are combined with the file paths read from {@link LinterOptions.fileList}.
+     * These files are filtered against the `files` globs found in the configuration.
+     */
+    files?: string[] | undefined;
+    /**
+     * Alias of {@link LinterOptions.files}.
+     */
+    file?: string[] | undefined;
+    /**
+     * Use the `files` configuration to filter the files found.
+     */
+    filterFiles?: boolean | undefined;
     /**
      * Files must be found and processed otherwise it is considered an error.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cspell",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "A Spelling Checker for Code!",
   "funding": "https://github.com/streetsidesoftware/cspell?sponsor=1",
   "bin": {
@@ -81,17 +81,17 @@
   },
   "homepage": "https://streetsidesoftware.github.io/cspell/",
   "dependencies": {
-    "@cspell/cspell-json-reporter": "8.4.0",
-    "@cspell/cspell-pipe": "8.4.0",
-    "@cspell/cspell-types": "8.4.0",
-    "@cspell/dynamic-import": "8.4.0",
+    "@cspell/cspell-json-reporter": "8.5.0",
+    "@cspell/cspell-pipe": "8.5.0",
+    "@cspell/cspell-types": "8.5.0",
+    "@cspell/dynamic-import": "8.5.0",
     "chalk": "^5.3.0",
     "chalk-template": "^1.1.0",
     "commander": "^12.0.0",
-    "cspell-gitignore": "8.4.0",
-    "cspell-glob": "8.4.0",
-    "cspell-io": "8.4.0",
-    "cspell-lib": "8.4.0",
+    "cspell-gitignore": "8.5.0",
+    "cspell-glob": "8.5.0",
+    "cspell-io": "8.5.0",
+    "cspell-lib": "8.5.0",
     "fast-glob": "^3.3.2",
     "fast-json-stable-stringify": "^2.1.0",
     "file-entry-cache": "^8.0.0",
@@ -107,9 +107,9 @@
     "@types/file-entry-cache": "^5.0.4",
     "@types/glob": "^8.1.0",
     "@types/micromatch": "^4.0.6",
-    "@types/semver": "^7.5.7",
+    "@types/semver": "^7.5.8",
     "micromatch": "^4.0.5",
     "minimatch": "^9.0.3"
   },
-  "gitHead": "f9ad457ca2102c6642c377417a95a4415f5ec3d8"
+  "gitHead": "098601b2e007bebf9e5ae894bed9a50559a102ed"
 }