WIP

.prettierignore

@@ -1,5 +1,5 @@
 /.github/
 /.makefiles/
 /artifacts/
-/test/fixture/specification/
-/ENVIRONMENT.md
+/CHANGELOG.md
+/test/fixture/specification/no-prettier/

.prettierrc.json

@@ -1,3 +1,12 @@
 {
-  "plugins": ["prettier-plugin-organize-imports"]
+  "plugins": ["prettier-plugin-organize-imports"],
+  "overrides": [
+    {
+      "files": "*.md",
+      "options": {
+        "printWidth": 80,
+        "proseWrap": "always"
+      }
+    }
+  ]
 }

CHANGELOG.md

@@ -2,8 +2,8 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog], and this project adheres to
-[Semantic Versioning].
+The format is based on [Keep a Changelog], and this project adheres to [Semantic
+Versioning].
 
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
@@ -39,8 +39,8 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ### Changed
 
-- **\[BREAKING\]** Explicit examples must be provided in a declaration if
-  the declaration uses constraints that would make the auto-generated examples
+- **\[BREAKING\]** Explicit examples must be provided in a declaration if the
+  declaration uses constraints that would make the auto-generated examples
   invalid.
 
 ## [v0.8.0] - 2024-03-23

ENVIRONMENT.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-The `example` app uses **declarative environment variables** powered by **[Austenite]**.
+The `example` app uses **declarative environment variables** powered by
+**[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -30,7 +31,8 @@ The `example` app uses **declarative environment variables** powered by **[Auste
 
 _CDN to use when serving static assets_
 
-The `CDN_URL` variable is a **required** variable that takes **absolute URL** values, with these constraints:
+The `CDN_URL` variable is a **required** variable that takes **absolute URL**
+values, with these constraints:
 
 - Protocol must be `http:` or `https:`
 
@@ -70,7 +72,8 @@ export DEBUG=false # false
 
 _Number of atoms on earth_
 
-The `EARTH_ATOM_COUNT` variable is an **optional** variable that takes **big integer** values.
+The `EARTH_ATOM_COUNT` variable is an **optional** variable that takes **big
+integer** values.
 
 ### Example values
 
@@ -98,7 +101,8 @@ export EARTH_ATOM_COUNT=0b11110001001000000 # binary
 
 _GRPC request timeout_
 
-The `GRPC_TIMEOUT` variable is an **optional** variable that takes **ISO 8601 duration** values, with these constraints:
+The `GRPC_TIMEOUT` variable is an **optional** variable that takes **ISO 8601
+duration** values, with these constraints:
 
 - Must be >= PT0.1S and <= PT10S
 
@@ -116,7 +120,8 @@ export GRPC_TIMEOUT=PT5S # 5 seconds
 
 _The minimum log level to record_
 
-The `LOG_LEVEL` variable is an **optional** variable that takes `debug`, `info`, `warn`, `error`, or `fatal`.
+The `LOG_LEVEL` variable is an **optional** variable that takes `debug`, `info`,
+`warn`, `error`, or `fatal`.
 
 ### Default value
 
@@ -150,7 +155,8 @@ export LOG_LEVEL=fatal # the application cannot proceed
 
 _Listen port for the HTTP server_
 
-The `PORT` variable is an **optional** variable that takes **port number** values.
+The `PORT` variable is an **optional** variable that takes **port number**
+values.
 
 ### Default value
 
@@ -168,7 +174,8 @@ export PORT=12345 # a port number
 
 _Database connection string for read-models_
 
-The `READ_DSN` variable is a **required** variable that takes **string** values, with these constraints:
+The `READ_DSN` variable is a **required** variable that takes **string** values,
+with these constraints:
 
 - Must have a minimum length of 30
 
@@ -182,7 +189,8 @@ export READ_DSN='host=localhost dbname=readmodels user=projector' # local databa
 
 _Kubernetes `redis-primary` service host_
 
-The `REDIS_PRIMARY_SERVICE_HOST` variable is a **required** variable that takes **hostname** values.
+The `REDIS_PRIMARY_SERVICE_HOST` variable is a **required** variable that takes
+**hostname** values.
 
 ### Example values
 
@@ -198,7 +206,8 @@ export REDIS_PRIMARY_SERVICE_HOST=10.0.0.11 # an IP address
 
 _Kubernetes `redis-primary` service port_
 
-The `REDIS_PRIMARY_SERVICE_PORT` variable is a **required** variable that takes **port number** values.
+The `REDIS_PRIMARY_SERVICE_PORT` variable is a **required** variable that takes
+**port number** values.
 
 ### Example values
 
@@ -210,7 +219,8 @@ export REDIS_PRIMARY_SERVICE_PORT=12345 # a port number
 
 _Ratio of requests to sample_
 
-The `SAMPLE_RATIO` variable is an **optional** variable that takes **number** values.
+The `SAMPLE_RATIO` variable is an **optional** variable that takes **number**
+values.
 
 ### Example values
 
@@ -246,7 +256,8 @@ export SAMPLE_RATIO=0b11110001001000000 # binary
 
 _Session token signing key_
 
-The `SESSION_KEY` variable is a **required** variable that takes **base64** values.
+The `SESSION_KEY` variable is a **required** variable that takes **base64**
+values.
 
 ### Example values
 
@@ -258,7 +269,8 @@ export SESSION_KEY=Y29ucXVpc3RhZG9y # base64 encoded string
 
 _Weighting for this node_
 
-The `WEIGHT` variable is a **required** variable that takes **integer** values, with these constraints:
+The `WEIGHT` variable is a **required** variable that takes **integer** values,
+with these constraints:
 
 - Must be >= 1
 

README.md

@@ -6,11 +6,15 @@ _Declarative environment variables for Node.js._
 [![Build status][badge-build-image]][badge-build-link]
 [![Test coverage][badge-coverage-image]][badge-coverage-link]
 
-[badge-build-image]: https://img.shields.io/github/actions/workflow/status/ezzatron/austenite/ci-node-library.yml?branch=main&style=for-the-badge
-[badge-build-link]: https://github.com/ezzatron/austenite/actions/workflows/ci-node-library.yml
-[badge-coverage-image]: https://img.shields.io/codecov/c/gh/ezzatron/austenite?style=for-the-badge
+[badge-build-image]:
+  https://img.shields.io/github/actions/workflow/status/ezzatron/austenite/ci-node-library.yml?branch=main&style=for-the-badge
+[badge-build-link]:
+  https://github.com/ezzatron/austenite/actions/workflows/ci-node-library.yml
+[badge-coverage-image]:
+  https://img.shields.io/codecov/c/gh/ezzatron/austenite?style=for-the-badge
 [badge-coverage-link]: https://codecov.io/gh/ezzatron/austenite
-[badge-version-image]: https://img.shields.io/npm/v/austenite?label=austenite&logo=npm&style=for-the-badge
+[badge-version-image]:
+  https://img.shields.io/npm/v/austenite?label=austenite&logo=npm&style=for-the-badge
 [badge-version-link]: https://npmjs.com/package/austenite
 
 ## Usage

package.json

@@ -49,6 +49,9 @@
     "mdast-util-gfm": "^3.0.0",
     "mdast-util-to-markdown": "^2.1.0"
   },
+  "optionalDependencies": {
+    "prettier": "^3.0.0"
+  },
   "devDependencies": {
     "@stryker-mutator/core": "^8.0.0",
     "@stryker-mutator/typescript-checker": "^8.0.0",

src/environment.ts

@@ -15,9 +15,11 @@ export type InitializeOptions = {
   readonly onInvalid?: OnInvalid;
 };
 
-export function initialize(options: InitializeOptions = {}): void {
+export async function initialize(
+  options: InitializeOptions = {},
+): Promise<void> {
   if (process.env.AUSTENITE_SPEC === "true") {
-    console.log(renderSpecification(variablesByName()));
+    console.log(await renderSpecification(variablesByName()));
 
     // eslint-disable-next-line n/no-process-exit
     process.exit(0);

src/specification.ts

@@ -2,7 +2,7 @@ import type { PhrasingContent, RootContent, TableRow } from "mdast";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { gfmToMarkdown } from "mdast-util-gfm";
 import { toMarkdown } from "mdast-util-to-markdown";
-import { basename } from "path";
+import { basename, join } from "path";
 import {
   extrinsicConstraints,
   type ExtrinsicConstraint,
@@ -13,20 +13,44 @@ import { Visitor } from "./schema.js";
 import { quote } from "./shell.js";
 import { Variable } from "./variable.js";
 
-export function render(variables: Variable<unknown>[]): string {
+export async function render(variables: Variable<unknown>[]): Promise<string> {
   const app = appName();
 
-  return toMarkdown(
-    {
-      type: "root",
-      children: [...headerAST(app, variables), ...specificationAST(variables)],
-    },
-    {
-      bullet: "-",
-      emphasis: "_",
-      extensions: [gfmToMarkdown()],
-    },
-  ).trimEnd();
+  return prettyPrint(
+    toMarkdown(
+      {
+        type: "root",
+        children: [
+          ...headerAST(app, variables),
+          ...specificationAST(variables),
+        ],
+      },
+      {
+        bullet: "-",
+        emphasis: "_",
+        extensions: [gfmToMarkdown()],
+      },
+    ),
+  );
+}
+
+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();
+  }
 }
 
 function appName(): string {

test/fixture/example/run.ts

@@ -13,7 +13,7 @@ import {
   weight,
 } from "./env.js";
 
-initialize();
+await initialize();
 
 console.log("");
 console.log("Environment is valid 🎉");

test/fixture/specification/app-env-var.md

@@ -1,7 +1,8 @@
 <BEGIN>
 # Environment variables
 
-The `<custom app name>` app uses **declarative environment variables** powered by **[Austenite]**.
+The `<custom app name>` app uses **declarative environment variables** powered
+by **[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -13,4 +14,5 @@ The `<custom app name>` app uses **declarative environment variables** powered b
 <!-- prettier-ignore-end -->
 
 [declaring]: https://github.com/ezzatron/austenite#declarations
+
 <END>

test/fixture/specification/big-integer/default.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-The `<app>` app uses **declarative environment variables** powered by **[Austenite]**.
+The `<app>` app uses **declarative environment variables** powered by
+**[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -19,7 +20,8 @@ The `<app>` app uses **declarative environment variables** powered by **[Austeni
 
 _Weighting for this node_
 
-The `WEIGHT` variable is an **optional** variable that takes **big integer** values.
+The `WEIGHT` variable is an **optional** variable that takes **big integer**
+values.
 
 ### Default value
 

test/fixture/specification/big-integer/examples.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-The `<app>` app uses **declarative environment variables** powered by **[Austenite]**.
+The `<app>` app uses **declarative environment variables** powered by
+**[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -19,7 +20,8 @@ The `<app>` app uses **declarative environment variables** powered by **[Austeni
 
 _Weighting for this node_
 
-The `WEIGHT` variable is a **required** variable that takes **big integer** values.
+The `WEIGHT` variable is a **required** variable that takes **big integer**
+values.
 
 ### Example values
 

test/fixture/specification/big-integer/optional.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-The `<app>` app uses **declarative environment variables** powered by **[Austenite]**.
+The `<app>` app uses **declarative environment variables** powered by
+**[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -19,7 +20,8 @@ The `<app>` app uses **declarative environment variables** powered by **[Austeni
 
 _Weighting for this node_
 
-The `WEIGHT` variable is an **optional** variable that takes **big integer** values.
+The `WEIGHT` variable is an **optional** variable that takes **big integer**
+values.
 
 ### Example values
 

test/fixture/specification/big-integer/required.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-The `<app>` app uses **declarative environment variables** powered by **[Austenite]**.
+The `<app>` app uses **declarative environment variables** powered by
+**[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -19,7 +20,8 @@ The `<app>` app uses **declarative environment variables** powered by **[Austeni
 
 _Weighting for this node_
 
-The `WEIGHT` variable is a **required** variable that takes **big integer** values.
+The `WEIGHT` variable is a **required** variable that takes **big integer**
+values.
 
 ### Example values
 

test/fixture/specification/binary/default.md

@@ -1,6 +1,7 @@
 # Environment variables
 
-The `<app>` app uses **declarative environment variables** powered by **[Austenite]**.
+The `<app>` app uses **declarative environment variables** powered by
+**[Austenite]**.
 
 [austenite]: https://github.com/ezzatron/austenite
 
@@ -19,7 +20,8 @@ The `<app>` app uses **declarative environment variables** powered by **[Austeni
 
 _Session token signing key_
 
-The `SESSION_KEY` variable is an **optional** variable that takes **base64** values.
+The `SESSION_KEY` variable is an **optional** variable that takes **base64**
+values.
 
 ### Default value