@intentius/chant-lexicon-gitlab 0.0.1

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

@@ -0,0 +1,54 @@
+/**
+ * WGL011: Unreachable job
+ *
+ * Detects jobs where all `rules:` entries evaluate to `when: never`,
+ * making the job unreachable. This usually indicates a configuration error.
+ *
+ * Note: This is a simple static check — it only catches the obvious case
+ * where every rule has `when: "never"` literally set. Complex conditions
+ * with `if:` expressions are not evaluated.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+export const wgl011: PostSynthCheck = {
+  id: "WGL011",
+  description: "Job has rules that always evaluate to never (unreachable)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [entityName, entity] of ctx.entities) {
+      if (isPropertyDeclarable(entity)) continue;
+      const entityType = (entity as Record<string, unknown>).entityType as string;
+      if (entityType !== "GitLab::CI::Job") continue;
+
+      const props = (entity as Record<string, unknown>).props as Record<string, unknown> | undefined;
+      if (!props?.rules || !Array.isArray(props.rules)) continue;
+
+      const rules = props.rules as Array<Record<string, unknown>>;
+      if (rules.length === 0) continue;
+
+      // Check if ALL rules have when: "never"
+      const allNever = rules.every((rule) => {
+        // If the rule is a declarable (e.g. new Rule({...})), check its props
+        const ruleProps = (rule as Record<string, unknown>).props as Record<string, unknown> | undefined;
+        const when = ruleProps?.when ?? (rule as Record<string, unknown>).when;
+        return when === "never";
+      });
+
+      if (allNever) {
+        diagnostics.push({
+          checkId: "WGL011",
+          severity: "warning",
+          message: `Job "${entityName}" has rules that all evaluate to "never" — this job will never run.`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,88 @@
+/**
+ * Helpers for parsing serialized GitLab CI YAML in post-synth checks.
+ *
+ * Since GitLab CI output is YAML (not JSON like CloudFormation), we parse
+ * the YAML sections structurally using simple regex/string parsing. The
+ * serializer emits a predictable format so we can extract what we need
+ * without a full YAML parser dependency.
+ */
+
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+/**
+ * Extract the primary output string from a serializer result.
+ */
+export function getPrimaryOutput(output: string | SerializerResult): string {
+  return typeof output === "string" ? output : output.primary;
+}
+
+/**
+ * Parse a serialized GitLab CI YAML into a structured object.
+ * Returns null if the output can't be parsed.
+ */
+export interface ParsedGitLabCI {
+  stages: string[];
+  jobs: Map<string, ParsedJob>;
+}
+
+export interface ParsedJob {
+  name: string;
+  stage?: string;
+  rules?: ParsedRule[];
+}
+
+export interface ParsedRule {
+  when?: string;
+  if?: string;
+}
+
+/**
+ * Extract stages list from serialized YAML.
+ */
+export function extractStages(yaml: string): string[] {
+  const stages: string[] = [];
+  const stagesMatch = yaml.match(/^stages:\n((?:\s+- .+\n?)+)/m);
+  if (stagesMatch) {
+    for (const line of stagesMatch[1].split("\n")) {
+      const item = line.match(/^\s+- (.+)$/);
+      if (item) stages.push(item[1].trim().replace(/^'|'$/g, ""));
+    }
+  }
+  return stages;
+}
+
+/**
+ * Extract job names and their stage values from serialized YAML.
+ */
+export function extractJobs(yaml: string): Map<string, ParsedJob> {
+  const jobs = new Map<string, ParsedJob>();
+
+  // Split into sections by double newlines
+  const sections = yaml.split("\n\n");
+  for (const section of sections) {
+    const lines = section.split("\n");
+    if (lines.length === 0) continue;
+
+    // Top-level key
+    const topMatch = lines[0].match(/^([a-z][a-z0-9_-]*):/);
+    if (!topMatch) continue;
+
+    const name = topMatch[1];
+    // Skip reserved keys
+    if (["stages", "default", "workflow", "variables", "include"].includes(name)) continue;
+
+    const job: ParsedJob = { name };
+
+    // Find stage within the section
+    for (const line of lines) {
+      const stageMatch = line.match(/^\s+stage:\s+(.+)$/);
+      if (stageMatch) {
+        job.stage = stageMatch[1].trim().replace(/^'|'$/g, "");
+      }
+    }
+
+    jobs.set(name, job);
+  }
+
+  return jobs;
+}

