@intentius/chant 0.0.4 → 0.0.8

package/README.md

@@ -1,364 +1,23 @@
 # @intentius/chant
 
-> Part of the [chant](../../README.md) monorepo. Published as [`@intentius/chant`](https://www.npmjs.com/package/@intentius/chant) on npm.
+Core package for [chant](https://intentius.io/chant/) — a type system for operations.
 
-Core functionality for chant - a lexicon-agnostic declarative infrastructure specification system.
+This package provides the lexicon-agnostic foundation that all chant lexicons build on. It includes the type system (Declarables, Intrinsics, Parameters, Outputs), the discovery and build pipeline, the semantic lint engine, the CLI, template import, and reusable codegen infrastructure for lexicon authors (runtime factories, naming strategies, generation and packaging pipelines, LSP providers).
 
-## Overview
+Install it alongside a lexicon to start declaring infrastructure as typed TypeScript.
 
-This package provides the foundational types, interfaces, and utilities that power chant's declarative infrastructure system. It includes:
-
-- **Type system**: Declarables, Intrinsics, Parameters, and Outputs
-- **Discovery system**: File scanning, module loading, and entity collection
-- **Build pipeline**: Dependency resolution, topological sorting, and serialization
-- **Error handling**: Structured errors for discovery, build, and lint phases
-- **Lint system**: Infrastructure code validation framework
-- **Template import**: Convert external templates to TypeScript
-- **Codegen infrastructure**: Reusable pipelines for generating, naming, packaging, and fetching schemas
-- **LSP providers**: Generic lexicon-based completion and hover helpers
-- **Runtime factories**: `createResource` and `createProperty` for Declarable-marked constructors
-
-## Key Concepts
-
-### Declarables
-
-A `Declarable` is any entity that can be declared in an infrastructure specification:
-
-```typescript
-import { isDeclarable, DECLARABLE_MARKER } from "@intentius/chant";
-
-if (isDeclarable(value)) {
-  console.log(value.entityType);
-}
-```
-
-### Intrinsics
-
-An `Intrinsic` represents a lexicon-provided function resolved at build time:
-
-```typescript
-import { isIntrinsic, INTRINSIC_MARKER } from "@intentius/chant";
-
-if (isIntrinsic(value)) {
-  const serialized = value.toJSON();
-}
-```
-
-### AttrRef
-
-Reference attributes of other entities with deferred resolution:
-
-```typescript
-import { AttrRef } from "@intentius/chant";
-
-const bucket = {};
-const arnRef = new AttrRef(bucket, "arn");
-
-// Later, during discovery
-arnRef._setLogicalName("MyBucket");
-arnRef.toJSON(); // { "Fn::GetAttr": ["MyBucket", "arn"] }
-```
-
-## Discovery System
-
-Discover and collect infrastructure entities from TypeScript files:
-
-```typescript
-import { discover } from "@intentius/chant";
-
-const result = await discover("./src/infra");
-// result.entities: Map of entity name to Declarable
-// result.dependencies: Dependency graph
-// result.sourceFiles: Discovered files
-// result.errors: Any errors encountered
-```
-
-### Individual Discovery Functions
-
-```typescript
-import {
-  findInfraFiles,
-  importModule,
-  collectEntities,
-  resolveAttrRefs,
-  buildDependencyGraph,
-  detectCycles,
-  topologicalSort,
-} from "@intentius/chant";
-
-// Find all .ts files (excluding tests and node_modules)
-const files = await findInfraFiles("./src");
-
-// Import a module
-const exports = await importModule("./src/resources.ts");
-
-// Collect declarables from modules
-const entities = collectEntities([
-  { file: "resources.ts", exports }
-]);
-
-// Resolve attribute references
-resolveAttrRefs(entities);
-
-// Build dependency graph
-const deps = buildDependencyGraph(entities);
-
-// Check for cycles
-const cycles = detectCycles(deps);
-
-// Topological sort
-const order = topologicalSort(deps);
-```
-
-## Build Pipeline
-
-Build infrastructure specifications with lexicon-specific serialization:
-
-```typescript
-import { build } from "@intentius/chant";
-import { myLexicon } from "@intentius/chant-lexicon-myplatform";
-
-const result = await build("./src/infra", [myLexicon]);
-// result.outputs: Map of lexicon name to serialized output
-// result.entities: Discovered entities
-// result.warnings: Build warnings
-// result.errors: Any errors
-```
-
-## Error Handling
-
-Structured error types for different phases:
-
-```typescript
-import { DiscoveryError, BuildError, LintError } from "@intentius/chant";
-
-// Discovery phase errors
-throw new DiscoveryError("config.ts", "Module not found", "import");
-
-// Build phase errors
-throw new BuildError("MyResource", "Invalid configuration");
-
-// Lint errors with location
-const error = new LintError(
-  "config.ts",
-  10,
-  5,
-  "no-unused",
-  "Variable is declared but never used"
-);
-
-// All errors support JSON serialization
-const json = error.toJSON();
-```
-
-## Lint System
-
-Validate infrastructure code with custom rules:
-
-```typescript
-import { parseFile } from "@intentius/chant";
-import type { LintRule, LintContext } from "@intentius/chant";
-
-// Parse a file for linting
-const sourceFile = parseFile("./src/infra/main.ts");
-
-// Define a lint rule
-const myRule: LintRule = {
-  id: "my-rule",
-  severity: "error",
-  category: "correctness",
-  check(context: LintContext): LintDiagnostic[] {
-    // Analyze context.sourceFile
-    return [];
-  },
-  fix(context: LintContext): LintFix[] {
-    // Optional: provide auto-fixes
-    return [];
-  }
-};
-```
-
-## Serializer Interface
-
-Implement lexicon-specific serialization:
-
-```typescript
-import type { Serializer, Declarable } from "@intentius/chant";
-
-const mySerializer: Serializer = {
-  name: "my-lexicon",
-  rulePrefix: "ML",
-  serialize(entities: Map<string, Declarable>): string {
-    // Serialize entities to lexicon-specific format
-    return JSON.stringify({ entities: Array.from(entities.keys()) });
-  }
-};
-```
-
-## Utilities
-
-Helper functions for working with declarables:
-
-```typescript
-import {
-  getAttributes,
-  getLogicalName,
-  LOGICAL_NAME_SYMBOL
-} from "@intentius/chant";
-
-// Get attribute names that have AttrRef values
-const attrs = getAttributes(myEntity);
-// ["arn", "endpoint"]
-
-// Get the logical name assigned during discovery
-(entity as any)[LOGICAL_NAME_SYMBOL] = "MyResource";
-const name = getLogicalName(entity);
-// "MyResource"
-```
-
-## Lexicon Detection
-
-Automatically detect which lexicon is being used:
-
-```typescript
-import { detectLexicon } from "@intentius/chant";
-
-const lexicon = await detectLexicon(["./src/infra/main.ts"]);
-// "aws" (currently the only supported lexicon)
-```
-
-## Template Import System
-
-Convert external templates to TypeScript:
-
-```typescript
-import type {
-  TemplateIR,
-  TemplateParser,
-  TypeScriptGenerator
-} from "@intentius/chant";
-
-// Parser converts external format to IR
-const parser: TemplateParser = {
-  parse(content: string): TemplateIR {
-    return { resources: [], parameters: [] };
-  }
-};
-
-// Generator converts IR to TypeScript
-const generator: TypeScriptGenerator = {
-  generate(ir: TemplateIR): GeneratedFile[] {
-    return [{ path: "resources.ts", content: "..." }];
-  }
-};
-```
-
-## Codegen Infrastructure
-
-Core provides reusable infrastructure for lexicon code generation pipelines. Lexicons supply provider-specific callbacks; core handles orchestration.
-
-### Runtime Factories
-
-Create Declarable-marked constructors for generated resource and property types:
-
-```typescript
-import { createResource, createProperty } from "@intentius/chant/runtime";
-
-// Creates a constructor that stamps out Declarable objects
-const MyResource = createResource("Provider::Service::Type", "my-lexicon", { arn: "Arn" });
-const MyProperty = createProperty("Provider::Service::Type.PropType", "my-lexicon");
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-aws
 ```
 
-### Naming Strategy
-
-Collision-free TypeScript class name generation, parameterized by data tables:
-
-```typescript
-import { NamingStrategy, type NamingConfig } from "@intentius/chant/codegen/naming";
-
-const config: NamingConfig = {
-  priorityNames: { "Provider::S3::Bucket": "Bucket" },
-  priorityAliases: {},
-  priorityPropertyAliases: {},
-  serviceAbbreviations: { "ElasticLoadBalancingV2": "Elbv2" },
-  shortName: (t) => t.split("::").pop()!,
-  serviceName: (t) => t.split("::")[1],
-};
-
-const naming = new NamingStrategy(inputs, config);
-naming.resolve("Provider::S3::Bucket"); // "Bucket"
-```
-
-### Generation Pipeline
-
-Generic pipeline orchestration — step sequencing, logging, warning collection, stats counting:
-
-```typescript
-import { generatePipeline, type GeneratePipelineConfig } from "@intentius/chant/codegen/generate";
-
-const config: GeneratePipelineConfig<MyParsedResult> = {
-  fetchSchemas: async (opts) => { /* ... */ },
-  parseSchema: (name, data) => { /* ... */ },
-  createNaming: (results) => new MyNamingStrategy(results),
-  generateRegistry: (results, naming) => { /* ... */ },
-  generateTypes: (results, naming) => { /* ... */ },
-  generateRuntimeIndex: (results, naming) => { /* ... */ },
-};
-
-const result = await generatePipeline(config, { verbose: true });
-```
-
-### Packaging Pipeline
-
-Bundles generation output into a distributable `BundleSpec`:
-
-```typescript
-import { packagePipeline, type PackagePipelineConfig } from "@intentius/chant/codegen/package";
-
-const result = await packagePipeline({
-  generate: (opts) => myGenerate(opts),
-  buildManifest: (genResult) => ({ name: "my-lexicon", version: "1.0.0", /* ... */ }),
-  srcDir: __dirname,
-  collectSkills: () => new Map(),
-});
-```
-
-### Fetch Utilities
-
-HTTP fetch with local file caching and zip extraction:
-
-```typescript
-import { fetchWithCache, extractFromZip } from "@intentius/chant/codegen/fetch";
-
-const data = await fetchWithCache({ url: "https://...", cacheFile: "/tmp/cache.zip" });
-const files = await extractFromZip(data, (name) => name.endsWith(".json"));
-```
-
-### LSP Providers
-
-Generic lexicon-based completion and hover:
-
-```typescript
-import { LexiconIndex, lexiconCompletions, lexiconHover } from "@intentius/chant/lsp/lexicon-providers";
-
-const index = new LexiconIndex(lexiconData);
-const completions = lexiconCompletions(ctx, index, "My resource");
-const hover = lexiconHover(ctx, index);
-```
-
-## TypeScript Support
-
-This package is written in TypeScript and provides full type definitions.
-
-## Documentation
-
-- [Core Concepts](../../docs/src/content/docs/guides/core-concepts.md) - Detailed guide on declarables, intrinsics, and the type system
-- [Testing Guide](../../TESTING.md) - Testing patterns and utilities
+**[Documentation →](https://intentius.io/chant/getting-started/introduction/)**
 
 ## Related Packages
 
-- `@intentius/chant-lexicon-aws` - AWS CloudFormation lexicon
-- `@intentius/chant-test-utils` - Testing utilities
+| Package | Role |
+|---------|------|
+| [@intentius/chant-lexicon-aws](https://www.npmjs.com/package/@intentius/chant-lexicon-aws) | AWS CloudFormation lexicon |
+| [@intentius/chant-lexicon-gitlab](https://www.npmjs.com/package/@intentius/chant-lexicon-gitlab) | GitLab CI lexicon |
 
 ## License
 

package/bin/chant

@@ -0,0 +1,20 @@
+#!/bin/sh
+# Cross-runtime CLI wrapper. Tries bun first, falls back to npx tsx.
+set -e
+
+# Resolve symlinks to find the real script location
+SELF="$0"
+while [ -L "$SELF" ]; do
+  DIR="$(cd "$(dirname "$SELF")" && pwd)"
+  SELF="$(readlink "$SELF")"
+  # Handle relative symlink targets
+  case "$SELF" in /*) ;; *) SELF="$DIR/$SELF" ;; esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SELF")" && pwd)"
+MAIN_TS="$SCRIPT_DIR/../src/cli/main.ts"
+
+if command -v bun >/dev/null 2>&1; then
+  exec bun "$MAIN_TS" "$@"
+else
+  exec npx tsx "$MAIN_TS" "$@"
+fi

package/package.json

@@ -1,23 +1,24 @@
 {
   "name": "@intentius/chant",
-  "version": "0.0.4",
+  "version": "0.0.8",
   "license": "Apache-2.0",
   "type": "module",
-  "files": ["src/"],
+  "files": ["src/", "bin/"],
   "publishConfig": {
-  "access": "public"
-},
-"bin": {
-  "chant": "./src/cli/main.ts"
-},
-"exports": {
-  ".": "./src/index.ts",
-  "./cli": "./src/cli/index.ts",
-  "./cli/*": "./src/cli/*",
-  "./*": "./src/*"
-},
-"dependencies": {
-  "fflate": "^0.8.2",
-  "zod": "^4.3.6"
-}
+    "access": "public"
+  },
+  "bin": {
+    "chant": "./bin/chant"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cli": "./src/cli/index.ts",
+    "./cli/*": "./src/cli/*",
+    "./*": "./src/*"
+  },
+  "dependencies": {
+    "fflate": "^0.8.2",
+    "picomatch": "^4.0.3",
+    "zod": "^4.3.6"
+  }
 }

package/src/bench.test.ts

@@ -6,60 +6,9 @@ import { discover } from "./discovery/index";
 import { runLint } from "./lint/engine";
 import { build } from "./build";
 import type { Serializer } from "./serializer";
-import type { LintRule } from "./lint/rule";
-
-// Import all core lint rules
-import {
-  flatDeclarationsRule,
-  exportRequiredRule,
-  fileDeclarableLimitRule,
-  singleConcernFileRule,
-  preferNamespaceImportRule,
-  barrelImportStyleRule,
-  declarableNamingConventionRule,
-  noUnusedDeclarableImportRule,
-  noRedundantValueCastRule,
-  noUnusedDeclarableRule,
-  noCyclicDeclarableRefRule,
-  noRedundantTypeImportRule,
-  noStringRefRule,
-  enforceBarrelImportRule,
-  enforceBarrelRefRule,
-  evl001NonLiteralExpressionRule,
-  evl002ControlFlowResourceRule,
-  evl003DynamicPropertyAccessRule,
-  evl004SpreadNonConstRule,
-  evl005ResourceBlockBodyRule,
-  evl006BarrelUsageRule,
-  evl007InvalidSiblingsRule,
-  evl008UnresolvableBarrelRefRule,
-} from "./lint/rules/index";
-
-const coreRules: LintRule[] = [
-  flatDeclarationsRule,
-  exportRequiredRule,
-  fileDeclarableLimitRule,
-  singleConcernFileRule,
-  preferNamespaceImportRule,
-  barrelImportStyleRule,
-  declarableNamingConventionRule,
-  noUnusedDeclarableImportRule,
-  noRedundantValueCastRule,
-  noUnusedDeclarableRule,
-  noCyclicDeclarableRefRule,
-  noRedundantTypeImportRule,
-  noStringRefRule,
-  enforceBarrelImportRule,
-  enforceBarrelRefRule,
-  evl001NonLiteralExpressionRule,
-  evl002ControlFlowResourceRule,
-  evl003DynamicPropertyAccessRule,
-  evl004SpreadNonConstRule,
-  evl005ResourceBlockBodyRule,
-  evl006BarrelUsageRule,
-  evl007InvalidSiblingsRule,
-  evl008UnresolvableBarrelRefRule,
-];
+import { loadCoreRules } from "./lint/rules/index";
+
+const coreRules = loadCoreRules();
 
 interface FixtureSize {
   name: string;

package/src/cli/commands/__fixtures__/init-lexicon-output/src/plugin.ts

@@ -19,7 +19,9 @@ export const fixturePlugin: LexiconPlugin = {
 
   async validate(options?: { verbose?: boolean }): Promise<void> {
     const { validate } = await import("./validate");
-    await validate(options);
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
   },
 
   async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
@@ -29,32 +31,15 @@ export const fixturePlugin: LexiconPlugin = {
 
   async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
     const { packageLexicon } = await import("./codegen/package");
-    await packageLexicon(options);
-  },
-
-  async rollback(options?: { restore?: string; verbose?: boolean }): Promise<void> {
-    const { listSnapshots, restoreSnapshot } = await import("./codegen/rollback");
+    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)));
-    const snapshotsDir = join(pkgDir, ".snapshots");
-
-    if (options?.restore) {
-      const generatedDir = join(pkgDir, "src", "generated");
-      restoreSnapshot(String(options.restore), generatedDir);
-      console.error(`Restored snapshot: ${options.restore}`);
-    } else {
-      const snapshots = listSnapshots(snapshotsDir);
-      if (snapshots.length === 0) {
-        console.error("No snapshots available.");
-      } else {
-        console.error(`Available snapshots (${snapshots.length}):`);
-        for (const s of snapshots) {
-          console.error(`  ${s.timestamp}  ${s.resources} resources  ${s.path}`);
-        }
-      }
-    }
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
   },
 
   // ── Optional extensions (uncomment and implement as needed) ───

package/src/cli/commands/__fixtures__/init-lexicon-output/src/validate.ts

@@ -1,24 +1,28 @@
 /**
- * Validate generated artifacts for the fixture lexicon.
+ * Validate generated lexicon-fixture artifacts.
  *
- * TODO: Add validation checks for your generated files.
+ * Thin wrapper around the core validation framework
+ * with fixture-specific configuration.
  */
-export async function validate(options?: { verbose?: boolean }): Promise<void> {
-  const checks = [
-    // TODO: Add checks — e.g. verify lexicon JSON exists, types compile,
-    // registry has expected resources, etc.
-    { name: "placeholder", ok: true, error: undefined as string | undefined },
-  ];
 
-  for (const check of checks) {
-    const status = check.ok ? "OK" : "FAIL";
-    const msg = check.error ? ` — ${check.error}` : "";
-    console.error(`  [${status}] ${check.name}${msg}`);
-  }
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
 
-  const failed = checks.filter((c) => !c.ok);
-  if (failed.length > 0) {
-    throw new Error("Validation failed");
-  }
-  console.error("All validation checks passed.");
+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-fixture artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-fixture.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
 }

package/src/cli/commands/__snapshots__/init-lexicon.test.ts.snap

@@ -129,7 +129,9 @@ export const fixturePlugin: LexiconPlugin = {
 
   async validate(options?: { verbose?: boolean }): Promise<void> {
     const { validate } = await import("./validate");
-    await validate(options);
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
   },
 
   async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
@@ -139,32 +141,15 @@ export const fixturePlugin: LexiconPlugin = {
 
   async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
     const { packageLexicon } = await import("./codegen/package");
-    await packageLexicon(options);
-  },
-
-  async rollback(options?: { restore?: string; verbose?: boolean }): Promise<void> {
-    const { listSnapshots, restoreSnapshot } = await import("./codegen/rollback");
+    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)));
-    const snapshotsDir = join(pkgDir, ".snapshots");
-
-    if (options?.restore) {
-      const generatedDir = join(pkgDir, "src", "generated");
-      restoreSnapshot(String(options.restore), generatedDir);
-      console.error(\`Restored snapshot: \${options.restore}\`);
-    } else {
-      const snapshots = listSnapshots(snapshotsDir);
-      if (snapshots.length === 0) {
-        console.error("No snapshots available.");
-      } else {
-        console.error(\`Available snapshots (\${snapshots.length}):\`);
-        for (const s of snapshots) {
-          console.error(\`  \${s.timestamp}  \${s.resources} resources  \${s.path}\`);
-        }
-      }
-    }
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(\`Packaged \${stats.resources} resources, \${stats.ruleCount} rules, \${stats.skillCount} skills\`);
   },
 
   // ── Optional extensions (uncomment and implement as needed) ───

package/src/cli/commands/build.ts

@@ -5,7 +5,7 @@ import { runPostSynthChecks } from "../../lint/post-synth";
 import type { PostSynthCheck } from "../../lint/post-synth";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { writeFileSync } from "fs";
-import { resolve } from "path";
+import { resolve, dirname, join } from "path";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 
 /**
@@ -172,7 +172,6 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
 
         // Write additional files (e.g. nested stack templates) alongside the primary output
         if (additionalFiles.size > 0) {
-          const { dirname, join } = require("path");
           const outputDir = dirname(outputPath);
           for (const [filename, content] of additionalFiles) {
             let fileContent = content;

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

@@ -52,7 +52,7 @@ describe("importCommand", () => {
     expect(result.lexicon).toBe("aws");
     expect(result.generatedFiles.length).toBeGreaterThan(0);
     expect(existsSync(outputDir)).toBe(true);
-  });
+  }, 15000);
 
   test("imports CloudFormation template with multiple resources", async () => {
     const template = {