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 17, 2026 11:06am

[cursor]

PR Summary

Low Risk
Discovery is limited to a fixed filename list in cwd and reuses existing config loading; explicit CLI paths are unchanged. Main caveat is cwd sensitivity if users run doc-kit from a subdirectory.

Overview
When --config-file is not passed, createRunConfiguration now looks in process.cwd() for the first existing file among doc-kit.config.js, .cjs, .mjs, .ts, .cts, and .mts, then loads it through the existing loadConfigFile path. An explicit --config-file still wins and skips discovery; if nothing matches, behavior stays the same as before (empty file config, CLI/defaults only).

Tests cover per-extension auto-detection, first-match priority when several files exist, explicit override, and the no-file fallback. importFromURL integration tests were added for type-strippable .ts / .cts / .mts config modules.

^{Reviewed by Cursor Bugbot for commit bebe41e. 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?