Add cacheStrategy option

.changeset/mighty-apricots-cheat.md

@@ -0,0 +1,5 @@
+---
+"stylelint": minor
+---
+
+Added: `cacheStrategy` option

docs/user-guide/usage/cli.md

@@ -20,6 +20,10 @@ The process exits without throwing an error when glob pattern matches no files.
 
 Path to a file or directory for the cache location. [More info](options.md#cachelocation).
 
+### `--cache-strategy`
+
+Strategy for the cache to use for detecting changed files. Can be either "metadata" or "content". [More info](options.md#cachestrategy).
+
 ### `--cache`
 
 Store the results of processed files so that Stylelint only operates on the changed ones. By default, the cache is stored in `./.stylelintcache` in `process.cwd()`. [More info](options.md#cache).

docs/user-guide/usage/options.md

@@ -110,6 +110,14 @@ If a directory is specified, Stylelint creates a cache file inside the specified
 
 _If the directory of `cacheLocation` does not exist, make sure you add a trailing `/` on \*nix systems or `\` on Windows. Otherwise, Stylelint assumes the path to be a file._
 
+## `cacheStrategy`
+
+CLI flag: `--cache-strategy`
+
+Strategy for the cache to use for detecting changed files. Can be either "metadata" or "content".
+
+The "content" strategy can be useful in cases where the modification time of your files changes even if their contents have not. For example, this can happen during git operations like "git clone" because git does not track file modification time.
+
 ## `maxWarnings`
 
 CLI flags: `--max-warnings, --mw`

lib/__tests__/__snapshots__/cli.test.js.snap

@@ -88,6 +88,16 @@ exports[`CLI --help 1`] = `
       If the directory for the cache does not exist, make sure you add a trailing \\"/\\"
       on *nix systems or \\"\\\\\\" on Windows. Otherwise the path will be assumed to be a file.
 
+    --cache-strategy              [default: \\"metadata\\"]
+
+      Strategy for the cache to use for detecting changed files. Can be either
+      \\"metadata\\" or \\"content\\".
+
+      The \\"content\\" strategy can be useful in cases where the modification time of
+      your files changes even if their contents have not. For example, this can happen
+      during git operations like \\"git clone\\" because git does not track file modification
+      time.
+
     --formatter, -f               [default: \\"string\\"]
 
       The output formatter: \\"compact\\", \\"github\\", \\"json\\", \\"string\\", \\"tap\\", \\"unix\\" or \\"verbose\\".

lib/__tests__/cli.test.js

@@ -50,6 +50,11 @@ describe('buildCLI', () => {
 		expect(buildCLI(['--cache-location=foo']).flags.cacheLocation).toBe('foo');
 	});
 
+	it('flags.cacheStrategy', () => {
+		expect(buildCLI(['--cache-strategy=content']).flags.cacheStrategy).toBe('content');
+		expect(buildCLI(['--cache-strategy=metadata']).flags.cacheStrategy).toBe('metadata');
+	});
+
 	it('flags.color', () => {
 		expect(buildCLI(['--color']).flags.color).toBe(true);
 		expect(buildCLI(['--no-color']).flags.color).toBe(false);

lib/__tests__/standalone-cache.test.js

@@ -194,3 +194,47 @@ describe('standalone cache uses cacheLocation', () => {
 		expect(cache.getKey(validFile)).toBeTruthy();
 	});
 });
+
+describe('standalone cache uses cacheStrategy', () => {
+	const cwd = path.join(__dirname, 'tmp', 'standalone-cache-uses-cacheStrategy');
+
+	safeChdir(cwd);
+
+	const expectedCacheFilePath = path.join(cwd, '.stylelintcache');
+
+	afterEach(async () => {
+		// clean up after each test
+		await removeFile(expectedCacheFilePath);
+		await removeFile(newFileDest);
+	});
+
+	it('cacheStrategy is "metadata"', async () => {
+		const cacheStrategy = 'metadata';
+
+		await fs.copyFile(validFile, newFileDest);
+		const { results } = await standalone(getConfig({ cacheStrategy }));
+
+		expect(results.some((file) => file.source === newFileDest)).toBe(true);
+
+		// No content change, but file metadata id changed
+		await fs.utimes(newFileDest, new Date(), new Date());
+		const { results: resultsCached } = await standalone(getConfig({ cacheStrategy }));
+
+		expect(resultsCached.some((file) => file.source === newFileDest)).toBe(true);
+	});
+
+	it('cacheStrategy is "content"', async () => {
+		const cacheStrategy = 'content';
+
+		await fs.copyFile(validFile, newFileDest);
+		const { results } = await standalone(getConfig({ cacheStrategy }));
+
+		expect(results.some((file) => file.source === newFileDest)).toBe(true);
+
+		// No content change, but file metadata id changed
+		await fs.utimes(newFileDest, new Date(), new Date());
+		const { results: resultsCached } = await standalone(getConfig({ cacheStrategy }));
+
+		expect(resultsCached.some((file) => file.source === newFileDest)).toBe(false);
+	});
+});

lib/cli.js

@@ -21,6 +21,7 @@ const EXIT_CODE_ERROR = 2;
  * @typedef {object} CLIFlags
  * @property {boolean} [cache]
  * @property {string} [cacheLocation]
+ * @property {string} [cacheStrategy]
  * @property {string | false} config
  * @property {string} [configBasedir]
  * @property {string} [customSyntax]
@@ -64,6 +65,7 @@ const EXIT_CODE_ERROR = 2;
  * @property {boolean} [cache]
  * @property {string} [configFile]
  * @property {string} [cacheLocation]
+ * @property {string} [cacheStrategy]
  * @property {string} [customSyntax]
  * @property {string} [codeFilename]
  * @property {string} [configBasedir]
@@ -173,6 +175,16 @@ const meowOptions = {
         If the directory for the cache does not exist, make sure you add a trailing "/"
         on *nix systems or "\\" on Windows. Otherwise the path will be assumed to be a file.
 
+      --cache-strategy              [default: "metadata"]
+
+        Strategy for the cache to use for detecting changed files. Can be either
+        "metadata" or "content".
+
+        The "content" strategy can be useful in cases where the modification time of
+        your files changes even if their contents have not. For example, this can happen
+        during git operations like "git clone" because git does not track file modification
+        time.
+
       --formatter, -f               [default: "string"]
 
         The output formatter: ${getFormatterOptionsText({ useOr: true })}.
@@ -236,6 +248,9 @@ const meowOptions = {
 		cacheLocation: {
 			type: 'string',
 		},
+		cacheStrategy: {
+			type: 'string',
+		},
 		color: {
 			type: 'boolean',
 		},
@@ -410,6 +425,10 @@ module.exports = async (argv) => {
 		optionsBase.cacheLocation = cli.flags.cacheLocation;
 	}
 
+	if (cli.flags.cacheStrategy) {
+		optionsBase.cacheStrategy = cli.flags.cacheStrategy;
+	}
+
 	if (cli.flags.fix) {
 		optionsBase.fix = cli.flags.fix;
 	}

lib/standalone.js

@@ -39,6 +39,7 @@ async function standalone({
 	allowEmptyInput = false,
 	cache: useCache = false,
 	cacheLocation,
+	cacheStrategy,
 	code,
 	codeFilename,
 	config,
@@ -179,10 +180,10 @@ async function standalone({
 		const stylelintVersion = pkg.version;
 		const hashOfConfig = hash(`${stylelintVersion}_${JSON.stringify(config || {})}`);
 
-		fileCache = new FileCache(cacheLocation, cwd, hashOfConfig);
+		fileCache = new FileCache(cacheLocation, cacheStrategy, cwd, hashOfConfig);
 	} else {
 		// No need to calculate hash here, we just want to delete cache file.
-		fileCache = new FileCache(cacheLocation, cwd);
+		fileCache = new FileCache(cacheLocation, cacheStrategy, cwd);
 		// Remove cache file if cache option is disabled
 		fileCache.destroy();
 	}

lib/utils/FileCache.js

@@ -5,7 +5,11 @@ const fileEntryCache = require('file-entry-cache');
 const getCacheFile = require('./getCacheFile');
 const path = require('path');
 
+const CACHE_STRATEGY_METADATA = 'metadata';
+const CACHE_STRATEGY_CONTENT = 'content';
+
 const DEFAULT_CACHE_LOCATION = './.stylelintcache';
+const DEFAULT_CACHE_STRATEGY = CACHE_STRATEGY_METADATA;
 const DEFAULT_HASH = '';
 
 /** @typedef {import('file-entry-cache').FileDescriptor["meta"] & { hashOfConfig?: string }} CacheMetadata */
@@ -18,13 +22,21 @@ const DEFAULT_HASH = '';
 class FileCache {
 	constructor(
 		cacheLocation = DEFAULT_CACHE_LOCATION,
+		cacheStrategy = DEFAULT_CACHE_STRATEGY,
 		cwd = process.cwd(),
 		hashOfConfig = DEFAULT_HASH,
 	) {
+		if (![CACHE_STRATEGY_METADATA, CACHE_STRATEGY_CONTENT].includes(cacheStrategy)) {
+			throw new Error(
+				`"${cacheStrategy}" cache strategy is unsupported. Specify either "${CACHE_STRATEGY_METADATA}" or "${CACHE_STRATEGY_CONTENT}"`,
+			);
+		}
+
 		const cacheFile = path.resolve(getCacheFile(cacheLocation, cwd));
+		const useCheckSum = cacheStrategy === CACHE_STRATEGY_CONTENT;
 
 		debug(`Cache file is created at ${cacheFile}`);
-		this._fileCache = fileEntryCache.create(cacheFile);
+		this._fileCache = fileEntryCache.create(cacheFile, undefined, useCheckSum);
 		this._hashOfConfig = hashOfConfig;
 	}
 

types/stylelint/index.d.ts

@@ -212,6 +212,7 @@ declare module 'stylelint' {
 			globbyOptions?: GlobbyOptions;
 			cache?: boolean;
 			cacheLocation?: string;
+			cacheStrategy?: string;
 			code?: string;
 			codeFilename?: string;
 			config?: Config;