@intentius/chant 0.0.8 → 0.0.10

package/src/codegen/generate-typescript.test.ts

@@ -88,6 +88,70 @@ describe("writeConstructor", () => {
   });
 });
 
+describe("writeConstructor with resourceAttributesType", () => {
+  test("empty props with attributes type emits both params", () => {
+    const lines: string[] = [];
+    writeConstructor(lines, [], undefined, "CFResourceAttributes");
+    expect(lines.join("\n")).toContain(
+      "constructor(props: Record<string, unknown>, attributes?: CFResourceAttributes);",
+    );
+  });
+
+  test("props with attributes type emits second param after closing brace", () => {
+    const lines: string[] = [];
+    writeConstructor(
+      lines,
+      [{ name: "BucketName", type: "string", required: true }],
+      undefined,
+      "CFResourceAttributes",
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("constructor(props: {");
+    expect(output).toContain("BucketName: string;");
+    expect(output).toContain("}, attributes?: CFResourceAttributes);");
+  });
+
+  test("without attributes type, closing brace has no second param", () => {
+    const lines: string[] = [];
+    writeConstructor(
+      lines,
+      [{ name: "Name", type: "string", required: true }],
+      undefined,
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("  });");
+    expect(output).not.toContain("attributes?");
+  });
+});
+
+describe("writeResourceClass with resourceAttributesType", () => {
+  test("resource class constructor includes attributes param", () => {
+    const lines: string[] = [];
+    writeResourceClass(
+      lines,
+      "Bucket",
+      [{ name: "BucketName", type: "string", required: false }],
+      [{ name: "Arn", type: "string" }],
+      undefined,
+      "CFResourceAttributes",
+    );
+    const output = lines.join("\n");
+    expect(output).toContain("}, attributes?: CFResourceAttributes);");
+    expect(output).toContain("readonly Arn: string;");
+  });
+
+  test("property class does not get attributes param", () => {
+    const lines: string[] = [];
+    writePropertyClass(
+      lines,
+      "BucketConfig",
+      [{ name: "Enabled", type: "boolean", required: false }],
+    );
+    const output = lines.join("\n");
+    expect(output).not.toContain("attributes?");
+  });
+});
+
 describe("writeEnumType", () => {
   test("writes single-line for short enum", () => {
     const lines: string[] = [];

package/src/codegen/generate-typescript.ts

@@ -42,10 +42,11 @@ export function writeResourceClass(
   properties: DtsProperty[],
   attributes: DtsAttribute[],
   remap?: Map<string, string>,
+  resourceAttributesType?: string,
 ): void {
   lines.push("");
   lines.push(`export declare class ${tsName} {`);
-  writeConstructor(lines, properties, remap);
+  writeConstructor(lines, properties, remap, resourceAttributesType);
 
   // Attributes as readonly properties (sorted)
   const attrs = [...attributes].sort((a, b) => a.name.localeCompare(b.name));
@@ -79,9 +80,14 @@ export function writeConstructor(
   lines: string[],
   props: DtsProperty[],
   remap: Map<string, string> | undefined,
+  resourceAttributesType?: string,
 ): void {
   if (props.length === 0) {
-    lines.push("  constructor(props: Record<string, unknown>);");
+    if (resourceAttributesType) {
+      lines.push(`  constructor(props: Record<string, unknown>, attributes?: ${resourceAttributesType});`);
+    } else {
+      lines.push("  constructor(props: Record<string, unknown>);");
+    }
     return;
   }
 
@@ -100,7 +106,11 @@ export function writeConstructor(
     }
     lines.push(`    ${p.name}${optional}: ${tsType};`);
   }
-  lines.push("  });");
+  if (resourceAttributesType) {
+    lines.push(`  }, attributes?: ${resourceAttributesType});`);
+  } else {
+    lines.push("  });");
+  }
 }
 
 /**

package/src/codegen/package.ts

@@ -113,7 +113,7 @@ export async function packagePipeline(
 /**
  * Collect lint rule source files from a lexicon package.
  * Auto-discovers .ts files in the specified directories,
- * skipping test files, barrel files (index.ts), and non-.ts files.
+ * skipping test files, re-export files (index.ts), and non-.ts files.
  */
 export function collectRules(
   srcDir: string,

package/src/composite.test.ts

@@ -151,8 +151,8 @@ describe("expandComposite", () => {
 
     const expanded = expandComposite("storage", MyComp({}));
     expect(expanded.size).toBe(2);
-    expect(expanded.get("storage_bucket")?.entityType).toBe("Bucket");
-    expect(expanded.get("storage_role")?.entityType).toBe("Role");
+    expect(expanded.get("storageBucket")?.entityType).toBe("Bucket");
+    expect(expanded.get("storageRole")?.entityType).toBe("Role");
   });
 
   test("handles nested composites", () => {
@@ -167,8 +167,8 @@ describe("expandComposite", () => {
 
     const expanded = expandComposite("app", Outer({}));
     expect(expanded.size).toBe(2);
-    expect(expanded.get("app_bucket")?.entityType).toBe("Bucket");
-    expect(expanded.get("app_nested_table")?.entityType).toBe("Table");
+    expect(expanded.get("appBucket")?.entityType).toBe("Bucket");
+    expect(expanded.get("appNestedTable")?.entityType).toBe("Table");
   });
 
   test("preserves Declarable identity (same object reference)", () => {
@@ -176,7 +176,7 @@ describe("expandComposite", () => {
     const MyComp = Composite<{}>(() => ({ bucket }));
 
     const expanded = expandComposite("s", MyComp({}));
-    expect(expanded.get("s_bucket")).toBe(bucket);
+    expect(expanded.get("sBucket")).toBe(bucket);
   });
 
   test("handles empty composite", () => {
@@ -230,6 +230,22 @@ describe("resource() helper", () => {
     const instance = resource(MockResource, {});
     expect(instance.arn).toBeInstanceOf(AttrRef);
   });
+
+  test("forwards attributes as second constructor argument", () => {
+    // MockResource doesn't store attributes, so use createResource which does
+    const { createResource } = require("./runtime");
+    const TestRes = createResource("Test::Resource", "test", { arn: "Arn" });
+    const attrs = { DependsOn: ["Other"], Condition: "IsProd" };
+    const instance = resource(TestRes as any, { name: "test" }, attrs);
+    expect((instance as any).attributes).toEqual(attrs);
+  });
+
+  test("without attributes, resource() creates instance with empty attributes", () => {
+    const { createResource } = require("./runtime");
+    const TestRes = createResource("Test::Resource", "test", { arn: "Arn" });
+    const instance = resource(TestRes as any, { name: "test" });
+    expect((instance as any).attributes).toEqual({});
+  });
 });
 
 function mockDeclarableWithProps(type: string, props: Record<string, unknown>): Declarable {
@@ -313,6 +329,57 @@ describe("withDefaults", () => {
     expect(CompositeRegistry.size).toBe(1);
   });
 
+  test("function-based defaults receive caller props", () => {
+    let receivedByFn: Partial<{ name: string; timeout: number }> | undefined;
+    const Base = Composite<{ name: string; timeout: number }>((props) => ({
+      item: mockDeclarable(props.name),
+    }));
+
+    const Wrapped = withDefaults(Base, (props) => {
+      receivedByFn = props;
+      return { timeout: 30 } as { timeout: number };
+    });
+    Wrapped({ name: "test" });
+    expect(receivedByFn).toEqual({ name: "test" });
+  });
+
+  test("user props override computed defaults", () => {
+    let received: { timeout: number } | undefined;
+    const Base = Composite<{ timeout: number }>((props) => {
+      received = props;
+      return { item: mockDeclarable() };
+    });
+
+    const Wrapped = withDefaults(Base, () => ({ timeout: 30 }) as { timeout: number });
+    Wrapped({ timeout: 60 });
+    expect(received!.timeout).toBe(60);
+  });
+
+  test("stacking: withDefaults(withDefaults(base, static), fn) works", () => {
+    let received: { a: number; b: number; c: number } | undefined;
+    const Base = Composite<{ a: number; b: number; c: number }>((props) => {
+      received = props;
+      return { item: mockDeclarable() };
+    });
+
+    const Step1 = withDefaults(Base, { a: 1 });
+    const Step2 = withDefaults(Step1, (props) => ({ b: (props.c ?? 0) + 10 }) as { b: number });
+    Step2({ c: 3 });
+    expect(received).toEqual({ a: 1, b: 13, c: 3 });
+  });
+
+  test("undefined computed values don't overwrite user props", () => {
+    let received: { name: string; timeout: number } | undefined;
+    const Base = Composite<{ name: string; timeout: number }>((props) => {
+      received = props;
+      return { item: mockDeclarable() };
+    });
+
+    const Wrapped = withDefaults(Base, () => ({ timeout: undefined }) as unknown as { timeout: number });
+    Wrapped({ name: "test", timeout: 42 });
+    expect(received!.timeout).toBe(42);
+  });
+
   test("expandComposite works identically on defaulted composites", () => {
     const Base = Composite<{ name: string; timeout: number }>((props) => ({
       fn: mockDeclarable(`Fn-${props.name}`),
@@ -323,8 +390,8 @@ describe("withDefaults", () => {
     const expanded = expandComposite("api", Wrapped({ name: "test" }));
 
     expect(expanded.size).toBe(2);
-    expect(expanded.get("api_fn")?.entityType).toBe("Fn-test");
-    expect(expanded.get("api_role")?.entityType).toBe("Role-test");
+    expect(expanded.get("apiFn")?.entityType).toBe("Fn-test");
+    expect(expanded.get("apiRole")?.entityType).toBe("Role-test");
   });
 });
 
@@ -342,8 +409,8 @@ describe("propagate", () => {
     const instance = propagate(MyComp({}), { env: "prod" });
     const expanded = expandComposite("s", instance);
 
-    const bucketProps = (expanded.get("s_bucket") as any).props;
-    const roleProps = (expanded.get("s_role") as any).props;
+    const bucketProps = (expanded.get("sBucket") as any).props;
+    const roleProps = (expanded.get("sRole") as any).props;
     expect(bucketProps.env).toBe("prod");
     expect(roleProps.env).toBe("prod");
   });
@@ -359,7 +426,7 @@ describe("propagate", () => {
       tags: [{ key: "env", value: "prod" }],
     });
     const expanded = expandComposite("s", instance);
-    const tags = (expanded.get("s_bucket") as any).props.tags;
+    const tags = (expanded.get("sBucket") as any).props.tags;
 
     expect(tags).toEqual([
       { key: "env", value: "prod" },
@@ -374,7 +441,7 @@ describe("propagate", () => {
 
     const instance = propagate(MyComp({}), { region: "eu-west-1" });
     const expanded = expandComposite("s", instance);
-    expect((expanded.get("s_bucket") as any).props.region).toBe("us-west-2");
+    expect((expanded.get("sBucket") as any).props.region).toBe("us-west-2");
   });
 
   test("undefined values in shared props are stripped", () => {
@@ -384,7 +451,7 @@ describe("propagate", () => {
 
     const instance = propagate(MyComp({}), { name: undefined, extra: "yes" });
     const expanded = expandComposite("s", instance);
-    const props = (expanded.get("s_bucket") as any).props;
+    const props = (expanded.get("sBucket") as any).props;
     expect(props.name).toBe("data");
     expect(props.extra).toBe("yes");
   });
@@ -402,8 +469,8 @@ describe("propagate", () => {
     const instance = propagate(Outer({}), { env: "prod" });
     const expanded = expandComposite("app", instance);
 
-    expect((expanded.get("app_bucket") as any).props.env).toBe("prod");
-    expect((expanded.get("app_nested_table") as any).props.env).toBe("prod");
+    expect((expanded.get("appBucket") as any).props.env).toBe("prod");
+    expect((expanded.get("appNestedTable") as any).props.env).toBe("prod");
   });
 
   test("expanded declarables are same object references", () => {
@@ -412,7 +479,7 @@ describe("propagate", () => {
 
     const instance = propagate(MyComp({}), { env: "prod" });
     const expanded = expandComposite("s", instance);
-    expect(expanded.get("s_bucket")).toBe(bucket);
+    expect(expanded.get("sBucket")).toBe(bucket);
   });
 
   test("composites without propagate work unchanged", () => {
@@ -421,6 +488,6 @@ describe("propagate", () => {
     }));
 
     const expanded = expandComposite("s", MyComp({}));
-    expect((expanded.get("s_bucket") as any).props.name).toBe("data");
+    expect((expanded.get("sBucket") as any).props.name).toBe("data");
   });
 });

package/src/composite.ts

@@ -123,7 +123,7 @@ export function expandComposite(
   const shared = (instance as any)[SHARED_PROPS] as Record<string, unknown> | undefined;
 
   for (const [memberName, member] of Object.entries(instance.members)) {
-    const fullName = `${prefix}_${memberName}`;
+    const fullName = `${prefix}${memberName[0].toUpperCase()}${memberName.slice(1)}`;
 
     if (isCompositeInstance(member)) {
       const nested = expandComposite(fullName, member);
@@ -182,10 +182,11 @@ type Simplify<T> = { [K in keyof T]: T[K] };
  */
 export function withDefaults<P, M extends CompositeMembers, D extends Partial<P>>(
   definition: CompositeDefinition<P, M>,
-  defaults: D,
+  defaults: D | ((props: Partial<P>) => D),
 ): CompositeDefinition<Simplify<PartialByDefault<P, D>>, M> {
   const wrapped = ((props: Simplify<PartialByDefault<P, D>>) => {
-    return definition({ ...defaults, ...props } as P);
+    const resolved = typeof defaults === "function" ? defaults(props as Partial<P>) : defaults;
+    return definition({ ...resolved, ...props } as P);
   }) as CompositeDefinition<Simplify<PartialByDefault<P, D>>, M>;
 
   Object.defineProperty(wrapped, "compositeName", {
@@ -236,8 +237,9 @@ export function propagate<M extends CompositeMembers>(
  * Exists so lint tooling can validate composite member construction (EVL005).
  */
 export function resource<T extends Declarable, P>(
-  Type: new (props: P) => T,
+  Type: new (props: P, attributes?: Record<string, unknown>) => T,
   props: P,
+  attributes?: Record<string, unknown>,
 ): T {
-  return new Type(props);
+  return new Type(props, attributes);
 }

package/src/detectLexicon.test.ts

@@ -213,7 +213,7 @@ describe("detectLexicons", () => {
   });
 
   test("detects lexicon from export statement", async () => {
-    const file = join(testDir, "barrel.ts");
+    const file = join(testDir, "reexport.ts");
     await writeFile(
       file,
       'export * from "@intentius/chant-lexicon-testdom";\nimport * as core from "@intentius/chant";'
@@ -224,7 +224,7 @@ describe("detectLexicons", () => {
   });
 
   test("detects lexicon from export with curly braces", async () => {
-    const file = join(testDir, "barrel.ts");
+    const file = join(testDir, "reexport.ts");
     await writeFile(
       file,
       'export { Bucket, Interpolate } from "@intentius/chant-lexicon-testdom";'

package/src/discovery/collect.test.ts

@@ -262,8 +262,8 @@ describe("collectEntities with composites", () => {
       { file: "test.ts", exports: { myComp: instance } },
     ]);
 
-    expect(entities.has("myComp_a")).toBe(true);
-    expect(entities.has("myComp_b")).toBe(true);
+    expect(entities.has("myCompA")).toBe(true);
+    expect(entities.has("myCompB")).toBe(true);
     expect(entities.has("myComp")).toBe(false);
   });
 });

package/src/discovery/collect.ts

@@ -23,7 +23,7 @@ export function collectEntities(
     for (const [name, value] of Object.entries(exports)) {
       if (isDeclarable(value)) {
         if (entities.has(name)) {
-          // Same object re-exported from multiple files (e.g. barrel re-exports) is fine
+          // Same object re-exported from multiple files (e.g. re-exports from multiple files) is fine
           if (entities.get(name) !== value) {
             throw new DiscoveryError(
               file,

package/src/index.ts

@@ -52,6 +52,7 @@ export * from "./codegen/validate";
 export * from "./codegen/docs";
 export * from "./runtime";
 export * from "./runtime-adapter";
+export * from "./resource-attributes";
 export * from "./stack-output";
 export * from "./child-project";
 export * from "./lsp/types";

package/src/lexicon-schema.ts

@@ -72,6 +72,14 @@ export const LexiconEntrySchema = z.object({
   createOnly: z.array(z.string()).optional(),
   writeOnly: z.array(z.string()).optional(),
   primaryIdentifier: z.array(z.string()).optional(),
+  deprecatedProperties: z.array(z.string()).optional(),
+  conditionalCreateOnly: z.array(z.string()).optional(),
+  replacementStrategy: z.enum(["delete_then_create", "create_then_delete"]).optional(),
+  tagging: z.object({
+    taggable: z.boolean(),
+    tagOnCreate: z.boolean(),
+    tagUpdatable: z.boolean(),
+  }).optional(),
   runtimeDeprecations: z.record(z.string(), z.string()).optional(),
 });
 

package/src/lexicon.ts

@@ -97,6 +97,18 @@ export interface IntrinsicDef {
   readonly isTag?: boolean;
 }
 
+/**
+ * Structured init template output from a lexicon plugin.
+ */
+export interface InitTemplateSet {
+  /** Source files written to src/ */
+  src: Record<string, string>;
+  /** Application scaffold files written to project root */
+  root?: Record<string, string>;
+  /** Scripts merged into generated package.json */
+  scripts?: Record<string, string>;
+}
+
 /**
  * Plugin interface for lexicon packages.
  *
@@ -156,7 +168,7 @@ export interface LexiconPlugin {
   skills?(): SkillDefinition[];
 
   /** Return source file templates for `chant init` project scaffolding */
-  initTemplates?(): Record<string, string>;
+  initTemplates?(template?: string): InitTemplateSet;
 
   /** Optional initialization hook */
   init?(): void | Promise<void>;

package/src/lint/declarative.ts

@@ -39,6 +39,10 @@ export interface RuleSpec {
   severity: Severity;
   /** Category for grouping */
   category: Category;
+  /** Human-readable description of what this rule checks */
+  description?: string;
+  /** Link to rule documentation */
+  helpUri?: string;
   /** Selector name (or compound) to find target nodes */
   selector: string;
   /** Optional match condition to further filter nodes */
@@ -61,6 +65,8 @@ export function rule(spec: RuleSpec): LintRule {
     id: spec.id,
     severity: spec.severity,
     category: spec.category,
+    description: spec.description,
+    helpUri: spec.helpUri,
     check(context: LintContext): LintDiagnostic[] {
       const diagnostics: LintDiagnostic[] = [];
       const sf = context.sourceFile;