@intentius/chant 0.0.18 → 0.0.24

package/bin/chant

@@ -15,6 +15,9 @@ MAIN_TS="$SCRIPT_DIR/../src/cli/main.ts"
 
 if command -v bun >/dev/null 2>&1; then
   exec bun "$MAIN_TS" "$@"
-else
+elif command -v npx >/dev/null 2>&1; then
   exec npx tsx "$MAIN_TS" "$@"
+else
+  echo "error: chant requires Bun (https://bun.sh) or Node.js (https://nodejs.org)" >&2
+  exit 1
 fi

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "@intentius/chant",
-  "version": "0.0.18",
+  "version": "0.0.24",
+  "description": "Declarative infrastructure-as-code toolkit — TypeScript on Bun",
   "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intentius/chant.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/intentius/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "declarative",
+    "cloudformation",
+    "aws",
+    "devops"
+  ],
   "type": "module",
   "files": [
     "src/",

package/src/build.test.ts

@@ -189,10 +189,12 @@ export const betaEntity = {
     expect(result.outputs.has("alpha")).toBe(true);
     expect(result.outputs.has("beta")).toBe(true);
 
-    const alphaOutput = JSON.parse(result.outputs.get("alpha")!);
+    const alphaRaw = result.outputs.get("alpha")!;
+    const alphaOutput = JSON.parse(typeof alphaRaw === "string" ? alphaRaw : alphaRaw.primary);
     expect(alphaOutput.alpha).toContain("alphaEntity");
 
-    const betaOutput = JSON.parse(result.outputs.get("beta")!);
+    const betaRaw = result.outputs.get("beta")!;
+    const betaOutput = JSON.parse(typeof betaRaw === "string" ? betaRaw : betaRaw.primary);
     expect(betaOutput.beta).toContain("betaEntity");
   });
 

package/src/build.ts

