@intentius/chant 0.0.1

package/src/lexicon-schema.test.ts

@@ -0,0 +1,239 @@
+import { describe, test, expect } from "bun:test";
+import {
+  validateManifest,
+  validateRegistry,
+  LexiconManifestSchema,
+  IntrinsicDefSchema,
+  LexiconEntrySchema,
+} from "./lexicon-schema";
+
+// ---------------------------------------------------------------------------
+// validateManifest
+// ---------------------------------------------------------------------------
+
+describe("validateManifest (Zod)", () => {
+  test("parses valid manifest object", () => {
+    const m = validateManifest({
+      name: "testdom",
+      version: "1.0.0",
+      chantVersion: ">=0.1.0",
+      namespace: "TST",
+      intrinsics: [{ name: "Interpolate", outputKey: "Fn::Interpolate", isTag: true }],
+      pseudoParameters: { StackName: "TestDom::StackName" },
+    });
+    expect(m.name).toBe("testdom");
+    expect(m.version).toBe("1.0.0");
+    expect(m.chantVersion).toBe(">=0.1.0");
+    expect(m.namespace).toBe("TST");
+    expect(m.intrinsics).toHaveLength(1);
+    expect(m.pseudoParameters?.StackName).toBe("TestDom::StackName");
+  });
+
+  test("parses valid JSON string", () => {
+    const m = validateManifest(JSON.stringify({ name: "testdom", version: "0.1.0" }));
+    expect(m.name).toBe("testdom");
+    expect(m.version).toBe("0.1.0");
+  });
+
+  test("optional fields can be omitted", () => {
+    const m = validateManifest({ name: "gcp", version: "2.0.0" });
+    expect(m.chantVersion).toBeUndefined();
+    expect(m.namespace).toBeUndefined();
+    expect(m.intrinsics).toBeUndefined();
+    expect(m.pseudoParameters).toBeUndefined();
+  });
+
+  test("throws on empty data (null/undefined)", () => {
+    expect(() => validateManifest(null)).toThrow("empty");
+    expect(() => validateManifest(undefined)).toThrow("empty");
+  });
+
+  test("throws on invalid JSON string", () => {
+    expect(() => validateManifest("{bad json")).toThrow("invalid JSON");
+  });
+
+  test("throws on non-object types", () => {
+    expect(() => validateManifest(42)).toThrow("must be a JSON object");
+    expect(() => validateManifest([])).toThrow("must be a JSON object");
+    expect(() => validateManifest(true)).toThrow("must be a JSON object");
+  });
+
+  test("throws on missing name", () => {
+    expect(() => validateManifest({ version: "1.0.0" })).toThrow();
+  });
+
+  test("throws on empty name", () => {
+    expect(() => validateManifest({ name: "", version: "1.0.0" })).toThrow("name");
+  });
+
+  test("throws on missing version", () => {
+    expect(() => validateManifest({ name: "testdom" })).toThrow();
+  });
+
+  test("throws on invalid semver version", () => {
+    expect(() => validateManifest({ name: "testdom", version: "not-a-version" })).toThrow("version");
+  });
+
+  test("accepts prerelease and build metadata in version", () => {
+    const m = validateManifest({ name: "testdom", version: "1.0.0-alpha.1" });
+    expect(m.version).toBe("1.0.0-alpha.1");
+
+    const m2 = validateManifest({ name: "testdom", version: "1.0.0+build.42" });
+    expect(m2.version).toBe("1.0.0+build.42");
+  });
+
+  test("rejects intrinsic with empty name", () => {
+    expect(() =>
+      validateManifest({
+        name: "testdom",
+        version: "1.0.0",
+        intrinsics: [{ name: "" }],
+      }),
+    ).toThrow("name");
+  });
+
+  test("error path includes field location for nested intrinsic error", () => {
+    try {
+      validateManifest({
+        name: "testdom",
+        version: "1.0.0",
+        intrinsics: [{ name: "" }],
+      });
+      expect(true).toBe(false); // should not reach
+    } catch (err: unknown) {
+      const msg = (err as Error).message;
+      expect(msg).toContain("intrinsics");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// IntrinsicDefSchema direct
+// ---------------------------------------------------------------------------
+
+describe("IntrinsicDefSchema", () => {
+  test("valid intrinsic passes", () => {
+    const result = IntrinsicDefSchema.safeParse({
+      name: "Ref",
+      description: "Reference function",
+      outputKey: "Ref",
+      isTag: false,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects empty name", () => {
+    const result = IntrinsicDefSchema.safeParse({ name: "" });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects missing name", () => {
+    const result = IntrinsicDefSchema.safeParse({ description: "no name" });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// LexiconEntrySchema direct
+// ---------------------------------------------------------------------------
+
+describe("LexiconEntrySchema", () => {
+  test("valid resource entry", () => {
+    const result = LexiconEntrySchema.safeParse({
+      resourceType: "TestDom::Storage::Bucket",
+      kind: "resource",
+      lexicon: "testdom",
+      attrs: { bucketArn: "BucketArn" },
+      createOnly: ["/properties/BucketName"],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("valid property entry (minimal)", () => {
+    const result = LexiconEntrySchema.safeParse({
+      resourceType: "TestDom::Storage::Bucket.LifecycleRule",
+      kind: "property",
+      lexicon: "testdom",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("rejects invalid kind", () => {
+    const result = LexiconEntrySchema.safeParse({
+      resourceType: "Foo",
+      kind: "unknown",
+      lexicon: "testdom",
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateRegistry
+// ---------------------------------------------------------------------------
+
+describe("validateRegistry", () => {
+  test("parses valid registry JSON", () => {
+    const registry = validateRegistry(
+      JSON.stringify({
+        S3Bucket: {
+          resourceType: "TestDom::Storage::Bucket",
+          kind: "resource",
+          lexicon: "testdom",
+        },
+        LambdaFunction: {
+          resourceType: "TestDom::Compute::Function",
+          kind: "resource",
+          lexicon: "testdom",
+          runtimeDeprecations: { "nodejs14.x": "deprecated" },
+        },
+      }),
+    );
+    expect(Object.keys(registry)).toHaveLength(2);
+    expect(registry.S3Bucket.kind).toBe("resource");
+    expect(registry.LambdaFunction.runtimeDeprecations?.["nodejs14.x"]).toBe("deprecated");
+  });
+
+  test("throws on invalid JSON", () => {
+    expect(() => validateRegistry("not json")).toThrow("invalid JSON");
+  });
+
+  test("throws on malformed registry entry", () => {
+    expect(() =>
+      validateRegistry(
+        JSON.stringify({
+          BadEntry: { resourceType: 123, kind: "resource", lexicon: "testdom" },
+        }),
+      ),
+    ).toThrow();
+  });
+
+  test("throws on registry with invalid kind enum", () => {
+    expect(() =>
+      validateRegistry(
+        JSON.stringify({
+          BadEntry: { resourceType: "Foo", kind: "module", lexicon: "testdom" },
+        }),
+      ),
+    ).toThrow();
+  });
+
+  test("throws on non-object registry value", () => {
+    expect(() => validateRegistry(JSON.stringify({ entry: "not an object" }))).toThrow();
+  });
+
+  test("error message includes path for nested issues", () => {
+    try {
+      validateRegistry(
+        JSON.stringify({
+          MyEntry: { resourceType: "Foo", kind: "bad", lexicon: "testdom" },
+        }),
+      );
+      expect(true).toBe(false);
+    } catch (err: unknown) {
+      const msg = (err as Error).message;
+      // Should include the key or path info
+      expect(msg).toContain("registry");
+    }
+  });
+});

package/src/lexicon-schema.ts

@@ -0,0 +1,144 @@
+/**
+ * Zod schemas for lexicon manifest and registry validation.
+ */
+
+import { z } from "zod";
+import type { LexiconManifest, IntrinsicDef } from "./lexicon";
+
+// ---------------------------------------------------------------------------
+// Intrinsic definitions
+// ---------------------------------------------------------------------------
+
+export const IntrinsicDefSchema = z.object({
+  name: z.string().min(1, "intrinsic name must not be empty"),
+  description: z.string().optional(),
+  outputKey: z.string().optional(),
+  isTag: z.boolean().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Lexicon manifest
+// ---------------------------------------------------------------------------
+
+const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/;
+
+export const LexiconManifestSchema = z.object({
+  name: z.string().min(1, "manifest name must not be empty"),
+  version: z.string().regex(semverRegex, "version must be valid semver (X.Y.Z)"),
+  chantVersion: z.string().optional(),
+  namespace: z.string().optional(),
+  intrinsics: z.array(IntrinsicDefSchema).optional(),
+  pseudoParameters: z.record(z.string(), z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Extension constraint schema (matches ExtensionConstraint from lexicon packages)
+// ---------------------------------------------------------------------------
+
+const ExtensionConstraintSchema = z.object({
+  name: z.string(),
+  type: z.enum(["if_then", "dependent_excluded", "required_or", "required_xor"]),
+  condition: z.unknown().optional(),
+  requirement: z.unknown().optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Property constraints schema (matches PropertyConstraints from lexicon packages)
+// ---------------------------------------------------------------------------
+
+const PropertyConstraintsSchema = z.object({
+  pattern: z.string().optional(),
+  minLength: z.number().optional(),
+  maxLength: z.number().optional(),
+  minimum: z.number().optional(),
+  maximum: z.number().optional(),
+  format: z.string().optional(),
+  const: z.unknown().optional(),
+  default: z.unknown().optional(),
+  enum: z.array(z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Lexicon entry (registry entry for a resource or property type)
+// ---------------------------------------------------------------------------
+
+export const LexiconEntrySchema = z.object({
+  resourceType: z.string(),
+  kind: z.enum(["resource", "property"]),
+  lexicon: z.string(),
+  attrs: z.record(z.string(), z.string()).optional(),
+  constraints: z.array(ExtensionConstraintSchema).optional(),
+  propertyConstraints: z.record(z.string(), PropertyConstraintsSchema).optional(),
+  createOnly: z.array(z.string()).optional(),
+  writeOnly: z.array(z.string()).optional(),
+  primaryIdentifier: z.array(z.string()).optional(),
+  runtimeDeprecations: z.record(z.string(), z.string()).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Inferred types (useful for consumers who don't import the interface types)
+// ---------------------------------------------------------------------------
+
+export type LexiconEntryParsed = z.infer<typeof LexiconEntrySchema>;
+
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a manifest from unknown input (object or JSON string).
+ * Throws a descriptive error on invalid input.
+ */
+export function validateManifest(data: unknown): LexiconManifest {
+  if (data === null || data === undefined) {
+    throw new Error("manifest data is empty");
+  }
+
+  if (typeof data === "string") {
+    try {
+      data = JSON.parse(data);
+    } catch (err) {
+      const msg = err instanceof SyntaxError ? err.message : String(err);
+      throw new Error(`invalid JSON in manifest: ${msg}`);
+    }
+  }
+
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error("manifest must be a JSON object");
+  }
+
+  const result = LexiconManifestSchema.safeParse(data);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+    const prefix = path ? `manifest field ${path}` : "manifest";
+    throw new Error(`${prefix}: ${issue.message}`);
+  }
+
+  return result.data as LexiconManifest;
+}
+
+/**
+ * Validate a registry JSON string into a typed record.
+ * Throws a descriptive error on invalid input.
+ */
+export function validateRegistry(json: string): Record<string, LexiconEntryParsed> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    const msg = err instanceof SyntaxError ? err.message : String(err);
+    throw new Error(`invalid JSON in registry: ${msg}`);
+  }
+
+  const schema = z.record(z.string(), LexiconEntrySchema);
+  const result = schema.safeParse(parsed);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+    const prefix = path ? `registry[${path}]` : "registry";
+    throw new Error(`${prefix}: ${issue.message}`);
+  }
+
+  return result.data;
+}

package/src/lexicon.ts

@@ -0,0 +1,212 @@
+import type { Serializer } from "./serializer";
+import type { LintRule } from "./lint/rule";
+import type { RuleSpec } from "./lint/declarative";
+import type { PostSynthCheck } from "./lint/post-synth";
+import type { TemplateParser } from "./import/parser";
+import type { TypeScriptGenerator } from "./import/generator";
+import type { ArtifactIntegrity } from "./lexicon-integrity";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
+
+/**
+ * Manifest for a packaged lexicon — metadata embedded in the tarball.
+ */
+export interface LexiconManifest {
+  name: string;
+  version: string;
+  chantVersion?: string;
+  namespace?: string;
+  intrinsics?: IntrinsicDef[];
+  pseudoParameters?: Record<string, string>;
+}
+
+/**
+ * Metadata about when and how a package was generated.
+ */
+export interface PackageMetadata {
+  generatedAt: string;
+  chantVersion: string;
+  generatorVersion: string;
+  sourceSchemaCount: number;
+}
+
+/**
+ * Container for all artifacts in a lexicon bundle.
+ */
+export interface BundleSpec {
+  manifest: LexiconManifest;
+  registry: string;
+  typesDTS: string;
+  rules: Map<string, string>;
+  skills: Map<string, string>;
+  integrity?: ArtifactIntegrity;
+  metadata?: PackageMetadata;
+}
+
+/**
+ * Trigger that determines when a skill should be suggested.
+ */
+export interface SkillTrigger {
+  type: "command" | "file-pattern" | "context";
+  value: string;
+}
+
+/**
+ * Parameter definition for a skill.
+ */
+export interface SkillParameter {
+  name: string;
+  description: string;
+  type: string;
+  required?: boolean;
+  default?: string;
+}
+
+/**
+ * Example showing how a skill is used.
+ */
+export interface SkillExample {
+  title: string;
+  description?: string;
+  input?: string;
+  output?: string;
+}
+
+/**
+ * Definition of a skill provided by a lexicon plugin.
+ * Content is full markdown with optional YAML frontmatter.
+ */
+export interface SkillDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly content: string;
+  readonly triggers?: SkillTrigger[];
+  readonly parameters?: SkillParameter[];
+  readonly examples?: SkillExample[];
+  readonly preConditions?: string[];
+  readonly postConditions?: string[];
+}
+
+/**
+ * Definition of a lexicon-specific intrinsic function
+ */
+export interface IntrinsicDef {
+  readonly name: string;
+  readonly description?: string;
+  readonly outputKey?: string;
+  readonly isTag?: boolean;
+}
+
+/**
+ * Plugin interface for lexicon packages.
+ *
+ * Required lifecycle methods enforce consistency: every lexicon must support
+ * generate, validate, coverage, package, and rollback operations.
+ */
+export interface LexiconPlugin {
+  // ── Required ──────────────────────────────────────────────
+  /** Human-readable name (e.g. "aws", "gcp") */
+  readonly name: string;
+
+  /** Serializer for build output */
+  readonly serializer: Serializer;
+
+  /** Generate lexicon artifacts (types, lexicon JSON, runtime) from spec */
+  generate(options?: { verbose?: boolean }): Promise<void>;
+
+  /** Validate generated lexicon artifacts */
+  validate(options?: { verbose?: boolean }): Promise<void>;
+
+  /** Analyze lexicon coverage across resource dimensions */
+  coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void>;
+
+  /** Package lexicon into distributable tarball */
+  package(options?: { verbose?: boolean; force?: boolean }): Promise<void>;
+
+  /** List or restore generation snapshots */
+  rollback(options?: { restore?: string; verbose?: boolean }): Promise<void>;
+
+  // ── Optional extensions ───────────────────────────────────
+  /** Return lint rules provided by this lexicon */
+  lintRules?(): LintRule[];
+
+  /** Return declarative rule specs for compilation via rule() */
+  declarativeRules?(): RuleSpec[];
+
+  /** Return post-synthesis checks for build validation */
+  postSynthChecks?(): PostSynthCheck[];
+
+  /** Return intrinsic function definitions */
+  intrinsics?(): IntrinsicDef[];
+
+  /** Return pseudo-parameter names (e.g. "MyDomain::StackName") */
+  pseudoParameters?(): string[];
+
+  /**
+   * Detect whether raw template content belongs to this lexicon.
+   * @param data - Parsed JSON object from a template file
+   * @returns true if this plugin can handle the template
+   */
+  detectTemplate?(data: unknown): boolean;
+
+  /** Return a parser for importing external templates into IR */
+  templateParser?(): TemplateParser;
+
+  /** Return a generator for converting IR to TypeScript */
+  templateGenerator?(): TypeScriptGenerator;
+
+  /** Return skills provided by this lexicon */
+  skills?(): SkillDefinition[];
+
+  /** Return source file templates for `chant init` project scaffolding */
+  initTemplates?(): Record<string, string>;
+
+  /** Optional initialization hook */
+  init?(): void | Promise<void>;
+
+  // LSP
+  /** Provide completions for LSP */
+  completionProvider?(ctx: CompletionContext): CompletionItem[];
+
+  /** Provide hover information for LSP */
+  hoverProvider?(ctx: HoverContext): HoverInfo | undefined;
+
+  /** Provide code actions for LSP */
+  codeActionProvider?(ctx: CodeActionContext): CodeAction[];
+
+  // Docs
+  /** Generate documentation pages */
+  docs?(options?: { verbose?: boolean }): Promise<void>;
+
+  // MCP
+  /** Return MCP tool contributions */
+  mcpTools?(): McpToolContribution[];
+
+  /** Return MCP resource contributions */
+  mcpResources?(): McpResourceContribution[];
+}
+
+/**
+ * Type guard to check if a value is a LexiconPlugin.
+ * Checks for required lifecycle methods in addition to name/serializer.
+ */
+export function isLexiconPlugin(value: unknown): value is LexiconPlugin {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("name" in value) ||
+    typeof (value as Record<string, unknown>).name !== "string" ||
+    !("serializer" in value) ||
+    typeof (value as Record<string, unknown>).serializer !== "object"
+  ) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.generate === "function" &&
+    typeof obj.validate === "function" &&
+    typeof obj.coverage === "function" &&
+    typeof obj.package === "function" &&
+    typeof obj.rollback === "function"
+  );
+}