{"slug": "no-cycle-finds-0-cycles-in-next-js-and-other-lies-caches-tell-you", "title": "no-cycle finds 0 cycles in next.js (and other lies caches tell you)", "summary": "The article describes a bug in a cycle-detection algorithm used in an ESLint plugin for Next.js, where a depth limit in the DFS search caused files to be incorrectly cached as \"acyclic\" when the search was truncated before finding a cycle. This caching bug cascaded across thousands of files, causing the tool to report zero cycles in a large codebase (14,556 files) while smaller scopes and a different tool (oxlint) correctly found 17 cycles. The fix involves tracking whether the DFS was truncated by the depth limit and only caching files as acyclic when the search fully completes without finding a cycle.", "body_md": "We benchmark `import-next/no-cycle`\n\nagainst `eslint-plugin-import/no-cycle`\n\nand oxlint's native Rust port on next.js (131K stars, 14,556 source files). The two ESLint plugins agreed: **0 cycles found**. oxlint disagreed: **17 cycles found**.\n\nWe trusted the consensus. Then we tested our own rule on a 33-file subset of the same repo (`packages/next/src/client/components/router-reducer/**`\n\n). It found **5+ cycles immediately**.\n\nSame rule. Same config. Same files. Different scope. Different answers.\n\nThe bug was 60 lines deep in the cache layer — and it explains why the wider scope returned silence.\n\n## The setup that hides the bug\n\nEvery cycle-detection algorithm has the same shape:\n\n- For each file F in the lint scope\n- Run a depth-bounded DFS over its import graph\n- If DFS returns to F → found a cycle\n- Else → F is acyclic, remember that for next time\n\nStep 4 is where caching pays off. With N files and average graph depth D, naive cycle detection is O(N²·D). With a \"known acyclic\" cache, repeat visits are O(1). On real codebases the cache hit rate is 70%+ — without it the rule gets too slow to run in CI.\n\nThe shape of the cache:\n\n```\ninterface FileSystemCache {\n  // ...\n  nonCyclicFiles: Set<string>; // files known not to be in any cycle\n}\n```\n\nAnd the use site:\n\n```\nfunction dfs(file: string, depth: number, visited: Set<string>) {\n  if (file === sourceFile) {\n    allCycles.push([...pathStack, file]);\n    return;\n  }\n  if (depth >= maxDepth) return; // <-- early return on depth limit\n  if (visited.has(file)) return;\n  if (cache.nonCyclicFiles.has(file)) return;\n  // ... recurse into imports\n}\n\ndfs(targetFile, 1, new Set());\nif (allCycles.length === 0) {\n  cache.nonCyclicFiles.add(targetFile); // <-- cache the result\n}\n```\n\nSpot the bug? It's between those two `// <--`\n\nlines.\n\n## Why the cache poisons itself\n\nWhen the DFS hits `depth >= maxDepth`\n\n, it returns *as if it had completed exploration without finding a cycle*. The caller can't tell the difference between \"I explored everything and found nothing\" and \"I gave up at depth 10.\"\n\nSo a file whose only cycle is at depth 12 (where 12 > maxDepth=10) gets:\n\n- DFS truncated at depth 10\n`allCycles.length === 0`\n\n-\n— incorrectly marked as known-acyclic`cache.nonCyclicFiles.add(targetFile)`\n\nNow any future DFS that traverses through that file short-circuits because of `if (cache.nonCyclicFiles.has(file)) return;`\n\n. The poisoning cascades: every file in the same SCC subtree gets marked acyclic by association.\n\nIn a small lint scope, you don't see the cascade — there aren't enough files for one bad cache entry to mask the others. In a 14K-file scope, one early miss-then-cache wipes out the whole cluster.\n\n## The narrow-vs-wide scope smoking gun\n\nHere's the test that proved it. Same rule, same config, same `--no-cache`\n\nflag (so ESLint doesn't cache between runs — but our in-process cache is still active for the duration of the run):\n\n``` bash\n# Wide scope: 2,363 files, includes everything in packages/\n$ eslint --config flagship.config.mjs 'packages/**/*.{ts,tsx,js}'\n# 0 import-next/no-cycle findings\n\n# Narrow scope: 33 files, just the router-reducer directory\n$ eslint --config flagship.config.mjs 'packages/next/src/client/components/router-reducer/**/*.ts'\n# 5+ import-next/no-cycle findings\n```\n\nThe narrow run finds cycles. The wide run, run from a fresh process with a fresh cache, also produces a fresh cache — but ESLint linits files in some order, and as it processes the 2,363 files, it builds up the `nonCyclicFiles`\n\ncache. By the time the lint pass reaches files that *do* belong to cycles, those cycles have been falsely marked acyclic via cascade.\n\noxlint, being a different process with its own implementation, doesn't share our cache. It uses oxlint's own `ModuleGraphVisitorBuilder`\n\nand finds 17 cycles.\n\n## The fix\n\nTrack whether the DFS was truncated, and don't cache truncated runs:\n\n``` js\nlet depthLimitHit = false;\n\nfunction dfs(file: string, depth: number, visited: Set<string>) {\n  if (file === sourceFile) {\n    allCycles.push([...pathStack, file]);\n    return;\n  }\n  if (depth >= maxDepth) {\n    depthLimitHit = true; // <-- record the truncation\n    return;\n  }\n  // ... rest unchanged\n}\n\ndfs(targetFile, 1, new Set());\n\n// Only cache as acyclic when DFS COMPLETED and found nothing.\n// A depth-truncated DFS isn't proof of acyclicity.\nif (allCycles.length === 0 && !depthLimitHit) {\n  cache.nonCyclicFiles.add(targetFile);\n}\n```\n\nFive lines. Re-running on next.js: **0 → 245 unique files in cycles, 914 unique (file, line) pairs**. The wide-scope correctness now matches the narrow-scope correctness.\n\n## What `eslint-plugin-import`\n\ndoes instead\n\nWhen you've found a real bug, it's worth checking how peers in the same landscape modeled the problem. The long-standing `eslint-plugin-import/no-cycle`\n\nrule uses a fundamentally different approach:\n\n``` js\n// from eslint-plugin-import/src/rules/no-cycle.js:73\nconst scc = options.disableScc\n  ? {}\n  : StronglyConnectedComponentsBuilder.get(myPath, context);\n\n// ...\n\n// If we're in different SCCs, we can't have a circular dependency\nconst hasDependencyCycle =\n  options.disableScc || scc[myPath] === scc[imported.path];\nif (!hasDependencyCycle) return;\n```\n\nThey build a strongly-connected-components graph **once per lint run**, then per-file the cycle check is O(1) — *\"are these two files in the same SCC?\"*. The SCC graph itself is computed in O(V+E) using Tarjan's algorithm.\n\nThis sidesteps the depth-limit problem entirely. SCCs are an exact answer to \"what are the cycle clusters?\" — there's no truncation, no approximation, no cache to poison. They cache the SCC result module-wide and clear it on `Program:exit`\n\n.\n\noxlint goes further: it builds an explicit module graph during parsing, then the cycle visitor runs against that graph directly. No need for SCC because the graph is already structured.\n\nBoth approaches share a property our DFS-with-cache approach lacks: **the algorithm is exact, not approximate**. The cache trades some compute for correctness — exactly what we accidentally did the wrong way.\n\n## What I'd do differently next time\n\nThree takeaways from the diagnosis:\n\n**Caches should never lie.** A cache entry should only encode information you've *proven*, not information you've *failed to disprove*. Our `nonCyclicFiles`\n\ncache encoded \"DFS found no cycle\" as \"no cycle exists.\" Those aren't the same statement.\n\n**Test the algorithm at the same scope you'll deploy at.** Our unit tests passed because the test fixtures are small and depth-bounded. The bug only surfaces at 2K+ files where the cache fills up enough for cascades to start. We need a stress test that mirrors production.\n\n**An exact algorithm sidesteps a class of bugs that caches can introduce.** SCC-based cycle detection (eslint-plugin-import) and module-graph walking (oxlint) avoid the depth-limit interaction by construction. We hold our DFS approach for a reason — incremental analysis benefits from per-file caching — but the depth-limit + cache interaction is exactly the kind of bug the SCC approach can't have. Worth re-evaluating whether incrementality is worth that trade.\n\nThe fix is in [packages/eslint-devkit/src/resolver/dependency-analysis.ts](https://github.com/ofri-peretz/eslint/blob/main/packages/eslint-devkit/src/resolver/dependency-analysis.ts). The bench that exposed it is [ benchmarks/suites/ilb-flagship](https://github.com/ofri-peretz/eslint/tree/main/benchmarks/suites/ilb-flagship).\n\nThis is one of three rule bugs caught by the same bench sweep. The companion writeups: [What ground truth caught that unit tests missed](https://ofriperetz.dev/articles/what-ground-truth-caught-that-unit-tests-missed) (the smoke-gate piece) and [When entropy isn't enough](https://ofriperetz.dev/articles/no-hardcoded-credentials-entropy-isnt-enough) (807 false credential findings on vercel/ai).\n\n## 📊 About the author\n\nI'm Ofri Peretz, building the Interlace ESLint ecosystem — a JavaScript static-analysis catalog that runs under ESLint and Oxlint with CI-enforced parity.", "url": "https://wpnews.pro/news/no-cycle-finds-0-cycles-in-next-js-and-other-lies-caches-tell-you", "canonical_source": "https://dev.to/ofri-peretz/no-cycle-finds-0-cycles-in-nextjs-and-other-lies-caches-tell-you-3ld8", "published_at": "2026-05-24 03:07:43+00:00", "updated_at": "2026-05-24 03:31:19.015896+00:00", "lang": "en", "topics": ["developer-tools", "open-source", "data"], "entities": ["Next.js", "ESLint", "oxlint", "import/no-cycle", "no-cycle"], "alternates": {"html": "https://wpnews.pro/news/no-cycle-finds-0-cycles-in-next-js-and-other-lies-caches-tell-you", "markdown": "https://wpnews.pro/news/no-cycle-finds-0-cycles-in-next-js-and-other-lies-caches-tell-you.md", "text": "https://wpnews.pro/news/no-cycle-finds-0-cycles-in-next-js-and-other-lies-caches-tell-you.txt", "jsonld": "https://wpnews.pro/news/no-cycle-finds-0-cycles-in-next-js-and-other-lies-caches-tell-you.jsonld"}}