@intentius/chant 0.0.1

package/src/lint/selectors.ts

@@ -0,0 +1,188 @@
+import * as ts from "typescript";
+
+/**
+ * A selector function that extracts matching nodes from a source file.
+ */
+export type SelectorFn = (sourceFile: ts.SourceFile) => ts.Node[];
+
+/**
+ * Registry of named selectors.
+ */
+const selectorRegistry = new Map<string, SelectorFn>();
+
+/**
+ * Recursively collect nodes matching a predicate.
+ */
+export function collectNodes(root: ts.Node, predicate: (node: ts.Node) => boolean): ts.Node[] {
+  const results: ts.Node[] = [];
+  function visit(node: ts.Node): void {
+    if (predicate(node)) {
+      results.push(node);
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(root);
+  return results;
+}
+
+/**
+ * Built-in selector: matches `new X(...)` constructor calls (resource instantiations).
+ */
+function selectResource(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => ts.isNewExpression(node));
+}
+
+/**
+ * Built-in selector: matches any resource — alias for `resource`.
+ */
+function selectAnyResource(sf: ts.SourceFile): ts.Node[] {
+  return selectResource(sf);
+}
+
+/**
+ * Built-in selector: matches string literal nodes.
+ */
+function selectStringLiteral(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => ts.isStringLiteral(node));
+}
+
+/**
+ * Built-in selector: matches exported declaration names.
+ */
+function selectExportName(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => {
+    if (ts.isVariableStatement(node)) {
+      return node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    }
+    if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) {
+      return node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    }
+    return false;
+  });
+}
+
+/**
+ * Built-in selector: matches import source strings.
+ */
+function selectImportSource(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => {
+    if (ts.isImportDeclaration(node)) {
+      return true;
+    }
+    return false;
+  });
+}
+
+/**
+ * Built-in selector: matches property assignments.
+ */
+function selectProperty(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => ts.isPropertyAssignment(node));
+}
+
+/**
+ * Built-in selector: matches the type argument of `new X<Type>(...)` expressions.
+ */
+function selectResourceType(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => {
+    if (ts.isNewExpression(node) && node.typeArguments && node.typeArguments.length > 0) {
+      return true;
+    }
+    return false;
+  });
+}
+
+/**
+ * Built-in selector: matches exported const declarations.
+ */
+function selectExportedConst(sf: ts.SourceFile): ts.Node[] {
+  return collectNodes(sf, (node) => {
+    if (!ts.isVariableStatement(node)) return false;
+    const hasExport = node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    if (!hasExport) return false;
+    return node.declarationList.flags === ts.NodeFlags.Const ||
+      (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
+  });
+}
+
+// Register built-in selectors
+const builtins: [string, SelectorFn][] = [
+  ["resource", selectResource],
+  ["any-resource", selectAnyResource],
+  ["string-literal", selectStringLiteral],
+  ["export-name", selectExportName],
+  ["import-source", selectImportSource],
+  ["property", selectProperty],
+  ["resource-type", selectResourceType],
+  ["exported-const", selectExportedConst],
+];
+
+for (const [name, fn] of builtins) {
+  selectorRegistry.set(name, fn);
+}
+
+/**
+ * Register a custom selector.
+ */
+export function registerSelector(name: string, fn: SelectorFn): void {
+  selectorRegistry.set(name, fn);
+}
+
+/**
+ * Resolve a selector name (or compound expression) to a SelectorFn.
+ *
+ * Compound selectors use `>` to scope: `"resource > property"` means
+ * "find all `resource` nodes, then within each, find all `property` nodes".
+ */
+export function resolveSelector(name: string): SelectorFn {
+  // Check for compound selector
+  if (name.includes(">")) {
+    const parts = name.split(">").map((s) => s.trim());
+    const fns = parts.map((part) => {
+      const fn = selectorRegistry.get(part);
+      if (!fn) {
+        throw new Error(`Unknown selector: "${part}"`);
+      }
+      return fn;
+    });
+
+    return (sf: ts.SourceFile): ts.Node[] => {
+      // Start with results from first selector
+      let nodes = fns[0](sf);
+
+      // For each subsequent selector, search within current nodes
+      for (let i = 1; i < fns.length; i++) {
+        const nextNodes: ts.Node[] = [];
+        for (const parent of nodes) {
+          const childSelector = fns[i];
+          const allMatches = childSelector(sf);
+          for (const match of allMatches) {
+            if (isDescendantOf(match, parent)) {
+              nextNodes.push(match);
+            }
+          }
+        }
+        nodes = nextNodes;
+      }
+      return nodes;
+    };
+  }
+
+  const fn = selectorRegistry.get(name);
+  if (!fn) {
+    throw new Error(`Unknown selector: "${name}"`);
+  }
+  return fn;
+}
+
+/**
+ * Check if a node is a descendant of another node.
+ */
+function isDescendantOf(node: ts.Node, ancestor: ts.Node): boolean {
+  let current = node.parent;
+  while (current) {
+    if (current === ancestor) return true;
+    current = current.parent;
+  }
+  return false;
+}

package/src/lsp/lexicon-providers.ts

@@ -0,0 +1,191 @@
+/**
+ * Generic lexicon-based LSP completion and hover providers.
+ *
+ * Provides LexiconIndex for looking up resources/properties by class name,
+ * and helper functions that implement the common completion/hover patterns
+ * shared across lexicons.
+ */
+
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "./types";
+
+// ── Lexicon Entry ──────────────────────────────────────────────────
+
+export interface LexiconEntry {
+  resourceType: string;
+  kind: "resource" | "property";
+  lexicon: string;
+  attrs?: Record<string, string>;
+  propertyConstraints?: Record<string, unknown>;
+  createOnly?: string[];
+  writeOnly?: string[];
+  primaryIdentifier?: string[];
+}
+
+// ── LexiconIndex ───────────────────────────────────────────────────
+
+/**
+ * Indexed access to lexicon entries for LSP features.
+ */
+export class LexiconIndex {
+  constructor(private entries: Record<string, LexiconEntry>) {}
+
+  /** All resource class names with their backing type names. */
+  getResourceNames(): Array<{ className: string; resourceType: string }> {
+    const results: Array<{ className: string; resourceType: string }> = [];
+    for (const [name, entry] of Object.entries(this.entries)) {
+      if (entry.kind === "resource") {
+        results.push({ className: name, resourceType: entry.resourceType });
+      }
+    }
+    return results;
+  }
+
+  /** Property names available on a given resource class. */
+  getPropertyNames(className: string): string[] {
+    const entry = this.entries[className];
+    if (!entry || entry.kind !== "resource") return [];
+
+    const props: string[] = [];
+    if (entry.propertyConstraints) {
+      props.push(...Object.keys(entry.propertyConstraints));
+    }
+    if (entry.createOnly) {
+      for (const p of entry.createOnly) {
+        if (!props.includes(p)) props.push(p);
+      }
+    }
+    if (entry.writeOnly) {
+      for (const p of entry.writeOnly) {
+        if (!props.includes(p)) props.push(p);
+      }
+    }
+    return props;
+  }
+
+  /** Look up a single entry by class name. */
+  getEntry(name: string): LexiconEntry | undefined {
+    return this.entries[name];
+  }
+}
+
+// ── Completion helper ──────────────────────────────────────────────
+
+/**
+ * Provide completions from a lexicon index.
+ *
+ * Handles two contexts:
+ * - After `new ` — suggests resource class names
+ * - Inside constructor props — suggests property names
+ *
+ * @param importSource - Human-readable source label for documentation
+ *   (e.g. "AWS CloudFormation resource")
+ */
+export function lexiconCompletions(
+  ctx: CompletionContext,
+  index: LexiconIndex,
+  importSource: string,
+): CompletionItem[] {
+  const { linePrefix, wordAtCursor } = ctx;
+
+  // After `new ` — suggest resource class names
+  if (/\bnew\s+\w*$/.test(linePrefix)) {
+    const resources = index.getResourceNames();
+    const filtered = wordAtCursor
+      ? resources.filter((r) => r.className.toLowerCase().startsWith(wordAtCursor.toLowerCase()))
+      : resources;
+
+    return filtered.slice(0, 50).map((r) => ({
+      label: r.className,
+      insertText: r.className,
+      kind: "resource" as const,
+      detail: r.resourceType,
+      documentation: `${importSource}: ${r.resourceType}`,
+    }));
+  }
+
+  // Inside constructor props — look for `new ClassName({` pattern
+  const constructorMatch = ctx.content.slice(0, ctx.content.split("\n").slice(0, ctx.position.line + 1).join("\n").length)
+    .match(/\bnew\s+(\w+)\s*\(\s*(?:["'][^"']*["']\s*,\s*)?{[^}]*$/s);
+
+  if (constructorMatch) {
+    const className = constructorMatch[1];
+    const props = index.getPropertyNames(className);
+    if (props.length > 0) {
+      const filtered = wordAtCursor
+        ? props.filter((p) => p.toLowerCase().startsWith(wordAtCursor.toLowerCase()))
+        : props;
+      return filtered.map((p) => ({
+        label: p,
+        insertText: p,
+        kind: "property" as const,
+        detail: `Property of ${className}`,
+      }));
+    }
+  }
+
+  return [];
+}
+
+// ── Hover helper ───────────────────────────────────────────────────
+
+/**
+ * Provide hover information from a lexicon index.
+ *
+ * @param formatHover - Lexicon-specific hover content formatter.
+ *   If not provided, uses a generic format.
+ */
+export function lexiconHover(
+  ctx: HoverContext,
+  index: LexiconIndex,
+  formatHover?: (className: string, entry: LexiconEntry) => HoverInfo | undefined,
+): HoverInfo | undefined {
+  const { word } = ctx;
+  if (!word) return undefined;
+
+  const entry = index.getEntry(word);
+  if (!entry) return undefined;
+
+  if (formatHover) {
+    return formatHover(word, entry);
+  }
+
+  // Default hover format for resource entries
+  if (entry.kind === "resource") {
+    return defaultResourceHover(word, entry);
+  }
+
+  return undefined;
+}
+
+function defaultResourceHover(className: string, entry: LexiconEntry): HoverInfo {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`Resource type: \`${entry.resourceType}\``);
+
+  if (entry.attrs && Object.keys(entry.attrs).length > 0) {
+    lines.push("");
+    lines.push("**Attributes:**");
+    for (const [key, value] of Object.entries(entry.attrs)) {
+      lines.push(`- \`${key}\` → \`${value}\``);
+    }
+  }
+
+  if (entry.primaryIdentifier && entry.primaryIdentifier.length > 0) {
+    lines.push("");
+    lines.push(`**Primary identifier:** ${entry.primaryIdentifier.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  if (entry.createOnly && entry.createOnly.length > 0) {
+    lines.push("");
+    lines.push(`**Create-only:** ${entry.createOnly.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  if (entry.writeOnly && entry.writeOnly.length > 0) {
+    lines.push("");
+    lines.push(`**Write-only:** ${entry.writeOnly.map((p) => `\`${p}\``).join(", ")}`);
+  }
+
+  return { contents: lines.join("\n") };
+}

package/src/lsp/types.ts

@@ -0,0 +1,79 @@
+/**
+ * Simplified LSP types for lexicon plugin contributions.
+ * No dependency on vscode-languageserver — just plain interfaces.
+ */
+
+export interface Position {
+  line: number;
+  character: number;
+}
+
+export interface Range {
+  start: Position;
+  end: Position;
+}
+
+export interface TextEdit {
+  range: Range;
+  newText: string;
+}
+
+export type CompletionItemKind =
+  | "resource"
+  | "property"
+  | "intrinsic"
+  | "pseudo-parameter"
+  | "value";
+
+export interface CompletionItem {
+  label: string;
+  insertText?: string;
+  kind?: CompletionItemKind;
+  detail?: string;
+  documentation?: string;
+}
+
+export interface CompletionContext {
+  uri: string;
+  content: string;
+  position: Position;
+  wordAtCursor: string;
+  linePrefix: string;
+}
+
+export interface HoverInfo {
+  contents: string;
+  range?: Range;
+}
+
+export interface HoverContext {
+  uri: string;
+  content: string;
+  position: Position;
+  word: string;
+  lineText: string;
+}
+
+export type CodeActionKind = "quickfix" | "refactor" | "source";
+
+export interface CodeAction {
+  title: string;
+  kind: CodeActionKind;
+  edits?: TextEdit[];
+  diagnosticRuleId?: string;
+  isPreferred?: boolean;
+}
+
+export interface CodeActionContext {
+  uri: string;
+  content: string;
+  range: Range;
+  diagnostics: CodeActionDiagnostic[];
+}
+
+export interface CodeActionDiagnostic {
+  range: Range;
+  message: string;
+  ruleId?: string;
+  severity?: "error" | "warning" | "info";
+}

package/src/mcp/types.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP contribution types for lexicon plugins.
+ */
+
+export interface McpToolContribution {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+  handler: (params: Record<string, unknown>) => Promise<unknown>;
+}
+
+export interface McpResourceContribution {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType?: string;
+  handler: () => Promise<string>;
+}

package/src/project/scan.test.ts

@@ -0,0 +1,178 @@
+import { describe, test, expect } from "bun:test";
+import { scanProject } from "./scan";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("scanProject", () => {
+  test("finds barrel and extracts lexicon package", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\nexport * from "./storage";\n`,
+      );
+      await writeFile(
+        join(dir, "storage.ts"),
+        `import * as td from "@intentius/chant-lexicon-testdom";\nexport const bucket = new td.Bucket({});\n`,
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.barrelPath).toBe(join(dir, "_.ts"));
+      expect(scan.lexiconPackage).toBe("@intentius/chant-lexicon-testdom");
+    });
+  });
+
+  test("collects exports from sibling files", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "storage.ts"),
+        `import * as td from "@intentius/chant-lexicon-testdom";\nexport const dataBucket = new td.Bucket({});\nexport const logsBucket = new td.Bucket({});\n`,
+      );
+      await writeFile(
+        join(dir, "compute.ts"),
+        `import * as td from "@intentius/chant-lexicon-testdom";\nexport const handler = new td.Function({});\n`,
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.exports).toHaveLength(3);
+      const names = scan.exports.map((e) => e.name);
+      expect(names).toContain("dataBucket");
+      expect(names).toContain("logsBucket");
+      expect(names).toContain("handler");
+    });
+  });
+
+  test("infers class names from new X.ClassName(...) patterns", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "resources.ts"),
+        [
+          `import * as td from "@intentius/chant-lexicon-testdom";`,
+          `export const bucket = new td.Bucket({});`,
+          `export const role = new td.Role({});`,
+          `export const fn = new td.Function({});`,
+        ].join("\n"),
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.exports).toHaveLength(3);
+
+      const bucket = scan.exports.find((e) => e.name === "bucket");
+      expect(bucket?.className).toBe("Bucket");
+
+      const role = scan.exports.find((e) => e.name === "role");
+      expect(role?.className).toBe("Role");
+
+      const fn = scan.exports.find((e) => e.name === "fn");
+      expect(fn?.className).toBe("Function");
+    });
+  });
+
+  test("infers class names from type annotations", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "config.ts"),
+        [
+          `import * as td from "@intentius/chant-lexicon-testdom";`,
+          `export const encryption: td.ServerSideEncryptionByDefault = { sseAlgorithm: "AES256" };`,
+          `export const versioning: td.VersioningConfiguration = { status: "Enabled" };`,
+        ].join("\n"),
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.exports).toHaveLength(2);
+
+      const encryption = scan.exports.find((e) => e.name === "encryption");
+      expect(encryption?.className).toBe("ServerSideEncryptionByDefault");
+
+      const versioning = scan.exports.find((e) => e.name === "versioning");
+      expect(versioning?.className).toBe("VersioningConfiguration");
+    });
+  });
+
+  test("excludes barrel, test files, and underscore-prefixed files", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "_internal.ts"),
+        `export const secret = "hidden";\n`,
+      );
+      await writeFile(
+        join(dir, "app.test.ts"),
+        `import { test } from "bun:test";\ntest("passes", () => {});\n`,
+      );
+      await writeFile(
+        join(dir, "app.spec.ts"),
+        `import { test } from "bun:test";\ntest("passes", () => {});\n`,
+      );
+      await writeFile(
+        join(dir, "app.ts"),
+        `export const app = "hello";\n`,
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.exports).toHaveLength(1);
+      expect(scan.exports[0].name).toBe("app");
+    });
+  });
+
+  test("throws on missing barrel", async () => {
+    await withTestDir(async (dir) => {
+      expect(() => scanProject(dir)).toThrow("No barrel file found");
+    });
+  });
+
+  test("returns empty className for exports without recognizable patterns", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "utils.ts"),
+        `export const greeting = "hello";\nexport const count = 42;\n`,
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.exports).toHaveLength(2);
+      for (const exp of scan.exports) {
+        expect(exp.className).toBe("");
+      }
+    });
+  });
+
+  test("infers class names from new _.ClassName(...) patterns", async () => {
+    await withTestDir(async (dir) => {
+      await writeFile(
+        join(dir, "_.ts"),
+        `export * from "@intentius/chant-lexicon-testdom";\n`,
+      );
+      await writeFile(
+        join(dir, "resources.ts"),
+        [
+          `import * as _ from "./_";`,
+          `export const bucket = new _.Bucket({});`,
+        ].join("\n"),
+      );
+
+      const scan = scanProject(dir);
+      expect(scan.exports).toHaveLength(1);
+      expect(scan.exports[0].className).toBe("Bucket");
+    });
+  });
+});