Improve specification output for URL declarations

src/declaration/big-integer.ts

@@ -8,7 +8,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar, toString } from "../schema.js";
+import { ScalarSchema, createScalar, toString } from "../schema.js";
 
 export type Options = DeclarationOptions<bigint>;
 
@@ -37,7 +37,7 @@ export function bigInteger<O extends Options>(
   };
 }
 
-function createSchema(): Scalar<bigint> {
+function createSchema(): ScalarSchema<bigint> {
   function unmarshal(v: string): bigint {
     try {
       return BigInt(v);

src/declaration/binary.ts

@@ -9,7 +9,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar } from "../schema.js";
+import { ScalarSchema, createScalar } from "../schema.js";
 
 const PATTERNS: Partial<Record<BufferEncoding, RegExp>> = {
   base64: /^[A-Za-z0-9+/]*={0,2}$/,
@@ -45,7 +45,7 @@ export function binary<O extends Options>(
   };
 }
 
-function createSchema(encoding: BufferEncoding): Scalar<Buffer> {
+function createSchema(encoding: BufferEncoding): ScalarSchema<Buffer> {
   function marshal(v: Buffer): string {
     return v.toString(encoding);
   }
@@ -76,7 +76,7 @@ function createUnmarshal(
 
 function buildExamples(
   encoding: BufferEncoding,
-  schema: Scalar<Buffer>,
+  schema: ScalarSchema<Buffer>,
 ): Examples {
   return createExamples({
     canonical: schema.marshal(Buffer.from("conquistador", "utf-8")),

src/declaration/boolean.ts

@@ -8,7 +8,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Enum, InvalidEnumError, createEnum } from "../schema.js";
+import { EnumSchema, InvalidEnumError, createEnum } from "../schema.js";
 import { SpecError } from "../variable.js";
 
 export type Options = DeclarationOptions<boolean> & {
@@ -47,7 +47,7 @@ export function boolean<O extends Options>(
   };
 }
 
-function createSchema(name: string, literals: Literals): Enum<boolean> {
+function createSchema(name: string, literals: Literals): EnumSchema<boolean> {
   for (const literal of Object.keys(literals)) {
     if (literal.length < 1) throw new EmptyLiteralError(name);
   }

src/declaration/duration.ts

@@ -9,7 +9,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar, toString } from "../schema.js";
+import { ScalarSchema, createScalar, toString } from "../schema.js";
 
 const { Duration } = Temporal;
 type Duration = Temporal.Duration;
@@ -41,7 +41,7 @@ export function duration<O extends Options>(
   };
 }
 
-function createSchema(): Scalar<Duration> {
+function createSchema(): ScalarSchema<Duration> {
   function unmarshal(v: string): Duration {
     try {
       return Duration.from(v);

src/declaration/enumeration.ts

@@ -8,7 +8,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Enum, InvalidEnumError, createEnum } from "../schema.js";
+import { EnumSchema, InvalidEnumError, createEnum } from "../schema.js";
 import { SpecError } from "../variable.js";
 
 export type Members<T> = Record<string, Member<T>>;
@@ -46,7 +46,7 @@ export function enumeration<T, O extends Options<T>>(
   };
 }
 
-function createSchema<T>(name: string, members: Members<T>): Enum<T> {
+function createSchema<T>(name: string, members: Members<T>): EnumSchema<T> {
   const entries = Object.entries(members);
 
   if (entries.length < 2) throw new InsufficientMembersError(name);

src/declaration/integer.ts

@@ -8,7 +8,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar, toString } from "../schema.js";
+import { ScalarSchema, createScalar, toString } from "../schema.js";
 
 export type Options = DeclarationOptions<number>;
 
@@ -37,7 +37,7 @@ export function integer<O extends Options>(
   };
 }
 
-function createSchema(): Scalar<number> {
+function createSchema(): ScalarSchema<number> {
   function unmarshal(v: string): number {
     const n = Number(v);
 

src/declaration/kubernetes-address.ts

@@ -10,7 +10,12 @@ import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
 import { create as createExamples } from "../example.js";
 import { Maybe, map, resolve } from "../maybe.js";
-import { Scalar, createScalar, createString, toString } from "../schema.js";
+import {
+  ScalarSchema,
+  createScalar,
+  createString,
+  toString,
+} from "../schema.js";
 import { Variable } from "../variable.js";
 
 export type KubernetesAddress = {
@@ -144,7 +149,7 @@ function registerPort(
   });
 }
 
-function createPortSchema(): Scalar<number> {
+function createPortSchema(): ScalarSchema<number> {
   function unmarshal(v: string): number {
     if (!/^\d*$/.test(v)) throw new Error("must be an unsigned integer");
     if (v !== "0" && v.startsWith("0")) {

src/declaration/network-port-number.ts

@@ -8,7 +8,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar, toString } from "../schema.js";
+import { ScalarSchema, createScalar, toString } from "../schema.js";
 
 export type Options = DeclarationOptions<number>;
 
@@ -38,7 +38,7 @@ export function networkPortNumber<O extends Options>(
   };
 }
 
-function createSchema(): Scalar<number> {
+function createSchema(): ScalarSchema<number> {
   function unmarshal(v: string): number {
     if (!/^\d*$/.test(v)) throw new Error("must be an unsigned integer");
     if (v !== "0" && v.startsWith("0")) {

src/declaration/number.ts

@@ -8,7 +8,7 @@ import {
 import { registerVariable } from "../environment.js";
 import { Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar, toString } from "../schema.js";
+import { ScalarSchema, createScalar, toString } from "../schema.js";
 
 export type Options = DeclarationOptions<number>;
 
@@ -37,7 +37,7 @@ export function number<O extends Options>(
   };
 }
 
-function createSchema(): Scalar<number> {
+function createSchema(): ScalarSchema<number> {
   function unmarshal(v: string): number {
     const n = Number(v);
 

src/declaration/url.ts

@@ -9,7 +9,7 @@ import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
 import { Example, Examples, create as createExamples } from "../example.js";
 import { resolve } from "../maybe.js";
-import { Scalar, createScalar, toString } from "../schema.js";
+import { createURL, toString, type URLSchema } from "../schema.js";
 import { Constraint, SpecError } from "../variable.js";
 
 // as per https://www.rfc-editor.org/rfc/rfc3986#section-3.1
@@ -33,7 +33,7 @@ export function url<O extends Options>(
   assertBase(name, validate, base);
 
   const def = defaultFromOptions(options);
-  const schema = createSchema(base);
+  const schema = createSchema(base, protocols);
 
   const v = registerVariable({
     name,
@@ -89,7 +89,10 @@ function assertBase(
   }
 }
 
-function createSchema(base: URL | undefined): Scalar<URL> {
+function createSchema(
+  base: URL | undefined,
+  protocols: string[] | undefined,
+): URLSchema {
   function unmarshal(v: string): URL {
     try {
       const url = new URL(v, base);
@@ -100,7 +103,7 @@ function createSchema(base: URL | undefined): Scalar<URL> {
     }
   }
 
-  return createScalar("URL", toString, unmarshal);
+  return createURL(base, protocols, toString, unmarshal);
 }
 
 function createValidate(

src/schema.ts

@@ -9,23 +9,28 @@ export type Schema<T> = {
 export type MarshalFn<T> = Schema<T>["marshal"];
 export type UnmarshalFn<T> = Schema<T>["unmarshal"];
 
-export type Scalar<T> = Schema<T> & {
+export type ScalarSchema<T> = Schema<T> & {
   readonly description: string;
 };
 
-export type Enum<T> = Schema<T> & {
+export type EnumSchema<T> = Schema<T> & {
   readonly members: Record<string, T>;
 };
 
-export function createString(description: string): Scalar<string> {
+export type URLSchema = Schema<URL> & {
+  readonly base: URL | undefined;
+  readonly protocols: string[] | undefined;
+};
+
+export function createString(description: string): ScalarSchema<string> {
   return createScalar(description, identity, identity);
 }
 
 export function createEnum<T>(
   members: Record<string, T>,
   marshal: MarshalFn<T>,
   unmarshal: UnmarshalFn<T>,
-): Enum<T> {
+): EnumSchema<T> {
   return {
     members,
     marshal,
@@ -37,11 +42,29 @@ export function createEnum<T>(
   };
 }
 
+export function createURL(
+  base: URL | undefined,
+  protocols: string[] | undefined,
+  marshal: MarshalFn<URL>,
+  unmarshal: UnmarshalFn<URL>,
+): URLSchema {
+  return {
+    base,
+    protocols,
+    marshal,
+    unmarshal,
+
+    accept(visitor) {
+      return visitor.visitURL(this);
+    },
+  };
+}
+
 export function createScalar<T>(
   description: string,
   marshal: MarshalFn<T>,
   unmarshal: UnmarshalFn<T>,
-): Scalar<T> {
+): ScalarSchema<T> {
   return {
     description,
     marshal,
@@ -54,8 +77,9 @@ export function createScalar<T>(
 }
 
 export type Visitor<T> = {
-  visitEnum(e: Enum<unknown>): T;
-  visitScalar(s: Scalar<unknown>): T;
+  visitEnum(e: EnumSchema<unknown>): T;
+  visitScalar(s: ScalarSchema<unknown>): T;
+  visitURL(s: URLSchema): T;
 };
 
 export class InvalidEnumError<T> extends Error {

src/specification.ts

@@ -4,6 +4,10 @@ import { Visitor } from "./schema.js";
 import { quote } from "./shell.js";
 import { Variable } from "./variable.js";
 
+const disjunctionFormatter = new Intl.ListFormat("en", {
+  type: "disjunction",
+});
+
 export function render(variables: Variable<unknown>[]): string {
   const app = appName();
 
@@ -85,21 +89,40 @@ function createSchemaRenderer(variable: Variable<unknown>): Visitor<string> {
 
   return {
     visitEnum({ members }) {
-      const listFormatter = new Intl.ListFormat("en", {
-        type: "disjunction",
-      });
       const acceptableValues = Object.keys(members).map((m) =>
         inlineCode(quote(m)),
       );
 
       return `The ${inlineCode(name)} variable is ${optionality} variable
-that takes ${listFormatter.format(acceptableValues)}.`;
+that takes ${disjunctionFormatter.format(acceptableValues)}.`;
     },
 
     visitScalar({ description }): string {
       return `The ${inlineCode(name)} variable is ${optionality} variable
 that takes ${strong(description)} values.`;
     },
+
+    visitURL({ base, protocols = [] }): string {
+      const protocolList: string =
+        protocols.length > 0
+          ? disjunctionFormatter.format(protocols.map((p) => inlineCode(p))) +
+            " "
+          : "";
+
+      const lines = [
+        `The ${inlineCode(name)} variable is ${optionality} variable
+that takes ${strong(`${protocolList}URL`)} values.`,
+      ];
+
+      if (base) {
+        lines.push(
+          `You can also use a URL reference relative to ` +
+            inlineCode(quote(base.toString())),
+        );
+      }
+
+      return lines.join("\n");
+    },
   };
 }
 

src/summary.ts

@@ -52,6 +52,10 @@ function createSchemaRenderer(): Visitor<string> {
     visitScalar(s) {
       return `<${s.description}>`;
     },
+
+    visitURL() {
+      return "<URL>";
+    },
   };
 }
 

test/fixture/specification/url/base.md

@@ -19,6 +19,7 @@ _Main logo image_
 
 The `LOGO` variable is a **required** variable
 that takes **URL** values.
+You can also use a URL reference relative to `https://base.example.org/path/to/resource`
 
 ### Example values
 

test/fixture/specification/url/protocols.md

@@ -7,18 +7,32 @@ The `<app>` app uses **declarative environment variables** powered by
 
 | Name                              | Usage    | Description             |
 | :-------------------------------- | :------- | :---------------------- |
+| [`HOMEPAGE`](#HOMEPAGE)           | Required | Main homepage URL       |
 | [`SOCKET_SERVER`](#SOCKET_SERVER) | Required | WebSocket server to use |
 
 > [!TIP]
 > If you set an empty value for an environment variable, the app behaves as if
 > that variable isn't set.
 
+## `HOMEPAGE`
+
+_Main homepage URL_
+
+The `HOMEPAGE` variable is a **required** variable
+that takes **`https:` URL** values.
+
+### Example values
+
+```sh
+export HOMEPAGE=https://host.example.org/path/to/resource # URL (https:)
+```
+
 ## `SOCKET_SERVER`
 
 _WebSocket server to use_
 
 The `SOCKET_SERVER` variable is a **required** variable
-that takes **URL** values.
+that takes **`ws:` or `wss:` URL** values.
 
 ### Example values