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 — loadConfigFile returns {} otherwise. As raised in #897, most config-driven tools also detect a conventional config file automatically, so a valid doc-kit.config.mjs sitting in the project root is silently ignored today. That is an easy footgun for anyone who assumes the file is picked up.

Change

• In createRunConfiguration, when no --config-file is provided, auto-detect a doc-kit.config.mjs in the current working directory and load it through the existing loader. An explicit --config-file still takes precedence, and when no file is present the configuration falls back to empty — unchanged behavior. No new dependency; a tight happy path, as the issue suggests.
• Add unit tests covering auto-detection, explicit-path precedence, and the no-file fallback.

Checks (Node 22)

• node --test --experimental-test-module-mocks src/utils/configuration/__tests__/index.test.mjs — 17 passing, including the new cases.

Fixes #897

---

Disclosure: this change was prepared with AI assistance and reviewed by me before submitting.
I ran the check(s) above in a network-isolated container and published a signed, re-runnable
record of that run, verifiable via GitHub artifact attestation:
https://northset-oss.github.io/verification-pilot/. Contributor self-run, not a maintainer verification.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jul 15, 2026 3:55pm

[cursor]

PR Summary

Low Risk
Configuration discovery only affects startup when no explicit config path is given; precedence and empty fallback preserve prior behavior aside from picking up conventional config files.

Overview
When --config-file is omitted, createRunConfiguration now scans process.cwd() for the first existing file among doc-kit.config.js, .cjs, .mjs, .ts, .cts, and .mts (in that order) and loads it via the existing loadConfigFile path. An explicit --config-file still wins and skips discovery; if nothing matches, behavior stays an empty file config merged with CLI flags and defaults.

Tests cover per-extension auto-detection, priority when multiple files exist, explicit-path precedence, and probing all candidates when none exist. Loader tests add integration checks that .ts / .cts / .mts configs import correctly through importFromURL.

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

[avivkeller]

What about:
.config.js
.config.cjs
.config.json?

[AugustinMauroy]

their aren't supported by the code.
IMO we should also support ts, cts, mts as types strippable code

[AugustinMauroy]

the logic here is wrong you should do something like this:

resolve configuration file:

  if --config option is provided:
    use the provided file
  else:
    search for a configuration file named:
      doc-kit.config.js
      doc-kit.config.cjs
      doc-kit.config.mjs
      doc-kit.config.ts
      doc-kit.config.cts
      doc-kit.config.mts

    use the first file that exists (following a defined priority)

  pass the resolved path to loadConfigFile()

[AysajanE]

Thanks — understood. I will replace the single .mjs probe with explicit --config-file precedence followed by discovery across the six names you listed, and add coverage for every extension plus the multiple-files case. Before I update the branch, should the order in your example (.js, .cjs, .mjs, .ts, .cts, .mts) also be the precedence when more than one exists? I will leave .json out unless you want it included.

[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?