feat(config): cosmiconfig (#939)

Author: avivkeller

.changeset/curvy-items-smile.md

@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': minor
+---
+
+Discover and load configuration files with `cosmiconfig`.

README.md

@@ -54,9 +54,11 @@ Commands:
 
 ### `generate`
 
-You must provide either `--target` (one or more generators to run) or
-`--config-file` (which supplies the targets). Running `generate` without either
-exits with an error pointing you to the help output.
+You must provide an input and at least one target through command-line options
+or a configuration file. Configuration is discovered automatically using
+`cosmiconfig`, or you can select a file explicitly with `--config-file`.
+Running `generate` without the required values exits with an error pointing you
+to the help output.
 
 ```
 Usage: @node-core/doc-kit generate [options]

bin/commands/generate.mjs

@@ -12,6 +12,7 @@ const { runGenerators } = createGenerator();
 
 /**
  * @typedef {Object} CLIOptions
+ * @property {string} configFile
  * @property {string[]} input
  * @property {string[]} target
  * @property {string[]} ignore

docs/configuration.md

@@ -1,16 +1,36 @@
 # Configuration
 
-`doc-kit`'s CLI supports a `--config-file` option, allowing for custom configuration files to be passed.
-These configuration files must be loadable via a `import()` call, so usually JSON or JavaScript files with default exports.
+`doc-kit` uses [`cosmiconfig`](https://github.com/cosmiconfig/cosmiconfig) to
+discover and load configuration. Run the CLI from your project directory and it
+will automatically look for a `doc-kit` property in `package.json`, rc files
+such as `.doc-kitrc.yml`, and module files such as `doc-kit.config.mjs`.
 
-By convention, this file is usually named `doc-kit.config.mjs` or `doc-kit.config.json`.
+Use `--config-file <path>` to load a specific file instead of searching.
 
 ## Configuration File Format
 
 Configuration files can be either:
 
-- **JavaScript/ESM** (`.mjs`, `.js` with `"type": "module"`)
+- **JavaScript** (`.js`, `.mjs`, `.cjs`)
+- **TypeScript** (`.ts`, when `typescript` is installed in the project)
 - **JSON** (`.json`)
+- **YAML** (`.yaml`, `.yml`, or an extensionless rc file)
+
+JavaScript and TypeScript configuration files export the configuration object.
+JSON and YAML files contain the object directly. A `package.json` configuration
+uses the `doc-kit` property:
+
+```json
+{
+  "doc-kit": {
+    "target": ["json"],
+    "global": {
+      "input": "doc/api/*.md",
+      "output": "out"
+    }
+  }
+}
+```
 
 ### Basic Example
 
@@ -94,10 +114,11 @@ export default {
 
 ## Configuration Merging
 
-Configurations are merged in the following order (earlier sources take precedence):
+Configurations are merged in the following order (higher sources take
+precedence):
 
-1. **Config file** (`--config-file`)
-2. **CLI options** (command-line arguments)
+1. **CLI options** (command-line arguments)
+2. **Configuration file** (discovered or selected with `--config-file`)
 3. **Default values** (built-in defaults)
 
 ## CLI Options Mapping

package-lock.json

@@ -72,6 +72,7 @@
     "@swc/wasm": "^1.15.46",
     "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",