package/src/lint/rules/artifact-no-expiry.ts

@@ -0,0 +1,62 @@
+/**
+ * WGL004: Artifacts without expiry
+ *
+ * Artifacts without `expireIn` (or `expire_in`) will be kept indefinitely,
+ * wasting storage. Always set an expiry for job artifacts.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const artifactNoExpiryRule: LintRule = {
+  id: "WGL004",
+  severity: "warning",
+  category: "performance",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isNewExpression(node)) {
+        let isArtifacts = false;
+        const expression = node.expression;
+
+        if (ts.isIdentifier(expression) && expression.text === "Artifacts") {
+          isArtifacts = true;
+        } else if (ts.isPropertyAccessExpression(expression) && expression.name.text === "Artifacts") {
+          isArtifacts = true;
+        }
+
+        if (isArtifacts && node.arguments && node.arguments.length > 0) {
+          const props = node.arguments[0];
+          if (ts.isObjectLiteralExpression(props)) {
+            const hasExpiry = props.properties.some((prop) => {
+              if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                return prop.name.text === "expireIn" || prop.name.text === "expire_in";
+              }
+              return false;
+            });
+
+            if (!hasExpiry) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "WGL004",
+                severity: "warning",
+                message: 'Artifacts without "expireIn" will be kept indefinitely. Set an expiry to save storage.',
+              });
+            }
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/deprecated-only-except.ts

@@ -0,0 +1,53 @@
+/**
+ * WGL001: Deprecated only/except keywords
+ *
+ * Flags usage of `only:` and `except:` in GitLab CI jobs.
+ * These keywords are deprecated in favor of `rules:` which provides
+ * more flexible conditional execution.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const deprecatedOnlyExceptRule: LintRule = {
+  id: "WGL001",
+  severity: "warning",
+  category: "style",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      // Look for property assignments named "only" or "except"
+      // inside new Job(...) or similar constructor calls
+      if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name)) {
+        const propName = node.name.text;
+        if (propName === "only" || propName === "except") {
+          // Check if this is inside a new expression (Job constructor)
+          let parent: ts.Node | undefined = node.parent;
+          while (parent) {
+            if (ts.isNewExpression(parent)) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "WGL001",
+                severity: "warning",
+                message: `"${propName}" is deprecated. Use "rules" for conditional job execution instead.`,
+              });
+              break;
+            }
+            parent = parent.parent;
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -0,0 +1,8 @@
+/**
+ * GitLab CI/CD lint rules
+ */
+
+export { deprecatedOnlyExceptRule } from "./deprecated-only-except";
+export { missingScriptRule } from "./missing-script";
+export { missingStageRule } from "./missing-stage";
+export { artifactNoExpiryRule } from "./artifact-no-expiry";

package/src/lint/rules/missing-script.ts

