@intentius/chant-lexicon-gcp 0.0.15

package/src/composites/vpc-network.ts

@@ -0,0 +1,165 @@
+/**
+ * VpcNetwork composite — ComputeNetwork + ComputeSubnetwork + ComputeFirewall + ComputeRouterNAT.
+ */
+
+export interface VpcSubnet {
+  /** Subnet name suffix. */
+  name: string;
+  /** IP CIDR range. */
+  ipCidrRange: string;
+  /** GCP region. */
+  region: string;
+  /** Enable private Google access (default: true). */
+  privateIpGoogleAccess?: boolean;
+}
+
+export interface VpcNetworkProps {
+  /** Network name. */
+  name: string;
+  /** Auto-create subnetworks (default: false — custom mode). */
+  autoCreateSubnetworks?: boolean;
+  /** Subnets to create in custom mode. */
+  subnets?: VpcSubnet[];
+  /** Enable Cloud NAT for outbound internet access (default: false). */
+  enableNat?: boolean;
+  /** NAT region (required if enableNat is true). */
+  natRegion?: string;
+  /** Allow internal traffic firewall rule (default: true). */
+  allowInternalTraffic?: boolean;
+  /** Allow SSH from IAP (default: false). */
+  allowIapSsh?: boolean;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** Namespace for all resources. */
+  namespace?: string;
+}
+
+export interface VpcNetworkResult {
+  network: Record<string, unknown>;
+  subnets: Record<string, unknown>[];
+  firewalls: Record<string, unknown>[];
+  router?: Record<string, unknown>;
+  routerNat?: Record<string, unknown>;
+}
+
+/**
+ * Create a VpcNetwork composite.
+ *
+ * @example
+ * ```ts
+ * import { VpcNetwork } from "@intentius/chant-lexicon-gcp";
+ *
+ * const { network, subnets, firewalls } = VpcNetwork({
+ *   name: "my-vpc",
+ *   subnets: [
+ *     { name: "app", ipCidrRange: "10.0.0.0/24", region: "us-central1" },
+ *     { name: "data", ipCidrRange: "10.0.1.0/24", region: "us-central1" },
+ *   ],
+ *   enableNat: true,
+ *   natRegion: "us-central1",
+ * });
+ * ```
+ */
+export function VpcNetwork(props: VpcNetworkProps): VpcNetworkResult {
+  const {
+    name,
+    autoCreateSubnetworks = false,
+    subnets: subnetDefs = [],
+    enableNat = false,
+    natRegion,
+    allowInternalTraffic = true,
+    allowIapSsh = false,
+    labels: extraLabels = {},
+    namespace,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  const network: Record<string, unknown> = {
+    metadata: {
+      name,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "network" },
+    },
+    autoCreateSubnetworks,
+    routingMode: "REGIONAL",
+  };
+
+  const subnets: Record<string, unknown>[] = subnetDefs.map((sub) => ({
+    metadata: {
+      name: `${name}-${sub.name}`,
+      ...(namespace && { namespace }),
+      labels: { ...commonLabels, "app.kubernetes.io/component": "subnet" },
+    },
+    networkRef: { name },
+    ipCidrRange: sub.ipCidrRange,
+    region: sub.region,
+    privateIpGoogleAccess: sub.privateIpGoogleAccess ?? true,
+  }));
+
+  const firewalls: Record<string, unknown>[] = [];
+
+  if (allowInternalTraffic) {
+    firewalls.push({
+      metadata: {
+        name: `${name}-allow-internal`,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "firewall" },
+      },
+      networkRef: { name },
+      allowed: [
+        { protocol: "tcp", ports: ["0-65535"] },
+        { protocol: "udp", ports: ["0-65535"] },
+        { protocol: "icmp" },
+      ],
+      sourceRanges: subnetDefs.map((s) => s.ipCidrRange),
+    });
+  }
+
+  if (allowIapSsh) {
+    firewalls.push({
+      metadata: {
+        name: `${name}-allow-iap-ssh`,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "firewall" },
+      },
+      networkRef: { name },
+      allowed: [{ protocol: "tcp", ports: ["22"] }],
+      sourceRanges: ["35.235.240.0/20"], // IAP IP range
+    });
+  }
+
+  const result: VpcNetworkResult = { network, subnets, firewalls };
+
+  if (enableNat && natRegion) {
+    const routerName = `${name}-router`;
+
+    result.router = {
+      metadata: {
+        name: routerName,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "router" },
+      },
+      networkRef: { name },
+      region: natRegion,
+    };
+
+    result.routerNat = {
+      metadata: {
+        name: `${name}-nat`,
+        ...(namespace && { namespace }),
+        labels: { ...commonLabels, "app.kubernetes.io/component": "nat" },
+      },
+      routerRef: { name: routerName },
+      region: natRegion,
+      natIpAllocateOption: "AUTO_ONLY",
+      sourceSubnetworkIpRangesToNat: "ALL_SUBNETWORKS_ALL_IP_RANGES",
+    };
+  }
+
+  return result;
+}

