@azure-tools/typespec-ts 0.56.0-dev.3 → 0.56.0-dev.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-ts",
-  "version": "0.56.0-dev.3",
+  "version": "0.56.0-dev.6",
   "description": "A TypeSpec emitter for TypeScript",
   "main": "dist/src/index.js",
   "type": "module",
@@ -42,9 +42,7 @@
     "@typespec/xml": "^0.83.0 || >=0.84.0-dev <0.84.0",
     "@typespec/ts-http-runtime": "0.3.6",
     "cross-env": "^10.1.0",
-    "mkdirp": "^3.0.1",
-    "npm-run-all": "~4.1.5",
-    "prettier": "^3.8.1",
+    "concurrently": "^10.0.0",
     "vitest": "^4.1.3",
     "vite": "^8.0.8",
     "@vitest/coverage-v8": "^4.1.3",
@@ -62,7 +60,6 @@
   },
   "dependencies": {
     "fast-xml-parser": "^5.7.0",
-    "handlebars": "^4.7.7",
     "prettier": "^3.8.1",
     "ts-morph": "^23.0.0",
     "tslib": "^2.3.1"
@@ -92,11 +89,11 @@
     "lint": "eslint . --ext .ts --max-warnings=0",
     "lint:fix": "eslint . --fix --ext .ts",
     "check:tree": "node ./test/commands/check-clean-tree.ts",
-    "integration-test-ci": "npm-run-all copy:typespec spector-test",
-    "spector-test": "npm-run-all --silent -p start-test-server --race generate-and-run",
-    "start-test-server": "mkdirp -p coverage && npx tsp-spector serve ./node_modules/@azure-tools/azure-http-specs/specs ./node_modules/@typespec/http-specs/specs --port 3002  --coverageFile ./coverage/spector-coverage-typescript-azure.json",
+    "integration-test-ci": "npm run copy:typespec && npm run spector-test",
+    "spector-test": "concurrently --kill-others --success first \"npm:start-test-server\" \"npm:generate-and-run\"",
+    "start-test-server": "node ./test/commands/start-test-server.js",
     "copy:typespec": "node ./test/commands/copy-typespec.ts",
-    "generate-and-run": "npm run generate-tsp-only:client && npm-run-all -p integration-test:alone generate-tsp-only:declarations && npm run stop-test-server -- -p 3002",
+    "generate-and-run": "npm run generate-tsp-only:client && concurrently --kill-others-on-fail \"npm:integration-test:alone\" \"npm:generate-tsp-only:declarations\" && npm run stop-test-server -- -p 3002",
     "generate-tsp-only": "node ./test/commands/gen-spector.js",
     "generate-tsp-only:client": "node ./test/commands/gen-spector.js --phase=client",
     "generate-tsp-only:declarations": "node ./test/commands/gen-spector.js --phase=declarations",

package/src/framework/declaration.ts

@@ -8,12 +8,14 @@ import {
   InterfaceDeclaration,
   InterfaceDeclarationStructure,
   SourceFile,
+  StatementStructures,
   StructureKind,
   TypeAliasDeclaration,
   TypeAliasDeclarationStructure,
 } from "ts-morph";
 import { useBinder } from "./hooks/binder.js";
 import { refkey as getRefKey } from "./refkey.js";
+import { enqueueStatement } from "./source-file-batch.js";
 export type DeclarationStructures =
   | ClassDeclarationStructure
   | EnumDeclarationStructure
@@ -80,25 +82,11 @@ export function addDeclaration(
   // Update the declaration name to be unique
   const trackedDeclaration = { ...declaration, name: trackedDeclarationName };
 
-  switch (trackedDeclaration.kind) {
-    case StructureKind.Class:
-      sourceFile.addClass(trackedDeclaration);
-      break;
-    case StructureKind.Enum:
-      sourceFile.addEnum(trackedDeclaration);
-      break;
-    case StructureKind.Function:
-      sourceFile.addFunction(trackedDeclaration);
-      break;
-    case StructureKind.Interface:
-      sourceFile.addInterface(trackedDeclaration);
-      break;
-    case StructureKind.TypeAlias:
-      if (trackedDeclaration.type) {
-        sourceFile.addTypeAlias(trackedDeclaration);
-      }
-      break;
-    default:
-      throw new Error(`Unsupported declaration kind ${(trackedDeclaration as any).kind}`);
+  // Skip empty type aliases (they have no body to emit). Done before
+  // dispatching so behaviour is identical whether batching or not.
+  if (trackedDeclaration.kind === StructureKind.TypeAlias && !trackedDeclaration.type) {
+    return;
   }
+
+  enqueueStatement(sourceFile, trackedDeclaration as StatementStructures);
 }

package/src/framework/source-file-batch.ts

@@ -0,0 +1,140 @@
+import {
+  ExportDeclarationStructure,
+  SourceFile,
+  StatementStructures,
+  StructureKind,
+} from "ts-morph";
+
+/**
+ * Generic per-source-file batch for ts-morph `add*` mutations.
+ *
+ * Each individual `sourceFile.addInterface/addFunction/addExportDeclaration/...`
+ * call re-parses the entire source file in ts-morph. Calling them in a loop
+ * therefore grows as O(N × file_size). This module collects structures while
+ * a batch is open and, on flush, issues a single `addStatements` call per file,
+ * collapsing N re-parses into 1.
+ *
+ * The batch is reference-counted so nested begin/flush pairs compose safely.
+ * Statements flush in insertion order and produce byte-identical output.
+ */
+
+let batchDepth = 0;
+const pendingByFile = new Map<SourceFile, StatementStructures[]>();
+
+/**
+ * Opens a batching scope. Subsequent `enqueueStatement` calls queue rather
+ * than mutate the AST until the matching `flushSourceFileBatch` is called.
+ */
+export function beginSourceFileBatch(): void {
+  batchDepth++;
+}
+
+/**
+ * Closes the most recent batching scope. When the outermost scope closes,
+ * all pending structures are written to their source files in bulk.
+ */
+export function flushSourceFileBatch(): void {
+  if (batchDepth === 0) {
+    return;
+  }
+  batchDepth--;
+  if (batchDepth > 0) {
+    return;
+  }
+  try {
+    for (const [sourceFile, statements] of pendingByFile) {
+      if (statements.length === 0) {
+        continue;
+      }
+      sourceFile.addStatements(statements);
+    }
+  } finally {
+    pendingByFile.clear();
+  }
+}
+
+/**
+ * Queues a statement structure for bulk-add on flush, or writes it
+ * immediately when no batch is open.
+ * @param sourceFile - Target source file.
+ * @param structure - The statement structure to add.
+ */
+export function enqueueStatement(sourceFile: SourceFile, structure: StatementStructures): void {
+  if (batchDepth > 0) {
+    let pending = pendingByFile.get(sourceFile);
+    if (!pending) {
+      pending = [];
+      pendingByFile.set(sourceFile, pending);
+    }
+    pending.push(structure);
+    return;
+  }
+  sourceFile.addStatements([structure]);
+}
+
+/**
+ * Returns the set of names exported from `sourceFile` considering both the
+ * declarations already present in its AST and any export declarations queued
+ * by the current batch. Use this in place of reading `getExportDeclarations`
+ * directly when callers dedup against existing exports inside a batch.
+ * @param sourceFile - The file to inspect.
+ */
+export function getEffectiveExportedNames(sourceFile: SourceFile): Set<string> {
+  const names = new Set<string>();
+  for (const decl of sourceFile.getExportDeclarations()) {
+    for (const named of decl.getNamedExports()) {
+      names.add(named.getAliasNode()?.getText() ?? named.getName());
+    }
+  }
+  const pending = pendingByFile.get(sourceFile);
+  if (pending) {
+    for (const structure of pending) {
+      if (structure.kind !== StructureKind.ExportDeclaration) {
+        continue;
+      }
+      collectNamedExportNames(structure.namedExports, names);
+    }
+  }
+  return names;
+}
+
+/**
+ * Returns the set of named exports queued in the current batch for
+ * `sourceFile`. Use this to union with any AST-based view of exports
+ * (e.g. `getExportedDeclarations`) when deduplicating against still-pending
+ * writes inside a batch.
+ * @param sourceFile - The file to inspect.
+ */
+export function getQueuedExportNames(sourceFile: SourceFile): Set<string> {
+  const names = new Set<string>();
+  const pending = pendingByFile.get(sourceFile);
+  if (!pending) {
+    return names;
+  }
+  for (const structure of pending) {
+    if (structure.kind !== StructureKind.ExportDeclaration) {
+      continue;
+    }
+    collectNamedExportNames(structure.namedExports, names);
+  }
+  return names;
+}
+
+function collectNamedExportNames(
+  named: ExportDeclarationStructure["namedExports"],
+  into: Set<string>,
+): void {
+  if (!named || typeof named === "function") {
+    // WriterFunction form is opaque to us; callers can't dedup by name.
+    return;
+  }
+  for (const item of named) {
+    if (typeof item === "string") {
+      into.add(item);
+    } else if (typeof item === "function") {
+      continue;
+    } else if (item) {
+      into.add(item.alias ?? item.name);
+    }
+  }
+}

package/src/interfaces.ts

@@ -223,7 +223,6 @@ export interface ClientOptions {
   generateTest?: boolean;
   generateSample?: boolean;
   azureOutputDirectory?: string;
-  isTypeSpecTest?: boolean;
   serviceInfo?: ServiceInfo;
   azureArm?: boolean;
   enableOperationGroup?: boolean;

package/src/lib.ts

@@ -39,7 +39,6 @@ export interface EmitterOptions {
    */
   "generate-test"?: boolean;
   "generate-sample"?: boolean;
-  "is-typespec-test"?: boolean;
   "azure-arm"?: boolean;
   "enable-operation-group"?: boolean;
   "enable-model-namespace"?: boolean;
@@ -170,11 +169,6 @@ export const EmitterOptionsSchema: JSONSchemaType<EmitterOptions> = {
       description:
         "Whether to generate sample files, for basic samples of your generated sdks. Defaults to `undefined`. Management packages' default to `true`.",
     },
-    "is-typespec-test": {
-      type: "boolean",
-      nullable: true,
-      description: "Internal option for test",
-    },
     "azure-arm": {
       type: "boolean",
       nullable: true,

package/src/metadata/build-readme-file.ts

@@ -1,12 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-ignore: to fix the handlebars issue
-import hbs from "handlebars";
 import { ClientModel } from "../interfaces.js";
 import { getClientName } from "../utils/name-constructors.js";
 import { NameType, normalizeName } from "../utils/name-utils.js";
+import { renderTemplate } from "./render-template.js";
 
 const azureReadmeModularTemplate = `# {{ clientDescriptiveName }} library for JavaScript
 
@@ -38,13 +36,10 @@ Key links:
 
 See our [support policy](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md) for more details.
 
-{{#if azure}}
 ### Prerequisites
 
 - An [Azure subscription][azure_sub].
-{{/if}}
 
-{{#if isReleasablePackage}}
 ### Install the \`{{ clientPackageName }}\` package
 
 Install the {{ clientDescriptiveName }} library for JavaScript with \`npm\`:
@@ -52,9 +47,7 @@ Install the {{ clientDescriptiveName }} library for JavaScript with \`npm\`:
 \`\`\`bash
 npm install {{ clientPackageName }}
 \`\`\`
-{{/if}}
 
-{{#if azure}}
 {{#if addCredentials}}
 ### Create and authenticate a \`{{ clientClassName}}\`
 
@@ -129,7 +122,8 @@ const credential = new InteractiveBrowserCredential({
 const client = new {{ clientClassName }}("<endpoint>", credential);
 \`\`\`
 {{/if}}
-{{/if}}{{/if}}
+{{/if}}
+
 
 ### JavaScript Bundle
 To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our [bundling documentation](https://aka.ms/AzureSDKBundling).
@@ -140,7 +134,6 @@ To use this client library in the browser, first you need to use a bundler. For
 
 \`{{ clientClassName }}\` is the primary interface for developers using the {{ clientDescriptiveName }} library. Explore the methods on this client object to understand the different features of the {{ serviceName }} service that you can access.
 
-{{#if azure}}
 ## Troubleshooting
 
 ### Logging
@@ -153,7 +146,7 @@ import { setLogLevel } from "@azure/logger";
 setLogLevel("info");
 \`\`\`
 
-For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs]({{ repoURL }}/tree/main/sdk/core/logger).
+For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger).
 
 {{#if samplesURL}}
 ## Next steps
@@ -163,54 +156,16 @@ Please take a look at the [samples]({{ samplesURL }}) directory for detailed exa
 
 ## Contributing
 
-If you'd like to contribute to this library, please read the [contributing guide]({{ contributingGuideURL }}) to learn more about how to build and test the code.
+If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code.
 
 ## Related projects
 
-- [{{ projectName }}]({{ repoURL }})
+- [Microsoft Azure SDK for JavaScript](https://github.com/Azure/azure-sdk-for-js)
 
 [azure_sub]: https://azure.microsoft.com/free/
 [azure_portal]: https://portal.azure.com
-{{#if identityPackageURL}}[azure_identity]: {{ identityPackageURL }}
-{{/if}}[defaultazurecredential]: {{ identityPackageURL }}#defaultazurecredential
-{{/if}}
-`;
-
-const nonBrandedReadmeTemplate = `# {{ clientDescriptiveName }} library for JavaScript
-
-{{ description }}
-
-Key links:
-
-{{#if packageSourceURL}}
-- [Source code]({{ packageSourceURL }})
-{{/if}}
-{{#if packageNPMURL}}
-- [Package (NPM)]({{ packageNPMURL }})
-{{/if}}
-{{#if apiRefURL}}
-- [API reference documentation]({{ apiRefURL }})
-{{/if}}
-{{#if serviceDocURL}}
-- [Product documentation]({{ serviceDocURL }})
-{{/if}}
-{{#if samplesURL}}
-- [Samples]({{ samplesURL }})
-{{/if}}
-
-## Getting started
-
-### Currently supported environments
-
-- LTS versions of Node.js
-
-### Install the \`{{ clientPackageName }}\` package
-
-Install the {{ clientDescriptiveName }} library for JavaScript with \`npm\`:
-
-\`\`\`bash
-npm install {{ clientPackageName }}
-\`\`\`
+[azure_identity]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity
+[defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#defaultazurecredential
 `;
 
 const apiReferenceTemplate = `{{#if apiRefURL}}
@@ -228,8 +183,6 @@ interface Metadata {
   clientPackageName: string;
   /** The name of the client class */
   clientClassName: string;
-  /** The URL of the repository the package lives in */
-  repoURL?: string;
   /** The URL to the package directory in the repository */
   packageSourceURL?: string;
   /** The URL to the package's samples */
@@ -240,29 +193,12 @@ interface Metadata {
   description?: string;
   /** The URL to the package on npmjs.org */
   packageNPMURL?: string;
-  /** The name of the project that lives in the repository */
-  projectName?: string;
   /** whether the client accepts standard credentials */
   addCredentials?: boolean;
-  /** The link to the identity package in the repository */
-  identityPackageURL?: string;
-  /** The URL for the service document */
-  serviceDocURL?: string;
-  /** The dependency info for this service */
-  dependencyDescription?: string;
-  dependencyLink?: string;
-  /** Indicates if the package is a multi-client */
-  hasMultiClients?: boolean;
   /** The URL to the API reference */
   apiRefURL?: string;
   /** Check if the rp is management plane */
   azureArm?: boolean;
-  /** Whether the package being generated is for an Azure service */
-  azure: boolean;
-  /** Indicates if the package is a test/releasable package. */
-  isReleasablePackage?: boolean;
-  /** The link to the contributing guide in the repository */
-  contributingGuideURL?: string;
   /** Indicates if the package need generate test files */
   generateTest?: boolean;
   /** Indicates if the package need SubscriptionId as the client parameter */
@@ -271,13 +207,10 @@ interface Metadata {
 
 export function buildReadmeFile(model: ClientModel) {
   const metadata = createMetadata(model) ?? {};
-  const readmeFileContents = hbs.compile(
-    model.options ? azureReadmeModularTemplate : nonBrandedReadmeTemplate,
-    { noEscape: true },
-  );
+  const content = renderTemplate(azureReadmeModularTemplate, metadata as Record<string, unknown>);
   return {
     path: "README.md",
-    content: readmeFileContents(metadata),
+    content,
   };
 }
 
@@ -301,7 +234,10 @@ export function updateReadmeFile(
   try {
     const metadata = createMetadata(model) ?? {};
 
-    const newApiRefLink = hbs.compile(apiReferenceTemplate, { noEscape: true })(metadata).trim();
+    const newApiRefLink = renderTemplate(
+      apiReferenceTemplate,
+      metadata as Record<string, unknown>,
+    ).trim();
 
     if (!newApiRefLink) {
       return { path: "README.md", content: existingReadmeContent };
@@ -329,14 +265,12 @@ function createMetadata(model: ClientModel): Metadata | undefined {
     return;
   }
   // const packageDetails = model.options.packageDetails;
-  const { packageDetails, azureOutputDirectory, serviceInfo, isTypeSpecTest } = model.options;
+  const { packageDetails, azureOutputDirectory, serviceInfo } = model.options;
 
-  const azureHuh =
-    packageDetails?.scopeName === "azure" || packageDetails?.scopeName === "azure-rest";
   const repoURL = "https://github.com/Azure/azure-sdk-for-js";
   const relativePackageSourcePath = azureOutputDirectory;
   const packageSourceURL =
-    relativePackageSourcePath && repoURL && `${repoURL}/tree/main/${relativePackageSourcePath}`;
+    relativePackageSourcePath && `${repoURL}/tree/main/${relativePackageSourcePath}`;
 
   const clientPackageName = packageDetails?.name;
   const clientClassName = getClientName(model);
@@ -363,17 +297,9 @@ function createMetadata(model: ClientModel): Metadata | undefined {
     packageNPMURL: `https://www.npmjs.com/package/${clientPackageName}`,
     samplesURL:
       model.options.generateSample && packageSourceURL ? `${packageSourceURL}/samples` : undefined,
-    apiRefURL: azureHuh
-      ? `https://learn.microsoft.com/javascript/api/${clientPackageName}${apiRefUrlQueryParameter}`
-      : undefined,
+    apiRefURL: `https://learn.microsoft.com/javascript/api/${clientPackageName}${apiRefUrlQueryParameter}`,
     azureArm: Boolean(model.options.azureArm),
-    azure: azureHuh,
-    isReleasablePackage: !isTypeSpecTest,
-    repoURL: repoURL,
-    projectName: azureHuh ? "Microsoft Azure SDK for JavaScript" : undefined,
-    identityPackageURL: repoURL && `${repoURL}/tree/main/sdk/identity/identity`,
     addCredentials: model.options.addCredentials,
-    contributingGuideURL: repoURL && `${repoURL}/blob/main/CONTRIBUTING.md`,
     generateTest: model.options.generateTest,
     hasSubscriptionId: model.options.hasSubscriptionId,
   };

package/src/metadata/render-template.ts

@@ -0,0 +1,202 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+/**
+ * A tiny, dependency-free renderer for the small subset of Handlebars/Mustache
+ * syntax used by the emitter's metadata templates. It intentionally supports only
+ * what those templates need:
+ *
+ * - `{{ name }}` interpolation (always "unescaped", matching the previous
+ *   `{ noEscape: true }` Handlebars option).
+ * - `{{#if name}} ... {{else}} ... {{/if}}` conditional blocks (nesting allowed).
+ *
+ * It reproduces Handlebars' "standalone" whitespace handling so that a block tag
+ * occupying its own line does not leave a blank line behind, keeping the rendered
+ * output byte-for-byte identical to the previous Handlebars-based implementation.
+ */
+
+type TemplateData = Record<string, unknown>;
+
+interface TextToken {
+  kind: "text";
+  value: string;
+}
+
+interface TagToken {
+  kind: "open" | "else" | "close" | "var";
+  /** Condition (for `open`) or variable name (for `var`). */
+  name: string;
+  /** Whether this block tag stands alone on its line (Handlebars semantics). */
+  standalone: boolean;
+}
+
+type Token = TextToken | TagToken;
+
+const MUSTACHE = /\{\{([^}]*)\}\}/g;
+
+function tokenize(template: string): Token[] {
+  const tokens: Token[] = [];
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+  MUSTACHE.lastIndex = 0;
+  while ((match = MUSTACHE.exec(template)) !== null) {
+    tokens.push({ kind: "text", value: template.slice(lastIndex, match.index) });
+    const inner = match[1]!.trim();
+    if (inner.startsWith("#if ")) {
+      tokens.push({ kind: "open", name: inner.slice(4).trim(), standalone: false });
+    } else if (inner === "else") {
+      tokens.push({ kind: "else", name: "", standalone: false });
+    } else if (inner === "/if") {
+      tokens.push({ kind: "close", name: "", standalone: false });
+    } else {
+      tokens.push({ kind: "var", name: inner, standalone: false });
+    }
+    lastIndex = match.index + match[0].length;
+  }
+  tokens.push({ kind: "text", value: template.slice(lastIndex) });
+  return tokens;
+}
+
+/**
+ * Applies Handlebars "standalone" whitespace stripping. A block tag (`#if`,
+ * `else`, `/if`) that is the only non-whitespace content on its line has the
+ * surrounding indentation and trailing newline removed.
+ */
+function stripStandaloneWhitespace(tokens: Token[]): void {
+  const isBlock = (t: Token): t is TagToken =>
+    t.kind === "open" || t.kind === "else" || t.kind === "close";
+
+  // First pass: detect standalone tags from the original text tokens.
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (!isBlock(token)) {
+      continue;
+    }
+    const prev = tokens[i - 1] as TextToken | undefined;
+    const next = tokens[i + 1] as TextToken | undefined;
+    const prevIsFirst = i - 1 === 0;
+    const nextIsLast = i + 1 === tokens.length - 1;
+
+    const prevValue = prev?.value ?? "";
+    const nextValue = next?.value ?? "";
+
+    const prevStandalone =
+      /\n[ \t]*$/.test(prevValue) || (prevIsFirst && /^[ \t]*$/.test(prevValue));
+    const nextStandalone =
+      /^[ \t]*\n/.test(nextValue) || (nextIsLast && /^[ \t]*$/.test(nextValue));
+
+    token.standalone = prevStandalone && nextStandalone;
+  }
+
+  // Second pass: strip whitespace around standalone tags.
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i]!;
+    if (!isBlock(token) || !token.standalone) {
+      continue;
+    }
+    const prev = tokens[i - 1] as TextToken | undefined;
+    const next = tokens[i + 1] as TextToken | undefined;
+    if (prev) {
+      // Drop the indentation preceding the tag, keeping the previous newline.
+      prev.value = prev.value.replace(/[ \t]*$/, "");
+    }
+    if (next) {
+      // Drop the rest of the tag's line, including its trailing newline.
+      next.value = /^[ \t]*\n/.test(next.value)
+        ? next.value.replace(/^[ \t]*\n/, "")
+        : next.value.replace(/^[ \t]*$/, "");
+    }
+  }
+}
+
+type Node = TextNode | VarNode | IfNode;
+interface TextNode {
+  kind: "text";
+  value: string;
+}
+interface VarNode {
+  kind: "var";
+  name: string;
+}
+interface IfNode {
+  kind: "if";
+  condition: string;
+  whenTrue: Node[];
+  whenFalse: Node[];
+}
+
+function parse(tokens: Token[], start: number, stopKinds: Token["kind"][]): [Node[], number] {
+  const nodes: Node[] = [];
+  let i = start;
+  while (i < tokens.length) {
+    const token = tokens[i]!;
+    if (token.kind === "text") {
+      if (token.value) {
+        nodes.push({ kind: "text", value: token.value });
+      }
+      i++;
+    } else if (token.kind === "var") {
+      nodes.push({ kind: "var", name: token.name });
+      i++;
+    } else if (token.kind === "open") {
+      const [whenTrue, afterTrue] = parse(tokens, i + 1, ["else", "close"]);
+      let whenFalse: Node[] = [];
+      let next = afterTrue;
+      if (tokens[next]?.kind === "else") {
+        const [elseNodes, afterElse] = parse(tokens, next + 1, ["close"]);
+        whenFalse = elseNodes;
+        next = afterElse;
+      }
+      // `next` now points at the matching `close` token.
+      nodes.push({ kind: "if", condition: token.name, whenTrue, whenFalse });
+      i = next + 1;
+    } else if (stopKinds.includes(token.kind)) {
+      return [nodes, i];
+    } else {
+      // Unmatched `else`/`close`; skip defensively.
+      i++;
+    }
+  }
+  return [nodes, i];
+}
+
+function isTruthy(value: unknown): boolean {
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  return Boolean(value);
+}
+
+function renderNodes(nodes: Node[], data: TemplateData): string {
+  let out = "";
+  for (const node of nodes) {
+    switch (node.kind) {
+      case "text":
+        out += node.value;
+        break;
+      case "var": {
+        const value = data[node.name];
+        out += value === undefined || value === null ? "" : String(value);
+        break;
+      }
+      case "if":
+        out += renderNodes(isTruthy(data[node.condition]) ? node.whenTrue : node.whenFalse, data);
+        break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Renders a metadata template against the provided data.
+ *
+ * @param template - Template using the supported `{{var}}` / `{{#if}}` subset.
+ * @param data - Values referenced by the template.
+ * @returns The rendered string.
+ */
+export function renderTemplate(template: string, data: TemplateData): string {
+  const tokens = tokenize(template);
+  stripStandaloneWhitespace(tokens);
+  const [nodes] = parse(tokens, 0, []);
+  return renderNodes(nodes, data);
+}