fix import issues

Author: noxify

.changeset/floppy-ants-tell.md

@@ -0,0 +1,5 @@
+---
+"@noxify/gitlab-ci-builder": patch
+---
+
+exclude anchor definitions without a valid job definition

README.md

@@ -137,6 +137,89 @@ await importYamlFile(".gitlab-ci.yml", "gitlab-ci.config.ts")
 
 This enables easy migration from YAML to TypeScript-based configurations.
 
+#### YAML Anchor Handling & Extends
+
+The import functionality handles both GitLab CI's native `extends` keyword and YAML anchors/aliases:
+
+##### Using `extends` (Recommended)
+
+When your YAML uses GitLab's `extends` keyword, the import preserves the reference:
+
+```yaml
+.base:
+  image: node:22
+  tags:
+    - docker
+
+build:
+  extends: .base # GitLab CI extends
+  script:
+    - npm run build
+```
+
+Generated output uses `extends` property:
+
+```ts
+config.template(".base", {
+  image: "node:22",
+  tags: ["docker"],
+})
+
+config.job("build", {
+  extends: ".base", // Preserved!
+  script: ["npm run build"],
+})
+
+// Or use the extends() helper method:
+config.extends(".base", "build", {
+  script: ["npm run build"],
+})
+```
+
+Both approaches produce equivalent output. The `extends()` helper is more concise when you want to explicitly show the inheritance relationship.
+
+##### Using YAML Anchors & Merges
+
+When using YAML merge operators (`<<: *anchor`), values are resolved and inlined:
+
+- **Anchor definitions** (`&anchor_name`) containing only primitive values (arrays, strings) are filtered out
+- **References** (`*anchor_name`) and **merges** (`<<: *anchor_name`) are resolved by the YAML parser and inlined
+- Only anchor definitions that are valid job/template objects are included as templates
+
+```yaml
+.tags_test: &tags_test # Filtered out (array-only anchor)
+  - test1
+  - test2
+
+.base: &base_config # Included (valid template)
+  image: node:22
+  tags:
+    - docker
+
+build:
+  <<: *base_config # Values merged inline
+  tags: *tags_test # Reference resolved
+  script:
+    - npm run build
+```
+
+Generated output has resolved values:
+
+```ts
+config.template(".base", {
+  image: "node:22",
+  tags: ["docker"],
+})
+
+config.job("build", {
+  image: "node:22", // Inlined from .base
+  tags: ["test1", "test2"], // Resolved from .tags_test
+  script: ["npm run build"],
+})
+```
+
+**Recommendation:** Use GitLab's `extends` keyword instead of YAML merge operators to maintain clearer relationships in the generated TypeScript code.
+
 ## API Reference
 
 This reference summarizes the primary `Config` API surface. Method signatures reflect

pnpm-lock.yaml

@@ -91,8 +91,17 @@ export function fromYaml(yamlContent: string): string {
   }
 
   // Jobs (separate templates and regular jobs)
-  const templateKeys = Object.keys(jobs).filter((k) => k.startsWith("."))
-  const jobKeys = Object.keys(jobs).filter((k) => !k.startsWith("."))
+  // Filter out anchor-only definitions (non-object values like arrays or strings)
+  const isValidJobDefinition = (value: unknown): value is Record<string, unknown> => {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+  }
+
+  const templateKeys = Object.keys(jobs).filter(
+    (k) => k.startsWith(".") && isValidJobDefinition(jobs[k]),
+  )
+  const jobKeys = Object.keys(jobs).filter(
+    (k) => !k.startsWith(".") && isValidJobDefinition(jobs[k]),
+  )
 
   // Templates first
   for (const key of templateKeys) {

src/import.ts

@@ -47,7 +47,7 @@ interface GitLabCi {
      * @see https://docs.gitlab.com/ee/ci/yaml/#tags
      */
     tags?: string[]
-    cache?: CacheDefinition
+    cache?: CacheDefinition | CacheDefinition[]
     artifacts?: ArtifactsDefinition
     retry?: RetryDefinition
     /**

src/types/main.ts

@@ -305,6 +305,10 @@ deploy-job:
 
     it("should handle anchors", () => {
       const yaml = `
+.tags_test: &tags_test
+  - test1
+  - test2
+
 .job_template: &job_configuration
   script:
     - test project
@@ -334,8 +338,22 @@ test:mysql:
 
       const ts = fromYaml(yaml)
 
+      // Anchor-only definitions (.tags_test) should be ignored
+      expect(ts).not.toContain('config.template(".tags_test"')
+
+      // Templates with actual job definitions should be included
+      expect(ts).toContain('config.template(".postgres_services"')
+      expect(ts).toContain('config.template(".mysql_services"')
+      expect(ts).toContain('config.template(".job_template"')
+
+      // Jobs should reference the merged anchor values
+      expect(ts).toContain('config.job("test:postgres"')
+      expect(ts).toContain('config.job("test:mysql"')
       expect(ts).toContain('services: ["postgres", "ruby"]')
       expect(ts).toContain('services: ["mysql", "ruby"]')
+
+      // Merged script from anchor should be present
+      expect(ts).toContain('"test project"')
     })
   })
 })