@intentius/chant 0.0.1

package/README.md

@@ -0,0 +1,365 @@
+# @intentius/chant
+
+> Part of the [chant](../../README.md) monorepo. Not yet published to npm.
+
+Core functionality for chant - a lexicon-agnostic declarative infrastructure specification system.
+
+## Overview
+
+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");
+```
+
+### 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
+
+## Related Packages
+
+- `@intentius/chant-lexicon-aws` - AWS CloudFormation lexicon
+- `@intentius/chant-test-utils` - Testing utilities
+
+## License
+
+See the main project LICENSE file.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@intentius/chant",
+  "version": "0.0.1",
+  "type": "module",
+  "files": ["src/"],
+  "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"
+}
+}

package/src/attrref.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from "bun:test";
+import { AttrRef } from "./attrref";
+import { INTRINSIC_MARKER, isIntrinsic } from "./intrinsic";
+
+describe("AttrRef", () => {
+  test("creates AttrRef with parent and attribute", () => {
+    const parent = { id: "test" };
+    const attrRef = new AttrRef(parent, "Arn");
+
+    expect(attrRef).toBeInstanceOf(AttrRef);
+    expect(attrRef.attribute).toBe("Arn");
+    expect(attrRef.parent.deref()).toBe(parent);
+  });
+
+  test("implements Intrinsic interface", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "Name");
+
+    expect(attrRef[INTRINSIC_MARKER]).toBe(true);
+    expect(isIntrinsic(attrRef)).toBe(true);
+  });
+
+  test("stores parent as WeakRef", () => {
+    const parent = { id: "test" };
+    const attrRef = new AttrRef(parent, "Id");
+
+    expect(attrRef.parent).toBeInstanceOf(WeakRef);
+    expect(attrRef.parent.deref()).toBe(parent);
+  });
+
+  test("getLogicalName returns undefined before set", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "Arn");
+
+    expect(attrRef.getLogicalName()).toBeUndefined();
+  });
+
+  test("getLogicalName returns the logical name after set", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "Arn");
+
+    attrRef._setLogicalName("MyResource");
+    expect(attrRef.getLogicalName()).toBe("MyResource");
+  });
+
+  test("_setLogicalName sets the logical name", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "Arn");
+
+    attrRef._setLogicalName("MyResource");
+
+    const json = attrRef.toJSON();
+    expect(json).toEqual({
+      __attrRef: { entity: "MyResource", attribute: "Arn" },
+    });
+  });
+
+  test("toJSON returns __attrRef when logical name is set", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "DomainName");
+
+    attrRef._setLogicalName("MyBucket");
+
+    const json = attrRef.toJSON();
+    expect(json).toEqual({
+      __attrRef: { entity: "MyBucket", attribute: "DomainName" },
+    });
+  });
+
+  test("toJSON throws when logical name is not set", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "Arn");
+
+    expect(() => attrRef.toJSON()).toThrow(
+      'Cannot serialize AttrRef for attribute "Arn": logical name not set'
+    );
+  });
+
+  test("toJSON throws with correct attribute name in error message", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "CustomAttribute");
+
+    expect(() => attrRef.toJSON()).toThrow(
+      'Cannot serialize AttrRef for attribute "CustomAttribute": logical name not set'
+    );
+  });
+
+  test("handles different attribute names", () => {
+    const parent = {};
+    const attributes = ["Arn", "Name", "Id", "DomainName", "PhysicalResourceId"];
+
+    for (const attr of attributes) {
+      const attrRef = new AttrRef(parent, attr);
+      attrRef._setLogicalName("Resource");
+
+      const json = attrRef.toJSON();
+      expect(json).toEqual({
+        __attrRef: { entity: "Resource", attribute: attr },
+      });
+    }
+  });
+
+  test("handles different logical names", () => {
+    const parent = {};
+    const logicalNames = ["MyBucket", "MyTable", "MyFunction", "My-Resource-123"];
+
+    for (const name of logicalNames) {
+      const attrRef = new AttrRef(parent, "Arn");
+      attrRef._setLogicalName(name);
+
+      const json = attrRef.toJSON();
+      expect(json).toEqual({
+        __attrRef: { entity: name, attribute: "Arn" },
+      });
+    }
+  });
+
+  test("_setLogicalName can be called multiple times", () => {
+    const parent = {};
+    const attrRef = new AttrRef(parent, "Arn");
+
+    attrRef._setLogicalName("FirstName");
+    expect(attrRef.toJSON()).toEqual({
+      __attrRef: { entity: "FirstName", attribute: "Arn" },
+    });
+
+    attrRef._setLogicalName("SecondName");
+    expect(attrRef.toJSON()).toEqual({
+      __attrRef: { entity: "SecondName", attribute: "Arn" },
+    });
+  });
+
+  test("maintains separate logical names for different instances", () => {
+    const parent = {};
+    const attrRef1 = new AttrRef(parent, "Arn");
+    const attrRef2 = new AttrRef(parent, "Name");
+
+    attrRef1._setLogicalName("Resource1");
+    attrRef2._setLogicalName("Resource2");
+
+    expect(attrRef1.toJSON()).toEqual({
+      __attrRef: { entity: "Resource1", attribute: "Arn" },
+    });
+    expect(attrRef2.toJSON()).toEqual({
+      __attrRef: { entity: "Resource2", attribute: "Name" },
+    });
+  });
+});

package/src/attrref.ts

@@ -0,0 +1,50 @@
+import { INTRINSIC_MARKER, type Intrinsic } from "./intrinsic";
+
+/**
+ * Reference to an attribute of a parent entity.
+ * Lexicon serializers read `getLogicalName()` and `attribute` to produce
+ * their own output format (e.g. CloudFormation `Fn::GetAttr`).
+ */
+export class AttrRef implements Intrinsic {
+  readonly [INTRINSIC_MARKER] = true as const;
+  readonly parent: WeakRef<object>;
+  readonly attribute: string;
+  private logicalName?: string;
+
+  constructor(parent: object, attribute: string) {
+    this.parent = new WeakRef(parent);
+    this.attribute = attribute;
+  }
+
+  /**
+   * Set the logical name for this attribute reference
+   * @internal
+   */
+  _setLogicalName(name: string): void {
+    this.logicalName = name;
+  }
+
+  /**
+   * Get the logical name assigned to this attribute reference.
+   */
+  getLogicalName(): string | undefined {
+    return this.logicalName;
+  }
+
+  /**
+   * Serialize to a generic envelope. Lexicon-specific serializers should
+   * read `getLogicalName()` and `attribute` directly instead of relying
+   * on this format.
+   * @throws {Error} If logical name has not been set
+   */
+  toJSON(): { __attrRef: { entity: string; attribute: string } } {
+    if (!this.logicalName) {
+      throw new Error(
+        `Cannot serialize AttrRef for attribute "${this.attribute}": logical name not set`
+      );
+    }
+    return {
+      __attrRef: { entity: this.logicalName, attribute: this.attribute },
+    };
+  }
+}