@intentius/chant-lexicon-gitlab 0.0.8 → 0.0.10

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

@@ -0,0 +1,131 @@
+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 { wgl012, checkDeprecatedProperties } from "./wgl012";
+
+class MockEntity implements Declarable {
+  readonly [DECLARABLE_MARKER] = true as const;
+  readonly lexicon = "gitlab";
+  readonly entityType: string;
+  readonly kind = "resource" as const;
+  readonly props: Record<string, unknown>;
+
+  constructor(entityType: string, props: Record<string, unknown> = {}) {
+    this.entityType = entityType;
+    this.props = props;
+  }
+}
+
+function makeCtx(entities: Map<string, Declarable>): PostSynthContext {
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: {
+      outputs: new Map(),
+      entities,
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+/** Synthetic deprecated-property map — no disk dependency. */
+function fakeDeprecated(): Map<string, Set<string>> {
+  return new Map([
+    ["GitLab::CI::Job", new Set(["only", "except"])],
+    ["GitLab::CI::Artifacts", new Set(["license_management"])],
+  ]);
+}
+
+describe("WGL012: Deprecated Property Usage", () => {
+  test("check metadata", () => {
+    expect(wgl012.id).toBe("WGL012");
+    expect(wgl012.description).toContain("Deprecated");
+  });
+
+  test("emits warning for deprecated property", () => {
+    const entities = new Map<string, Declarable>([
+      ["deployJob", new MockEntity("GitLab::CI::Job", {
+        only: ["main"],
+        script: ["deploy.sh"],
+      })],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), fakeDeprecated());
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL012");
+    expect(diags[0].severity).toBe("warning");
+    expect(diags[0].message).toContain("only");
+    expect(diags[0].message).toContain("deployJob");
+    expect(diags[0].message).toContain("deprecated");
+    expect(diags[0].entity).toBe("deployJob");
+    expect(diags[0].lexicon).toBe("gitlab");
+  });
+
+  test("emits one warning per deprecated property", () => {
+    const entities = new Map<string, Declarable>([
+      ["oldJob", new MockEntity("GitLab::CI::Job", {
+        only: ["main"],
+        except: ["tags"],
+        script: ["test"],
+      })],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), fakeDeprecated());
+    expect(diags).toHaveLength(2);
+    expect(diags.some((d) => d.message.includes("only"))).toBe(true);
+    expect(diags.some((d) => d.message.includes("except"))).toBe(true);
+  });
+
+  test("no diagnostic for non-deprecated properties", () => {
+    const entities = new Map<string, Declarable>([
+      ["testJob", new MockEntity("GitLab::CI::Job", {
+        script: ["npm test"],
+        stage: "test",
+      })],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), fakeDeprecated());
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic for entity type not in map", () => {
+    const entities = new Map<string, Declarable>([
+      ["myCache", new MockEntity("GitLab::CI::Cache", {
+        paths: ["node_modules/"],
+      })],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), fakeDeprecated());
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no diagnostic on empty entities", () => {
+    const diags = checkDeprecatedProperties(makeCtx(new Map()), fakeDeprecated());
+    expect(diags).toHaveLength(0);
+  });
+
+  test("returns empty when deprecated map is empty", () => {
+    const entities = new Map<string, Declarable>([
+      ["job", new MockEntity("GitLab::CI::Job", { only: ["main"] })],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), new Map());
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags deprecated properties across multiple entities", () => {
+    const entities = new Map<string, Declarable>([
+      ["oldJob", new MockEntity("GitLab::CI::Job", { only: ["main"], script: ["test"] })],
+      ["artifacts", new MockEntity("GitLab::CI::Artifacts", { license_management: "report.json" })],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), fakeDeprecated());
+    expect(diags).toHaveLength(2);
+    expect(diags[0].entity).toBe("oldJob");
+    expect(diags[1].entity).toBe("artifacts");
+  });
+
+  test("handles entity with no props", () => {
+    const entities = new Map<string, Declarable>([
+      ["emptyJob", new MockEntity("GitLab::CI::Job")],
+    ]);
+    const diags = checkDeprecatedProperties(makeCtx(entities), fakeDeprecated());
+    expect(diags).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,86 @@
+/**
+ * WGL012: Deprecated Property Usage
+ *
+ * Flags properties marked as deprecated in the GitLab CI schema.
+ * Sources: description text mining (keywords like "Deprecated", "legacy").
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+
+interface LexiconEntry {
+  kind: string;
+  resourceType: string;
+  deprecatedProperties?: string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Load deprecated properties per entity type from the lexicon JSON.
+ */
+function loadDeprecatedProperties(): Map<string, Set<string>> {
+  const map = new Map<string, Set<string>>();
+  try {
+    const pkgDir = join(__dirname, "..", "..", "..");
+    const lexiconPath = join(pkgDir, "src", "generated", "lexicon-gitlab.json");
+    const content = readFileSync(lexiconPath, "utf-8");
+    const data = JSON.parse(content) as Record<string, LexiconEntry>;
+
+    for (const [_name, entry] of Object.entries(data)) {
+      if (entry.resourceType && entry.deprecatedProperties && entry.deprecatedProperties.length > 0) {
+        map.set(entry.resourceType, new Set(entry.deprecatedProperties));
+      }
+    }
+  } catch {
+    // Lexicon not available — skip
+  }
+  return map;
+}
+
+/**
+ * Core detection logic — exported for direct testing with synthetic data.
+ */
+export function checkDeprecatedProperties(
+  ctx: PostSynthContext,
+  deprecated: Map<string, Set<string>>,
+): PostSynthDiagnostic[] {
+  if (deprecated.size === 0) return [];
+
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [entityName, entity] of ctx.entities) {
+    if (isPropertyDeclarable(entity)) continue;
+
+    const entityType = (entity as Record<string, unknown>).entityType as string;
+    const deprProps = deprecated.get(entityType);
+    if (!deprProps) continue;
+
+    const props = (entity as Record<string, unknown>).props as Record<string, unknown> | undefined;
+    if (!props) continue;
+
+    for (const propName of Object.keys(props)) {
+      if (deprProps.has(propName)) {
+        diagnostics.push({
+          checkId: "WGL012",
+          severity: "warning",
+          message: `Entity "${entityName}" (${entityType}) uses deprecated property "${propName}" — consider alternatives`,
+          entity: entityName,
+          lexicon: "gitlab",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl012: PostSynthCheck = {
+  id: "WGL012",
+  description: "Deprecated property usage — flags properties marked as deprecated in the GitLab CI schema",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkDeprecatedProperties(ctx, loadDeprecatedProperties());
+  },
+};

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

@@ -0,0 +1,164 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl013, checkInvalidNeeds } from "./wgl013";
+
+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("WGL013: Invalid needs: Target", () => {
+  test("check metadata", () => {
+    expect(wgl013.id).toBe("WGL013");
+    expect(wgl013.description).toContain("needs:");
+  });
+
+  test("dangling needs target → error", () => {
+    const yaml = `stages:
+  - build
+  - test
+
+build:
+  stage: build
+  script:
+    - npm run build
+
+test:
+  stage: test
+  needs:
+    - nonexistent
+  script:
+    - npm test`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL013");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("nonexistent");
+    expect(diags[0].message).toContain("not defined");
+    expect(diags[0].entity).toBe("test");
+    expect(diags[0].lexicon).toBe("gitlab");
+  });
+
+  test("self-referencing needs → error", () => {
+    const yaml = `stages:
+  - build
+
+build:
+  stage: build
+  needs:
+    - build
+  script:
+    - npm run build`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL013");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("itself");
+    expect(diags[0].entity).toBe("build");
+  });
+
+  test("valid needs → no diagnostic", () => {
+    const yaml = `stages:
+  - build
+  - test
+
+build:
+  stage: build
+  script:
+    - npm run build
+
+test:
+  stage: test
+  needs:
+    - build
+  script:
+    - npm test`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no needs → no diagnostic", () => {
+    const yaml = `stages:
+  - build
+
+build:
+  stage: build
+  script:
+    - npm run build`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("multiple jobs, only one with bad needs → 1 diagnostic", () => {
+    const yaml = `stages:
+  - build
+  - test
+  - deploy
+
+build:
+  stage: build
+  script:
+    - npm run build
+
+test:
+  stage: test
+  needs:
+    - build
+  script:
+    - npm test
+
+deploy:
+  stage: deploy
+  needs:
+    - nonexistent
+  script:
+    - ./deploy.sh`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].entity).toBe("deploy");
+    expect(diags[0].message).toContain("nonexistent");
+  });
+
+  test("skips check when include: is present", () => {
+    const yaml = `include:
+  - local: .gitlab/ci/templates.yml
+
+stages:
+  - test
+
+test:
+  stage: test
+  needs:
+    - from-included-file
+  script:
+    - npm test`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("multiple invalid needs → multiple diagnostics", () => {
+    const yaml = `stages:
+  - build
+
+build:
+  stage: build
+  needs:
+    - ghost1
+    - ghost2
+  script:
+    - npm run build`;
+    const diags = checkInvalidNeeds(makeCtx(yaml));
+    expect(diags).toHaveLength(2);
+    expect(diags[0].message).toContain("ghost1");
+    expect(diags[1].message).toContain("ghost2");
+  });
+});

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

@@ -0,0 +1,62 @@
+/**
+ * WGL013: Invalid `needs:` Target
+ *
+ * Detects two cases in the serialized YAML:
+ * - Dangling reference: `needs:` names a job not defined in the pipeline
+ * - Self-reference: job lists itself in `needs:`
+ *
+ * Both cause GitLab pipeline validation failures.
+ *
+ * Caveat: when `include:` is present, referenced jobs may come from
+ * included files, so the check is skipped.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, hasInclude } from "./yaml-helpers";
+
+export function checkInvalidNeeds(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    if (hasInclude(yaml)) continue;
+
+    const jobs = extractJobs(yaml);
+    const jobNames = new Set(jobs.keys());
+
+    for (const [jobName, job] of jobs) {
+      if (!job.needs) continue;
+
+      for (const need of job.needs) {
+        if (need === jobName) {
+          diagnostics.push({
+            checkId: "WGL013",
+            severity: "error",
+            message: `Job "${jobName}" lists itself in needs: — self-references are invalid`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        } else if (!jobNames.has(need)) {
+          diagnostics.push({
+            checkId: "WGL013",
+            severity: "error",
+            message: `Job "${jobName}" needs "${need}" which is not defined in the pipeline`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl013: PostSynthCheck = {
+  id: "WGL013",
+  description: "Invalid needs: target — dangling reference or self-reference",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkInvalidNeeds(ctx);
+  },
+};

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

@@ -0,0 +1,97 @@
+import { describe, test, expect } from "bun:test";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl014, checkInvalidExtends } from "./wgl014";
+
+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("WGL014: Invalid extends: Target", () => {
+  test("check metadata", () => {
+    expect(wgl014.id).toBe("WGL014");
+    expect(wgl014.description).toContain("extends:");
+  });
+
+  test("extends nonexistent template → error", () => {
+    const yaml = `stages:
+  - deploy
+
+deploy:
+  stage: deploy
+  extends: .nonexistent-template
+  script:
+    - ./deploy.sh`;
+    const diags = checkInvalidExtends(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL014");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain(".nonexistent-template");
+    expect(diags[0].message).toContain("not defined");
+    expect(diags[0].entity).toBe("deploy");
+    expect(diags[0].lexicon).toBe("gitlab");
+  });
+
+  test("extends existing hidden job → no diagnostic", () => {
+    const yaml = `.deploy-template:
+  image: alpine
+  script:
+    - echo "template"
+
+deploy:
+  stage: deploy
+  extends: .deploy-template
+  script:
+    - ./deploy.sh`;
+    const diags = checkInvalidExtends(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("no extends → no diagnostic", () => {
+    const yaml = `stages:
+  - build
+
+build:
+  stage: build
+  script:
+    - npm run build`;
+    const diags = checkInvalidExtends(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("skips check when include: is present", () => {
+    const yaml = `include:
+  - local: .gitlab/ci/templates.yml
+
+deploy:
+  stage: deploy
+  extends: .deploy-template
+  script:
+    - ./deploy.sh`;
+    const diags = checkInvalidExtends(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("multiple extends targets, one invalid → 1 diagnostic", () => {
+    const yaml = `.base:
+  image: alpine
+
+deploy:
+  stage: deploy
+  extends: [.base, .missing]
+  script:
+    - ./deploy.sh`;
+    const diags = checkInvalidExtends(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain(".missing");
+  });
+});

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

@@ -0,0 +1,51 @@
+/**
+ * WGL014: Invalid `extends:` Target
+ *
+ * Detects jobs that `extends:` a template not defined in the pipeline YAML.
+ * GitLab rejects pipelines with unresolved extends references.
+ *
+ * Caveat: when `include:` is present, templates may come from
+ * included files, so the check is skipped.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractJobs, hasInclude } from "./yaml-helpers";
+
+export function checkInvalidExtends(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [, output] of ctx.outputs) {
+    const yaml = getPrimaryOutput(output);
+    if (hasInclude(yaml)) continue;
+
+    const jobs = extractJobs(yaml);
+    const jobNames = new Set(jobs.keys());
+
+    for (const [jobName, job] of jobs) {
+      if (!job.extends) continue;
+
+      for (const target of job.extends) {
+        if (!jobNames.has(target)) {
+          diagnostics.push({
+            checkId: "WGL014",
+            severity: "error",
+            message: `Job "${jobName}" extends "${target}" which is not defined in the pipeline`,
+            entity: jobName,
+            lexicon: "gitlab",
+          });
+        }
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const wgl014: PostSynthCheck = {
+  id: "WGL014",
+  description: "Invalid extends: target — references a template not in the pipeline",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkInvalidExtends(ctx);
+  },
+};