@intentius/chant 0.84.0 → 0.85.0

package/src/cli/mcp/tools/composites.ts

@@ -0,0 +1,98 @@
+import type { CompositeEntry, LexiconPlugin } from "../../../lexicon";
+
+/**
+ * The `composites` tool (#2662): what composites the loaded lexicons export,
+ * what each one bundles and what it takes. "What composites do you have for
+ * aws?" is `{ lexicon: "aws" }`.
+ *
+ * Everything here reads `LexiconPlugin.composites()`, which is static catalog
+ * data. No composite is loaded or called and no provider is asked anything.
+ */
+export const compositesTool = {
+  name: "composites",
+  description:
+    "List the composites the loaded lexicons export: what each builds, the resource kinds it bundles, and its parameters",
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      lexicon: {
+        type: "string",
+        description: "Only composites from this lexicon (e.g. 'aws', 'k8s')",
+      },
+      query: {
+        type: "string",
+        description: "Keyword matched against the composite's name, description, bundled resource kinds and parameter names",
+      },
+      limit: {
+        type: "number",
+        description: "Maximum number of composites to return (default: 50)",
+      },
+    },
+  },
+};
+
+/**
+ * Every composite the plugins contribute, in plugin order. A plugin whose
+ * `composites()` throws contributes nothing rather than failing the listing.
+ */
+export function collectComposites(plugins: LexiconPlugin[]): CompositeEntry[] {
+  const entries: CompositeEntry[] = [];
+  for (const plugin of plugins) {
+    let contributed: CompositeEntry[] = [];
+    try {
+      contributed = plugin.composites?.() ?? [];
+    } catch {
+      contributed = [];
+    }
+    for (const entry of contributed) entries.push({ ...entry, lexicon: entry.lexicon || plugin.name });
+  }
+  return entries;
+}
+
+/**
+ * How well an entry matches a lowercased keyword: 0 for no match, higher for
+ * better. A name match beats a bundled kind, which beats a word in the
+ * description or a parameter name, so `queue` lists `LambdaSqs` ahead of a
+ * composite that merely mentions queues.
+ */
+export function compositeMatchScore(entry: CompositeEntry, lowerQuery: string): number {
+  const name = entry.name.toLowerCase();
+  if (name.startsWith(lowerQuery)) return 4;
+  if (name.includes(lowerQuery)) return 3;
+  if (entry.bundles.some((b) => b.toLowerCase().includes(lowerQuery))) return 2;
+  if (entry.description.toLowerCase().includes(lowerQuery)) return 1;
+  if (entry.params.some((p) => p.name.toLowerCase().includes(lowerQuery))) return 1;
+  return 0;
+}
+
+export function createCompositesHandler(
+  plugins: LexiconPlugin[],
+): (params: Record<string, unknown>) => Promise<unknown> {
+  return async (params) => {
+    const lexicon = typeof params.lexicon === "string" && params.lexicon !== "" ? params.lexicon : undefined;
+    const query = typeof params.query === "string" && params.query !== "" ? params.query : undefined;
+    const limit = typeof params.limit === "number" ? params.limit : 50;
+
+    let entries = collectComposites(plugins);
+    if (lexicon) entries = entries.filter((e) => e.lexicon === lexicon);
+
+    if (query) {
+      const lowerQuery = query.toLowerCase();
+      entries = entries
+        .map((entry) => ({ entry, score: compositeMatchScore(entry, lowerQuery) }))
+        .filter(({ score }) => score > 0)
+        .sort((a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name))
+        .map(({ entry }) => entry);
+    }
+
+    return {
+      ...(lexicon ? { lexicon } : {}),
+      ...(query ? { query } : {}),
+      // The loaded lexicons, so an empty answer for `lexicon: "cedar"` reads
+      // as "cedar exports none" when cedar is listed, and "not loaded" when not.
+      lexicons: plugins.map((p) => p.name),
+      total: entries.length,
+      composites: entries.slice(0, limit),
+    };
+  };
+}

package/src/cli/mcp/tools/search.ts

@@ -1,17 +1,20 @@
 import type { LexiconPlugin } from "../../../lexicon";
