@intentius/chant 0.0.5 → 0.0.9

package/src/lint/rule-registry.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect } from "bun:test";
+import { buildRuleRegistry } from "./rule-registry";
+import type { LintRule, LintContext, LintDiagnostic } from "./rule";
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "./post-synth";
+
+function mockRule(id: string, overrides: Partial<LintRule> = {}): LintRule {
+  return {
+    id,
+    severity: "warning",
+    category: "correctness",
+    description: `Description for ${id}`,
+    check: (): LintDiagnostic[] => [],
+    ...overrides,
+  };
+}
+
+function mockCheck(id: string, description: string): PostSynthCheck {
+  return {
+    id,
+    description,
+    check: (): PostSynthDiagnostic[] => [],
+  };
+}
+
+describe("buildRuleRegistry", () => {
+  test("collects core rules", () => {
+    const entries = buildRuleRegistry([
+      mockRule("COR001"),
+      mockRule("COR008"),
+    ]);
+
+    expect(entries).toHaveLength(2);
+    expect(entries[0].id).toBe("COR001");
+    expect(entries[0].source).toBe("core");
+    expect(entries[0].phase).toBe("pre-synth");
+    expect(entries[0].description).toBe("Description for COR001");
+  });
+
+  test("collects plugin lint rules", () => {
+    const entries = buildRuleRegistry([], [
+      {
+        name: "aws",
+        rules: [mockRule("WAW001", { category: "security" })],
+      },
+    ]);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].source).toBe("aws");
+    expect(entries[0].category).toBe("security");
+  });
+
+  test("collects plugin post-synth checks", () => {
+    const entries = buildRuleRegistry([], [
+      {
+        name: "aws",
+        postSynthChecks: [
+          mockCheck("WAW018", "S3 public access not blocked"),
+        ],
+      },
+    ]);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].phase).toBe("post-synth");
+    expect(entries[0].hasAutoFix).toBe(false);
+    expect(entries[0].category).toBe("security");
+  });
+
+  test("sorts entries by ID", () => {
+    const entries = buildRuleRegistry([
+      mockRule("COR008"),
+      mockRule("COR001"),
+    ]);
+
+    expect(entries[0].id).toBe("COR001");
+    expect(entries[1].id).toBe("COR008");
+  });
+
+  test("detects auto-fix capability", () => {
+    const withFix = mockRule("COR001");
+    withFix.fix = () => [];
+    const withoutFix = mockRule("COR002");
+
+    const entries = buildRuleRegistry([withFix, withoutFix]);
+
+    expect(entries.find((e) => e.id === "COR001")?.hasAutoFix).toBe(true);
+    expect(entries.find((e) => e.id === "COR002")?.hasAutoFix).toBe(false);
+  });
+
+  test("falls back to rule ID when description is missing", () => {
+    const rule = mockRule("COR001");
+    delete (rule as Record<string, unknown>).description;
+
+    const entries = buildRuleRegistry([rule]);
+    expect(entries[0].description).toBe("COR001");
+  });
+
+  test("combines core and plugin rules", () => {
+    const entries = buildRuleRegistry(
+      [mockRule("COR001")],
+      [
+        {
+          name: "aws",
+          rules: [mockRule("WAW001")],
+          postSynthChecks: [mockCheck("WAW010", "Redundant DependsOn")],
+        },
+      ],
+    );
+
+    expect(entries).toHaveLength(3);
+    expect(entries.map((e) => e.id)).toEqual(["COR001", "WAW001", "WAW010"]);
+  });
+});

package/src/lint/rule-registry.ts

