fixup! WIP

CHANGELOG.md

@@ -16,10 +16,15 @@ Versioning].
 
 ### Changed
 
+- **\[BREAKING\]** The `initialize()` function is now `async`.
+- If you have [Prettier] installed in your project, Austenite will now use it to
+  format generated Markdown specification output.
 - The generated specification output has been improved.
 - Markdown phrasing content is now supported in variable and constraint
   descriptions.
 
+[prettier]: https://prettier.io/
+
 ## [v0.9.1] - 2024-03-25
 
 [v0.9.1]: https://github.com/ezzatron/austenite/releases/tag/v0.9.1

src/environment.ts

@@ -1,5 +1,8 @@
 import { EOL } from "os";
-import { render as renderSpecification } from "./specification.js";
+import {
+  render as renderSpecification,
+  type PrettyPrintType,
+} from "./specification.js";
 import { render as renderSummary } from "./summary.js";
 import { Results, validate } from "./validation.js";
 import {
@@ -13,13 +16,15 @@ let state: State = createInitialState();
 
 export type InitializeOptions = {
   readonly onInvalid?: OnInvalid;
+  readonly prettyPrint?: PrettyPrintType;
 };
 
 export async function initialize(
   options: InitializeOptions = {},
 ): Promise<void> {
   if (process.env.AUSTENITE_SPEC === "true") {
-    console.log(await renderSpecification(variablesByName()));
+    const { prettyPrint = "prettier" } = options;
+    console.log(await renderSpecification(prettyPrint, variablesByName()));
 
     // eslint-disable-next-line n/no-process-exit
     process.exit(0);

src/specification.ts

@@ -13,10 +13,16 @@ import { Visitor } from "./schema.js";
 import { quote } from "./shell.js";
 import { Variable } from "./variable.js";
 
-export async function render(variables: Variable<unknown>[]): Promise<string> {
+export type PrettyPrintType = "prettier" | "none";
+
+export async function render(
+  prettyPrintType: PrettyPrintType,
+  variables: Variable<unknown>[],
+): Promise<string> {
   const app = appName();
 
   return prettyPrint(
+    prettyPrintType,
     toMarkdown(
       {
         type: "root",
@@ -34,23 +40,30 @@ export async function render(variables: Variable<unknown>[]): Promise<string> {
   );
 }
 
-async function prettyPrint(markdown: string): Promise<string> {
-  try {
-    const prettier = await import("prettier");
-
-    const options = (await prettier.resolveConfig(
-      join(process.cwd(), "ENVIRONMENT.md"),
-    )) ?? {
-      printWidth: 80,
-      proseWrap: "always",
-    };
-
-    return (
-      await prettier.format(markdown, { ...options, parser: "markdown" })
-    ).trimEnd();
-  } catch {
-    return markdown.trimEnd();
+async function prettyPrint(
+  prettyPrintType: PrettyPrintType,
+  markdown: string,
+): Promise<string> {
+  if (prettyPrintType === "prettier") {
+    try {
+      const prettier = await import("prettier");
+
+      const options = (await prettier.resolveConfig(
+        join(process.cwd(), "ENVIRONMENT.md"),
+      )) ?? {
+        printWidth: 80,
+        proseWrap: "always",
+      };
+
+      return (
+        await prettier.format(markdown, { ...options, parser: "markdown" })
+      ).trimEnd();
+    } catch {
+      // fall through
+    }
   }
+
+  return markdown.trimEnd();
 }
 
 function appName(): string {

test/fixture/specification/no-prettier/prettier-disabled.md

@@ -0,0 +1,35 @@
+<BEGIN>
+# Environment variables
+
+The `<app>` app uses **declarative environment variables** powered by **[Austenite]**.
+
+[austenite]: https://github.com/ezzatron/austenite
+
+| Name            | Usage    | Description     |
+| :-------------- | :------- | :-------------- |
+| [`LOGO`](#logo) | Required | Main logo image |
+
+<!-- prettier-ignore-start -->
+
+> [!TIP]
+> If you set an empty value for an environment variable, the app behaves as if that variable isn't set.
+
+<!-- prettier-ignore-end -->
+
+## `LOGO`
+
+_Main logo image_
+
+The `LOGO` variable is a **required** variable that takes **absolute URL** values, or **relative URL** values relative to `https://base.example.org/path/to/resource`.
+
+### Example values
+
+```sh
+export LOGO=https://host.example.org/path/to/resource # URL (absolute)
+```
+
+```sh
+export LOGO=path/to/resource # URL (relative)
+```
+
+<END>

test/suite/specification-prettier.spec.ts

@@ -93,6 +93,20 @@ describe("Specification documents (Prettier unavailable)", () => {
       expect(exitCode).toBe(0);
     });
   });
+
+  describe("when pretty printing is explicitly disabled", () => {
+    it("doesn't pretty print the specification output", async () => {
+      url("LOGO", "Main logo image", {
+        base: new URL("https://base.example.org/path/to/resource"),
+      });
+      await initialize({ prettyPrint: "none" });
+
+      await expect(
+        "<BEGIN>\n" + mockConsole.readStdout() + "\n<END>\n",
+      ).toMatchFileSnapshot(fixturePath("no-prettier/prettier-disabled"));
+      expect(exitCode).toBe(0);
+    });
+  });
 });
 
 function fixturePath(name: string): string {