Support description comments in printer and builder (#11)

jongwooha98 · claude · web-flow · commit d88f56ee8e2c · 2026-03-09T23:12:55.000+09:00
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/packages/builder/src/index.ts b/packages/builder/src/index.ts
@@ -58,6 +58,7 @@ export interface ParameterDefinition {
   name: string;
   type: ParamType;
   optional?: boolean;
+  comment?: string;
 }
 
 export interface PageDefinition {
@@ -71,15 +72,16 @@ export interface PageDefinition {
  * URLSpec builder class for programmatic generation of .urlspec files
  */
 export class URLSpec {
-  private paramTypes: Map<string, ParamType> = new Map();
+  private paramTypes: Map<string, { type: ParamType; comment?: string }> =
+    new Map();
   private globalParams: ParameterDefinition[] = [];
   private pages: PageDefinition[] = [];
 
   /**
    * Add a parameter type definition
    */
-  addParamType(name: string, type: ParamType): void {
-    this.paramTypes.set(name, type);
+  addParamType(name: string, type: ParamType, comment?: string): void {
+    this.paramTypes.set(name, { type, comment });
   }
 
   /**
@@ -102,8 +104,10 @@ export class URLSpec {
   toAST(): URLSpecDocument {
     // Build param types
     const paramTypes: ParamTypeDeclaration[] = [];
-    for (const [name, type] of this.paramTypes.entries()) {
-      paramTypes.push(createParamTypeDeclaration(name, this.buildType(type)));
+    for (const [name, { type, comment }] of this.paramTypes.entries()) {
+      paramTypes.push(
+        createParamTypeDeclaration(name, this.buildType(type), comment),
+      );
     }
 
     // Build global block
@@ -121,6 +125,7 @@ export class URLSpec {
         page.name,
         page.path,
         page.parameters?.map((p) => this.buildParameter(p)),
+        page.comment,
       ),
     );
 
@@ -220,6 +225,7 @@ export class URLSpec {
       param.name,
       this.buildType(param.type),
       param.optional,
+      param.comment,
     );
   }
 }
diff --git a/packages/builder/test/builder.test.ts b/packages/builder/test/builder.test.ts
@@ -128,6 +128,66 @@ describe("URLSpec Builder", () => {
     expect(result).toContain("page rejectedList = /jobs/rejected");
   });
 
+  describe("Comment/Description Support", () => {
+    it("should output page comments", () => {
+      const spec = new URLSpec();
+      spec.addPage({
+        name: "list",
+        path: "/jobs",
+        comment: "Job listing page",
+      });
+      const result = spec.toString();
+      expect(result).toContain("// Job listing page");
+      expect(result).toContain("page list = /jobs {");
+    });
+
+    it("should output parameter comments", () => {
+      const spec = new URLSpec();
+      spec.addPage({
+        name: "list",
+        path: "/jobs",
+        parameters: [
+          { name: "sort", type: "string", comment: "Sort order" },
+        ],
+      });
+      const result = spec.toString();
+      expect(result).toContain("  // Sort order");
+      expect(result).toContain("  sort: string;");
+    });
+
+    it("should output param type comments", () => {
+      const spec = new URLSpec();
+      spec.addParamType("sortOrder", ["recent", "popular"], "Available sort orders");
+      spec.addPage({ name: "list", path: "/jobs" });
+      const result = spec.toString();
+      expect(result).toContain("// Available sort orders");
+    });
+
+    it("should output global parameter comments", () => {
+      const spec = new URLSpec();
+      spec.addGlobalParam({
+        name: "utm_source",
+        type: "string",
+        optional: true,
+        comment: "UTM source tracking",
+      });
+      spec.addPage({ name: "list", path: "/jobs" });
+      const result = spec.toString();
+      expect(result).toContain("  // UTM source tracking");
+    });
+
+    it("should output multi-line comments", () => {
+      const spec = new URLSpec();
+      spec.addPage({
+        name: "list",
+        path: "/jobs",
+        comment: "Job listing page\nDisplays all available jobs",
+      });
+      const result = spec.toString();
+      expect(result).toContain("// Job listing page\n// Displays all available jobs");
+    });
+  });
+
   describe("Security - Path Traversal Prevention", () => {
     it("should reject paths with .. traversal sequences", async () => {
       const spec = new URLSpec();
diff --git a/packages/language/src/ast-builder.ts b/packages/language/src/ast-builder.ts
@@ -65,12 +65,17 @@ export function createTypeReference(refName: string): TypeReference {
 export function createParamTypeDeclaration(
   name: string,
   type: Type,
+  description?: string,
 ): ParamTypeDeclaration {
-  return {
+  const node = {
     $type: "ParamTypeDeclaration",
     name,
     type,
   } as ParamTypeDeclaration;
+  if (description) {
+    (node as any).$description = description;
+  }
+  return node;
 }
 
 /**
@@ -80,13 +85,18 @@ export function createParameterDeclaration(
   name: string,
   type: Type,
   optional?: boolean,
+  description?: string,
 ): ParameterDeclaration {
-  return {
+  const node = {
     $type: "ParameterDeclaration",
     name,
     type,
     optional: optional ? "?" : undefined,
   } as ParameterDeclaration;
+  if (description) {
+    (node as any).$description = description;
+  }
+  return node;
 }
 
 /**
@@ -152,13 +162,18 @@ export function createPageDeclaration(
   name: string,
   pathStr: string,
   parameters?: ParameterDeclaration[],
+  description?: string,
 ): PageDeclaration {
-  return {
+  const node = {
     $type: "PageDeclaration",
     name,
     path: parsePath(pathStr),
     parameters: parameters || [],
   } as PageDeclaration;
+  if (description) {
+    (node as any).$description = description;
+  }
+  return node;
 }
 
 /**
diff --git a/packages/language/src/cst-utils.ts b/packages/language/src/cst-utils.ts
@@ -0,0 +1,40 @@
+/**
+ * CST utilities for extracting metadata from Concrete Syntax Tree nodes
+ */
+
+import type { AstNode } from "langium";
+
+/**
+ * Extract description from comments preceding an AST node
+ */
+export function extractDescription(node: AstNode): string | undefined {
+  const cstNode = node.$cstNode;
+  if (!cstNode?.container) return undefined;
+
+  const container = cstNode.container;
+  const children = container.content;
+  const currentIndex = children.indexOf(cstNode);
+  const comments: string[] = [];
+
+  // Look at previous siblings only at the immediate level
+  let foundNonWhitespace = false;
+  for (let i = currentIndex - 1; i >= 0; i--) {
+    const sibling = children[i];
+    if (sibling.tokenType?.name === "SL_COMMENT") {
+      const commentText = sibling.text.replace(/^\/\/\s*/, "").trim();
+      if (commentText) {
+        comments.unshift(commentText);
+      }
+      foundNonWhitespace = true;
+    } else if (sibling.tokenType?.name === "WS") {
+      const newlineCount = (sibling.text.match(/\n/g) || []).length;
+      if (newlineCount > 1 && foundNonWhitespace) {
+        break;
+      }
+    } else {
+      break;
+    }
+  }
+
+  return comments.length > 0 ? comments.join("\n") : undefined;
+}
diff --git a/packages/language/src/index.ts b/packages/language/src/index.ts
@@ -24,6 +24,9 @@ export type {
   ResolvedURLSpec,
 } from "./resolved-types";
 
+// Export CST utilities
+export { extractDescription } from "./cst-utils";
+
 // Export resolver
 export { resolve } from "./resolver";
 
diff --git a/packages/language/src/printer.ts b/packages/language/src/printer.ts
@@ -1,4 +1,4 @@
-import type { LangiumDocument } from "langium";
+import type { AstNode, LangiumDocument } from "langium";
 import type {
   PageDeclaration,
   ParameterDeclaration,
@@ -10,6 +10,24 @@ import type {
   UnionType,
   URLSpecDocument,
 } from "./__generated__/ast";
+import { extractDescription } from "./cst-utils";
+
+/**
+ * Get description from a node: check $description (builder) or CST (parsed)
+ */
+function getDescription(node: AstNode): string | undefined {
+  const builderDesc = (node as any).$description;
+  if (builderDesc) return builderDesc;
+  return extractDescription(node);
+}
+
+/**
+ * Convert a description string into formatted comment lines
+ */
+function descriptionLines(desc: string | undefined, indent: string): string[] {
+  if (!desc) return [];
+  return desc.split("\n").map((line) => `${indent}// ${line}`);
+}
 
 /**
  * Print Langium AST back to .urlspec format
@@ -21,6 +39,7 @@ export function print(doc: LangiumDocument<URLSpecDocument>): string {
   // Param types
   if (model.paramTypes.length > 0) {
     for (const paramType of model.paramTypes) {
+      lines.push(...descriptionLines(getDescription(paramType), ""));
       lines.push(`param ${paramType.name} = ${printType(paramType.type)};`);
     }
     lines.push("");
@@ -30,6 +49,7 @@ export function print(doc: LangiumDocument<URLSpecDocument>): string {
   if (model.global) {
     lines.push("global {");
     for (const param of model.global.parameters) {
+      lines.push(...descriptionLines(getDescription(param), "  "));
       lines.push(`  ${printParameter(param)}`);
     }
     lines.push("}");
@@ -38,6 +58,7 @@ export function print(doc: LangiumDocument<URLSpecDocument>): string {
 
   // Pages
   for (const page of model.pages) {
+    lines.push(...descriptionLines(getDescription(page), ""));
     lines.push(printPage(page));
     lines.push("");
   }
@@ -54,6 +75,7 @@ function printPage(page: PageDeclaration): string {
   lines.push(`page ${page.name} = ${path} {`);
 
   for (const param of page.parameters) {
+    lines.push(...descriptionLines(getDescription(param), "  "));
     lines.push(`  ${printParameter(param)}`);
   }
 
diff --git a/packages/language/src/resolver.ts b/packages/language/src/resolver.ts
@@ -1,4 +1,4 @@
-import type { AstNode, LangiumDocument } from "langium";
+import type { LangiumDocument } from "langium";
 import type {
   PageDeclaration,
   ParameterDeclaration,
@@ -9,6 +9,7 @@ import type {
   UnionType,
   URLSpecDocument,
 } from "./__generated__/ast";
+import { extractDescription } from "./cst-utils";
 import type {
   ResolvedPage,
   ResolvedParameter,
@@ -18,41 +19,6 @@ import type {
   ResolvedURLSpec,
 } from "./resolved-types";
 
-/**
- * Extract description from comments preceding an AST node
- */
-function extractDescription(node: AstNode): string | undefined {
-  const cstNode = node.$cstNode;
-  if (!cstNode?.container) return undefined;
-
-  const container = cstNode.container;
-  const children = container.content;
-  const currentIndex = children.indexOf(cstNode);
-  const comments: string[] = [];
-
-  // Look at previous siblings only at the immediate level
-  let foundNonWhitespace = false;
-  for (let i = currentIndex - 1; i >= 0; i--) {
-    const sibling = children[i];
-    if (sibling.tokenType?.name === "SL_COMMENT") {
-      const commentText = sibling.text.replace(/^\/\/\s*/, "").trim();
-      if (commentText) {
-        comments.unshift(commentText);
-      }
-      foundNonWhitespace = true;
-    } else if (sibling.tokenType?.name === "WS") {
-      const newlineCount = (sibling.text.match(/\n/g) || []).length;
-      if (newlineCount > 1 && foundNonWhitespace) {
-        break;
-      }
-    } else {
-      break;
-    }
-  }
-
-  return comments.length > 0 ? comments.join("\n") : undefined;
-}
-
 /**
  * Resolve Langium AST to user-friendly ResolvedURLSpec
  * - Resolves type references to actual types
diff --git a/packages/language/test/printer.test.ts b/packages/language/test/printer.test.ts
