@intentius/chant-lexicon-gitlab 0.0.8 → 0.0.10

package/src/lint/post-synth/wgl015.test.ts

@@ -0,0 +1,139 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl015, checkCircularNeeds } from "./wgl015";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL015: Circular needs: Chain", () => {
+  test("check metadata", () => {
+    expect(wgl015.id).toBe("WGL015");
+    expect(wgl015.description).toContain("Circular");
+  });
+
+  test("A→B→A cycle → error", () => {
+    const yaml = `stages:
+  - build
+
+job-a:
+  stage: build
+  needs:
+    - job-b
+  script:
+    - echo a
+
+job-b:
+  stage: build
+  needs:
+    - job-a
+  script:
+    - echo b`;
+    const diags = checkCircularNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL015");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("job-a");
+    expect(diags[0].message).toContain("job-b");
+    expect(diags[0].message).toContain("→");
+    expect(diags[0].lexicon).toBe("gitlab");
+  });
+
+  test("A→B→C→A cycle → error", () => {
+    const yaml = `stages:
+  - build
+
+job-a:
+  stage: build
+  needs:
+    - job-b
+  script:
+    - echo a
+
+job-b:
+  stage: build
+  needs:
+    - job-c
+  script:
+    - echo b
+
+job-c:
+  stage: build
+  needs:
+    - job-a
+  script:
+    - echo c`;
+    const diags = checkCircularNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("job-a");
+    expect(diags[0].message).toContain("job-b");
+    expect(diags[0].message).toContain("job-c");
+  });
+
+  test("A→B, B→C (no cycle) → no diagnostic", () => {
+    const yaml = `stages:
+  - build
+
+job-a:
+  stage: build
+  needs:
+    - job-b
+  script:
+    - echo a
+
+job-b:
+  stage: build
+  needs:
+    - job-c
+  script:
+    - echo b
+
+job-c:
+  stage: build
+  script:
+    - echo c`;
+    const diags = checkCircularNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no needs at all → no diagnostic", () => {
+    const yaml = `stages:
+  - build
+
+job-a:
+  stage: build
+  script:
+    - echo a
+
+job-b:
+  stage: build
+  script:
+    - echo b`;
+    const diags = checkCircularNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("needs referencing unknown job (no cycle) → no diagnostic", () => {
+    const yaml = `stages:
+  - build
+
+job-a:
+  stage: build
+  needs:
+    - unknown-job
+  script:
+    - echo a`;
+    const diags = checkCircularNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/wgl015.ts

@@ -0,0 +1,85 @@
+/**
+ * WGL015: Circular `needs:` Chain
+ *
+ * DFS-based cycle detection on the `needs:` dependency graph.
+ * If A needs B and B needs A, GitLab rejects the pipeline.
+ *
+ * Reports one diagnostic per cycle found, listing the full chain.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export function checkCircularNeeds(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    const jobs = extractJobs(yaml);
+
+    // Build adjacency list from needs
+    const graph = new Map<string, string[]>();
+    for (const [jobName, job] of jobs) {
+      graph.set(jobName, job.needs ?? []);
+    }
+
+    // DFS cycle detection
+    const visited = new Set<string>();
+    const inStack = new Set<string>();
+    const reportedInCycle = new Set<string>();
+
+    function dfs(node: string, path: string[]): void {
+      if (inStack.has(node)) {
+        // Found a cycle — extract the cycle portion
+        const cycleStart = path.indexOf(node);
+        const cycle = path.slice(cycleStart);
+        cycle.push(node);
+
+        // Only report if we haven't already reported a cycle containing these nodes
+        const cycleKey = [...cycle].sort().join(",");
+        if (!reportedInCycle.has(cycleKey)) {
+          reportedInCycle.add(cycleKey);
+          diagnostics.push({
+            checkId: "WGL015",
+            severity: "error",
+            message: `Circular needs: chain detected: ${cycle.join(" → ")}`,
+            entity: node,
+            lexicon: "gitlab",
+          });
+        }
+        return;
+      }
+
+      if (visited.has(node)) return;
+
+      visited.add(node);
+      inStack.add(node);
+
+      for (const neighbor of graph.get(node) ?? []) {
+        // Only follow edges to known jobs
+        if (graph.has(neighbor)) {
+          dfs(neighbor, [...path, node]);
+        }
+      }
+
+      inStack.delete(node);
+    }
+
+    for (const jobName of graph.keys()) {
+      if (!visited.has(jobName)) {
+        dfs(jobName, []);
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl015: PostSynthCheck = {
+  id: "WGL015",
+  description: "Circular needs: chain — cycle in job dependency graph",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkCircularNeeds(ctx);
+  },
+};

package/src/lint/post-synth/yaml-helpers.ts

@@ -29,6 +29,8 @@ export interface ParsedJob {
   name: string;
   stage?: string;
   rules?: ParsedRule[];
+  needs?: string[];
+  extends?: string[];
 }
 
 export interface ParsedRule {
@@ -63,8 +65,8 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
     const lines = section.split("\n");
     if (lines.length === 0) continue;
 
-    // Top-level key
-    const topMatch = lines[0].match(/^([a-z][a-z0-9_-]*):/);
+    // Top-level key (including dot-prefixed hidden jobs like .deploy-template)
+    const topMatch = lines[0].match(/^(\.?[a-z][a-z0-9_.-]*):/);
     if (!topMatch) continue;
 
     const name = topMatch[1];
@@ -73,12 +75,63 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
 
     const job: ParsedJob = { name };
 
-    // Find stage within the section
+    // Find stage, needs, extends within the section
+    let inNeeds = false;
     for (const line of lines) {
       const stageMatch = line.match(/^\s+stage:\s+(.+)$/);
       if (stageMatch) {
         job.stage = stageMatch[1].trim().replace(/^'|'$/g, "");
       }
+
+      // extends: .template or extends: [.a, .b]
+      const extendsMatch = line.match(/^\s+extends:\s+(.+)$/);
+      if (extendsMatch) {
+        const val = extendsMatch[1].trim();
+        if (val.startsWith("[")) {
+          // Inline array: [.a, .b]
+          job.extends = val.slice(1, -1).split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+        } else {
+          job.extends = [val.replace(/^'|'$/g, "")];
+        }
+      }
+
+      // needs: block (list form)
+      if (line.match(/^\s+needs:$/)) {
+        inNeeds = true;
+        job.needs = [];
+        continue;
+      }
+
+      if (inNeeds) {
+        // - job-name (simple string form)
+        const simpleNeed = line.match(/^\s+- ([a-z][a-z0-9_.-]*)$/);
+        if (simpleNeed) {
+          job.needs!.push(simpleNeed[1]);
+          continue;
+        }
+        // - 'job-name' (quoted string form)
+        const quotedNeed = line.match(/^\s+- '([^']+)'$/);
+        if (quotedNeed) {
+          job.needs!.push(quotedNeed[1]);
+          continue;
+        }
+        // - job: job-name (object form)
+        const objectNeed = line.match(/^\s+- job:\s+(.+)$/);
+        if (objectNeed) {
+          job.needs!.push(objectNeed[1].trim().replace(/^'|'$/g, ""));
+          continue;
+        }
+        // End of needs block when we hit a non-indented-list line
+        if (!line.match(/^\s+\s/) || line.match(/^\s+[a-z_]+:/)) {
+          inNeeds = false;
+        }
+      }
+
+      // needs: [a, b] (inline array form)
+      const inlineNeeds = line.match(/^\s+needs:\s+\[(.+)\]$/);
+      if (inlineNeeds) {
+        job.needs = inlineNeeds[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+      }
     }
 
     jobs.set(name, job);
@@ -86,3 +139,12 @@ export function extractJobs(yaml: string): Map<string, ParsedJob> {
 
   return jobs;
 }
+
+/**
+ * Check whether the YAML contains an `include:` directive.
+ * When includes are present, `needs:` and `extends:` may reference
+ * jobs/templates from included files, so checks should be lenient.
+ */
+export function hasInclude(yaml: string): boolean {
+  return /^include:/m.test(yaml);
+}

package/src/plugin.test.ts

@@ -83,27 +83,51 @@ describe("gitlabPlugin", () => {
 
   test("returns post-synth checks", () => {
     const checks = gitlabPlugin.postSynthChecks!();
-    expect(checks).toHaveLength(2);
+    expect(checks).toHaveLength(6);
     const ids = checks.map((c) => c.id);
     expect(ids).toContain("WGL010");
     expect(ids).toContain("WGL011");
+    expect(ids).toContain("WGL012");
+    expect(ids).toContain("WGL013");
+    expect(ids).toContain("WGL014");
+    expect(ids).toContain("WGL015");
   });
 
   // -----------------------------------------------------------------------
   // Init templates
   // -----------------------------------------------------------------------
 
-  test("returns init templates", () => {
-    const templates = gitlabPlugin.initTemplates!();
-    expect(templates).toBeDefined();
-    expect(templates["config.ts"]).toBeDefined();
-    expect(templates["test.ts"]).toBeDefined();
+  test("returns default init templates with src files", () => {
+    const result = gitlabPlugin.initTemplates!();
+    expect(result.src).toBeDefined();
+    expect(result.src["config.ts"]).toBeDefined();
+    expect(result.src["pipeline.ts"]).toBeDefined();
   });
 
-  test("init templates import from gitlab lexicon", () => {
-    const templates = gitlabPlugin.initTemplates!();
-    expect(templates["config.ts"]).toContain("@intentius/chant-lexicon-gitlab");
-    expect(templates["test.ts"]).toContain("@intentius/chant-lexicon-gitlab");
+  test("default init templates import from gitlab lexicon", () => {
+    const result = gitlabPlugin.initTemplates!();
+    expect(result.src["config.ts"]).toContain("@intentius/chant-lexicon-gitlab");
+    expect(result.src["pipeline.ts"]).toContain("@intentius/chant-lexicon-gitlab");
+  });
+
+  test("node-pipeline template uses NodePipeline composite", () => {
+    const result = gitlabPlugin.initTemplates!("node-pipeline");
+    expect(result.src["pipeline.ts"]).toContain("NodePipeline");
+  });
+
+  test("python-pipeline template uses PythonPipeline composite", () => {
+    const result = gitlabPlugin.initTemplates!("python-pipeline");
+    expect(result.src["pipeline.ts"]).toContain("PythonPipeline");
+  });
+
+  test("docker-build template uses DockerBuild composite", () => {
+    const result = gitlabPlugin.initTemplates!("docker-build");
+    expect(result.src["pipeline.ts"]).toContain("DockerBuild");
+  });
+
+  test("review-app template uses ReviewApp composite", () => {
+    const result = gitlabPlugin.initTemplates!("review-app");
+    expect(result.src["pipeline.ts"]).toContain("ReviewApp");
   });
 
   // -----------------------------------------------------------------------
@@ -165,8 +189,10 @@ describe("gitlabPlugin", () => {
     expect(skills[0].content).toContain("user-invocable: true");
     expect(skills[0].content).toContain("chant build");
     expect(skills[0].content).toContain("chant lint");
-    expect(skills[0].triggers).toHaveLength(2);
-    expect(skills[0].examples).toHaveLength(1);
+    expect(skills[0].triggers).toHaveLength(5);
+    expect(skills[0].examples).toHaveLength(5);
+    expect(skills[0].preConditions).toHaveLength(3);
+    expect(skills[0].postConditions).toHaveLength(2);
   });
 
   // -----------------------------------------------------------------------
@@ -194,7 +220,7 @@ describe("gitlabPlugin", () => {
     const result = await catalog.handler();
     const parsed = JSON.parse(result);
     expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed.length).toBe(16);
+    expect(parsed.length).toBe(19);
     const job = parsed.find((e: { className: string }) => e.className === "Job");
     expect(job).toBeDefined();
     expect(job.kind).toBe("resource");