Enhance YAML script formatting with intelligent detection of shell patterns and improved handling for script-related properties

Author: noxify

.changeset/script-formatting-improvement.md

@@ -0,0 +1,14 @@
+---
+"@noxify/gitlab-ci-builder": patch
+---
+
+Improve script formatting in YAML import with intelligent detection of shell operators.
+
+The import now intelligently formats `script`, `before_script`, and `after_script` properties:
+
+- **Simple multi-line commands** → Split into string array for better readability
+- **Line continuations** (`\`) → Preserved as template literals
+- **Shell operators** (heredoc `<<`, pipes `|`, redirects `>`, `>>`, `2>`, `<`) → Preserved as template literals
+- **Single-line commands** → Formatted as simple strings
+
+This produces more idiomatic and readable TypeScript code while preserving shell command semantics.

src/import.ts

@@ -126,6 +126,59 @@ export function fromYaml(yamlContent: string): string {
   return lines.join("\n")
 }
 
+/**
+ * Format script values (script, before_script, after_script) intelligently.
+ *
+ * Detects shell-specific patterns and formats accordingly:
+ * - Line continuations (\) → Template literal
+ * - Heredoc (<<) → Template literal
+ * - Shell operators (|, >, >>, 2>, &>, <) → Template literal
+ * - Simple multi-line commands → Array of strings
+ * - Single line → String
+ */
+function formatScriptValue(value: unknown): string {
+  if (typeof value !== "string") {
+    return formatValue(value, 0)
+  }
+
+  // Single line without special characters
+  if (!value.includes("\n")) {
+    return JSON.stringify(value)
+  }
+
+  // Check for shell-specific patterns that require keeping as single string
+  const shellOperatorPatterns = [
+    /\\\n/, // Line continuation
+    /<</, // Heredoc
+    /(?<!\|)\|(?!\|)/, // Pipe (but not ||) - negative lookbehind and lookahead
+    />>?/, // Redirect output
+    /2>/, // Redirect stderr
+    /&>/, // Redirect both
+    /(?<!<)<(?!<)/, // Redirect input (but not <<) - negative lookbehind and lookahead
+  ]
+
+  const hasShellOperators = shellOperatorPatterns.some((pattern) => pattern.test(value))
+
+  if (hasShellOperators) {
+    // Keep as template literal to preserve exact formatting
+    // Escape backticks and ${} in the string
+    const escaped = value.replace(/`/g, "\\`").replace(/\$\{/g, "\\${")
+    return `\`${escaped}\``
+  }
+
+  // Simple multi-line without shell operators - split into array
+  const lines = value
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+
+  if (lines.length === 1) {
+    return JSON.stringify(lines[0])
+  }
+
+  return `[${lines.map((l) => JSON.stringify(l)).join(", ")}]`
+}
+
 /**
  * Format a value as TypeScript code with proper indentation.
  */