@@ -29,6 +29,8 @@ export interface BuildResult {
   outputs: Map<string, string | SerializerResult>;
   /** Map of entity name to Declarable entity */
   entities: Map<string, Declarable>;
+  /** Resource-level dependency graph from discovery */
+  dependencies: Map<string, Set<string>>;
   /** Array of warnings encountered during the build */
   warnings: string[];
   /** Array of errors encountered during discovery and build */
@@ -430,6 +432,7 @@ export async function build(
   return {
     outputs,
     entities: discoveryResult.entities,
+    dependencies: discoveryResult.dependencies,
     warnings,
     errors,
     manifest,

package/src/builder.test.ts

@@ -36,6 +36,7 @@ class SimpleResourceBuilder extends Builder<TestResource> {
       throw new Error("Name and type are required");
     }
     return {
+      lexicon: "test",
       entityType: "TestResource",
       [DECLARABLE_MARKER]: true,
       name: this.name,
@@ -72,6 +73,7 @@ class ValidatedResourceBuilder extends Builder<TestResource> {
       throw new Error("Name and type are required");
     }
     return {
+      lexicon: "test",
       entityType: "TestResource",
       [DECLARABLE_MARKER]: true,
       name: this.name,
@@ -103,6 +105,7 @@ class DefaultsResourceBuilder extends Builder<TestResource> {
 
   build(): TestResource {
     return {
+      lexicon: "test",
       entityType: "TestResource",
       [DECLARABLE_MARKER]: true,
       name: this.name,

package/src/cli/commands/__fixtures__/init-lexicon-output/docs/astro.config.mjs

@@ -8,9 +8,6 @@ export default defineConfig({
       title: 'Fixture',
       sidebar: [
         { label: 'Overview', slug: '' },
-        { label: 'Getting Started', slug: 'getting-started' },
-        { label: 'Serialization', slug: 'serialization' },
-        { label: 'Lint Rules', slug: 'lint-rules' },
       ],
     }),
   ],

package/src/cli/commands/build.ts

@@ -3,6 +3,7 @@ import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks } from "../../lint/post-synth";
 import type { PostSynthCheck } from "../../lint/post-synth";
+import { sortedJsonReplacer } from "../../utils";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { writeFileSync } from "fs";
 import { resolve, dirname, join } from "path";
@@ -214,6 +215,10 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const resourceCount = result.entities.size;
   const fileCount = result.sourceFileCount;
 
+  if (fileCount === 0 && errors.length === 0) {
+    console.error(formatInfo("No source files found — create .ts files in the target directory"));
+  }
+
   if (options.verbose && errors.length === 0) {
     console.error(
       formatSuccess(
@@ -231,18 +236,6 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   };
 }
 
-/**
- * JSON.stringify replacer that sorts object keys for deterministic output
- */
-function sortedJsonReplacer(_key: string, value: unknown): unknown {
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))
-    );
-  }
-  return value;
-}
-
 /**
  * Simple JSON to YAML converter
  */

package/src/cli/commands/diff.test.ts

@@ -86,7 +86,8 @@ export const myBucket = {
     const combined: Record<string, unknown> = {};
     const sortedSerializerNames = [...buildResult.outputs.keys()].sort();
     for (const serializerName of sortedSerializerNames) {
-      combined[serializerName] = JSON.parse(buildResult.outputs.get(serializerName)!);
+      const raw = buildResult.outputs.get(serializerName)!;
+      combined[serializerName] = JSON.parse(typeof raw === "string" ? raw : raw.primary);
     }
 
     // Sort keys to match diffCommand behavior

package/src/cli/commands/diff.ts

@@ -46,7 +46,8 @@ export async function diffCommand(options: DiffOptions): Promise<DiffResult> {
   const combined: Record<string, unknown> = {};
   const sortedLexiconNames = [...result.outputs.keys()].sort();
   for (const lexiconName of sortedLexiconNames) {
-    combined[lexiconName] = JSON.parse(result.outputs.get(lexiconName)!);
+    const raw = result.outputs.get(lexiconName)!;
+    combined[lexiconName] = JSON.parse(typeof raw === "string" ? raw : raw.primary);
   }
   const currentOutput = JSON.stringify(combined, sortedJsonReplacer, 2);
 

package/src/cli/commands/init-lexicon/templates/codegen.ts

@@ -0,0 +1,188 @@
+/**
+ * Codegen template generators for init-lexicon scaffold.
+ */
+
+export function generateCodegenGenerateTs(): string {
+  return `import { generatePipeline, writeGeneratedArtifacts } from "@intentius/chant/codegen/generate";
+import type { GenerateResult } from "@intentius/chant/codegen/generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Run the code generation pipeline.
+ *
+ * Each callback has a TODO describing what to implement.
+ */
+export async function generate(options?: { verbose?: boolean }): Promise<GenerateResult> {
+  const result = await generatePipeline({
+    // Must return Map<typeName, Buffer> — each entry is one schema file.
+    // Example: fetch a zip, extract JSON files, key by type name.
+    // See lexicons/aws/src/spec/fetch.ts for a working example.
+    fetchSchemas: async (opts) => {
+      throw new Error("TODO: implement fetchSchemas — download your upstream spec");
+    },
+
+    // Must return a ParsedResult (with propertyTypes[] and enums[] at minimum).
+    // Return null to skip a schema file.
+    // See lexicons/aws/src/spec/parse.ts for a working example.
+    parseSchema: (name, data) => {
+      throw new Error("TODO: implement parseSchema — parse a single schema file");
+    },
+
+    // Must return a NamingStrategy instance.
+    // See lexicons/aws/src/codegen/naming.ts and ./naming.ts for setup.
+    createNaming: (results) => {
+      throw new Error("TODO: implement createNaming — return a NamingStrategy instance");
+    },
+
+    // Must return a string of JSON (the lexicon registry).
+    // Use buildRegistry + serializeRegistry from @intentius/chant/codegen/generate-registry.
+    // See lexicons/aws/src/codegen/generate.ts for a working example.
+    generateRegistry: (results, naming) => {
+      throw new Error("TODO: implement generateRegistry — produce lexicon JSON");
+    },
+
+    // Must return a string of TypeScript declarations (.d.ts content).
+    // See lexicons/aws/src/codegen/generate.ts for a working example.
+    generateTypes: (results, naming) => {
+      throw new Error("TODO: implement generateTypes — produce .d.ts content");
+    },
+
+    // Must return a string of TypeScript (runtime index with factory exports).
+    // Use generateRuntimeIndex from @intentius/chant/codegen/generate-runtime-index.
+    // See lexicons/aws/src/codegen/generate.ts for a working example.
+    generateRuntimeIndex: (results, naming) => {
+      throw new Error("TODO: implement generateRuntimeIndex — produce index.ts content");
+    },
+  });
+
+  if (options?.verbose) {
+    console.error(\`Generated \${result.resources} resources, \${result.properties} property types\`);
+  }
+
+  return result;
+}
+
+/**
+ * Write generated files to the package directory.
+ */
+export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
+  const dir = pkgDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  writeGeneratedArtifacts({
+    baseDir: dir,
+    files: {
+      "lexicon.json": result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+    },
+  });
+}
+`;
+}
+
+export function generateCodegenGenerateCliTs(): string {
+  return `#!/usr/bin/env bun
+import { generate, writeGeneratedFiles } from "./generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const result = await generate({ verbose: true });
+writeGeneratedFiles(result, pkgDir);
+`;
+}
+
+export function generateCodegenNamingTs(): string {
+  return `import { NamingStrategy, type NamingConfig, type NamingInput } from "@intentius/chant/codegen/naming";
+
+/**
+ * Naming configuration for this lexicon.
+ *
+ * TODO: Populate these tables with your provider's naming conventions.
+ */
+export const namingConfig: NamingConfig = {
+  // High-priority short names for common resource types
+  priorityNames: {},
+
+  // Aliases for resource types that need alternate names
+  priorityAliases: {},
+
+  // Aliases for property types
+  priorityPropertyAliases: {},
+
+  // Abbreviations for service names (used in collision resolution)
+  serviceAbbreviations: {},
+
+  // Extract the short name from a fully-qualified type string
+  shortName: (typeName: string) => typeName.split("::").pop()!,
+
+  // Extract the service name from a fully-qualified type string
+  serviceName: (typeName: string) => typeName.split("::")[1] ?? typeName,
+};
+
+/**
+ * Create a NamingStrategy instance from parsed results.
+ */
+export function createNaming(inputs: NamingInput[]): NamingStrategy {
+  return new NamingStrategy(inputs, namingConfig);
+}
+`;
+}
+
+export function generateCodegenPackageTs(name: string): string {
+  return `import { packagePipeline } from "@intentius/chant/codegen/package";
+import type { PackagePipelineConfig } from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Package the ${name} lexicon for distribution.
+ */
+export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
+  const srcDir = dirname(fileURLToPath(import.meta.url));
+
+  const { spec, stats } = await packagePipeline({
+    generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+    buildManifest: (genResult) => ({
+      name: "${name}",
+      version: "0.0.1",
+    }),
+    srcDir,
+    collectSkills: () => new Map(),
+  });
+
+  console.error(\`Packaged \${stats.resources} resources, \${stats.ruleCount} rules\`);
+  return { spec, stats };
+}
+`;
+}
+
+export function generateCodegenDocsTs(name: string): string {
+  return `import { docsPipeline, writeDocsSite } from "@intentius/chant/codegen/docs";
+
+/**
+ * Generate documentation site for the ${name} lexicon.
+ */
+export async function generateDocs(options?: { verbose?: boolean }): Promise<void> {
+  const config = {
+    name: "${name}",
+    displayName: "${name.charAt(0).toUpperCase() + name.slice(1)}",
+    description: "${name} lexicon documentation",
+    distDir: "./dist",
+    outDir: "./docs",
+    // TODO: Implement service grouping for your provider
+    serviceFromType: (type: string) => type.split("::")[1] ?? type,
+    // TODO: Implement resource documentation URLs
+    resourceTypeUrl: (type: string) => \`#\${type}\`,
+  };
+
+  const result = docsPipeline(config);
+  writeDocsSite(config, result);
+
+  if (options?.verbose) {
+    console.error("Documentation generated");
+  }
+}
+`;
+}

package/src/cli/commands/init-lexicon/templates/docs.ts

@@ -0,0 +1,81 @@
+/**
+ * Docs site template generators for init-lexicon scaffold.
+ */
+
+export function generateDocsPackageJson(name: string): string {
+  return JSON.stringify(
+    {
+      name: `@intentius/chant-lexicon-${name}-docs`,
+      type: "module",
+      version: "0.0.1",
+      private: true,
+      scripts: {
+        dev: "astro dev",
+        build: "astro build",
+        preview: "astro preview",
+      },
+      dependencies: {
+        "@astrojs/starlight": "^0.37.6",
+        astro: "^5.6.1",
+        sharp: "^0.34.2",
+      },
+    },
+    null,
+    2,
+  ) + "\n";
+}
+
+export function generateDocsTsConfig(): string {
+  return JSON.stringify(
+    {
+      extends: "astro/tsconfigs/strict",
+      include: [".astro/types.d.ts", "**/*"],
+      exclude: ["dist"],
+    },
+    null,
+    2,
+  ) + "\n";
+}
+
+export function generateDocsAstroConfig(name: string): string {
+  const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+  return `// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: '${displayName}',
+      sidebar: [
+        { label: 'Overview', slug: '' },
+      ],
+    }),
+  ],
+});
+`;
+}
+
+export function generateDocsContentConfig(): string {
+  return `import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
+`;
+}
+
+export function generateDocsIndexMdx(name: string): string {
+  const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+  return `---
+title: Overview
+description: ${displayName} lexicon for chant
+---
+
+Welcome to the ${displayName} lexicon documentation.
+
+Run \`just generate\` to populate this site with generated reference pages.
+`;
+}

package/src/cli/commands/init-lexicon/templates/examples.ts

@@ -0,0 +1,35 @@
+/**
+ * Example template generators for init-lexicon scaffold.
+ */
+
+export function generateExamplePackageJson(name: string): string {
+  return JSON.stringify(
+    {
+      name: `@intentius/chant-lexicon-${name}-example-getting-started`,
+      version: "0.0.1",
+      private: true,
+      dependencies: {
+        [`@intentius/chant-lexicon-${name}`]: "workspace:*",
+        "@intentius/chant": "workspace:*",
+      },
+    },
+    null,
+    2,
+  ) + "\n";
+}
+
+export function generateExampleInfraTs(name: string, names: { packageName: string }): string {
+  return `/**
+ * Getting-started example for the ${name} lexicon.
+ *
+ * TODO: Replace with a real infrastructure definition
+ * that uses resources from the ${name} lexicon.
+ */
+
+// import { SomeResource } from "${names.packageName}";
+//
+// export const myResource = SomeResource("example", {
+//   // properties...
+// });
+`;
+}

package/src/cli/commands/init-lexicon/templates/lint.ts

@@ -0,0 +1,30 @@
+/**
+ * Lint template generators for init-lexicon scaffold.
+ */
+
+export function generateSampleRuleTs(names: { rulePrefix: string }): string {
+  return `import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+
+/**
+ * ${names.rulePrefix}001: Sample lint rule
+ *
+ * TODO: Replace with a real lint rule for your lexicon.
+ */
+export const sampleRule: LintRule = {
+  id: "${names.rulePrefix}001",
+  severity: "warning",
+  category: "style",
+  description: "Sample lint rule — replace with real checks",
+
+  check(context: LintContext): LintDiagnostic[] {
+    // TODO: Implement rule logic
+    return [];
+  },
+};
+`;
+}
+
+export function generateLintRulesIndexTs(): string {
+  return `export { sampleRule } from "./sample";
+`;
+}

package/src/cli/commands/init-lexicon/templates/lsp.ts

@@ -0,0 +1,39 @@
+/**
+ * LSP template generators for init-lexicon scaffold.
+ */
+
+export function generateLspCompletionsTs(name: string): string {
+  return `import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+// import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
+
+/**
+ * Provide LSP completions for ${name} resources.
+ *
+ * TODO: Build a LexiconIndex from your generated lexicon data
+ * and delegate to lexiconCompletions().
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  // const index = new LexiconIndex(lexiconData);
+  // return lexiconCompletions(ctx, index, "${name} resource");
+  return [];
+}
+`;
+}
+
+export function generateLspHoverTs(name: string): string {
+  return `import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+// import { LexiconIndex, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
+
+/**
+ * Provide LSP hover information for ${name} resources.
+ *
+ * TODO: Build a LexiconIndex from your generated lexicon data
+ * and delegate to lexiconHover().
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  // const index = new LexiconIndex(lexiconData);
+  // return lexiconHover(ctx, index, myCustomHoverFormatter);
+  return undefined;
+}
+`;
+}

package/src/cli/commands/init-lexicon/templates/plugin.ts

@@ -0,0 +1,110 @@
+/**
+ * Plugin and index template generators for init-lexicon scaffold.
+ */
+
+export function generatePluginTs(name: string, names: { pluginVarName: string; serializerVarName: string }): string {
+  return `import type { LexiconPlugin, SkillDefinition, IntrinsicDef } from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import { ${names.serializerVarName} } from "./serializer";
+
+/**
+ * ${name} lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const ${names.pluginVarName}: LexiconPlugin = {
+  name: "${name}",
+  serializer: ${names.serializerVarName},
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    const { generate } = await import("./codegen/generate");
+    await generate(options);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    // TODO: Implement coverage analysis
+    console.error("Coverage analysis not yet implemented");
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(\`Packaged \${stats.resources} resources, \${stats.ruleCount} rules, \${stats.skillCount} skills\`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    const { rules } = require("./lint/rules");
+    return rules;
+  },
+
+  postSynthChecks() {
+    return []; // TODO: Add post-synth checks
+  },
+
+  skills() {
+    return []; // TODO: Add skills
+  },
+
+  mcpTools() {
+    return []; // TODO: Implement MCP tools
+  },
+
+  mcpResources() {
+    return []; // TODO: Implement MCP resources
+  },
+
+  detectTemplate(data: unknown) {
+    return false; // TODO: Detect if a template belongs to this lexicon
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    const { completions } = require("./lsp/completions");
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    const { hover } = require("./lsp/hover");
+    return hover(ctx);
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+};
+`;
+}
+
+export function generateIndexTs(names: { pluginVarName: string; serializerVarName: string }): string {
+  return `// Plugin
+export { ${names.pluginVarName} } from "./plugin";
+
+// Serializer
+export { ${names.serializerVarName} } from "./serializer";
+
+// Generated resources — export everything from generated index
+// After running \`chant generate\`, this re-exports all resource classes
+// export * from "./generated/index";
+`;
+}