feat(config): auto-detect supported config files in the working directory

[AysajanE]

Problem

doc-kit generate only loads configuration when --config-file is passed explicitly. As raised in #897, a conventional project-level configuration file is otherwise silently ignored.

Change

• When --config-file is omitted, use cosmiconfig('doc-kit').search() from the current working directory and merge the discovered configuration. An explicit --config-file still bypasses discovery, and the no-file fallback remains unchanged.
• Add cosmiconfig as a runtime dependency, add a patch changeset, and cover discovery, explicit-path precedence, and the no-file fallback with unit tests.

Checks (Node 22)

• focused configuration tests: 17/17 passed
• full test suite: 527/527 passed
• lint: 0 errors (2 pre-existing unrelated warnings)
• formatting: passed
• real-file smoke test: supported extensions and first-match priority passed

Fixes #897

---

Disclosure: this change was prepared with AI assistance and reviewed by me before submitting. The linked Northset receipt records the original submitted revision; the current head includes later maintainer-requested revisions and is not covered by that original immutable run record. I self-ran the checks listed above on the current revision. Contributor self-run, not maintainer verification.
https://northset-oss.github.io/verification-pilot/

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 19, 2026 9:19pm

[cursor]

PR Summary

Low Risk
CLI configuration resolution only; explicit --config-file is unchanged and behavior falls back to {} when no file is found.

Overview
When --config-file is not passed, createRunConfiguration now uses cosmiconfig (doc-kit module name) to search the working directory for a config file and merge its config object. Explicit --config-file still goes through loadConfigFile / importFromURL and skips cosmiconfig.

Adds cosmiconfig as a runtime dependency and extends configuration unit tests for auto-discovery, explicit-path precedence, and the empty-config fallback when search finds nothing.

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

[AugustinMauroy]

adding blocker since feature isn't correctly covered.

thanks @AysajanE for you effort here

[AysajanE]

Thanks for the specific direction, @AugustinMauroy and @avivkeller. I have updated and rebased the branch to cover the full supported configuration-file set.

When --config-file is omitted, discovery now checks this exact priority order:

1. doc-kit.config.js
2. doc-kit.config.cjs
3. doc-kit.config.mjs
4. doc-kit.config.ts
5. doc-kit.config.cts
6. doc-kit.config.mts

The first existing file wins. An explicit configFile still bypasses discovery, JSON is not included because it is unsupported, and the no-file behavior remains unchanged.

Coverage now includes:

• all six discovered filenames;
• exact probe order and first-match priority;
• explicit-path precedence;
• no-file fallback;
• native loading for TypeScript, CommonJS TypeScript, and ES module TypeScript configurations.

Local verification on current upstream main b9750dc:

• focused configuration and loader tests: 34 passed
• full test suite: 529 passed, 0 failed
• lint: 0 errors; 2 pre-existing unrelated warnings
• format check: passed
• diff check: passed

I also checked the still-open dynamic-configuration PR #905. It touches the same configuration area but implements dynamic default values, so there is no semantic overlap with this file-discovery correction at present.

The updated head is 662687f. Could you please take another look when CI is ready?

[avivkeller]

I feel like a dep like cosmiconfig does this for us?

[avivkeller]

Didn't mean to close! Feel free to iterate based on my feedback

[AysajanE]

Thanks — that makes sense. I have reworked the revision locally to use cosmiconfig for discovery instead of maintaining the file-probing logic ourselves. The explorer is configured for the current working directory and the agreed six doc-kit.config.* names, in priority order; an explicit --config-file still bypasses discovery, and the existing loader remains responsible for JavaScript and TypeScript module loading.

Local verification is green: focused configuration tests 17/17, full suite 527/527, six-extension plus priority smoke check passed, lint has 0 errors (2 pre-existing unrelated warnings), and formatting passed. I have not updated the PR head yet.

[avivkeller]

Can you push those changes?

[AysajanE]

Thanks — I’ve pushed the cosmiconfig revision in ed0755a.

Configuration discovery is now scoped to the current working directory and uses the agreed priority order for doc-kit.config.js, .cjs, .mjs, .ts, .cts, and .mts. An explicit --config-file still bypasses discovery.

Validation after the update:

• focused configuration tests: 17/17 passed
• full test suite: 527/527 passed
• lint: 0 errors (2 pre-existing unrelated warnings)
• formatting: passed
• real-file smoke test: all six extensions and first-match priority passed

Please take another look when convenient.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.96%. Comparing base (4534824) to head (4c8e448).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #901      +/-   ##
==========================================
- Coverage   86.17%   84.96%   -1.21%     
==========================================
  Files         188      192       +4     
  Lines       17146    17558     +412     
  Branches     1540     1559      +19     
==========================================
+ Hits        14776    14919     +143     
- Misses       2363     2633     +270     
+ Partials        7        6       -1     

☔ 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.

[avivkeller]

Why is this so complex?

Can we not just:

const explorer = cosmiconfig('doc-kit');
const result = await explorer.search();

[AysajanE]

You are right that search() already starts from process.cwd() and defaults to a non-traversing search, so the explicit working directory and searchStrategy are redundant.

The additional searchPlaces and loaders were preserving the six filenames requested in the earlier review: doc-kit.config.js, .cjs, .mjs, .ts, .cts, and .mts, with a defined priority. In particular, cosmiconfig defaults do not discover .cts or .mts, and using its defaults would also broaden discovery to package/rc/JSON/YAML conventions.

I can simplify this to cosmiconfig("doc-kit").search() if that earlier six-extension requirement is no longer desired. That would intentionally drop automatic .cts/.mts discovery and follow the standard cosmiconfig conventions instead, while explicit --config-file paths would remain unchanged. Could you confirm which behavior you prefer?

[avivkeller]

I'd prefer that you simplified this, as I had requested, regardless of MTS/TS support.

I'd also prefer to I spoke to a human :-)

[AysajanE]

Got it. I am reading every comment here as the real person Aysajan Eziz, as I am typing this manually.

[AysajanE]

Thanks, @avivkeller. @AugustinMauroy, the current head (4c8e448) now uses the simplified cosmiconfig('doc-kit').search() approach requested in the later review, and Aviv has approved that head. Your earlier changes-request review is still the review decision GitHub shows; when convenient, would you mind re-reviewing the current head?

[avivkeller]

I believe this pull request was submitted in a way that conflicts with the transparency and good-faith collaboration that open source depends on.

From what I can tell, it appears that this project and our volunteer maintainers have been used as part of Northset's product demonstration efforts. We were never asked whether we wished to participate in those efforts, nor do we endorse or intend to help market or validate commercial AI products through our review process.

For that reason, I am not comfortable accepting this contribution, regardless of its technical merits (who are only merit-worthy after heavy review by myself). I can't speak for the Node.js Project, but I personally ask that our project, and other unconsenting open-source projects, not be used as part of future promotional campaigns without prior consent, it wastes maintainer time and lowers our productivity.

Accordingly, I’m closing this pull request. However, I encourage future contributions to follow the usual open-source workflow, with contributors taking clear personal ownership of their submissions rather than presenting them as part of an external agentic verification program. I look forward to your future contributions, sent in a personal capacity rather than a marketing stunt.

(Disclaimer: I'm not a member of the Node.js TSC, or the OpenJS Foundation's staff, so I am not speaking on their behalf. I'm speaking as a maintainer who feels that this is a violation of our review efforts)