@intentius/chant-lexicon-gcp 0.0.16 → 0.0.22

package/dist/rules/schema-registry.ts

@@ -0,0 +1,91 @@
+/**
+ * Schema registry for GCP Config Connector resources.
+ *
+ * Loads lexicon-gcp.json and builds a lookup from CRD kind to field schema,
+ * used by post-synth rules to validate YAML against known CRD schemas.
+ */
+
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+
+export interface FieldSchema {
+  type: string;
+  required: boolean;
+  enum?: string[];
+  ref?: boolean;
+}
+
+export interface ResourceSchema {
+  fields: Record<string, FieldSchema>;
+  required: string[];
+}
+
+interface LexiconEntry {
+  kind: "resource" | "property";
+  gvkKind?: string;
+  schema?: ResourceSchema;
+}
+
+let cachedRegistry: Map<string, ResourceSchema> | null = null;
+
+/**
+ * Get the schema registry: Map<gvkKind, ResourceSchema>.
+ */
+export function getSchemaRegistry(): Map<string, ResourceSchema> {
+  if (cachedRegistry) return cachedRegistry;
+
+  cachedRegistry = new Map();
+  try {
+    const lexicon = require("../../generated/lexicon-gcp.json") as Record<string, LexiconEntry>;
+    for (const entry of Object.values(lexicon)) {
+      if (entry.kind === "resource" && entry.gvkKind && entry.schema) {
+        cachedRegistry.set(entry.gvkKind, entry.schema);
+      }
+    }
+  } catch {
+    // Lexicon JSON not yet generated — return empty registry
+  }
+
+  return cachedRegistry;
+}
+
+/**
+ * Levenshtein distance between two strings.
+ */
+export function levenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+
+  return dp[m][n];
+}
+
+/**
+ * Find the closest field name by Levenshtein distance.
+ * Returns the suggestion if distance ≤ 3, otherwise undefined.
+ */
+export function suggestField(unknown: string, knownFields: string[]): string | undefined {
+  let best: string | undefined;
+  let bestDist = 4; // threshold
+
+  for (const field of knownFields) {
+    const dist = levenshtein(unknown.toLowerCase(), field.toLowerCase());
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = field;
+    }
+  }
+
+  return best;
+}

package/dist/rules/wgc401.ts