package/src/coverage.test.ts

@@ -0,0 +1,27 @@
+import { describe, test, expect } from "bun:test";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const generatedDir = join(pkgDir, "src", "generated");
+const hasGenerated = existsSync(join(generatedDir, "lexicon-gcp.json"));
+
+describe("coverage", () => {
+  test.skipIf(!hasGenerated)("analyzeGcpCoverage function exists", async () => {
+    const { analyzeGcpCoverage } = await import("./coverage");
+    expect(typeof analyzeGcpCoverage).toBe("function");
+  });
+
+  test("handles missing generated files gracefully", async () => {
+    const { analyzeGcpCoverage } = await import("./coverage");
+    // If generated files don't exist, this should throw/exit rather than crash
+    if (!hasGenerated) {
+      try {
+        await analyzeGcpCoverage();
+      } catch {
+        // Expected — no generated files
+      }
+    }
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,51 @@
+/**
+ * GCP lexicon coverage analysis.
+ */
+
+import {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type CoverageReport,
+} from "@intentius/chant/codegen/coverage";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+export {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type ResourceCoverage,
+  type CoverageReport,
+  type CoverageThresholds,
+  type ThresholdResult,
+} from "@intentius/chant/codegen/coverage";
+
+export async function analyzeGcpCoverage(opts?: {
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<void> {
+  const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+  const lexiconPath = join(pkgDir, "src", "generated", "lexicon-gcp.json");
+  const content = readFileSync(lexiconPath, "utf-8");
+  const report = computeCoverage(content);
+
+  if (opts?.verbose) {
+    console.log(formatVerbose(report));
+  } else {
+    console.log(formatSummary(report));
+  }
+
+  if (typeof opts?.minOverall === "number") {
+    const result = checkThresholds(report, { minOverallPct: opts.minOverall });
+    if (!result.ok) {
+      for (const v of result.violations) console.error(`  FAIL: ${v}`);
+      throw new Error("Coverage below threshold");
+    }
+  }
+}

package/src/default-labels.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "bun:test";
+import {
+  defaultLabels,
+  defaultAnnotations,
+  isDefaultLabels,
+  isDefaultAnnotations,
+  DEFAULT_LABELS_MARKER,
+  DEFAULT_ANNOTATIONS_MARKER,
+} from "./default-labels";
+import { DECLARABLE_MARKER } from "@intentius/chant/declarable";
+
+describe("defaultLabels", () => {
+  test("returns object with correct markers", () => {
+    const dl = defaultLabels({ env: "prod" });
+    expect(dl[DEFAULT_LABELS_MARKER]).toBe(true);
+    expect(dl[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("has lexicon gcp", () => {
+    const dl = defaultLabels({ env: "prod" });
+    expect(dl.lexicon).toBe("gcp");
+  });
+
+  test("has correct entityType", () => {
+    const dl = defaultLabels({ env: "prod" });
+    expect(dl.entityType).toBe("chant:gcp:defaultLabels");
+  });
+
+  test("labels are accessible", () => {
+    const dl = defaultLabels({ env: "prod", team: "platform" });
+    expect(dl.labels.env).toBe("prod");
+    expect(dl.labels.team).toBe("platform");
+  });
+
+  test("empty labels allowed", () => {
+    const dl = defaultLabels({});
+    expect(dl.labels).toEqual({});
+  });
+});
+
+describe("defaultAnnotations", () => {
+  test("returns object with correct markers", () => {
+    const da = defaultAnnotations({ "cnrm.cloud.google.com/project-id": "my-project" });
+    expect(da[DEFAULT_ANNOTATIONS_MARKER]).toBe(true);
+    expect(da[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("has lexicon gcp", () => {
+    const da = defaultAnnotations({ note: "hello" });
+    expect(da.lexicon).toBe("gcp");
+  });
+
+  test("has correct entityType", () => {
+    const da = defaultAnnotations({ note: "hello" });
+    expect(da.entityType).toBe("chant:gcp:defaultAnnotations");
+  });
+
+  test("annotations are accessible", () => {
+    const da = defaultAnnotations({ "cnrm.cloud.google.com/project-id": "my-project" });
+    expect(da.annotations["cnrm.cloud.google.com/project-id"]).toBe("my-project");
+  });
+
+  test("empty annotations allowed", () => {
+    const da = defaultAnnotations({});
+    expect(da.annotations).toEqual({});
+  });
+});
+
+describe("isDefaultLabels", () => {
+  test("returns true for defaultLabels result", () => {
+    expect(isDefaultLabels(defaultLabels({ env: "prod" }))).toBe(true);
+  });
+
+  test("returns false for null", () => {
+    expect(isDefaultLabels(null)).toBe(false);
+  });
+
+  test("returns false for undefined", () => {
+    expect(isDefaultLabels(undefined)).toBe(false);
+  });
+
+  test("returns false for regular objects", () => {
+    expect(isDefaultLabels({ labels: { env: "prod" } })).toBe(false);
+  });
+
+  test("returns false for defaultAnnotations", () => {
+    expect(isDefaultLabels(defaultAnnotations({ note: "hi" }))).toBe(false);
+  });
+});
+
+describe("isDefaultAnnotations", () => {
+  test("returns true for defaultAnnotations result", () => {
+    expect(isDefaultAnnotations(defaultAnnotations({ note: "hi" }))).toBe(true);
+  });
+
+  test("returns false for null", () => {
+    expect(isDefaultAnnotations(null)).toBe(false);
+  });
+
+  test("returns false for undefined", () => {
+    expect(isDefaultAnnotations(undefined)).toBe(false);
+  });
+
+  test("returns false for regular objects", () => {
+    expect(isDefaultAnnotations({ annotations: {} })).toBe(false);
+  });
+
+  test("returns false for defaultLabels", () => {
+    expect(isDefaultAnnotations(defaultLabels({ env: "prod" }))).toBe(false);
+  });
+});

package/src/default-labels.ts

@@ -0,0 +1,93 @@
+/**
+ * Default Labels & Annotations — declares project-wide labels/annotations
+ * for all GCP Config Connector resources.
+ *
+ * When a project exports a `defaultLabels(...)` or `defaultAnnotations(...)`
+ * declaration, the serializer automatically injects them into every resource's
+ * metadata at synthesis time. Explicit labels/annotations on individual
+ * resources take precedence.
+ */
+
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+
+export const DEFAULT_LABELS_MARKER = Symbol.for("chant.gcp.defaultLabels");
+export const DEFAULT_ANNOTATIONS_MARKER = Symbol.for("chant.gcp.defaultAnnotations");
+
+export interface DefaultLabels extends Declarable {
+  readonly [DEFAULT_LABELS_MARKER]: true;
+  readonly [DECLARABLE_MARKER]: true;
+  readonly lexicon: "gcp";
+  readonly entityType: "chant:gcp:defaultLabels";
+  readonly labels: Record<string, unknown>;
+}
+
+export interface DefaultAnnotations extends Declarable {
+  readonly [DEFAULT_ANNOTATIONS_MARKER]: true;
+  readonly [DECLARABLE_MARKER]: true;
+  readonly lexicon: "gcp";
+  readonly entityType: "chant:gcp:defaultAnnotations";
+  readonly annotations: Record<string, unknown>;
+}
+
+export function isDefaultLabels(value: unknown): value is DefaultLabels {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    DEFAULT_LABELS_MARKER in value &&
+    (value as Record<symbol, unknown>)[DEFAULT_LABELS_MARKER] === true
+  );
+}
+
+export function isDefaultAnnotations(value: unknown): value is DefaultAnnotations {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    DEFAULT_ANNOTATIONS_MARKER in value &&
+    (value as Record<symbol, unknown>)[DEFAULT_ANNOTATIONS_MARKER] === true
+  );
+}
+
+/**
+ * Declare project-wide default labels for all GCP Config Connector resources.
+ *
+ * @example
+ * ```ts
+ * import { defaultLabels } from "@intentius/chant-lexicon-gcp";
+ *
+ * export const labels = defaultLabels({
+ *   "app.kubernetes.io/managed-by": "chant",
+ *   "env": "production",
+ * });
+ * ```
+ */
+export function defaultLabels(labels: Record<string, unknown>): DefaultLabels {
+  return {
+    [DEFAULT_LABELS_MARKER]: true,
+    [DECLARABLE_MARKER]: true,
+    lexicon: "gcp",
+    entityType: "chant:gcp:defaultLabels",
+    labels,
+  };
+}
+
+/**
+ * Declare project-wide default annotations for all GCP Config Connector resources.
+ *
+ * @example
+ * ```ts
+ * import { defaultAnnotations, GCP } from "@intentius/chant-lexicon-gcp";
+ *
+ * export const annotations = defaultAnnotations({
+ *   "cnrm.cloud.google.com/project-id": GCP.ProjectId,
+ * });
+ * ```
+ */
+export function defaultAnnotations(annotations: Record<string, unknown>): DefaultAnnotations {
+  return {
+    [DEFAULT_ANNOTATIONS_MARKER]: true,
+    [DECLARABLE_MARKER]: true,
+    lexicon: "gcp",
+    entityType: "chant:gcp:defaultAnnotations",
+    annotations,
+  };
+}