docs(reporters): add "json" reporter and rename "default" to "pretty"

.changeset/cyan-cows-cheer.md

@@ -0,0 +1,5 @@
+---
+'@emigrate/docs': minor
+---
+
+Add documentation for the built-in "json" reporter

.changeset/pink-bobcats-prove.md

@@ -0,0 +1,5 @@
+---
+'@emigrate/docs': minor
+---
+
+The "default" reporter is now named "pretty"

docs/astro.config.mjs

@@ -171,8 +171,12 @@ export default defineConfig({
                   link: '/plugins/reporters/',
                 },
                 {
-                  label: 'Default Reporter',
+                  label: 'Pretty Reporter (default)',
-                  link: '/plugins/reporters/default/',
+                  link: '/plugins/reporters/pretty/',
+                },
+                {
+                  label: 'JSON Reporter',
+                  link: '/plugins/reporters/json/',
                 },
                 {
                   label: 'Pino Reporter',

docs/src/content/docs/commands/list.mdx

@@ -86,6 +86,9 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install
 
 ### `-r`, `--reporter <name>`
 
+**type:** `"pretty" | "json" | string`  
+**default:** `"pretty"`
+
 The <Link href="/plugins/reporters/">reporter</Link> to use for listing the migrations.
 
 The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

docs/src/content/docs/commands/new.mdx

@@ -101,6 +101,9 @@ In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package
 
 ### `-r`, `--reporter <name>`
 
+**type:** `"pretty" | "json" | string`  
+**default:** `"pretty"`
+
 The <Link href="/plugins/reporters/">reporter</Link> to use for listing the migrations.
 
 The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

docs/src/content/docs/commands/remove.mdx

@@ -95,6 +95,9 @@ In case you have both a `emigrate-storage-somedb` and a `somedb` package install
 
 ### `-r`, `--reporter <name>`
 
+**type:** `"pretty" | "json" | string`  
+**default:** `"pretty"`
+
 The <Link href="/plugins/reporters/">reporter</Link> to use for listing the migrations.
 
 The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

docs/src/content/docs/commands/up.mdx

@@ -147,6 +147,9 @@ In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package
 
 ### `-r`, `--reporter <name>`
 
+**type:** `"pretty" | "json" | string`  
+**default:** `"pretty"`
+
 The <Link href="/plugins/reporters/">reporter</Link> to use for reporting the migration progress.
 
 The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:

docs/src/content/docs/plugins/reporters/default.mdx

@@ -1,23 +0,0 @@
----
-title: Default Reporter
----
-
-Emigrate's default reporter. The default reporter recognizes if the current terminal is an interactive shell (or if it's a CI environment), if that's the case _no_ animations will be shown.
-
-## Usage
-
-By default, Emigrate uses the default reporter.
-
-## Example output
-
-```bash
-
-Emigrate up v0.10.0 /Users/joakim/dev/@aboviq/test-emigrate (dry run)
-
-  1 pending migrations to run
-
-  › migration-folder/20231218135441244_create_some_table.sql (pending)
-
-  1 pending (1 total)
-
-```

docs/src/content/docs/plugins/reporters/index.mdx

@@ -20,6 +20,7 @@ Or set it up in your configuration file, see <Link href="/reference/configuratio
 ## Available Reporters
 
 <CardGrid>
-  <LinkCard title="Default Reporter" href="default/" />
+  <LinkCard title="Pretty Reporter" description="The default reporter" href="pretty/" />
-  <LinkCard title="Pino Reporter" href="pino/" />
+  <LinkCard title="JSON Reporter" description="A built-in reporter for outputing a JSON object" href="json/" />
+  <LinkCard title="Pino Reporter" description="A reporter package for outputting new line delimited JSON" href="pino/" />
 </CardGrid>

docs/src/content/docs/plugins/reporters/json.mdx

@@ -0,0 +1,102 @@
+---
+title: JSON Reporter
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import Link from '@components/Link.astro';
+
+An Emigrate reporter that outputs a JSON object.
+
+The reporter is included by default and does not need to be installed separately.
+
+## Usage
+
+### Via CLI
+
+<Tabs>
+  <TabItem label="npm">
+    ```bash
+    npx emigrate <command> --reporter json
+    ```
+  </TabItem>
+  <TabItem label="pnpm">
+    ```bash
+    pnpm emigrate <command> --reporter json
+    ```
+  </TabItem>
+  <TabItem label="yarn">
+    ```bash
+    yarn emigrate <command> --reporter json
+    ```
+  </TabItem>
+  <TabItem label="bun">
+    ```bash
+    bunx --bun emigrate <command> --reporter json
+    ```
+  </TabItem>
+  <TabItem label="deno">
+    ```json title="package.json" {3}
+    {
+      "scripts": {
+        "emigrate": "emigrate"
+      }
+    }
+    ```
+
+    ```bash
+    deno task emigrate <command> --reporter json
+    ```
+  </TabItem>
+</Tabs>
+
+See for instance the <Link href="/commands/up/#-r---reporter-name">Reporter Option</Link> for the `up` command for more information.
+
+### Via configuration file
+
+<Tabs>
+  <TabItem label="JavaScript">
+    ```js title="emigrate.config.js"
+    /** @type {import('@emigrate/cli').EmigrateConfig} */
+    export default {
+      reporter: 'json',
+    };
+    ```
+  </TabItem>
+  <TabItem label="TypeScript">
+    ```ts title="emigrate.config.ts"
+    import { type EmigrateConfig } from '@emigrate/cli';
+
+    const config: EmigrateConfig = {
+      reporter: 'json',
+    };
+
+    export default config;
+    ```
+  </TabItem>
+</Tabs>
+
+See <Link href="/reference/configuration/#reporter">Reporter Configuration</Link> for more information.
+
+## Example output
+
+```json
+{
+  "command": "up",
+  "version": "0.17.2",
+  "numberTotalMigrations": 1,
+  "numberDoneMigrations": 0,
+  "numberSkippedMigrations": 0,
+  "numberFailedMigrations": 0,
+  "numberPendingMigrations": 1,
+  "success": true,
+  "startTime": 1707206599968,
+  "endTime": 1707206600005,
+  "migrations": [
+    {
+      "name": "/your/project/migrations/20240206075446123_some_other_table.sql",
+      "status": "pending",
+      "duration": 0
+    }
+  ]
+}
+```

docs/src/content/docs/plugins/reporters/pino.mdx

@@ -91,11 +91,27 @@ See for instance the <Link href="/commands/up/#-r---reporter-name">Reporter Opti
 
 ### Via configuration file
 
-```js title="emigrate.config.js" {2}
+<Tabs>
-export default {
+  <TabItem label="JavaScript">
-  reporter: 'pino',
+    ```js title="emigrate.config.js"
-};
+    /** @type {import('@emigrate/cli').EmigrateConfig} */
-```
+    export default {
+      reporter: 'pino',
+    };
+    ```
+  </TabItem>
+  <TabItem label="TypeScript">
+    ```ts title="emigrate.config.ts"
+    import { type EmigrateConfig } from '@emigrate/cli';
+
+    const config: EmigrateConfig = {
+      reporter: 'pino',
+    };
+
+    export default config;
+    ```
+  </TabItem>
+</Tabs>
 
 See <Link href="/reference/configuration/#reporter">Reporter Configuration</Link> for more information.
 

