feat: improve visualization rendering with professional libraries

Author: noxify

.changeset/visualization-improvements.md

@@ -0,0 +1,10 @@
+---
+"@noxify/gitlab-ci-builder": minor
+---
+
+Improve visualization rendering with professional libraries
+
+- Replace custom ASCII tree rendering with `oo-ascii-tree` for better box-drawing characters
+- Replace custom table rendering with `climt` for professional CLI tables
+  - Change table layout from horizontal to vertical (Stage | Job columns)
+  - Display one job per row with full ext ends chains

README.md

@@ -473,20 +473,38 @@ console.log(mermaid)
 **Output:**
 
 ```mermaid
-graph TD
-  n0["build [build]"]:::job
-  n1[".base"]:::template
-  n2["test [test]"]:::job
-  n0 --> n1
-  n2 --> n1
+---
+config:
+  layout: elk
+---
+graph LR
   classDef template fill:#e1f5ff,stroke:#0366d6
   classDef job fill:#fff5e1,stroke:#fb8500
   classDef remote fill:#ffe1f5,stroke:#c026d3
+
+  subgraph Templates
+    n1[".build_template"]:::template
+    n2[".base"]:::template
+    n4[".test_template"]:::template
+  end
+
+  subgraph "build"
+    n0["build"]:::job
+  end
+
+  subgraph "test"
+    n3["test"]:::job
+  end
+
+  n0 --> n1
+  n1 --> n2
+  n3 --> n4
+  n4 --> n2
 ```
 
 #### ASCII Trees
 
-Generate hierarchical ASCII tree views of job inheritance:
+Generate hierarchical ASCII tree views of job inheritance using `oo-ascii-tree` for clean, professional box-drawing characters:
 
 ```ts
 const ascii = config.generateAsciiTree({
@@ -500,15 +518,19 @@ console.log(ascii)
 **Output:**
 
 ```
-└─ build (build)
-  └─ .base [T]
-└─ test (test)
-  └─ .base [T]
+build (build)
+ └─┬ .build_template [T]
+   └── .base [T]
+test (test)
+ └─┬ .test_template [T]
+   └── .base [T]
 ```
 
+The ASCII tree uses Unicode box-drawing characters for a clean, readable hierarchy that works great in terminal output and documentation.
+
 #### Stage Tables
 
-Generate tabular views showing jobs organized by stage:
+Generate formatted tables using `climt` showing jobs with their full inheritance chains:
 
 ```ts
 const table = config.generateStageTable({
@@ -521,11 +543,18 @@ console.log(table)
 **Output:**
 
 ```
-build         │ test         │ deploy
-──────────────┼──────────────┼─────────────
-build ← .base │ test ← .base │
+┌───────┬────────────────────────────────────────────┐
+│ STAGE │ JOB                                        │
+├───────┼────────────────────────────────────────────┤
+│ build │ build-frontend ← .build_template ← .base   │
+│ build │ build-backend ← .build_template ← .base    │
+│ test  │ test-unit ← .test_template ← .base         │
+│ test  │ test-e2e ← .test_template ← .base          │
+└───────┴────────────────────────────────────────────┘
 ```
 
+The table shows one job per row with its complete extends chain, making it easy to understand the full inheritance hierarchy at a glance.
+
 ### Visualization Options
 
 All visualization methods accept optional configuration:

package.json

@@ -52,9 +52,11 @@
   "prettier": "./prettier.config.mjs",
   "dependencies": {
     "@commander-js/extra-typings": "^14.0.0",
+    "climt": "^0.2.0",
     "commander": "^14.0.2",
     "deepmerge": "4.3.1",
     "js-yaml": "4.1.1",
+    "oo-ascii-tree": "^1.120.0",
     "read-pkg": "^10.0.0",
     "tinyglobby": "0.2.15",
     "typescript": "5.9.3",

pnpm-lock.yaml

@@ -82,6 +82,8 @@ Examples:
         if (result.mermaid) {
           // eslint-disable-next-line no-console
           console.log("\n=== Mermaid Diagram ===\n")
+          // eslint-disable-next-line no-console
+          console.log(result.mermaid)
         }
 
         if (result.ascii) {
@@ -99,7 +101,7 @@ Examples:
         }
       } catch (error) {
         // eslint-disable-next-line no-console
-        console.error("Error:", error instanceof Error ? error.message : String(error))
+        console.error("Error:", error)
         process.exit(1)
       }
     })

src/cli/commands/visualize.ts

@@ -1,11 +1,24 @@
 import yaml from "js-yaml"
 
 /**
- * Custom YAML type for !reference tags
- * Converts !reference [.template, script] to string literal
+ * Custom YAML type for !reference tags - String representation
+ * Converts !reference [.template, script] to string literal for TypeScript generation
  */
 export const referenceTag = new yaml.Type("!reference", {
   kind: "sequence",
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   construct: (data: unknown[]) => `!reference [${(data || []).join(", ")}]`,
 })
+
+/**
+ * Custom YAML type for !reference tags - Object representation
+ * Stores reference as an object with kind and path for resolution
+ */
+export const referenceTagResolvable = new yaml.Type("!reference", {
+  kind: "sequence",
+  construct: (data: unknown[]) => ({
+    kind: "reference",
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    path: data || [],
+  }),
+})

src/importer/yaml-parser/reference.ts

@@ -8,6 +8,8 @@ export interface ExtendsGraphNode {
   name: string
   definition: JobDefinitionNormalized
   extends: string[]
+  /** Original unresolved extends before include resolution */
+  unresolvedExtends?: string[]
   isTemplate: boolean
   isRemote: boolean
 }