@@ -0,0 +1,59 @@
+/**
+ * WGC401: Unknown spec field
+ *
+ * Flags fields in a Config Connector resource spec that are not defined
+ * in the CRD schema. Includes "did you mean?" suggestion via Levenshtein.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseGcpManifests, isConfigConnectorResource, getResourceName, getSpec } from "./gcp-helpers";
+import { getSchemaRegistry, suggestField } from "./schema-registry";
+
+export const wgc401: PostSynthCheck = {
+  id: "WGC401",
+  description: "Config Connector resource spec contains unknown field",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const registry = getSchemaRegistry();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      if (typeof output !== "string") continue;
+
+      const manifests = parseGcpManifests(output);
+
+      for (const manifest of manifests) {
+        if (!isConfigConnectorResource(manifest)) continue;
+
+        const kind = manifest.kind;
+        if (!kind) continue;
+
+        const schema = registry.get(kind);
+        if (!schema) continue; // No schema available for this kind
+
+        const spec = getSpec(manifest);
+        if (!spec) continue;
+
+        const knownFields = Object.keys(schema.fields);
+        const resourceName = getResourceName(manifest);
+
+        for (const field of Object.keys(spec)) {
+          if (field in schema.fields) continue;
+
+          const suggestion = suggestField(field, knownFields);
+          const hint = suggestion ? ` — did you mean "${suggestion}"?` : "";
+
+          diagnostics.push({
+            checkId: "WGC401",
+            severity: "error",
+            message: `Resource "${resourceName}" (${kind}): unknown spec field "${field}"${hint}`,
+            entity: resourceName,
+            lexicon: "gcp",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wgc402.ts

@@ -0,0 +1,54 @@
+/**
+ * WGC402: Missing required spec field
+ *
+ * Flags Config Connector resources that are missing required fields
+ * according to their CRD schema.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseGcpManifests, isConfigConnectorResource, getResourceName, getSpec } from "./gcp-helpers";
+import { getSchemaRegistry } from "./schema-registry";
+
+export const wgc402: PostSynthCheck = {
+  id: "WGC402",
+  description: "Config Connector resource is missing a required spec field",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const registry = getSchemaRegistry();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      if (typeof output !== "string") continue;
+
+      const manifests = parseGcpManifests(output);
+
+      for (const manifest of manifests) {
+        if (!isConfigConnectorResource(manifest)) continue;
+
+        const kind = manifest.kind;
+        if (!kind) continue;
+
+        const schema = registry.get(kind);
+        if (!schema) continue;
+
+        const spec = getSpec(manifest);
+        const specKeys = new Set(spec ? Object.keys(spec) : []);
+        const resourceName = getResourceName(manifest);
+
+        for (const requiredField of schema.required) {
+          if (!specKeys.has(requiredField)) {
+            diagnostics.push({
+              checkId: "WGC402",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): missing required field "${requiredField}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wgc403.ts

@@ -0,0 +1,84 @@
+/**
+ * WGC403: Type/structure mismatch in spec field
+ *
+ * Flags spec fields where the value type doesn't match the CRD schema:
+ * - String where number expected (e.g. availableMemoryMb: "512")
+ * - Scalar string where resourceRef object expected (e.g. topicRef: "name")
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseGcpManifests, isConfigConnectorResource, getResourceName, getSpec } from "./gcp-helpers";
+import { getSchemaRegistry } from "./schema-registry";
+
+export const wgc403: PostSynthCheck = {
+  id: "WGC403",
+  description: "Config Connector resource spec field has wrong type or structure",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const registry = getSchemaRegistry();
+
+    for (const [_lexicon, output] of ctx.outputs) {
+      if (typeof output !== "string") continue;
+
+      const manifests = parseGcpManifests(output);
+
+      for (const manifest of manifests) {
+        if (!isConfigConnectorResource(manifest)) continue;
+
+        const kind = manifest.kind;
+        if (!kind) continue;
+
+        const schema = registry.get(kind);
+        if (!schema) continue;
+
+        const spec = getSpec(manifest);
+        if (!spec) continue;
+
+        const resourceName = getResourceName(manifest);
+
+        for (const [field, value] of Object.entries(spec)) {
+          const fieldSchema = schema.fields[field];
+          if (!fieldSchema) continue; // Unknown fields handled by WGC401
+
+          // Check: resourceRef field expects an object, got a scalar
+          if (fieldSchema.ref && typeof value === "string") {
+            diagnostics.push({
+              checkId: "WGC403",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): field "${field}" expects a resourceRef object (e.g. { name, kind }), got string "${value}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+            continue;
+          }
+
+          // Check: number field got a string that looks numeric
+          if (fieldSchema.type === "number" && typeof value === "string") {
+            diagnostics.push({
+              checkId: "WGC403",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): field "${field}" expects a number, got string "${value}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+            continue;
+          }
+
+          // Check: boolean field got a string
+          if (fieldSchema.type === "boolean" && typeof value === "string") {
+            diagnostics.push({
+              checkId: "WGC403",
+              severity: "error",
+              message: `Resource "${resourceName}" (${kind}): field "${field}" expects a boolean, got string "${value}"`,
+              entity: resourceName,
+              lexicon: "gcp",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-gcp.md

@@ -9,7 +9,7 @@ user-invocable: true
 
 ## How chant and Config Connector relate
 
-chant is a **synthesis-only** tool — it compiles TypeScript source files into Config Connector YAML manifests. chant does NOT call GCP APIs. Your job as an agent is to bridge the two:
+chant is a **synthesis compiler** — it compiles TypeScript source files into Config Connector YAML manifests. `chant build` does not call GCP APIs; synthesis is pure and deterministic. Config Connector resources are Kubernetes objects, so the optional `chant state snapshot` command queries the Kubernetes API to capture deployment metadata (resource status, conditions, observed state) for observability. Your job as an agent is to bridge synthesis and deployment:
 
 - Use **chant** for: build, lint, diff (local YAML comparison)
 - Use **kubectl** for: apply, rollback, monitoring, troubleshooting
@@ -49,6 +49,9 @@ chant lint src/
 # Build
 chant build src/ --output manifests.yaml
 
+# See what changed since last deploy (compares current build against last snapshot's digest)
+chant state diff staging gcp
+
 # Dry run
 kubectl apply -f manifests.yaml --dry-run=server
 

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.0.16",
+  "version": "0.0.22",
+  "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intentius/chant.git",
+    "directory": "lexicons/gcp"
+  },
+  "bugs": {
+    "url": "https://github.com/intentius/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "gcp",
+    "google-cloud",
+    "chant"
+  ],
   "type": "module",
   "files": [
     "src/",
@@ -25,7 +43,7 @@
     "prepack": "bun run generate && bun run bundle && bun run validate"
   },
   "dependencies": {
-    "@intentius/chant": "0.0.15",
+    "@intentius/chant": "0.0.22",
     "fflate": "^0.8.2",
     "js-yaml": "^4.1.0"
   },

package/src/codegen/docs.test.ts

@@ -0,0 +1,16 @@
+import { describe, test, expect } from "bun:test";
+import { generateDocs } from "./docs";
+
+describe("generateDocs", () => {
+  test("generateDocs function exists and is callable", () => {
+    expect(typeof generateDocs).toBe("function");
+  });
+
+  test("generateDocs returns a promise", () => {
+    const result = generateDocs({ verbose: false });
+    expect(result).toBeDefined();
+    expect(typeof result.then).toBe("function");
+    // Suppress unhandled rejection if it fails due to missing data
+    result.catch(() => {});
+  });
+});

package/src/codegen/docs.ts

@@ -807,6 +807,9 @@ The \`chant-gcp\` skill covers:
 | \`examples/basic-bucket\` | Example StorageBucket code |`,
       },
     ],
+    sidebarExtra: [
+      { label: "Deploying to GKE", slug: "gke-kubernetes" },
+    ],
   };
 
   const result = docsPipeline(config);

package/src/codegen/generate.test.ts

@@ -0,0 +1,18 @@
+import { describe, test, expect } from "bun:test";
+import { generate } from "./generate";
+
+describe("generate", () => {
+  test("generate function exists and is callable", () => {
+    expect(typeof generate).toBe("function");
+  });
+
+  test("generate returns a promise", { timeout: 15000 }, () => {
+    // Call with no-op options to verify it returns a promise-like object.
+    // We don't await because it may require network/file access.
+    const result = generate({ dryRun: true });
+    expect(result).toBeDefined();
+    expect(typeof result.then).toBe("function");
+    // Suppress unhandled rejection if it fails due to missing spec
+    result.catch(() => {});
+  });
+});

package/src/codegen/generate.ts

@@ -113,6 +113,17 @@ function generateLexiconJSON(results: GcpParseResult[], naming: NamingStrategy):
       gvkKind: r.gvk.kind,
       group: r.gvk.group,
       properties: r.resource.properties.length,
+      schema: {
+        fields: Object.fromEntries(
+          r.resource.properties.map((p) => [p.name, {
+            type: p.tsType,
+            required: p.required,
+            ...(p.enum && { enum: p.enum }),
+            ...(p.isResourceRef && { ref: true }),
+          }]),
+        ),
+        required: r.resource.properties.filter((p) => p.required).map((p) => p.name),
+      },
       attrs: Object.fromEntries(
         r.resource.attributes.map((a) => [a.name, a.tsType]),
       ),

package/src/codegen/package.test.ts

@@ -0,0 +1,16 @@
+import { describe, test, expect } from "bun:test";
+import { packageLexicon } from "./package";
+
+describe("packageLexicon", () => {
+  test("packageLexicon function exists and is callable", () => {
+    expect(typeof packageLexicon).toBe("function");
+  });
+
+  test("packageLexicon returns a promise", () => {
+    const result = packageLexicon({ verbose: false });
+    expect(result).toBeDefined();
+    expect(typeof result.then).toBe("function");
+    // Suppress unhandled rejection if it fails due to missing artifacts
+    result.catch(() => {});
+  });
+});