Merge pull request #69 from caioricciuti/fix/project-bundle-format

Project export: marker lines in cells and comma tags round-trip

Author: caioricciuti

src/lib/projectBundle/__tests__/format.test.ts

@@ -51,10 +51,17 @@ describe("queries", () => {
     ["empty", query({ sql: "" })],
     ["header-like SQL", query({ sql: "-- name: not a header\nSELECT 1" })],
     ["folder", query({ folder: "team/finance" })],
+    ["tag with a comma", query({ tags: ["sales, weekly", "q4"] })],
+    ["tag that looks like JSON", query({ tags: ["[draft]", "b"] })],
   ])("round-trips %s", (_label, original) => {
     expect(parseQuery(serializeQuery(original), "fallback")).toEqual(original);
   });
 
+  it("writes a plain tag list unless a tag holds a comma", () => {
+    expect(serializeQuery(query({ tags: ["a", "b"] }))).toContain("-- tags: a, b\n");
+    expect(serializeQuery(query({ tags: ["a, b", "c"] }))).toContain('-- tags: ["a, b","c"]\n');
+  });
+
   it("reads hand-written files without a header", () => {
     expect(parseQuery("SELECT 42;\n", "answer")).toEqual(
       query({ name: "answer", sql: "SELECT 42;" })
@@ -104,6 +111,23 @@ describe("notebooks", () => {
     expect(parseNotebook(serializeNotebook(notebook), "fallback")).toEqual(notebook);
   });
 
+  it("round-trips a cell whose text contains a cell marker line", () => {
+    const tricky = {
+      title: "Markers",
+      cells: [
+        {
+          type: "markdown" as const,
+          content: "How cells are stored:\n<!-- cell:python -->\nthat line",
+        },
+        { type: "python" as const, content: "# <!-- cell:sql -->\n<!-- cell:sql collapsed -->" },
+        { type: "markdown" as const, content: "\\<!-- cell:markdown -->" },
+      ],
+    };
+    const text = serializeNotebook(tricky);
+    expect(text).toContain("\n\\<!-- cell:python -->\n");
+    expect(parseNotebook(text, "x")).toEqual(tricky);
+  });
+
   it("round-trips an empty notebook", () => {
     const empty = { title: "Empty", cells: [] };
     expect(parseNotebook(serializeNotebook(empty), "x")).toEqual(empty);

src/lib/projectBundle/format.ts

@@ -125,14 +125,40 @@ const oneLine = (text: string): string => text.replace(/\s*\n\s*/g, " ").trim();
 
 const HEADER_LINE = /^-- (name|description|tags|folder):(?: (.*))?$/;
 
+/** Either form the serializer writes: a JSON array, or names separated by commas. */
+function parseTags(value: string): string[] {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed: unknown = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) {
+        return parsed.map((tag) => String(tag).trim()).filter(Boolean);
+      }
+    } catch {
+      // Not JSON after all: a tag list that happens to start with a bracket.
+    }
+  }
+  return trimmed
+    .split(",")
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+}
+
 export function serializeQuery(query: BundleQuery): string {
   const header = [`-- name: ${oneLine(query.name)}`];
   if (query.description) {
     for (const line of normalizeNewlines(query.description).split("\n")) {
       header.push(line ? `-- description: ${line}` : "-- description:");
     }
   }
-  if (query.tags.length > 0) header.push(`-- tags: ${query.tags.map(oneLine).join(", ")}`);
+  if (query.tags.length > 0) {
+    // A comma inside a tag would read back as two tags, so such a list is
+    // written as JSON; the plain form stays for every other file.
+    const tags = query.tags.map(oneLine);
+    header.push(
+      `-- tags: ${tags.some((tag) => tag.includes(",")) ? JSON.stringify(tags) : tags.join(", ")}`
+    );
+  }
   if (query.folder && query.folder !== "default")
     header.push(`-- folder: ${oneLine(query.folder)}`);
   return withFinalNewline(`${header.join("\n")}\n\n${query.sql}`);
@@ -158,10 +184,7 @@ export function parseQuery(text: string, fallbackName: string): BundleQuery {
         description.push(value);
         break;
       case "tags":
-        tags = value
-          .split(",")
-          .map((tag) => tag.trim())
-          .filter(Boolean);
+        tags = parseTags(value);
         break;
       case "folder":
         folder = value.trim() || "default";
@@ -188,6 +211,29 @@ export function parseQuery(text: string, fallbackName: string): BundleQuery {
 
 const CELL_MARKER = /^<!-- cell:(sql|python|markdown)( collapsed)? -->$/;
 const CODE_FENCE_OPEN = /^(`{3,}|~{3,})\s*(sql|python|py)\b.*$/i;
+/** A content line that is a marker, or a marker already behind backslashes. */
+const MARKER_LIKE_LINE = /^(\\*)(<!-- cell:(?:sql|python|markdown)(?: collapsed)? -->)$/;
+
+/**
+ * A cell whose text contains a line that is exactly a cell marker would be
+ * cut in two on import. Such a line gets one more backslash in the file
+ * (so lines that already start with backslashes stay distinct), and
+ * `unescapeMarkers` takes one away. Files from before this never contain
+ * the escaped form, so they read as they always did.
+ */
+function escapeMarkers(content: string): string {
+  return content
+    .split("\n")
+    .map((line) => line.replace(MARKER_LIKE_LINE, "\\$1$2"))
+    .join("\n");
+}
+
+function unescapeMarkers(content: string): string {
+  return content
+    .split("\n")
+    .map((line) => (MARKER_LIKE_LINE.test(line) && line.startsWith("\\") ? line.slice(1) : line))
+    .join("\n");
+}
 
 type CodeCellType = "sql" | "python";
 
@@ -205,11 +251,12 @@ export function serializeNotebook(notebook: BundleNotebook): string {
   const parts = [`# ${oneLine(notebook.title) || "Untitled Notebook"}`];
   for (const cell of notebook.cells) {
     const marker = `<!-- cell:${cell.type}${cell.collapsed ? " collapsed" : ""} -->`;
+    const content = escapeMarkers(cell.content);
     if (cell.type === "sql" || cell.type === "python") {
-      const fence = fenceFor(cell.content);
-      parts.push(`${marker}\n${fence}${cell.type}\n${cell.content}\n${fence}`);
+      const fence = fenceFor(content);
+      parts.push(`${marker}\n${fence}${cell.type}\n${content}\n${fence}`);
     } else {
-      parts.push(`${marker}\n${cell.content}`);
+      parts.push(`${marker}\n${content}`);
     }
   }
   return withFinalNewline(parts.join("\n\n"));
@@ -273,7 +320,7 @@ export function parseNotebook(text: string, fallbackTitle: string): BundleNotebo
     const cellType = type === "sql" || type === "python" ? type : "markdown";
     return {
       type: cellType,
-      content: cellType === "markdown" ? body.join("\n") : parseCodeBody(body),
+      content: unescapeMarkers(cellType === "markdown" ? body.join("\n") : parseCodeBody(body)),
       ...(collapsed ? { collapsed: true } : {}),
     };
   });