Fix description extraction to respect blank line separation (#16)

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: tonyfromundefined

.changeset/puny-places-change.md

@@ -0,0 +1,7 @@
+---
+"urlspec-vscode-extension": patch
+"@urlspec/language": patch
+"@urlspec/builder": patch
+---
+
+fix: seperate page description when new line inserted between

packages/language/src/cst-utils.ts

@@ -2,10 +2,11 @@
  * CST utilities for extracting metadata from Concrete Syntax Tree nodes
  */
 
-import type { AstNode } from "langium";
+import type { AstNode, LeafCstNode } from "langium";
 
 /**
- * Extract description from comments preceding an AST node
+ * Extract description from comments preceding an AST node.
+ * Stops at a blank line between comment blocks.
  */
 export function extractDescription(node: AstNode): string | undefined {
   const cstNode = node.$cstNode;
@@ -16,24 +17,35 @@ export function extractDescription(node: AstNode): string | undefined {
   const currentIndex = children.indexOf(cstNode);
   const comments: string[] = [];
 
-  // Look at previous siblings only at the immediate level
-  let foundNonWhitespace = false;
+  // nextCommentLine tracks the start line of the most recently collected
+  // comment (the one closest to the node). We use it to detect blank lines
+  // between comment groups: if the gap between two adjacent SL_COMMENTs is
+  // more than 1 line, there is a blank line between them and we stop.
+  let nextCommentLine: number | undefined;
+
   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();
+    const sibling = children[i] as LeafCstNode | { tokenType: undefined };
+    if (!("tokenType" in sibling) || sibling.tokenType === undefined) {
+      // Composite node (another declaration) — stop
+      break;
+    }
+    if (sibling.tokenType.name === "SL_COMMENT") {
+      const leaf = sibling as LeafCstNode;
+      // If there is a blank line between this comment and the next one
+      // we already collected, stop before including this comment.
+      if (
+        nextCommentLine !== undefined &&
+        nextCommentLine - leaf.range.end.line > 1
+      ) {
+        break;
+      }
+      const commentText = leaf.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;
+      nextCommentLine = leaf.range.start.line;
     }
+    // WS tokens are not present in container.content, so no else branch needed
   }
 
   return comments.length > 0 ? comments.join("\n") : undefined;

packages/language/test/fixtures/section-comment-separation.urlspec

@@ -0,0 +1,13 @@
+// =============================================
+// 에스크로 (Escrow)
+// =============================================
+
+// 에스크로 결제 주문 페이지
+page escrowPaymentOrder = /escrow/payment {
+  channelId: string;
+  amount: string;
+}
+
+page noDescription = /no-desc {
+  channelId: string;
+}

packages/language/test/resolver.test.ts

@@ -164,4 +164,11 @@ describe("URLSpec Resolver", () => {
       "Status of a job posting",
     );
   });
+
+  it("should not include section header comment separated by blank line", async () => {
+    const doc = await parseFile(fixture("section-comment-separation.urlspec"));
+    const spec = resolve(doc);
+    expect(spec.pages[0]?.description).toBe("에스크로 결제 주문 페이지");
+    expect(spec.pages[1]?.description).toBeUndefined();
+  });
 });