+import { collectComposites, compositeMatchScore } from "./composites";
 
 /**
  * Search tool definition for MCP
  */
 export const searchTool = {
   name: "search",
-  description: "Search the resource catalog across loaded lexicons by keyword",
+  description:
+    "Search the resource catalog and the composite catalog across loaded lexicons by keyword; a composite comes back with kind 'composite'",
   inputSchema: {
     type: "object" as const,
     properties: {
       query: {
         type: "string",
-        description: "Search query — matches against resource type, class name, and kind",
+        description:
+          "Search query: matches a resource's type, class name and kind, and a composite's name, description and the resource kinds it bundles",
       },
       lexicon: {
         type: "string",
@@ -32,6 +35,20 @@ interface CatalogEntry {
   kind?: string;
 }
 
+/** A composite in search results (#2662): `kind` is always `"composite"`. */
+interface CompositeResult {
+  kind: "composite";
+  name: string;
+  description: string;
+  bundles: string[];
+}
+
+type SearchResult = (CatalogEntry | CompositeResult) & { lexicon: string; score: number };
+
+function sortKey(result: SearchResult): string {
+  return "resourceType" in result ? result.resourceType ?? "" : result.name;
+}
+
 /**
  * Create a search handler with access to loaded plugins
  */
@@ -44,7 +61,7 @@ export function createSearchHandler(
     const limit = (params.limit as number) ?? 20;
 
     const lowerQuery = query.toLowerCase();
-    const results: Array<CatalogEntry & { lexicon: string; score: number }> = [];
+    const results: SearchResult[] = [];
 
     const candidates = lexiconFilter
       ? plugins.filter((p) => p.name === lexiconFilter)
@@ -86,10 +103,35 @@ export function createSearchHandler(
       }
     }
 
-    // Sort: prefix matches first, then alphabetical by resourceType
+    // Composites (#2662), so one query finds both a resource type and the
+    // composite that bundles it. A name or bundled-kind prefix ranks with the
+    // resource prefix matches. The full entry (params included) is the
+    // `composites` tool's answer; search keeps a result short.
+    for (const entry of collectComposites(candidates)) {
+      const score = compositeMatchScore(entry, lowerQuery);
+      if (score === 0) continue;
+      const isPrefix =
+        entry.name.toLowerCase().startsWith(lowerQuery) ||
+        entry.bundles.some((b) => b.toLowerCase().startsWith(lowerQuery));
+      results.push({
+        kind: "composite",
+        name: entry.name,
+        description: entry.description,
+        bundles: entry.bundles,
+        lexicon: entry.lexicon,
+        score: isPrefix ? 1 : 0,
+      });
+    }
+
+    // Sort: prefix matches first; within a tier composites ahead of resource
+    // types, since a handful of composites would otherwise sort behind every
+    // `AWS::...` type the same word prefixes; then alphabetical.
     results.sort((a, b) => {
       if (a.score !== b.score) return b.score - a.score;
-      return (a.resourceType ?? "").localeCompare(b.resourceType ?? "");
+      const aComposite = a.kind === "composite" ? 0 : 1;
+      const bComposite = b.kind === "composite" ? 0 : 1;
+      if (aComposite !== bComposite) return aComposite - bComposite;
+      return sortKey(a).localeCompare(sortKey(b));
     });
 
     const limited = results.slice(0, limit);

package/src/cli/registry.ts

@@ -285,6 +285,8 @@ export interface ParsedArgs {
   kind?: string;
   /** Every `--kind` given, in order: `chant workspace graph --intent` reads each (#2651). */
   kinds?: string[];
+  /** `chant workspace graph --composites` (#2662): print each composite instance with the components that can deploy it. */
+  composites?: boolean;
   /** `chant workspace graph --intent <path[:start-end]>` (#2651): the region the intent graph is over. */
   intent?: string;
   /** `chant workspace records --current` (#2546): leave out records a closed record supersedes. */

package/src/components/cli-support.test.ts

@@ -389,6 +389,22 @@ export const backup =
     expect(result.composites?.["aws-plane"]).toEqual(["ArtifactBucket", "OperatorRole"]);
     expect(result.composites?.plain).toBeUndefined();
   });
+
+  test("carries each component's archetype, declared or inferred (#2662)", async () => {
+    await writeFile(
+      join(testDir, "lib.component.ts"),
+      `export const lib = { name: "lib", archetype: "service", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "plain.component.ts"),
+      `export const plain = { name: "plain", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+
+    const result = await computeComponentGraph(testDir);
+
+    expect(result.success).toBe(true);
+    expect(result.archetypes).toEqual({ lib: "service", plain: "infra" });
+  });
 });
 
 // ── runComponents (#585) ─────────────────────────────────────────────────────

package/src/components/cli-support.ts

@@ -25,7 +25,7 @@
 import { lexiconModulePath, lexiconNames } from "../lexicon-module";
 import { discoverComponents } from "./discover";
 import type { BuildParamProvenance } from "../provenance";
-import { projectToJson, type Archetype } from "./component";
+import { inferArchetype, projectToJson, type Archetype } from "./component";
 import {
   resolveComponentGraph,
   runInterpretDriver,
@@ -152,6 +152,10 @@ export interface ComponentGraphResult {
    * entirely rather than defaulting to a guess; a consumer with no entry here
    * keeps applying its own naming-convention default. */
   composites?: Record<string, string[]>;
+  /** Component name → its archetype, declared or inferred from the composition
+   * (`inferArchetype`), so a reader can label a component without its source
+   * (#2662). */
+  archetypes?: Record<string, Archetype>;
   error?: string;
 }
 
@@ -187,7 +191,9 @@ export async function computeComponentGraph(
   // component name → declared composite kind(s) (#1492), only for components
   // that declared them — no identity fallback (see ComponentGraphResult doc).
   const composites: Record<string, string[]> = {};
+  const archetypes: Record<string, Archetype> = {};
   for (const [name, discovered] of result.components) {
+    archetypes[name] = discovered.component.archetype ?? inferArchetype(discovered.component);
     files[name] = relative(path, discovered.filePath);
     const declared = discovered.component.liveNames;
     liveNames[name] = declared && declared.length > 0 ? [...declared] : [name];
@@ -201,7 +207,7 @@ export async function computeComponentGraph(
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files, liveNames, composites };
+    return { success: true, order, waves, edges, files, liveNames, composites, archetypes };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };

package/src/composite.ts

@@ -71,6 +71,15 @@ export function isCompositeInstance(value: unknown): value is CompositeInstance
   );
 }
 
+/**
+ * Type guard: is this value a composite definition, what `Composite()` and
+ * `withDefaults()` return? A lexicon's composite catalog test uses it to find
+ * the composites a module exports (#2662).
+ */
+export function isCompositeDefinition(value: unknown): value is CompositeDefinition<unknown> {
+  return typeof value === "function" && typeof (value as { compositeName?: unknown }).compositeName === "string";
+}
+
 /**
  * Global registry of composite definitions.
  */

package/src/lexicon.ts

@@ -28,6 +28,7 @@ import type { BehaviourKinds } from "./behaviour-kinds";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
+import type { Archetype } from "./components/component";
 
 // Re-exported so a lexicon that hosts Op runs (#2121) can type its
 // `opRuntime` from the same entry it imports the plugin contract from.
@@ -929,6 +930,45 @@ export interface AuditEntitiesInput {
   baseDir?: string;
 }
 
+/**
+ * One parameter of a composite, read from the composite's declared props type
+ * (#2662).
+ */
+export interface CompositeParam {
+  /** The prop name as a caller writes it. */
+  name: string;
+  /** The declared TypeScript type, as source text (long inline types are shortened). */
+  type: string;
+  /** False when the prop is optional. */
+  required: boolean;
+  /** The prop's JSDoc summary, when it has one. */
+  description?: string;
+}
+
+/**
+ * A composite this lexicon exports, as static catalog data (#2662).
+ *
+ * The catalog is what `chant serve mcp` answers "what composites do you have
+ * for aws?" from: the `composites` tool, the `chant://composites` resource and
+ * `search` results of kind `composite` all read it, and none of them calls a
+ * provider. A lexicon writes it once, from source, and a test in the lexicon
+ * holds it to the composites the package actually exports.
+ */
+export interface CompositeEntry {
+  /** The exported name a caller imports (an alias gets its own entry). */
+  name: string;
+  /** The lexicon that exports it. */
+  lexicon: string;
+  /** One line saying what it builds. */
+  description: string;
+  /** Resource kinds (the lexicon's class names) its members are, nested composites flattened. */
+  bundles: string[];
+  /** Its props, from the declared props type. */
+  params: CompositeParam[];
+  /** The component archetype that ships it, when that is known. */
+  archetype?: Archetype;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -1212,6 +1252,13 @@ export interface LexiconPlugin {
   /** Generate documentation pages */
   docs?(options?: { verbose?: boolean }): Promise<void>;
 
+  /**
+   * The composites this lexicon exports, as static data (#2662). Read by the
+   * MCP `composites` tool, the `chant://composites` resource and `search`.
+   * Omit for a lexicon that exports no composites.
+   */
+  composites?(): CompositeEntry[];
+
   // MCP
   /** Return MCP tool contributions */
   mcpTools?(): McpToolContribution[];

package/src/workspace/__fixtures__/contract-repo.ts

@@ -98,3 +98,20 @@ case "$1" in
   *) echo "Error: Unknown command: $1" >&2; exit 1 ;;
 esac
 `;
+
+/**
+ * A chant older than `workspace member-run` that answers from files (#2662):
+ * `chant graph --components` prints the member's `components.json`, or an
+ * empty IR when there is none, and plain `chant graph` prints `ir.json`. A
+ * `components.json` holding `FAIL` makes the component graph exit 1.
+ */
+export const FAKE_FILE_GRAPH_CHANT = `#!/bin/sh
+[ "$1" = graph ] || { echo "Error: Unknown command: $1" >&2; exit 1; }
+case " $* " in
+  *" --components "*)
+    if [ ! -f components.json ]; then printf '{"version":1,"nodes":[],"edges":[],"groups":{}}\\n'
+    elif grep -q FAIL components.json; then echo "Error: component discovery failed" >&2; exit 1
+    else cat components.json; fi ;;
+  *) cat ir.json ;;
+esac
+`;