docs/src/content/docs/plugins/reporters/pretty.mdx

@@ -0,0 +1,90 @@
+---
+title: Pretty Reporter (default)
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import Link from '@components/Link.astro';
+
+Emigrate's default reporter. It recognizes if the current terminal is an interactive shell (or if it's a CI environment), if that's the case _no_ animations will be shown.
+
+The reporter is included by default and does not need to be installed separately.
+
+## Usage
+
+By default, Emigrate uses the "pretty" reporter, but it can also be explicitly set by using the <Link href="/commands/up/#-r---reporter-name">`--reporter`</Link> flag.
+
+<Tabs>
+  <TabItem label="npm">
+    ```bash
+    npx emigrate <command> --reporter pretty
+    ```
+  </TabItem>
+  <TabItem label="pnpm">
+    ```bash
+    pnpm emigrate <command> --reporter pretty
+    ```
+  </TabItem>
+  <TabItem label="yarn">
+    ```bash
+    yarn emigrate <command> --reporter pretty
+    ```
+  </TabItem>
+  <TabItem label="bun">
+    ```bash
+    bunx --bun emigrate <command> --reporter pretty
+    ```
+  </TabItem>
+  <TabItem label="deno">
+    ```json title="package.json" {3}
+    {
+      "scripts": {
+        "emigrate": "emigrate"
+      }
+    }
+    ```
+
+    ```bash
+    deno task emigrate <command> --reporter pretty
+    ```
+  </TabItem>
+</Tabs>
+
+Or by setting it in the configuration file.
+
+<Tabs>
+  <TabItem label="JavaScript">
+    ```js title="emigrate.config.js"
+    /** @type {import('@emigrate/cli').EmigrateConfig} */
+    export default {
+      reporter: 'pretty',
+    };
+    ```
+  </TabItem>
+  <TabItem label="TypeScript">
+    ```ts title="emigrate.config.ts"
+    import { type EmigrateConfig } from '@emigrate/cli';
+
+    const config: EmigrateConfig = {
+      reporter: 'pretty',
+    };
+
+    export default config;
+    ```
+  </TabItem>
+</Tabs>
+
+See <Link href="/reference/configuration/#reporter">Reporter Configuration</Link> for more information.
+
+## Example output
+
+```bash
+
+Emigrate up v0.17.2 /your/working/directory (dry run)
+
+  1 pending migrations to run
+
+  › migration-folder/20231218135441244_create_some_table.sql (pending)
+
+  1 pending (1 total)
+
+```

docs/src/content/docs/reference/configuration.mdx

@@ -45,9 +45,9 @@ Set the directory where your migrations are located, relative to the project roo
 
 ### `reporter`
 
-**type:** `string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)`
+**type:** `"pretty" | "json" | string | EmigrateReporter | Promise<EmigrateReporter> | (() => Promise<EmigrateReporter>)`
 
-**default:** `"default"` - the default reporter
+**default:** `"pretty"` - the default reporter
 
 Set the reporter to use for the different commands. Specifying a <Link href="/plugins/reporters/">reporter</Link> is most useful in a CI or production environment where you either ship logs or want to have a machine-readable format.
 
@@ -64,6 +64,9 @@ export default {
   up: {
     reporter: 'json',
   },
+  new: {
+    reporter: 'pretty', // Not really necessary, as it's the default
+  },
 };
 ```