@@ -0,0 +1,65 @@
+/**
+ * WGL002: Missing script
+ *
+ * A GitLab CI job must have `script`, `trigger`, or `run` defined.
+ * Jobs without any of these will fail pipeline validation.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+const VALID_EXECUTION_PROPS = new Set(["script", "trigger", "run"]);
+
+export const missingScriptRule: LintRule = {
+  id: "WGL002",
+  severity: "error",
+  category: "correctness",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isNewExpression(node)) {
+        // Check for `new Job(...)` or `new gl.Job(...)`
+        let isJob = false;
+        const expression = node.expression;
+
+        if (ts.isIdentifier(expression) && expression.text === "Job") {
+          isJob = true;
+        } else if (ts.isPropertyAccessExpression(expression) && expression.name.text === "Job") {
+          isJob = true;
+        }
+
+        if (isJob && node.arguments && node.arguments.length > 0) {
+          const props = node.arguments[0];
+          if (ts.isObjectLiteralExpression(props)) {
+            const hasExecution = props.properties.some((prop) => {
+              if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                return VALID_EXECUTION_PROPS.has(prop.name.text);
+              }
+              return false;
+            });
+
+            if (!hasExecution) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "WGL002",
+                severity: "error",
+                message: 'Job must have "script", "trigger", or "run" defined.',
+              });
+            }
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/missing-stage.ts

@@ -0,0 +1,62 @@
+/**
+ * WGL003: Missing stage
+ *
+ * Jobs should declare a `stage` property. Without it, the job defaults
+ * to the "test" stage which may not be the intended behavior.
+ */
+
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+export const missingStageRule: LintRule = {
+  id: "WGL003",
+  severity: "info",
+  category: "style",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isNewExpression(node)) {
+        let isJob = false;
+        const expression = node.expression;
+
+        if (ts.isIdentifier(expression) && expression.text === "Job") {
+          isJob = true;
+        } else if (ts.isPropertyAccessExpression(expression) && expression.name.text === "Job") {
+          isJob = true;
+        }
+
+        if (isJob && node.arguments && node.arguments.length > 0) {
+          const props = node.arguments[0];
+          if (ts.isObjectLiteralExpression(props)) {
+            const hasStage = props.properties.some((prop) => {
+              if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+                return prop.name.text === "stage";
+              }
+              return false;
+            });
+
+            if (!hasStage) {
+              const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+              diagnostics.push({
+                file: sourceFile.fileName,
+                line: line + 1,
+                column: character + 1,
+                ruleId: "WGL003",
+                severity: "info",
+                message: 'Job does not declare a "stage". It will default to "test".',
+              });
+            }
+          }
+        }
+      }
+
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,146 @@
+import { describe, test, expect } from "bun:test";
+import * as ts from "typescript";
+import type { LintContext } from "@intentius/chant/lint/rule";
+import { deprecatedOnlyExceptRule } from "./deprecated-only-except";
+import { missingScriptRule } from "./missing-script";
+import { missingStageRule } from "./missing-stage";
+import { artifactNoExpiryRule } from "./artifact-no-expiry";
+
+function createContext(code: string, fileName = "test.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: fileName };
+}
+
+// ── WGL001: deprecated only/except ──────────────────────────────────
+
+describe("WGL001: deprecated-only-except", () => {
+  test("flags 'only' in new Job()", () => {
+    const ctx = createContext(`const j = new Job({ only: ["main"], script: ["test"] });`);
+    const diags = deprecatedOnlyExceptRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("WGL001");
+    expect(diags[0].message).toContain("only");
+  });
+
+  test("flags 'except' in new Job()", () => {
+    const ctx = createContext(`const j = new Job({ except: ["tags"], script: ["test"] });`);
+    const diags = deprecatedOnlyExceptRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("except");
+  });
+
+  test("flags both 'only' and 'except'", () => {
+    const ctx = createContext(`const j = new Job({ only: ["main"], except: ["tags"], script: ["test"] });`);
+    const diags = deprecatedOnlyExceptRule.check(ctx);
+    expect(diags).toHaveLength(2);
+  });
+
+  test("does not flag 'rules'", () => {
+    const ctx = createContext(`const j = new Job({ rules: [{ if: "$CI" }], script: ["test"] });`);
+    const diags = deprecatedOnlyExceptRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag 'only' outside new expression", () => {
+    const ctx = createContext(`const only = "main";`);
+    const diags = deprecatedOnlyExceptRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── WGL002: missing script ──────────────────────────────────────────
+
+describe("WGL002: missing-script", () => {
+  test("flags Job without script, trigger, or run", () => {
+    const ctx = createContext(`const j = new Job({ stage: "test" });`);
+    const diags = missingScriptRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("WGL002");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("does not flag Job with script", () => {
+    const ctx = createContext(`const j = new Job({ script: ["test"] });`);
+    const diags = missingScriptRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag Job with trigger", () => {
+    const ctx = createContext(`const j = new Job({ trigger: "other/project" });`);
+    const diags = missingScriptRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag Job with run", () => {
+    const ctx = createContext(`const j = new Job({ run: ["echo test"] });`);
+    const diags = missingScriptRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags gl.Job() without script", () => {
+    const ctx = createContext(`const j = new gl.Job({ stage: "build" });`);
+    const diags = missingScriptRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag non-Job constructors", () => {
+    const ctx = createContext(`const c = new Cache({ paths: ["node_modules/"] });`);
+    const diags = missingScriptRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── WGL003: missing stage ───────────────────────────────────────────
+
+describe("WGL003: missing-stage", () => {
+  test("flags Job without stage", () => {
+    const ctx = createContext(`const j = new Job({ script: ["test"] });`);
+    const diags = missingStageRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("WGL003");
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("test");
+  });
+
+  test("does not flag Job with stage", () => {
+    const ctx = createContext(`const j = new Job({ stage: "build", script: ["make"] });`);
+    const diags = missingStageRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});
+
+// ── WGL004: artifact no expiry ──────────────────────────────────────
+
+describe("WGL004: artifact-no-expiry", () => {
+  test("flags Artifacts without expireIn", () => {
+    const ctx = createContext(`const a = new Artifacts({ paths: ["dist/"] });`);
+    const diags = artifactNoExpiryRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("WGL004");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("does not flag Artifacts with expireIn", () => {
+    const ctx = createContext(`const a = new Artifacts({ paths: ["dist/"], expireIn: "1 week" });`);
+    const diags = artifactNoExpiryRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag Artifacts with expire_in", () => {
+    const ctx = createContext(`const a = new Artifacts({ paths: ["dist/"], expire_in: "30 days" });`);
+    const diags = artifactNoExpiryRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags gl.Artifacts without expiry", () => {
+    const ctx = createContext(`const a = new gl.Artifacts({ paths: ["dist/"] });`);
+    const diags = artifactNoExpiryRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("does not flag non-Artifacts constructors", () => {
+    const ctx = createContext(`const j = new Job({ script: ["test"] });`);
+    const diags = artifactNoExpiryRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+});

package/src/lsp/completions.test.ts

@@ -0,0 +1,85 @@
+import { describe, test, expect } from "bun:test";
+import { gitlabCompletions } from "./completions";
+import type { CompletionContext } from "@intentius/chant/lsp/types";
+
+function makeCtx(overrides: Partial<CompletionContext>): CompletionContext {
+  return {
+    uri: "file:///test.ts",
+    content: "",
+    position: { line: 0, character: 0 },
+    wordAtCursor: "",
+    linePrefix: "",
+    ...overrides,
+  };
+}
+
+describe("gitlabCompletions", () => {
+  test("returns resource completions for 'new ' prefix", () => {
+    const ctx = makeCtx({
+      linePrefix: "const j = new Job",
+      wordAtCursor: "Job",
+      content: "const j = new Job",
+      position: { line: 0, character: 17 },
+    });
+
+    const items = gitlabCompletions(ctx);
+    expect(items.length).toBeGreaterThan(0);
+    const job = items.find((i) => i.label === "Job");
+    expect(job).toBeDefined();
+    expect(job!.kind).toBe("resource");
+  });
+
+  test("returns all resource completions when no filter", () => {
+    const ctx = makeCtx({
+      linePrefix: "const x = new ",
+      wordAtCursor: "",
+      content: "const x = new ",
+      position: { line: 0, character: 14 },
+    });
+
+    const items = gitlabCompletions(ctx);
+    const labels = items.map((i) => i.label);
+    expect(labels).toContain("Job");
+    expect(labels).toContain("Default");
+    expect(labels).toContain("Workflow");
+  });
+
+  test("filters completions by prefix", () => {
+    const ctx = makeCtx({
+      linePrefix: "const x = new D",
+      wordAtCursor: "D",
+      content: "const x = new D",
+      position: { line: 0, character: 15 },
+    });
+
+    const items = gitlabCompletions(ctx);
+    const labels = items.map((i) => i.label);
+    expect(labels).toContain("Default");
+    expect(labels).not.toContain("Job");
+  });
+
+  test("returns empty for non-constructor context", () => {
+    const ctx = makeCtx({
+      linePrefix: "const x = foo(",
+      wordAtCursor: "",
+      content: "const x = foo(",
+      position: { line: 0, character: 14 },
+    });
+
+    const items = gitlabCompletions(ctx);
+    expect(items).toHaveLength(0);
+  });
+
+  test("completion items have detail with resource type", () => {
+    const ctx = makeCtx({
+      linePrefix: "const j = new Job",
+      wordAtCursor: "Job",
+      content: "const j = new Job",
+      position: { line: 0, character: 17 },
+    });
+
+    const items = gitlabCompletions(ctx);
+    const job = items.find((i) => i.label === "Job");
+    expect(job!.detail).toContain("GitLab::CI::Job");
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,18 @@
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-gitlab.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide GitLab CI completions based on context.
+ */
+export function gitlabCompletions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "GitLab CI entity");
+}