@intentius/chant-lexicon-gitlab 0.0.16 → 0.0.18

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

@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl018 } from "./wgl018";
+
+class MockJob implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Job";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+function makeCtx(entities: Map<string, Declarable>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL018: Missing Timeout", () => {
+  test("check metadata", () => {
+    expect(wgl018.id).toBe("WGL018");
+    expect(wgl018.description).toContain("timeout");
+  });
+
+  test("flags job without timeout", () => {
+    const entities = new Map<string, Declarable>([
+      ["buildJob", new MockJob({ script: ["npm build"] })],
+    ]);
+    const diags = wgl018.check(makeCtx(entities));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("buildJob");
+  });
+
+  test("does not flag job with timeout", () => {
+    const entities = new Map<string, Declarable>([
+      ["buildJob", new MockJob({ script: ["npm build"], timeout: "10 minutes" })],
+    ]);
+    const diags = wgl018.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags multiple jobs without timeout", () => {
+    const entities = new Map<string, Declarable>([
+      ["job1", new MockJob({ script: ["test"] })],
+      ["job2", new MockJob({ script: ["build"] })],
+    ]);
+    const diags = wgl018.check(makeCtx(entities));
+    expect(diags).toHaveLength(2);
+  });
+
+  test("no diagnostics on empty entities", () => {
+    const diags = wgl018.check(makeCtx(new Map()));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,39 @@
+/**
+ * WGL018: Missing Timeout
+ *
+ * Warns about jobs without an explicit `timeout:` setting.
+ * The default (1 hour) may be too long for most jobs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+export const wgl018: PostSynthCheck = {
+  id: "WGL018",
+  description: "Missing timeout — jobs without explicit timeout may run too long",
+
+  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) continue;
+
+      if (!props.timeout) {
+        diagnostics.push({
+          checkId: "WGL018",
+          severity: "warning",
+          message: `Job "${entityName}" has no explicit timeout — default is 1 hour which may be too long`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,76 @@
+import { describe, test, expect } from "bun:test";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl019 } from "./wgl019";
+
+class MockJob implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Job";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+function makeCtx(entities: Map<string, Declarable>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL019: Missing Retry on Deploy Jobs", () => {
+  test("check metadata", () => {
+    expect(wgl019.id).toBe("WGL019");
+    expect(wgl019.description).toContain("retry");
+  });
+
+  test("flags deploy job without retry", () => {
+    const entities = new Map<string, Declarable>([
+      ["deployApp", new MockJob({ script: ["deploy.sh"], stage: "deploy" })],
+    ]);
+    const diags = wgl019.check(makeCtx(entities));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("deployApp");
+  });
+
+  test("does not flag deploy job with retry", () => {
+    const entities = new Map<string, Declarable>([
+      ["deployApp", new MockJob({ script: ["deploy.sh"], stage: "deploy", retry: { max: 2 } })],
+    ]);
+    const diags = wgl019.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag non-deploy job without retry", () => {
+    const entities = new Map<string, Declarable>([
+      ["testJob", new MockJob({ script: ["npm test"], stage: "test" })],
+    ]);
+    const diags = wgl019.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("recognizes staging as a deploy stage", () => {
+    const entities = new Map<string, Declarable>([
+      ["stagingDeploy", new MockJob({ script: ["deploy.sh"], stage: "staging" })],
+    ]);
+    const diags = wgl019.check(makeCtx(entities));
+    expect(diags).toHaveLength(1);
+  });
+
+  test("no diagnostics on empty entities", () => {
+    const diags = wgl019.check(makeCtx(new Map()));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * WGL019: Missing Retry on Deploy Jobs
+ *
+ * Deploy-stage jobs should have a `retry:` strategy to handle transient
+ * infrastructure failures. This is informational, not a hard requirement.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+const DEPLOY_STAGES = new Set(["deploy", "deployment", "release", "production", "staging"]);
+
+export const wgl019: PostSynthCheck = {
+  id: "WGL019",
+  description: "Missing retry — deploy jobs without retry strategy",
+
+  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) continue;
+
+      const stage = props.stage as string | undefined;
+      if (!stage || !DEPLOY_STAGES.has(stage.toLowerCase())) continue;
+
+      if (!props.retry) {
+        diagnostics.push({
+          checkId: "WGL019",
+          severity: "info",
+          message: `Deploy job "${entityName}" (stage: ${stage}) has no retry strategy — consider adding retry for transient failures`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "bun:test";
+import { wgl020, checkDuplicateJobNames } from "./wgl020";
+
+describe("WGL020: Duplicate Job Names", () => {
+  test("check metadata", () => {
+    expect(wgl020.id).toBe("WGL020");
+    expect(wgl020.description).toContain("Duplicate");
+  });
+
+  test("flags duplicate job names", () => {
+    const yaml = `build-app:
+  script:
+    - npm build
+
+build-app:
+  script:
+    - npm run build
+`;
+    const diags = checkDuplicateJobNames(yaml);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("build-app");
+    expect(diags[0].message).toContain("2 times");
+  });
+
+  test("does not flag unique job names", () => {
+    const yaml = `build-app:
+  script:
+    - npm build
+
+test-app:
+  script:
+    - npm test
+`;
+    const diags = checkDuplicateJobNames(yaml);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("ignores reserved keys", () => {
+    const yaml = `stages:
+  - build
+
+variables:
+  FOO: bar
+`;
+    const diags = checkDuplicateJobNames(yaml);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostics on empty yaml", () => {
+    const diags = checkDuplicateJobNames("");
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,56 @@
+/**
+ * WGL020: Duplicate Job Names
+ *
+ * Detects multiple jobs that resolve to the same kebab-case name in
+ * the serialized YAML. GitLab silently merges duplicate keys, which
+ * causes unexpected behavior.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs } from "./yaml-helpers";
+
+export function checkDuplicateJobNames(yaml: string): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  // Count occurrences of each top-level key (raw line parsing, not extractJobs,
+  // to detect actual YAML key duplication)
+  const keyCounts = new Map<string, number>();
+  const lines = yaml.split("\n");
+
+  for (const line of lines) {
+    const topMatch = line.match(/^(\.?[a-z][a-z0-9_.-]*):/);
+    if (topMatch) {
+      const name = topMatch[1];
+      if (["stages", "default", "workflow", "variables", "include"].includes(name)) continue;
+      keyCounts.set(name, (keyCounts.get(name) ?? 0) + 1);
+    }
+  }
+
+  for (const [name, count] of keyCounts) {
+    if (count > 1) {
+      diagnostics.push({
+        checkId: "WGL020",
+        severity: "error",
+        message: `Duplicate job name "${name}" appears ${count} times — GitLab will silently merge these`,
+        entity: name,
+        lexicon: "gitlab",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl020: PostSynthCheck = {
+  id: "WGL020",
+  description: "Duplicate job names — multiple jobs resolving to same name",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      diagnostics.push(...checkDuplicateJobNames(yaml));
+    }
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,62 @@
+import { describe, test, expect } from "bun:test";
+import { wgl021, checkUnusedVariables } from "./wgl021";
+
+describe("WGL021: Unused Variables", () => {
+  test("check metadata", () => {
+    expect(wgl021.id).toBe("WGL021");
+    expect(wgl021.description).toContain("Unused");
+  });
+
+  test("flags unused global variable", () => {
+    const yaml = `variables:
+  UNUSED_VAR: hello
+  USED_VAR: world
+
+test-job:
+  script:
+    - echo $USED_VAR
+`;
+    const diags = checkUnusedVariables(yaml);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("UNUSED_VAR");
+  });
+
+  test("does not flag used variable", () => {
+    const yaml = `variables:
+  NODE_ENV: production
+
+test-job:
+  script:
+    - echo $NODE_ENV
+`;
+    const diags = checkUnusedVariables(yaml);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("detects braced variable references", () => {
+    const yaml = `variables:
+  APP_NAME: myapp
+
+deploy-job:
+  script:
+    - echo \${APP_NAME}
+`;
+    const diags = checkUnusedVariables(yaml);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostics when no global variables", () => {
+    const yaml = `test-job:
+  script:
+    - npm test
+`;
+    const diags = checkUnusedVariables(yaml);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostics on empty yaml", () => {
+    const diags = checkUnusedVariables("");
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,62 @@
+/**
+ * WGL021: Unused Variables
+ *
+ * Detects global `variables:` that are not referenced by any job script.
+ * Unused variables add noise and may indicate stale configuration.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractGlobalVariables } from "./yaml-helpers";
+
+export function checkUnusedVariables(yaml: string): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  const globalVars = extractGlobalVariables(yaml);
+  if (globalVars.size === 0) return diagnostics;
+
+  // Get the rest of the YAML (everything after the global variables block)
+  // to search for references
+  for (const [varName] of globalVars) {
+    // Check if $VARNAME or ${VARNAME} appears anywhere in the YAML (outside the variables block)
+    const refPattern = new RegExp(`\\$\\{?${varName}\\}?`);
+    // Also check for uses in extends, needs, etc. — search all sections
+    const sections = yaml.split("\n\n");
+    let found = false;
+
+    for (const section of sections) {
+      // Skip the global variables section itself
+      if (section.trimStart().startsWith("variables:")) continue;
+
+      if (refPattern.test(section)) {
+        found = true;
+        break;
+      }
+    }
+
+    if (!found) {
+      diagnostics.push({
+        checkId: "WGL021",
+        severity: "warning",
+        message: `Global variable "${varName}" is not referenced in any job script`,
+        entity: varName,
+        lexicon: "gitlab",
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl021: PostSynthCheck = {
+  id: "WGL021",
+  description: "Unused variables — global variables not referenced by any job",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      diagnostics.push(...checkUnusedVariables(yaml));
+    }
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,86 @@
+import { describe, test, expect } from "bun:test";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl022 } from "./wgl022";
+
+class MockJob implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Job";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+function makeCtx(entities: Map<string, Declarable>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL022: Missing Artifacts Expiry", () => {
+  test("check metadata", () => {
+    expect(wgl022.id).toBe("WGL022");
+    expect(wgl022.description).toContain("artifacts");
+  });
+
+  test("flags artifacts without expire_in", () => {
+    const entities = new Map<string, Declarable>([
+      ["buildJob", new MockJob({
+        script: ["npm build"],
+        artifacts: { paths: ["dist/"] },
+      })],
+    ]);
+    const diags = wgl022.check(makeCtx(entities));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("buildJob");
+    expect(diags[0].message).toContain("expire_in");
+  });
+
+  test("does not flag artifacts with expire_in", () => {
+    const entities = new Map<string, Declarable>([
+      ["buildJob", new MockJob({
+        script: ["npm build"],
+        artifacts: { paths: ["dist/"], expire_in: "1 week" },
+      })],
+    ]);
+    const diags = wgl022.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag job without artifacts", () => {
+    const entities = new Map<string, Declarable>([
+      ["testJob", new MockJob({ script: ["npm test"] })],
+    ]);
+    const diags = wgl022.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("handles artifacts as declarable with props", () => {
+    const entities = new Map<string, Declarable>([
+      ["buildJob", new MockJob({
+        script: ["npm build"],
+        artifacts: { props: { paths: ["dist/"], expire_in: "30 days" } },
+      })],
+    ]);
+    const diags = wgl022.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostics on empty entities", () => {
+    const diags = wgl022.check(makeCtx(new Map()));
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * WGL022: Missing Artifacts Expiry
+ *
+ * Warns about `artifacts:` without `expire_in:`, which causes disk bloat
+ * on the GitLab instance. Default retention is "never expire" in some
+ * GitLab configurations.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+export const wgl022: PostSynthCheck = {
+  id: "WGL022",
+  description: "Missing artifacts expiry — artifacts without expire_in cause disk bloat",
+
+  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?.artifacts) continue;
+
+      const artifacts = props.artifacts as Record<string, unknown>;
+      // artifacts might be a Declarable with its own props
+      const artProps = (artifacts.props as Record<string, unknown> | undefined) ?? artifacts;
+
+      if (!artProps.expire_in && !artProps.expireIn) {
+        diagnostics.push({
+          checkId: "WGL022",
+          severity: "warning",
+          message: `Job "${entityName}" has artifacts without expire_in — set an expiry to avoid disk bloat`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

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

@@ -0,0 +1,88 @@
+import { describe, test, expect } from "bun:test";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl023 } from "./wgl023";
+
+class MockJob implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType = "GitLab::CI::Job";
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(props: Record<string, unknown> = {}) {
+    this.props = props;
+  }
+}
+
+function makeCtx(entities: Map<string, Declarable>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL023: Overly Broad Rules", () => {
+  test("check metadata", () => {
+    expect(wgl023.id).toBe("WGL023");
+    expect(wgl023.description).toContain("Overly broad");
+  });
+
+  test("flags single rule with only when: always", () => {
+    const entities = new Map<string, Declarable>([
+      ["alwaysJob", new MockJob({
+        script: ["test"],
+        rules: [{ when: "always" }],
+      })],
+    ]);
+    const diags = wgl023.check(makeCtx(entities));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("info");
+    expect(diags[0].message).toContain("alwaysJob");
+  });
+
+  test("does not flag rule with when: always and if condition", () => {
+    const entities = new Map<string, Declarable>([
+      ["conditionalJob", new MockJob({
+        script: ["test"],
+        rules: [{ if: "$CI_COMMIT_BRANCH == 'main'", when: "always" }],
+      })],
+    ]);
+    const diags = wgl023.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag multiple rules", () => {
+    const entities = new Map<string, Declarable>([
+      ["multiRuleJob", new MockJob({
+        script: ["test"],
+        rules: [
+          { when: "always" },
+          { when: "never" },
+        ],
+      })],
+    ]);
+    const diags = wgl023.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("does not flag job without rules", () => {
+    const entities = new Map<string, Declarable>([
+      ["simpleJob", new MockJob({ script: ["test"] })],
+    ]);
+    const diags = wgl023.check(makeCtx(entities));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostics on empty entities", () => {
+    const diags = wgl023.check(makeCtx(new Map()));
+    expect(diags).toHaveLength(0);
+  });
+});