@@ -178,6 +231,17 @@ function formatValue(value: unknown, indentLevel: number): string {
     const props = entries.map(([k, v]) => {
       const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k) ? k : JSON.stringify(k)
 
+      // Special handling for script-related properties
+      const scriptProperties = ["script", "before_script", "after_script"]
+      if (scriptProperties.includes(k)) {
+        // For script arrays, format each element intelligently
+        if (Array.isArray(v)) {
+          const formattedScripts = v.map((item) => formatScriptValue(item))
+          return `${indent}${key}: [${formattedScripts.join(", ")}]`
+        }
+        return `${indent}${key}: ${formatScriptValue(v)}`
+      }
+
       // Special handling for properties that should be strings but might be single-element arrays
       // These properties accept string | string[] but single values are more common
       const singleValueProperties = ["extends", "annotations", "dotenv"]

tests/script-formatting.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it } from "vitest"
+
+import { fromYaml } from "../src/import"
+
+describe("Script formatting", () => {
+  it("should format simple single-line script as string", () => {
+    const yaml = `
+test:
+  script:
+    - echo "hello world"
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain('script: ["echo \\"hello world\\""]')
+  })
+
+  it("should format simple multi-line commands as array", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      echo "step1"
+      echo "step2"
+      echo "step3"
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain(
+      'script: [["echo \\"step1\\"", "echo \\"step2\\"", "echo \\"step3\\""]]',
+    )
+  })
+
+  it("should preserve line continuation with backslash as template literal", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      apk update && \\
+          apk add --no-cache libc6-compat aws-cli jq && \\
+          rm -rf /var/cache/apk/*
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("script: [`apk update")
+    expect(result).toContain("apk add --no-cache")
+    expect(result).toContain("rm -rf /var/cache/apk/*")
+    expect(result).toContain("`]")
+  })
+
+  it("should preserve heredoc as template literal", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      cat <<EOF
+      line1
+      line2
+      EOF
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("script: [`cat <<EOF")
+    expect(result).toContain("line1")
+    expect(result).toContain("line2")
+    expect(result).toContain("EOF")
+    expect(result).toContain("`]")
+  })
+
+  it("should preserve pipe operators as template literal", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      cat file.txt | grep "pattern" | sort
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain('script: [`cat file.txt | grep "pattern" | sort')
+    expect(result).toContain("`]")
+  })
+
+  it("should preserve output redirection as template literal", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      echo "output" > file.txt
+      echo "append" >> file.txt
+      command 2> error.log
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("script: [`echo")
+    expect(result).toContain("> file.txt")
+    expect(result).toContain(">> file.txt")
+    expect(result).toContain("2> error.log")
+    expect(result).toContain("`]")
+  })
+
+  it("should handle mixed script array with different formats", () => {
+    const yaml = `
+test:
+  script:
+    - echo "simple"
+    - |
+      echo "multi1"
+      echo "multi2"
+    - |
+      complex && \\
+          continuation
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain('script: ["echo \\"simple\\"",')
+    expect(result).toContain('["echo \\"multi1\\"", "echo \\"multi2\\""]')
+    expect(result).toContain("`complex")
+  })
+
+  it("should handle before_script with shell operators", () => {
+    const yaml = `
+test:
+  before_script:
+    - |
+      mkdir ~/.npm-global
+      export PATH=$PATH:~/.npm-global/bin
+      npm i -g [email protected]
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("before_script:")
+    expect(result).toContain('["mkdir ~/.npm-global", "export PATH=$PATH:~/.npm-global/bin"')
+  })
+
+  it("should handle after_script with continuations", () => {
+    const yaml = `
+test:
+  after_script:
+    - |
+      cleanup && \\
+          remove_temp
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("after_script: [`cleanup")
+    expect(result).toContain("remove_temp")
+    expect(result).toContain("`]")
+  })
+
+  it("should handle logical operators correctly", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      command1 || echo "fallback"
+      command2 && echo "success"
+`
+    const result = fromYaml(yaml)
+    // || and && are logical operators, not pipes - should be split into array
+    expect(result).toContain(
+      '["command1 || echo \\"fallback\\"", "command2 && echo \\"success\\""]',
+    )
+  })
+
+  it("should escape backticks in template literals", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      echo \`date\` > file.txt
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("\\`date\\`")
+  })
+
+  it("should escape template expressions in template literals", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      echo "\${VAR}" > file.txt
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("\\${VAR}")
+  })
+
+  it("should handle empty lines in multiline scripts", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      echo "line1"
+
+      echo "line2"
+`
+    const result = fromYaml(yaml)
+    // Empty lines should be filtered out when splitting
+    expect(result).toContain('["echo \\"line1\\"", "echo \\"line2\\""]')
+  })
+
+  it("should handle input redirection", () => {
+    const yaml = `
+test:
+  script:
+    - |
+      command < input.txt
+`
+    const result = fromYaml(yaml)
+    expect(result).toContain("`command < input.txt")
+    expect(result).toContain("`]")
+  })
+})