@intentius/chant 0.0.22 → 0.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Bun",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

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";
+`;
+}

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

@@ -0,0 +1,182 @@
+/**
+ * Project-level template generators for init-lexicon scaffold.
+ */
+
+export function generatePackageJson(name: string, names: { packageName: string }): string {
+  const pkg = {
+    name: names.packageName,
+    version: "0.0.1",
+    type: "module",
+    private: true,
+    files: ["src/", "dist/"],
+    exports: {
+      ".": "./src/index.ts",
+      "./*": "./src/*",
+      "./manifest": "./dist/manifest.json",
+      "./meta": "./dist/meta.json",
+      "./types": "./dist/types/index.d.ts",
+    },
+    scripts: {
+      generate: "bun run src/codegen/generate-cli.ts",
+      validate: "bun run src/validate-cli.ts",
+      docs: "bun src/codegen/docs-cli.ts",
+      prepack: "bun run generate && bun run validate",
+    },
+    dependencies: {
+      "@intentius/chant": "workspace:*",
+    },
+    devDependencies: {
+      typescript: "^5.9.3",
+    },
+  };
+
+  return JSON.stringify(pkg, null, 2) + "\n";
+}
+
+export function generateTsConfig(): string {
+  const config = {
+    extends: "../../tsconfig.json",
+    compilerOptions: {
+      rootDir: "./src",
+      outDir: "./dist",
+    },
+    include: ["src/**/*"],
+  };
+
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
+export function generateJustfile(name: string): string {
+  return `# Default recipe - list all available commands
+default:
+    @just --list
+
+# Generate types and metadata from upstream schemas
+generate:
+    bun run src/codegen/generate-cli.ts
+
+# Validate generated artifacts
+validate:
+    bun run src/validate-cli.ts
+
+# Generate docs site, install deps, and start dev server
+docs:
+    bun run src/codegen/docs-cli.ts
+    bun install --cwd docs
+    bun --cwd docs dev
+
+# Build docs site for production
+docs-build:
+    bun run src/codegen/docs-cli.ts
+    bun install --cwd docs
+    bun --cwd docs build
+
+# Package the lexicon (generate + validate)
+package: generate validate
+`;
+}
+
+export function generateGitignore(): string {
+  return `dist/
+node_modules/
+.cache/
+`;
+}
+
+export function generateReadme(name: string, names: { packageName: string }): string {
+  return `# ${names.packageName}
+
+${name} lexicon plugin for [chant](https://github.com/intentius/chant).
+
+## Getting started
+
+\`\`\`bash
+# Generate types from upstream spec
+just generate
+
+# Validate generated artifacts
+just validate
+
+# Generate documentation
+just docs
+\`\`\`
+
+## Project structure
+
+- \`src/plugin.ts\` — LexiconPlugin with all lifecycle methods
+- \`src/serializer.ts\` — Build output serializer
+- \`src/codegen/\` — Code generation pipeline
+- \`src/spec/\` — Upstream schema fetching and parsing
+- \`src/lint/rules/\` — Lint rules
+- \`src/lsp/\` — LSP completions and hover
+- \`src/generated/\` — Generated artifacts (do not edit)
+`;
+}
+
+export function generateSerializerTs(name: string, names: { serializerVarName: string; rulePrefix: string }): string {
+  return `import type { Serializer, Declarable } from "@intentius/chant";
+
+/**
+ * ${name} serializer — produces minimal JSON output.
+ *
+ * TODO: Replace with your lexicon's output format.
+ */
+export const ${names.serializerVarName}: Serializer = {
+  name: "${name}",
+  rulePrefix: "${names.rulePrefix}",
+
+  serialize(entities: Map<string, Declarable>): string {
+    const resources: Record<string, unknown> = {};
+
+    for (const [entityName, entity] of entities) {
+      resources[entityName] = {
+        type: entity.entityType,
+        // TODO: Convert entity properties to your output format
+      };
+    }
+
+    return JSON.stringify({ resources }, null, 2);
+  },
+};
+`;
+}
+
+export function generateValidateTs(name: string): string {
+  return `/**
+ * Validate generated lexicon-${name} artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with ${name}-specific configuration.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+// TODO: Add names of required entities for your lexicon
+const REQUIRED_NAMES: string[] = [];
+
+/**
+ * Validate the generated lexicon-${name} artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-${name}.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}
+`;
+}
+
+export function generateValidateCliTs(): string {
+  return `#!/usr/bin/env bun
+import { validate } from "./validate";
+
+await validate({ verbose: true });
+`;
+}