@@ -0,0 +1,118 @@
+/**
+ * Rule registry — collects metadata from all rule sources into a flat, sortable array.
+ * Used for documentation generation and programmatic rule introspection.
+ */
+
+import type { LintRule, Severity, Category } from "./rule";
+import type { PostSynthCheck } from "./post-synth";
+
+export interface RuleEntry {
+  /** Unique rule ID (e.g. "COR001", "WAW018") */
+  id: string;
+  /** Human-readable description of what this rule checks */
+  description: string;
+  /** Rule category */
+  category: Category;
+  /** Default severity level */
+  defaultSeverity: Severity;
+  /** Source of the rule ("core" or lexicon name) */
+  source: "core" | string;
+  /** Phase the rule runs in */
+  phase: "pre-synth" | "post-synth";
+  /** Whether this rule provides automatic fixes */
+  hasAutoFix: boolean;
+  /** Link to rule documentation */
+  helpUri?: string;
+}
+
+/**
+ * Build a rule registry from core rules and plugin-provided rules/checks.
+ *
+ * @param coreRules - Core LintRules (COR/EVL rules from packages/core)
+ * @param plugins - Array of plugin contributions with name, rules, and post-synth checks
+ * @returns Flat array of RuleEntry sorted by ID
+ */
+export function buildRuleRegistry(
+  coreRules: LintRule[],
+  plugins: Array<{
+    name: string;
+    rules?: LintRule[];
+    postSynthChecks?: PostSynthCheck[];
+  }> = [],
+): RuleEntry[] {
+  const entries: RuleEntry[] = [];
+
+  // Core lint rules
+  for (const rule of coreRules) {
+    entries.push({
+      id: rule.id,
+      description: rule.description ?? rule.id,
+      category: rule.category,
+      defaultSeverity: rule.severity,
+      source: "core",
+      phase: "pre-synth",
+      hasAutoFix: typeof rule.fix === "function",
+      helpUri: rule.helpUri,
+    });
+  }
+
+  // Plugin-provided lint rules and post-synth checks
+  for (const plugin of plugins) {
+    if (plugin.rules) {
+      for (const rule of plugin.rules) {
+        entries.push({
+          id: rule.id,
+          description: rule.description ?? rule.id,
+          category: rule.category,
+          defaultSeverity: rule.severity,
+          source: plugin.name,
+          phase: "pre-synth",
+          hasAutoFix: typeof rule.fix === "function",
+          helpUri: rule.helpUri,
+        });
+      }
+    }
+
+    if (plugin.postSynthChecks) {
+      for (const check of plugin.postSynthChecks) {
+        entries.push({
+          id: check.id,
+          description: check.description,
+          category: inferPostSynthCategory(check.id),
+          defaultSeverity: inferPostSynthSeverity(check.id, check.description),
+          source: plugin.name,
+          phase: "post-synth",
+          hasAutoFix: false,
+          helpUri: `https://chant.dev/lint-rules/${check.id.toLowerCase()}`,
+        });
+      }
+    }
+  }
+
+  return entries.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Infer category for post-synth checks from rule ID prefix.
+ * WAW018+ are security rules, existing WAW/COR/EXT default to correctness.
+ */
+function inferPostSynthCategory(id: string): Category {
+  const num = parseInt(id.replace(/\D/g, ""), 10);
+  if (id.startsWith("WAW") && num >= 18) return "security";
+  return "correctness";
+}
+
+/**
+ * Infer default severity for post-synth checks.
+ * Security checks with "error" level: WAW018, WAW019, WAW021.
+ */
+function inferPostSynthSeverity(id: string, description: string): Severity {
+  // Check if the description hints at severity
+  if (description.toLowerCase().includes("error")) return "error";
+  // Known error-level security checks
+  const errorIds = new Set(["WAW018", "WAW019", "WAW021"]);
+  if (errorIds.has(id)) return "error";
+  // Info-level checks
+  if (id === "WAW027") return "info";
+  return "warning";
+}

package/src/lint/rule.ts

@@ -34,6 +34,10 @@ export interface LintDiagnostic {
   line: number;
   /** Column number (1-based) */
   column: number;
+  /** End line number (1-based), when the diagnostic spans a range */
+  endLine?: number;
+  /** End column number (1-based), when the diagnostic spans a range */
+  endColumn?: number;
   /** ID of the rule that produced this diagnostic */
   ruleId: string;
   /** Severity level */
@@ -73,6 +77,10 @@ export interface LintRule {
   severity: Severity;
   /** Category for grouping */
   category: Category;
+  /** Human-readable description of what this rule checks */
+  description?: string;
+  /** Link to rule documentation */
+  helpUri?: string;
   /** Check the code and return diagnostics */
   check(context: LintContext, options?: Record<string, unknown>): LintDiagnostic[];
   /** Optionally provide fixes for issues found */

package/src/lint/rules/cor017-composite-name-match.ts

@@ -7,7 +7,7 @@ import { isCompositeCallee } from "./composite-scope";
  *
  * The second argument to Composite() (the name string) must match the
  * const variable it's assigned to. This name is used in resource expansion
- * (e.g. healthApi_role, healthApi_func) and in error messages.
+ * (e.g. healthApiRole, healthApiFunc) and in error messages.
  *
  * Triggers on: const LambdaApi = Composite(fn, "MyFunction")  — mismatch
  * Triggers on: const LambdaApi = Composite(fn)                — missing name
@@ -100,6 +100,7 @@ export const cor017CompositeNameMatchRule: LintRule = {
   id: "COR017",
   severity: "error",
   category: "correctness",
+  description: "Composite name argument must match the variable it is assigned to",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/cor018-composite-prefer-lexicon-type.ts

@@ -5,7 +5,7 @@ import { isCompositeCallee } from "./composite-scope";
 /**
  * COR018: Prefer lexicon property types in Composite props
  *
- * Composite prop interfaces should use lexicon property types (via the barrel)
+ * Composite prop interfaces should use lexicon property types (via the lexicon package)
  * instead of locally-declared interfaces or type aliases. Local types next to
  * a Composite definition often duplicate existing lexicon property types.
  *
@@ -13,7 +13,7 @@ import { isCompositeCallee } from "./composite-scope";
  *              in the same file as the Composite (excluding the props interface itself)
  * OK: InstanceType<typeof _.Role_Policy>
  * OK: primitives (string, number, boolean)
- * OK: barrel-imported types
+ * OK: lexicon-imported types
  */
 
 /**
@@ -60,7 +60,7 @@ function findLocalTypeDeclarations(sourceFile: ts.SourceFile): Map<string, ts.No
 
 /**
  * Collect type references used in a props interface's field types.
- * Returns names of locally-referenced types (not primitives, not from barrel).
+ * Returns names of locally-referenced types (not primitives, not from the lexicon package).
  */
 function collectFieldTypeRefs(
   propsDecl: ts.Node,
@@ -161,6 +161,7 @@ export const cor018CompositePreferLexiconTypeRule: LintRule = {
   id: "COR018",
   severity: "info",
   category: "style",
+  description: "Prefer lexicon property types over local interfaces in Composite props",
   check(context: LintContext): LintDiagnostic[] {
     return checkFile(context);
   },

package/src/lint/rules/declarable-naming-convention.ts

@@ -62,6 +62,7 @@ export const declarableNamingConventionRule: LintRule = {
   id: "COR005",
   severity: "warning",
   category: "style",
+  description: "Exported declarable instances must use camelCase naming",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl001-non-literal-expression.ts

@@ -141,6 +141,7 @@ export const evl001NonLiteralExpressionRule: LintRule = {
   id: "EVL001",
   severity: "error",
   category: "correctness",
+  description: "Resource constructor property values must be statically evaluable — no function calls",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl002-control-flow-resource.ts

@@ -53,6 +53,7 @@ export const evl002ControlFlowResourceRule: LintRule = {
   id: "EVL002",
   severity: "error",
   category: "correctness",
+  description: "Resource constructors must not appear inside control flow statements",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl003-dynamic-property-access.ts

@@ -33,6 +33,7 @@ export const evl003DynamicPropertyAccessRule: LintRule = {
   id: "EVL003",
   severity: "error",
   category: "correctness",
+  description: "Computed property access must use a string or numeric literal key",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl004-spread-non-const.ts

@@ -103,6 +103,7 @@ export const evl004SpreadNonConstRule: LintRule = {
   id: "EVL004",
   severity: "error",
   category: "correctness",
+  description: "Spread expressions must reference a const variable or literal, not a dynamic source",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl005-resource-block-body.ts

@@ -41,6 +41,7 @@ export const evl005ResourceBlockBodyRule: LintRule = {
   id: "EVL005",
   severity: "error",
   category: "correctness",
+  description: "The resource() callback must use expression body, not block body",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl007-invalid-siblings.ts

@@ -131,6 +131,7 @@ export const evl007InvalidSiblingsRule: LintRule = {
   id: "EVL007",
   severity: "error",
   category: "correctness",
+  description: "Validates that siblings access in Composite factories references existing member keys",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/evl009-composite-no-constant.ts

@@ -183,6 +183,7 @@ export const evl009CompositeNoConstantRule: LintRule = {
   id: "EVL009",
   severity: "warning",
   category: "style",
+  description: "Flags extractable constants inside Composite factories — move to a separate file",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const importedNames = collectImportedNames(context.sourceFile);

package/src/lint/rules/evl010-composite-no-transform.ts

@@ -61,6 +61,7 @@ export const evl010CompositeNoTransformRule: LintRule = {
   id: "EVL010",
   severity: "warning",
   category: "style",
+  description: "Flags data transformations (map, filter, reduce) inside Composite factories",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/export-required.ts

@@ -149,6 +149,7 @@ export const exportRequiredRule: LintRule = {
   id: "COR008",
   severity: "warning",
   category: "correctness",
+  description: "Detects declarable instances that are not exported for chant discovery",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const exportInfo = collectExportInfo(context.sourceFile);

package/src/lint/rules/file-declarable-limit.ts

@@ -73,6 +73,7 @@ export const fileDeclarableLimitRule: LintRule = {
   id: "COR009",
   severity: "warning",
   category: "style",
+  description: "Limits the number of Declarable instances per file to encourage splitting by concern",
   check(context: LintContext, options?: Record<string, unknown>): LintDiagnostic[] {
     const limit = (typeof options?.max === "number" ? options.max : null) ?? DECLARABLE_LIMIT;
     const instances: ts.NewExpression[] = [];

package/src/lint/rules/flat-declarations.test.ts

@@ -163,7 +163,7 @@ describe("COR001: flat-declarations", () => {
     expect(diagnostics[0].ruleId).toBe("COR001");
   });
 
-  test("does not trigger inside Composite() factory callback", () => {
+  test("triggers inside Composite() factory callback", () => {
     const code = `
       const MyComposite = Composite((props) => {
         const role = new Role({
@@ -177,10 +177,11 @@ describe("COR001: flat-declarations", () => {
     `;
     const context = createContext(code);
     const diagnostics = flatDeclarationsRule.check(context);
-    expect(diagnostics).toHaveLength(0);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR001");
   });
 
-  test("does not trigger inside _.Composite() factory callback", () => {
+  test("triggers inside _.Composite() factory callback", () => {
     const code = `
       const MyComposite = _.Composite((props) => {
         const role = new _.Role({
@@ -191,10 +192,11 @@ describe("COR001: flat-declarations", () => {
     `;
     const context = createContext(code);
     const diagnostics = flatDeclarationsRule.check(context);
-    expect(diagnostics).toHaveLength(0);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].ruleId).toBe("COR001");
   });
 
-  test("still triggers outside Composite() in same file", () => {
+  test("triggers both inside and outside Composite() in same file", () => {
     const code = `
       const MyComposite = Composite((props) => {
         const role = new Role({ config: { value: 1 } });
@@ -204,7 +206,6 @@ describe("COR001: flat-declarations", () => {
     `;
     const context = createContext(code);
     const diagnostics = flatDeclarationsRule.check(context);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0].message).toContain("Inline object");
+    expect(diagnostics).toHaveLength(2);
   });
 });

package/src/lint/rules/flat-declarations.ts

@@ -1,6 +1,5 @@
 import * as ts from "typescript";
 import type { LintRule, LintContext, LintDiagnostic } from "../rule";
-import { isInsideCompositeFactory } from "./composite-scope";
 
 /**
  * COR001: No inline objects in Declarable constructors
@@ -17,8 +16,7 @@ import { isInsideCompositeFactory } from "./composite-scope";
 
 function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
   // Check for NewExpression nodes (constructor calls)
-  // Skip resource constructors inside Composite() factory callbacks
-  if (ts.isNewExpression(node) && !isInsideCompositeFactory(node)) {
+  if (ts.isNewExpression(node)) {
     // Check if the first argument is an object literal
     if (node.arguments && node.arguments.length > 0) {
       const firstArg = node.arguments[0];
@@ -62,6 +60,7 @@ export const flatDeclarationsRule: LintRule = {
   id: "COR001",
   severity: "warning",
   category: "style",
+  description: "Detects inline object literals in Declarable constructors — extract to named exports",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/no-cyclic-declarable-ref.ts

@@ -128,6 +128,7 @@ export const noCyclicDeclarableRefRule: LintRule = {
   id: "COR011",
   severity: "error",
   category: "correctness",
+  description: "Detects circular references between declarables in the same file",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const declarables = collectExportedDeclarables(context.sourceFile);

package/src/lint/rules/no-redundant-type-import.ts

@@ -13,6 +13,7 @@ export const noRedundantTypeImportRule: LintRule = {
   id: "COR012",
   severity: "warning",
   category: "style",
+  description: "Flags redundant type imports when a namespace import already provides access",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const sf = context.sourceFile;

package/src/lint/rules/no-redundant-value-cast.ts

@@ -38,6 +38,7 @@ export const noRedundantValueCastRule: LintRule = {
   id: "COR015",
   severity: "warning",
   category: "style",
+  description: "Flags redundant 'as Value<...>' casts — Intrinsic types already satisfy Value<T>",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     checkNode(context.sourceFile, context, diagnostics);

package/src/lint/rules/no-string-ref.ts

@@ -15,6 +15,7 @@ export const noStringRefRule: LintRule = {
   id: "COR003",
   severity: "warning",
   category: "correctness",
+  description: "Flags string-based GetAtt() and Ref() calls — use typed property access instead",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const sf = context.sourceFile;

package/src/lint/rules/no-unused-declarable-import.ts

@@ -77,6 +77,7 @@ export const noUnusedDeclarableImportRule: LintRule = {
   id: "COR010",
   severity: "warning",
   category: "style",
+  description: "Flags unused namespace imports from @intentius/chant packages",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const imports = collectNamespaceImports(context.sourceFile);

package/src/lint/rules/no-unused-declarable.test.ts

@@ -124,6 +124,14 @@ describe("COR004: no-unused-declarable", () => {
     expect(diags).toHaveLength(0);
   });
 
+  test("OK for Parameter declarations (inherently cross-file)", () => {
+    const ctx = createContext(
+      `export const environment = new Parameter("String", { description: "env" });`,
+    );
+    const diags = noUnusedDeclarableRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
   test("detects reference in array literal", () => {
     const ctx = createContext(
       `export const bucket = new Bucket({});\n` + `export const list = [bucket];`,

package/src/lint/rules/no-unused-declarable.ts

@@ -51,6 +51,9 @@ function collectExportedDeclarables(sourceFile: ts.SourceFile): DeclarableInfo[]
       const className = getNewExpressionClassName(decl.initializer);
       if (!className || !isCapitalized(className)) continue;
 
+      // Parameters are inherently cross-file (declared in params.ts, consumed via Ref() elsewhere)
+      if (className === "Parameter") continue;
+
       declarables.push({
         name: decl.name.text,
         node,
@@ -92,6 +95,7 @@ export const noUnusedDeclarableRule: LintRule = {
   id: "COR004",
   severity: "warning",
   category: "correctness",
+  description: "Detects exported declarables that are never referenced in the same file",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
     const declarables = collectExportedDeclarables(context.sourceFile);

package/src/lint/rules/single-concern-file.ts

@@ -64,6 +64,7 @@ export const singleConcernFileRule: LintRule = {
   id: "COR013",
   severity: "info",
   category: "style",
+  description: "Flags files mixing resource Declarables with configuration Declarables",
   check(context: LintContext): LintDiagnostic[] {
     const newExpressions: NewExpressionInfo[] = [];
     collectNewExpressions(context.sourceFile, context.sourceFile, newExpressions);

package/src/lsp/lexicon-providers.ts

@@ -19,6 +19,10 @@ export interface LexiconEntry {
   createOnly?: string[];
   writeOnly?: string[];
   primaryIdentifier?: string[];
+  deprecatedProperties?: string[];
+  conditionalCreateOnly?: string[];
+  replacementStrategy?: "delete_then_create" | "create_then_delete";
+  tagging?: { taggable: boolean; tagOnCreate: boolean; tagUpdatable: boolean };
 }
 
 // ── LexiconIndex ───────────────────────────────────────────────────
@@ -109,8 +113,10 @@ export function lexiconCompletions(
 
   if (constructorMatch) {
     const className = constructorMatch[1];
+    const entry = index.getEntry(className);
     const props = index.getPropertyNames(className);
     if (props.length > 0) {
+      const deprecatedSet = new Set(entry?.deprecatedProperties ?? []);
       const filtered = wordAtCursor
         ? props.filter((p) => p.toLowerCase().startsWith(wordAtCursor.toLowerCase()))
         : props;
@@ -119,6 +125,7 @@ export function lexiconCompletions(
         insertText: p,
         kind: "property" as const,
         detail: `Property of ${className}`,
+        ...(deprecatedSet.has(p) && { deprecated: true }),
       }));
     }
   }

package/src/lsp/types.ts

@@ -31,6 +31,7 @@ export interface CompletionItem {
   kind?: CompletionItemKind;
   detail?: string;
   documentation?: string;
+  deprecated?: boolean;
 }
 
 export interface CompletionContext {