feat(config): cosmiconfig

[avivkeller]

Fixes #897 by adding cosmiconfig as a dependency.

[cursor]

PR Summary

Medium Risk
Changes default config resolution for every generate run (cwd-based search) and adds a runtime dependency; behavior is covered by updated unit tests but may surprise users who relied on no implicit config file.

Overview
Configuration loading now goes through cosmiconfig instead of importFromURL. With no --config-file, the CLI searches the project for doc-kit config (package.json, .doc-kitrc.yml, doc-kit.config.mjs, etc.); with --config-file, it loads that path. Missing config still merges as {}.

README and docs/configuration.md describe auto-discovery, supported formats (including YAML and optional TypeScript), and clarify that CLI options override discovered/file config, then defaults.

Tests mock cosmiconfig (search / load) and assert discovery runs when no explicit config file is passed.

^{Reviewed by Cursor Bugbot for commit 464549b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview, Comment	Jul 25, 2026 3:37am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
nodejs-doc-kit	Ignored		Jul 25, 2026 3:37am

[codecov]

Codecov Report

❌ Patch coverage is 98.24561% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 84.94%. Comparing base (e6f1769) to head (464549b).

Files with missing lines	Patch %	Lines
bin/commands/generate.mjs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #939   +/-   ##
=======================================
  Coverage   84.94%   84.94%           
=======================================
  Files         195      195           
  Lines       17583    17600   +17     
  Branches     1574     1577    +3     
=======================================
+ Hits        14935    14951   +16     
- Misses       2642     2643    +1     
  Partials        6        6           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

api-links Generator

Output: 1 file differs

apilinks.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    'Agent.defaultMaxSockets': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L291',
    'Buffer.alloc': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L435',
    'Buffer.allocUnsafe': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L449',
    'Buffer.allocUnsafeSlow': 'https://github.com/nodejs/node/blob/HEAD/lib/buffer.js#L461',
...
    'agent.addRequest': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L356',
+   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L326',
-   'agent.createConnection': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L295',
    'agent.createSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L427',
    'agent.destroy': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L660',
+   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L484',
-   'agent.getName': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L325',
    'agent.keepSocketAlive': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L616',
    'agent.removeSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L555',
    'agent.reuseSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_agent.js#L652',
    'assert.assert': 'https://github.com/nodejs/node/blob/HEAD/lib/assert.js#L185',
    'asyncResource.asyncId': 'https://github.com/nodejs/node/blob/HEAD/lib/async_hooks.js#L243',
...
    'server.address': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2596',
+   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2729',
+   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L120',
+   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L122',
-   'server.close': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L671',
-   'server.closeAllConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L681',
-   'server.closeIdleConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L693',
    'server.getConnections': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2691',
    'server.listen': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2398',
    'server.ref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2834',
+   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/https.js#L124',
-   'server.setTimeout': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L709',
    'server.unref': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2843',
+   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2769',
-   'server[SymbolAsyncDispose]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L677',
    'server[kDeserialize]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2319',
    'server[kTransferList]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2292',
    'server[kTransfer]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2297',
+   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/net.js#L2798',
-   'server[undefined]': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L716',
    'serverresponse._finish': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L246',
    'serverresponse._implicitHeader': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L403',
    'serverresponse.assignSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L296',
    'serverresponse.detachSocket': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L307',
    'serverresponse.statusCode': 'https://github.com/nodejs/node/blob/HEAD/lib/_http_server.js#L269',

Performance estimate _{(single CI run)}

• Generation time: 22.1% slower (1.31 s → 1.60 s)
• Peak memory: 0.7% lower (351.48 MB → 349.11 MB)

legacy-html Generator

Performance estimate _{(single CI run)}

• Generation time: 4.4% slower (17.90 s → 18.68 s)
• Peak memory: 3.5% lower (2.35 GB → 2.26 GB)

legacy-json Generator

Performance estimate _{(single CI run)}

• Generation time: 32.7% faster (8.51 s → 5.73 s)
• Peak memory: 7.8% higher (1.79 GB → 1.93 GB)

llms-txt Generator

Performance estimate _{(single CI run)}

• Generation time: unchanged (8.07 s → 8.07 s)
• Peak memory: 5.1% higher (1.68 GB → 1.76 GB)

orama-db Generator

Output size: 1 file changed · net +1.38 KB

File size details

File	Main	PR	Change
orama-db.json	8.90 MB	8.90 MB	+1.38 KB (+0.0%)

Performance estimate _{(single CI run)}

• Generation time: 6.4% slower (7.77 s → 8.27 s)
• Peak memory: 2.1% higher (1.71 GB → 1.74 GB)

web Generator

Output size: 3 files changed · net +198.00 B

File size details

File	Main	PR	Change
FunctionSignature-lh0ywe-m.js	189.94 KB	—	-189.94 KB (-100.0%)
FunctionSignature-DBD6PEuT.js	—	189.94 KB	+189.94 KB
all.html	21.26 MB	21.26 MB	+198.00 B (+0.0%)

Performance estimate _{(single CI run)}

• Generation time: 0.3% slower (77.80 s → 78.00 s)
• Peak memory: 2.3% higher (5.63 GB → 5.75 GB)

[bmuenzenmeyer]

i didnt run it locally, but LGTM