\n
\n\nQuality: promises, dead code, footgun syntax
\n\n- `no-floating-promises`: An async call whose result you ignore can swallow errors; await it or add `.catch()`.\n- `no-misused-promises`: Stops passing an async function where a plain one is expected (event handlers, effects).\n- `exhaustive-switch`: A `switch` over a fixed set of values must handle every case (or have a default).\n- `no-empty-function`: Flags empty function bodies so a stub doesn't ship by accident.\n- `no-useless-code`: Removes no-ops: pointless string joins, `.call()`/`.apply()`, redundant object keys.\n- `no-debug-code`: Catches leftover `debugger` statements before they ship.\n- `no-redundant-zod-parse`: Skips re-validating data that is already typed to the schema.\n- `banned-syntax`: Blocks footguns: `void`, labels, octal, `delete` on variables, global assignment.\n- `syntax`: Nudges to modern JS: `const` over `var`, template strings, object shorthand.\n\n\n
\n\nType safety: keep types tight and honest
\n\n- `type-precision`: Nine checks that keep types specific and meaningful instead of vague.\n- `typescript`: Compiler-powered catches: missing null checks, hidden `any`, unsafe index access, shadowed names.\n- `narrow-param-type`: Suggests narrower parameter types when a function uses only part of what it accepts.\n- `unnecessary-type-assertion`: Flags `as T` casts that change nothing because the type already matches.\n- `any-propagation`: Tracks `any` leaking through assignments and returns, eroding safety.\n- `await-non-thenable`: Flags `await` on something that isn't a Promise (a no-op that hints at a bug).\n- `no-base-to-string`: Stops objects becoming `\"[object Object]\"` because they lack a real `toString()`.\n- `unbranded-type-consistency`: Wants IDs to use branded types so a `userId` and a `postId` can't be mixed up.\n- `prefer-literal-union`: Replace loose string comparisons with a precise set of allowed values.\n- `prefer-satisfies-over-as`: Use `satisfies T` instead of `as T` on literals so types aren't silently widened.\n- `restrict-plus-operands`: Allows `+` only on operands that are safe to add, so strings and numbers don't mix by accident.\n- `restrict-template-expr`: Flags unsafe values stuffed into template strings.\n\n\n
\n\nPerformance: avoid slow patterns
\n\n- `performance`: Common slow spots: regex built in a loop, sync I/O, long chains, mutating arrays in callbacks.\n- `promise-all-opportunity`: Spots awaits done one-by-one that could run together with `Promise.all`.\n- `cache-primitive-args`: `React.cache` only works reliably with primitive arguments; flags the rest.\n- `cache-caller-count`: `React.cache` only pays off with 2+ callers; flags single-use ones.\n- `missing-returning`: Reminds you to add `.returning()` on a DB insert/update when you need the result.\n- `no-db-antipatterns`: Blocks DB transactions the serverless driver doesn't support, and per-row queries in a loop (N+1).\n\n\n
\n\nSecurity: injection, secrets, unsafe code
\n\n- `security`: Classic web holes: prototype pollution, `dangerouslySetInnerHTML`, `javascript:` URLs, `document.write`.\n- `safety`: Runtime footguns: bad constructor returns, promise-executor mistakes, non-atomic updates, `parseInt` without a radix.\n- `input-validation`: Server actions must validate their input (Zod `safeParse`) before doing anything with it.\n- `no-dynamic-sql`: Blocks raw SQL built from dynamic strings, the classic SQL-injection path.\n- `no-ssrf`: Stops `fetch()` to a user-controlled URL in server code (server-side request forgery).\n- `no-page-params-unsafe-parse`: Page params should fail gracefully instead of crashing: use a safe-parse helper.\n- `no-implied-eval`: Flags running strings as code (`eval`, string `setTimeout`, `new Function`).\n- `unnecessary-use-server`: Removes `\"use server\"` on code no client ever calls, shrinking the attack surface.\n- `no-child-process`: Flags shell commands built from input (`exec`/`execSync`), a command-injection risk.\n- `no-non-literal-fs-path`: Flags file access with a path that comes from input, a path-traversal risk.\n- `no-non-literal-require`: Flags `require()`/`import()` of a module name that comes from input.\n- `no-non-literal-regexp`: Flags regexes built from input, which can hang on crafted strings (ReDoS).\n- `no-weak-crypto`: Flags broken hash algorithms like MD5/SHA-1.\n- `no-secrets`: Flags hardcoded API keys, tokens, and private keys in your code.\n\n\n
\n\nCorrectness: real bugs the compiler can prove
\n\n- `correctness`: Bug-prevention: self-assignment, unsafe `finally`, loops that run once, reassigned params.\n- `logic`: Compiler-checked logic bugs: identical conditions, leaked renders, writes that are never read.\n- `error-handling`: Catches empty `catch` blocks and errors thrown without a cause.\n- `no-identical-binary-operands`: Both sides of an operator are identical (`a && a`, `x - x`), which is redundant or always constant.\n- `no-unthrown-error`: A `new Error()` built but never thrown, usually a forgotten `throw`.\n- `no-all-duplicated-branches`: Every branch of an if/else or switch runs the same code, so the condition decides nothing.\n- `no-collection-size-mischeck`: A length/size check that is always true or false (`arr.length >= 0`).\n\n\n
\n\nReact: hooks, effects, client/server boundary
\n\n- `react`: React pitfalls: components nested in components, `setState` in effects, race conditions, missing button `type`.\n- `rules-of-hooks`: Hooks must run at the top level, never in conditions, loops, or after a return.\n- `exhaustive-deps`: Effect/callback/memo dependency arrays must list every value they use.\n- `effect-cleanup`: Effects that add listeners or timers must clean them up.\n- `state-hooks-cluster`: Flags tangled `useState` that should be one well-modeled state object.\n- `no-async-client-component`: Client components can't be `async`; it crashes at runtime.\n- `no-client-data-fetch`: Don't call `fetch`/axios in a client component; use a server action.\n- `no-unescaped-entities`: Flags raw HTML characters in JSX text that should be escaped.\n- `jsx-no-useless-fragment`: Removes `<>…` fragments that wrap a single child for nothing.\n\n\n
\n\nStyle: clarity and modern patterns
\n\n- `readability`: Flags hard-to-read shapes: nested ternaries/switches, `this` aliasing.\n- `simplification`: Simpler equivalents: drop useless `else`, collapse nested `if`, return immediately.\n- `naming-convention`: Blocks shadowing built-in names and label-as-variable confusion.\n- `duplicate-import`: Merges multiple imports from the same module into one.\n- `prefer-optional-chain`: Use `a?.b` instead of `a && a.b`.\n- `prefer-nullish-coalescing`: Use `??` instead of `||` for values that can be null/undefined.\n- `prefer-modern-api`: Nudge to modern methods: `includes`, `flatMap`, `at`, `startsWith`, `Object.hasOwn`.\n- `no-deprecated-api`: Blocks legacy footguns like `__proto__` and extending native prototypes.\n- `deprecated-usage`: Flags use of anything marked `@deprecated`.\n- `no-underscore-prefix`: Use real names instead of `_name`, or `_` for a deliberate discard.\n- `no-implicit-coercion`: Flags sneaky conversions: `==`, `+x`, `'' + x`, `!!x`.\n- `no-magic-numbers`: Pull unexplained numbers into named constants.\n- `no-multiline-comments`: Use line comments, not `/** */` JSDoc blocks.\n\n\n
\n\nArchitecture: boundaries, dead code, structure
\n\n- `unused-export`: Flags exports that nothing imports (dead public API).\n- `no-re-export`: Import from the real source, not a pass-through barrel file.\n- `self-import`: Flags a file importing itself.\n- `no-import-cycle`: Detects circular imports between files.\n- `no-duplicated-constants`: Flags local constants that just duplicate a central one.\n- `no-local-constants`: `UPPER_SNAKE` constants belong in a central constants file.\n- `max-file-lines`: Flags files that have grown too long.\n- `route-boundary`: Keeps routes/features isolated so they don't reach into each other.\n- `prop-drilling`: Flags components passing props straight through without using them.\n- `zustand-patterns`: Enforces correct Zustand store usage (selectors, no store-in-effect).\n- `no-client-server-only-import`: Client code must not pull in server-only modules.\n- `no-db-origin-client-boundary`: Database row types must not leak to the client side.\n- `no-duplicate-schema-export`: Flags two same-named schemas, which create incompatible types.\n\n\n
\n\n## Secret scanning\n\n`no-secrets` flags hardcoded credentials in string literals, such as keys for AWS, GitHub, Stripe, Google, Slack, 1Password and Anthropic, private keys, and dozens more formats. It matches a curated public pattern set ([`assets/secret-patterns.json`](assets/secret-patterns.json)) of distinctive vendor formats, with no entropy guessing. Every pattern uses bounded quantifiers, so matching stays linear and cannot hang on crafted input (ReDoS), even on a 60 KB minified or base64 literal. Each pattern is checked against its own examples when it loads, and all matching happens locally. `pnpm refresh-secret-patterns` refreshes the set.\n\nThe patterns are forked from [gitleaks](https://github.com/gitleaks/gitleaks) (MIT, © 2019 Zachary Rice). dlint keeps only the formats that are unambiguous by prefix, checks that each compiles to a bounded, ReDoS-safe JavaScript regex, and drops formats that are not secrets (ARNs, public or publishable keys, URLs). See [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md).\n\n**Scope:** the secret scan favors precision over recall. It catches credentials with a known vendor format, but not arbitrary high-entropy strings or secrets split across concatenations. The taint-based rules (`no-child-process`, `no-non-literal-*`) are best-effort checks within one function: they catch direct cases, but not input passed through a helper or a reassignment. Treat both as one layer of defense, not as proof that the code is clean.\n\n## HTML report\n\n`--format html` writes an interactive report of the project's health:\n\nDuplication: copy-paste and complexity
\n\n- `semantic-clone`: Finds functions that do the same thing with a different look (type-equivalent + similar body).\n- `syntactic-clone`: Finds near-identical copy-pasted blocks across files.\n- `complexity`: Flags functions that are too deep, too long, or too branchy.\n\n\n ![\"dlint](\"assets/report-dashboard.jpg\")
\n
\n ![\"dlint](\"assets/report-findings.jpg\")
\n
\n` |\n| `isBuiltinCollection` | Is it `Map`, `Set`, or `Array`, readonly forms included? |\n| `hasJsDocTag` | Check JSDoc annotations on declarations |\n| `isDbCall` | Detect ORM/database call expressions |\n| `dbRootMethod` | Method called on the DB handle of a call chain |\n| `returnTypeHasProperties` | Check if return type has specific fields |\n| `isFromPackage` | Is the import from a specific npm package? |\n| `resolveCallBody` | Resolve function body across file boundaries |\n| `bodyContainsCall` | Does a function body call a specific function? |\n| `resolveImportedModule` | Resolve an import specifier the way the program does |\n| `collectValueImports` | Specifiers a file loads at runtime, `import()` included |\n| `isTypeOnlyImport` | Does an import or re-export pull no runtime value? |\n| `isWriteTarget` | Is the expression assigned, incremented or deleted? |\n| `valueSymbolOf` | The variable an identifier names, `{ a }` shorthand included |\n| `isSameReference` | Do two expressions name the same variable or property? |\n| `isThenable` | Does the type have a callable `then`? |\n| `tokenizeFile` | Extract normalized token blocks for clone detection |\n| `tokenSimilarity` | Bigram Jaccard coefficient between token sequences |\n| `collectTypeDeclarations` | Discover all interfaces and type aliases |\n| `collectFunctionSignatures` | Extract function signature fingerprints |\n| `memberJaccard` | Type member similarity score |\n| `signatureKey` | Deterministic function signature hash |\n| `buildReferenceIndex` | Cross-file export usage tracking |\n\n
\n\n## Configuration\n\n```typescript\nimport type { DlintConfig } from \"@dfine-io-gmbh/dlint\";\n\nexport default {\n bundledRules: true, // load the package's universal rules (default; false to opt out)\n rulesDir: \".dlint/rules\", // project-specific rules (optional; override bundled by id)\n severity: \"error\", // default severity\n include: [\"**/*.ts\", \"**/*.tsx\"], // what to scan\n exclude: [\"node_modules\", \".next\"], // what to skip\n tsconfig: \"./tsconfig.json\", // your project's tsconfig\n maxFileSize: 500_000, // skip files larger than 500KB\n referencesDir: \".dlint/references\", // advisory docs for rules\n groups: [\n // opt into the opinionated rule set (ships off by default)\n { id: \"opinionated\", severity: \"error\" },\n ],\n overrides: [\n // per-rule severity tuning (wins over groups and the default)\n { ruleId: \"no-magic-numbers\", severity: \"warning\" },\n { ruleId: \"max-file-lines\", severity: \"off\" },\n ],\n} satisfies DlintConfig;\n```\n\n### Rule groups\n\nRules are bundled into groups that you toggle with one severity. The package ships one built-in group, `opinionated`, set to `off`. It holds the 25 style and architecture rules (plus a few opinionated sub-checks) that a generic project may not share. Enable the whole set in one line:\n\n```typescript\nexport default {\n groups: [{ id: \"opinionated\", severity: \"error\" }],\n} satisfies DlintConfig;\n```\n\nThe most specific setting wins, in this order: a per-rule `override`, the rule's own declared severity, its group, then the global default. So you can enable the group and still silence one rule via `overrides`, or turn off a single sub-check with `{ ruleId: \"typescript:no-explicit-any\", severity: \"off\" }`.\n\nYou can also build your own groups to switch rules by concern. A group with a new `id` brings its own `rules`. A group that reuses a built-in `id` sets that group's severity, and if it also lists `rules`, they replace the built-in members:\n\n```typescript\nexport default {\n groups: [\n { id: \"opinionated\", severity: \"error\" }, // enable the built-in set\n // your own group: toggle a concern together (here: report, don't fail CI)\n {\n id: \"soft\",\n severity: \"warning\",\n rules: [\"no-base-to-string\", \"exhaustive-switch\", \"no-floating-promises\"],\n },\n ],\n} satisfies DlintConfig;\n```\n\n### Rule options\n\nEach rule's tunable values (the `CONFIG` block at the top of the rule file) are defaults. Override them per project in `ruleOptions`, keyed by rule id. You don't copy the rule, so its logic stays in one place and keeps improving with `pnpm update`:\n\n```typescript\nexport default {\n ruleOptions: {\n \"max-file-lines\": { maxLines: 500 },\n \"no-magic-numbers\": { ignoredNumbers: [0, 1, -1, 2, 100] },\n complexity: { maxComplexity: 20, maxDepth: 5 },\n \"route-boundary\": {\n appDir: \"src/app\",\n allowedPairs: [[\"checkout\", \"cart\"]],\n },\n \"unbranded-type-consistency\": {\n externalIdNames: [\"deviceId\", \"videoDeviceId\"],\n },\n // exclude a deliberately-mirrored, separately-bundled module from the duplicate scan\n \"no-duplicate-schema-export\": { ignorePaths: [\"worker/\"] },\n },\n} satisfies DlintConfig;\n```\n\nEach `CONFIG` const maps to a camelCase option key (`MAX_LINES` → `maxLines`, `EXTERNAL_ID_NAMES` → `externalIdNames`). Options apply across all files and combine freely with `overrides` (severity, file scope) and `groups`.\n\n**The `opinionated` group:** `any-propagation`, `cache-caller-count`, `complexity`, `duplicate-import`, `error-handling`, `max-file-lines`, `narrow-param-type`, `no-duplicated-constants`, `no-empty-function`, `no-local-constants`, `no-magic-numbers`, `no-multiline-comments`, `no-re-export`, `no-underscore-prefix`, `prefer-literal-union`, `prefer-satisfies-over-as`, `promise-all-opportunity`, `readability`, `route-boundary`, `semantic-clone`, `simplification`, `syntactic-clone`, `type-precision`, `unbranded-type-consistency`, `unused-export`, plus the opinionated sub-checks of `performance`, `typescript`, and `no-implicit-coercion` (their universal sub-checks stay on).\n\n## CLI\n\n```\nnpx dlint [options] Lint (default: full project scan)\nnpx dlint init Scaffold .dlint/rules + dlint.config.ts\nnpx dlint --help, -h Show all flags\n\nScan modes (default: full project):\n --files