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

.changeset/quiet-dingos-detect.md

@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': patch
+---
+
+Automatically discover doc-kit configuration in the current working directory when `--config-file` is omitted.

package.json

@@ -61,6 +61,7 @@
     "@swc/html-wasm": "^1.15.43",
     "acorn": "^8.17.0",
     "commander": "^15.0.0",
+    "cosmiconfig": "^9.0.2",
     "dedent": "^1.7.2",
     "estree-util-to-js": "^2.0.0",
     "estree-util-visit": "^2.0.0",

src/utils/configuration/__tests__/index.test.mjs

@@ -5,6 +5,8 @@ import { describe, it, mock, beforeEach } from 'node:test';
 const mockParseChangelog = mock.fn(async changelog => [changelog]);
 const mockParseIndex = mock.fn(async index => [index]);
 const mockImportFromURL = mock.fn(async () => ({}));
+const mockSearch = mock.fn(async () => null);
+const mockCosmiconfig = mock.fn(() => ({ search: mockSearch }));
 
 const createMockConfig = (overrides = {}) => ({
   global: {},
@@ -37,6 +39,9 @@ mock.module('../../../parsers/markdown.mjs', {
 mock.module('../../loaders.mjs', {
   namedExports: { importFromURL: mockImportFromURL },
 });
+mock.module('cosmiconfig', {
+  namedExports: { cosmiconfig: mockCosmiconfig },
+});
 
 const {
   assertRunnableOptions,
@@ -49,9 +54,13 @@ const {
 
 // Helper to reset all mocks
 const resetAllMocks = () => {
-  [mockParseChangelog, mockParseIndex, mockImportFromURL].forEach(m =>
-    m.mock.resetCalls()
+  [mockParseChangelog, mockParseIndex, mockImportFromURL, mockSearch].forEach(
+    m => m.mock.resetCalls()
   );
+  mockCosmiconfig.mock.resetCalls();
+  mockImportFromURL.mock.mockImplementation(async () => ({}));
+  mockSearch.mock.mockImplementation(async () => null);
+  mockCosmiconfig.mock.mockImplementation(() => ({ search: mockSearch }));
 };
 
 // Helper to count specific function calls
@@ -184,6 +193,43 @@ describe('config.mjs', () => {
       assert.strictEqual(config.web.showSearchBox, true);
     });
 
+    it('should discover a config through cosmiconfig', async () => {
+      mockSearch.mock.mockImplementationOnce(async () => ({
+        config: createMockConfig({
+          global: { input: 'auto-detected-src/' },
+        }),
+        filepath: `${process.cwd()}/doc-kit.config.mjs`,
+      }));
+
+      const config = await createRunConfiguration({});
+
+      assert.strictEqual(config.global.input, 'auto-detected-src/');
+      assert.strictEqual(mockCosmiconfig.mock.calls.length, 1);
+      assert.deepStrictEqual(mockCosmiconfig.mock.calls[0].arguments, [
+        'doc-kit',
+      ]);
+      assert.strictEqual(mockSearch.mock.calls.length, 1);
+      assert.deepStrictEqual(mockSearch.mock.calls[0].arguments, []);
+    });
+
+    it('should prefer an explicit config file', async () => {
+      mockImportFromURL.mock.mockImplementationOnce(async () =>
+        createMockConfig({ global: { input: 'explicit-src/' } })
+      );
+
+      const config = await createRunConfiguration({
+        configFile: 'explicit-config.mjs',
+      });
+
+      assert.strictEqual(config.global.input, 'explicit-src/');
+      assert.strictEqual(mockCosmiconfig.mock.calls.length, 0);
+      assert.strictEqual(mockImportFromURL.mock.calls.length, 1);
+      assert.strictEqual(
+        mockImportFromURL.mock.calls[0].arguments[0],
+        'explicit-config.mjs'
+      );
+    });
+
     it('should transform string values only once', async () => {
       const changelogUrl = 'https://example.com/changelog.md';
       const indexUrl = 'https://example.com/index.md';
@@ -223,14 +269,16 @@ describe('config.mjs', () => {
       assert.strictEqual(config.chunkSize, 1);
     });
 
-    it('should work without config file', async () => {
+    it('should use an empty config when no config file is present', async () => {
       const config = await createRunConfiguration({
         version: '20.0.0',
         threads: 4,
       });
 
       assert.ok(config);
       assert.strictEqual(config.threads, 4);
+      assert.strictEqual(mockCosmiconfig.mock.calls.length, 1);
+      assert.strictEqual(mockSearch.mock.calls.length, 1);
       assert.strictEqual(mockImportFromURL.mock.calls.length, 0);
     });