@intentius/chant 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.ts

@@ -1,5 +1,6 @@
 import type { Declarable } from "./declarable";
 import type { Serializer, SerializerResult } from "./serializer";
+import type { OwnershipMarker } from "./ownership";
 import type { DiscoveryError, BuildError } from "./errors";
 import { BuildError as BuildErrorClass } from "./errors";
 import { LexiconOutput, isLexiconOutput } from "./lexicon-output";
@@ -24,6 +25,17 @@ export interface BuildManifest {
 /**
  * Result of the build process
  */
+/**
+ * Optional inputs to the build pipeline.
+ */
+export interface BuildOptions {
+  /**
+   * When set, serializers stamp this ownership marker into each resource's
+   * native metadata channel. Resolved from project config by the caller.
+   */
+  ownership?: OwnershipMarker;
+}
+
 export interface BuildResult {
   /** Map of lexicon name to serialized output (string or multi-file result) */
   outputs: Map<string, string | SerializerResult>;
@@ -310,6 +322,7 @@ export async function build(
   path: string,
   serializers: Serializer[],
   parentBuildStack?: Set<string>,
+  options?: BuildOptions,
 ): Promise<BuildResult> {
   const warnings: string[] = [];
   const errors: Array<DiscoveryError | BuildError> = [];
@@ -363,7 +376,7 @@ export async function build(
         );
         continue;
       }
-      const childResult = await build(childPath, serializers, buildStack);
+      const childResult = await build(childPath, serializers, buildStack, options);
       entity.buildResult = childResult;
       if (childResult.errors.length > 0) {
         for (const err of childResult.errors) {
@@ -429,7 +442,10 @@ export async function build(
         ...(outputsByLexicon.get(lexiconName) ?? []),
         ...unassignedOutputs,
       ];
-      outputs.set(lexiconName, serializer.serialize(lexiconEntities, lexiconLexiconOutputs));
+      outputs.set(
+        lexiconName,
+        serializer.serialize(lexiconEntities, lexiconLexiconOutputs, { ownership: options?.ownership }),
+      );
     } else {
       warnings.push(`No serializer found for lexicon "${lexiconName}"`);
     }

package/src/cli/commands/build.ts

@@ -1,4 +1,5 @@
 import { build } from "../../build";
+import { loadChantConfig, resolveOwnershipMarker } from "../../config";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
 import { runPostSynthChecks } from "../../lint/post-synth";
@@ -53,8 +54,15 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // Resolve the path
   const infraPath = resolve(options.path);
 
+  // Resolve opt-in ownership marking from project config (search the infra dir
+  // and its parent, where chant.config.* usually lives).
+  const { config } = await loadChantConfig(infraPath).then((r) =>
+    r.configPath ? r : loadChantConfig(dirname(infraPath)),
+  );
+  const ownership = resolveOwnershipMarker(config);
+
   // Run the build
-  const result = await build(infraPath, options.serializers);
+  const result = await build(infraPath, options.serializers, undefined, { ownership });
 
   // Format errors
   for (const error of result.errors) {

package/src/cli/commands/import-live.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { liveImportFromPlugins } from "./import";
+import { mkdir, rm, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { LexiconPlugin, ExportedTemplate, ResourceSelector } from "../../lexicon";
+import type { TypeScriptGenerator } from "../../import/generator";
+import type { TemplateIR } from "../../import/parser";
+
+const generator: TypeScriptGenerator = {
+  generate(ir: TemplateIR) {
+    return [
+      {
+        path: "main.ts",
+        content: ir.resources
+          .map((r) => `export const ${r.logicalId} = ${JSON.stringify(r.properties)};`)
+          .join("\n"),
+      },
+    ];
+  },
+};
+
+function fakeExporter(name: string, ir: ExportedTemplate): LexiconPlugin {
+  return {
+    name,
+    serializer: {} as never,
+    generate: async () => {},
+    validate: async () => {},
+    coverage: async () => {},
+    package: async () => {},
+    templateGenerator: () => generator,
+    async exportResources(opts: { selector?: ResourceSelector }): Promise<ExportedTemplate> {
+      if (!opts.selector) return ir;
+      return {
+        ...ir,
+        resources: ir.resources.filter(
+          (r) =>
+            (opts.selector!.type === undefined || r.type === opts.selector!.type) &&
+            (opts.selector!.name === undefined || r.logicalId === opts.selector!.name),
+        ),
+      };
+    },
+  };
+}
+
+const sampleIR: ExportedTemplate = {
+  resources: [
+    { logicalId: "bucket", type: "Fake::Bucket", properties: { versioning: true } },
+    { logicalId: "queue", type: "Fake::Queue", properties: { fifo: false } },
+  ],
+  parameters: [],
+};
+
+describe("liveImportFromPlugins (#114)", () => {
+  let outputDir: string;
+
+  beforeEach(async () => {
+    outputDir = join(tmpdir(), `chant-live-import-${Date.now()}-${Math.random()}`);
+    await mkdir(outputDir, { recursive: true });
+  });
+  afterEach(async () => {
+    await rm(outputDir, { recursive: true, force: true });
+  });
+
+  test("regenerates resources from a live exporter", async () => {
+    const result = await liveImportFromPlugins([fakeExporter("fake", sampleIR)], {
+      environment: "prod",
+      output: outputDir,
+      force: true,
+    });
+    expect(result.success).toBe(true);
+    expect(result.lexicon).toBe("fake");
+    const content = await readFile(join(outputDir, result.generatedFiles[0]), "utf-8");
+    expect(content).toContain("bucket");
+    expect(content).toContain("queue");
+  });
+
+  test("--name selector narrows the regenerated source", async () => {
+    const result = await liveImportFromPlugins([fakeExporter("fake", sampleIR)], {
+      environment: "prod",
+      output: outputDir,
+      force: true,
+      selector: { name: "queue" },
+    });
+    const content = await readFile(join(outputDir, result.generatedFiles[0]), "utf-8");
+    expect(content).toContain("queue");
+    expect(content).not.toContain("bucket");
+  });
+
+  test("errors when no lexicon supports live export", async () => {
+    const nonExporter: LexiconPlugin = {
+      name: "noexport",
+      serializer: {} as never,
+      generate: async () => {},
+      validate: async () => {},
+      coverage: async () => {},
+      package: async () => {},
+    };
+    const result = await liveImportFromPlugins([nonExporter], {
+      environment: "prod",
+      output: outputDir,
+    });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("live export");
+  });
+
+  test("--lexicon narrows to the named exporter", async () => {
+    const result = await liveImportFromPlugins(
+      [fakeExporter("a", sampleIR), fakeExporter("b", sampleIR)],
+      { environment: "prod", output: outputDir, force: true, lexicon: "b" },
+    );
+    expect(result.success).toBe(true);
+    expect(result.lexicon).toBe("b");
+  });
+
+  test("errors when the environment exports nothing", async () => {
+    const empty = fakeExporter("fake", { resources: [], parameters: [] });
+    const result = await liveImportFromPlugins([empty], {
+      environment: "prod",
+      output: outputDir,
+    });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("No resources exported");
+  });
+});

package/src/cli/commands/import.ts

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "fs";
 import { join, resolve, basename, dirname } from "path";
 import { formatSuccess, formatWarning, formatError } from "../format";
-import type { TemplateIR, ResourceIR, TemplateParser } from "../../import/parser";
+import type { TemplateIR, ResourceIR, ParameterIR, TemplateParser } from "../../import/parser";
 import type { GeneratedFile, TypeScriptGenerator } from "../../import/generator";
 import { loadPlugins, resolveProjectLexicons } from "../plugins";
-import type { LexiconPlugin } from "../../lexicon";
+import type { LexiconPlugin, ResourceSelector } from "../../lexicon";
 
 /**
  * Import command options
@@ -310,6 +310,156 @@ export async function importCommand(options: ImportOptions): Promise<ImportResul
   };
 }
 
+/**
+ * Live import options — read from a running cloud/cluster instead of a file.
+ */
+export interface LiveImportOptions {
+  /** Environment to resolve (passed to each lexicon's exportResources). */
+  environment: string;
+  /** Restrict to one lexicon by name (e.g. "aws", "k8s"). */
+  lexicon?: string;
+  /** Output directory (defaults to ./infra/). */
+  output?: string;
+  /** Force overwrite existing files. */
+  force?: boolean;
+  /** Selector forwarded to the lexicon. */
+  selector?: ResourceSelector;
+  /** Restrict to chant-owned resources (inert until ownership marking lands). */
+  owned?: boolean;
+  /** Keep server-defaulted fields instead of stripping to declared shape. */
+  verbatim?: boolean;
+}
+
+/**
+ * Merge several template IRs into one. Resources and parameters concatenate;
+ * later metadata wins on key collisions.
+ */
+function mergeIR(parts: TemplateIR[]): TemplateIR {
+  const resources: ResourceIR[] = [];
+  const parameters: ParameterIR[] = [];
+  let metadata: Record<string, unknown> | undefined;
+  for (const part of parts) {
+    resources.push(...part.resources);
+    parameters.push(...part.parameters);
+    if (part.metadata) metadata = { ...(metadata ?? {}), ...part.metadata };
+  }
+  return { resources, parameters, metadata };
+}
+
+/**
+ * Import directly from a live environment: ask each lexicon's exportResources
+ * for full-fidelity IR, then generate chant TypeScript from it.
+ *
+ * Unlike file import, the live config may contain secrets — the caller prints a
+ * warning. Reuses the same by-category output organization as file import.
+ */
+export async function importFromLive(options: LiveImportOptions): Promise<ImportResult> {
+  const projectDir = resolve(options.output ? dirname(options.output) : ".");
+
+  // Resolve project lexicons, then hand off to the testable core.
+  let plugins: LexiconPlugin[];
+  try {
+    const lexiconNames = await resolveProjectLexicons(projectDir);
+    plugins = await loadPlugins(lexiconNames);
+  } catch {
+    plugins = [];
+  }
+
+  return liveImportFromPlugins(plugins, options);
+}
+
+/**
+ * Live-import core: given resolved plugins, export and generate. Split from
+ * plugin resolution so it can be tested with fake exporters (no cloud calls).
+ */
+export async function liveImportFromPlugins(
+  plugins: LexiconPlugin[],
+  options: LiveImportOptions,
+): Promise<ImportResult> {
+  const outputDir = resolve(options.output ?? "./infra/");
+  const warnings: string[] = [];
+
+  let exporters = plugins.filter((p) => p.exportResources && p.templateGenerator);
+  if (options.lexicon) {
+    exporters = exporters.filter((p) => p.name === options.lexicon);
+  }
+
+  if (exporters.length === 0) {
+    return {
+      success: false,
+      generatedFiles: [],
+      warnings: [],
+      error: options.lexicon
+        ? `Lexicon "${options.lexicon}" does not support live export, or is not in this project.`
+        : "No project lexicon supports live export (exportResources).",
+    };
+  }
+
+  // Collect IR from every exporter, tagging which lexicon produced output.
+  const irParts: TemplateIR[] = [];
+  let generatorLexicon: LexiconPlugin | undefined;
+  for (const plugin of exporters) {
+    let ir: TemplateIR;
+    try {
+      ir = await plugin.exportResources!({
+        environment: options.environment,
+        selector: options.selector,
+        owned: options.owned,
+        verbatim: options.verbatim,
+      });
+    } catch (err) {
+      warnings.push(`${plugin.name}: live export failed — ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    if (ir.resources.length === 0) continue;
+    irParts.push(ir);
+    generatorLexicon ??= plugin;
+  }
+
+  if (irParts.length === 0 || !generatorLexicon) {
+    return {
+      success: false,
+      generatedFiles: [],
+      warnings,
+      error: `No resources exported from environment "${options.environment}".`,
+    };
+  }
+
+  if (exporters.length > 1 && irParts.length > 1) {
+    warnings.push("Multiple lexicons exported resources; generated with the first. Use --lexicon to target one.");
+  }
+
+  const ir = mergeIR(irParts);
+  const generator = generatorLexicon.templateGenerator!();
+
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  const files = generateOrganizedFiles(ir, generator);
+  const generatedFiles: string[] = [];
+  for (const file of files) {
+    const filePath = join(outputDir, file.path);
+    const dirPath = join(outputDir, file.path.split("/").slice(0, -1).join("/"));
+    if (dirPath && !existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+    }
+    if (existsSync(filePath) && !options.force) {
+      warnings.push(`File ${file.path} already exists, skipping`);
+      continue;
+    }
+    writeFileSync(filePath, file.content);
+    generatedFiles.push(file.path);
+  }
+
+  return {
+    success: true,
+    generatedFiles,
+    warnings,
+    lexicon: generatorLexicon.name,
+  };
+}
+
 /**
  * Print import result
  */

package/src/cli/commands/migrate.ts

@@ -241,7 +241,7 @@ async function loadMigrationRules(targetLexicon: string): Promise<LintRule[]> {
  * Format the migration report as Markdown, mirroring the output format
  * prescribed by the upstream gitlab-org/ci-cd/github-actions-to-gitlab-ci
  * skill: overview, classification, diagnostic table, aggregated manual
- * setup steps, suggested GitLab improvements, honest caveats.
+ * setup steps, suggested GitLab improvements, caveats.
  *
  * The same data backs the SARIF report (via formatSarif); this is the
  * human-readable surface.
@@ -310,7 +310,7 @@ function formatMarkdownSummary(
 
   if (totals.error > 0 || totals.warning > 0) {
     lines.push("");
-    lines.push("### Honest caveats");
+    lines.push("### Caveats");
     lines.push("");
     lines.push(`The translation has ${totals.error} item${totals.error === 1 ? "" : "s"} needing review and ${totals.warning} approximation${totals.warning === 1 ? "" : "s"}. Review the diagnostics above before pushing the generated YAML.`);
   }