@intentius/chant 0.1.13 → 0.1.15

package/src/op/types.ts

@@ -52,7 +52,7 @@ export interface ActivityStep {
    * The serializer captures the awaited result into a temporary, then emits
    * `upsertSearchAttributes({ <name>: [String(<from-path>)] })` immediately
    * after. Useful for filtering runs by outcome (e.g. `Drift: "true"/"false"`
-   * from a stateDiff activity).
+   * from a lifecycleDiff activity).
    *
    * `from` is a dot-path into the return value (e.g. `"drifted"` for
    * `{ drifted: boolean }`); when omitted, the whole return value is

package/src/ownership.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "vitest";
+import {
+  ownershipEntries,
+  ownershipKeys,
+  hasOwnershipMarker,
+  readOwnership,
+  classifyOwnership,
+  tagArrayToMap,
+  OWNERSHIP_MANAGED_BY_VALUE,
+} from "./ownership";
+import { resolveOwnershipMarker } from "./config";
+
+describe("ownershipEntries (#119)", () => {
+  test("label channel carries managed-by + stack + env", () => {
+    const e = ownershipEntries("label", { stack: "billing", env: "prod" });
+    expect(e["app.kubernetes.io/managed-by"]).toBe("chant");
+    expect(e["chant.intentius.io/stack"]).toBe("billing");
+    expect(e["chant.intentius.io/env"]).toBe("prod");
+  });
+
+  test("aws-tag channel uses colon keys", () => {
+    const e = ownershipEntries("aws-tag", { stack: "billing" });
+    expect(e["chant:managed-by"]).toBe("chant");
+    expect(e["chant:stack"]).toBe("billing");
+    expect(e["chant:env"]).toBeUndefined(); // env omitted when not set
+  });
+
+  test("azure-tag channel uses hyphen keys (no slash, which Azure forbids)", () => {
+    const e = ownershipEntries("azure-tag", { stack: "billing", env: "stg" });
+    expect(e["chant-managed-by"]).toBe("chant");
+    expect(e["chant-stack"]).toBe("billing");
+    expect(e["chant-env"]).toBe("stg");
+    expect(Object.keys(e).some((k) => k.includes("/"))).toBe(false);
+  });
+
+  test("carries stack identity, not just managed=true", () => {
+    const a = ownershipEntries("label", { stack: "stack-a" });
+    const b = ownershipEntries("label", { stack: "stack-b" });
+    expect(a[ownershipKeys("label").stack]).not.toBe(b[ownershipKeys("label").stack]);
+  });
+});
+
+describe("hasOwnershipMarker / readOwnership", () => {
+  test("detects chant's marker even when co-stamped with other tools", () => {
+    const tags = {
+      "chant:managed-by": OWNERSHIP_MANAGED_BY_VALUE,
+      "chant:stack": "billing",
+      "team": "payments", // foreign co-stamp
+    };
+    expect(hasOwnershipMarker(tags, "aws-tag")).toBe(true);
+  });
+
+  test("absent marker → not owned", () => {
+    expect(hasOwnershipMarker({ team: "payments" }, "aws-tag")).toBe(false);
+    expect(hasOwnershipMarker(undefined, "label")).toBe(false);
+  });
+
+  test("readOwnership recovers stack/env from a marked resource", () => {
+    const labels = ownershipEntries("label", { stack: "billing", env: "prod" });
+    expect(readOwnership(labels, "label")).toEqual({ stack: "billing", env: "prod" });
+  });
+
+  test("readOwnership returns undefined when unmarked", () => {
+    expect(readOwnership({ foo: "bar" }, "label")).toBeUndefined();
+  });
+});
+
+describe("classifyOwnership / tagArrayToMap (#120)", () => {
+  test("marker present → owned, absent → foreign", () => {
+    expect(classifyOwnership({ "chant:managed-by": "chant" }, "aws-tag")).toBe("owned");
+    expect(classifyOwnership({ team: "x" }, "aws-tag")).toBe("foreign");
+    expect(classifyOwnership(undefined, "label")).toBe("foreign");
+  });
+
+  test("tagArrayToMap converts CloudFormation {Key,Value} tags", () => {
+    const map = tagArrayToMap([
+      { Key: "chant:managed-by", Value: "chant" },
+      { Key: "chant:stack", Value: "billing" },
+    ]);
+    expect(map["chant:managed-by"]).toBe("chant");
+    expect(classifyOwnership(map, "aws-tag")).toBe("owned");
+  });
+
+  test("tagArrayToMap tolerates undefined / malformed entries", () => {
+    expect(tagArrayToMap(undefined)).toEqual({});
+    expect(tagArrayToMap([{ Value: "no-key" }])).toEqual({});
+  });
+});
+
+describe("resolveOwnershipMarker (config opt-in)", () => {
+  test("enabled when stack is set", () => {
+    expect(resolveOwnershipMarker({ ownership: { stack: "billing", env: "prod" } })).toEqual({
+      stack: "billing",
+      env: "prod",
+    });
+  });
+
+  test("off when no ownership config", () => {
+    expect(resolveOwnershipMarker({})).toBeUndefined();
+  });
+
+  test("off when stack missing", () => {
+    expect(resolveOwnershipMarker({ ownership: { env: "prod" } })).toBeUndefined();
+  });
+
+  test("off when explicitly disabled", () => {
+    expect(resolveOwnershipMarker({ ownership: { stack: "billing", enabled: false } })).toBeUndefined();
+  });
+});

package/src/ownership.ts

@@ -0,0 +1,142 @@
+/**
+ * Ownership marker contract.
+ *
+ * chant stamps managed resources with a provider-native marker at synthesis
+ * time. This is what later lets `delete` be precise without an authoritative
+ * state file — the ownership record lives on the cloud resource, not in a file
+ * chant has to host or lock. The marker is standard tags/labels, so walk-away
+ * cost stays zero: nothing proprietary lands in the output.
+ *
+ * The marker carries stack identity, not just `managed=true`, so one stack
+ * never mistakes another stack's resources for its own. Ownership means
+ * "carries chant's marker", not "carries only chant's marker" — co-stamping
+ * with other tools is fine.
+ */
+
+/** The value of the managed-by marker for every channel. */
+export const OWNERSHIP_MANAGED_BY_VALUE = "chant";
+
+/**
+ * Stack (and optional environment) identity stamped onto a resource. Computed
+ * from project config and threaded into each serializer.
+ */
+export interface OwnershipMarker {
+  /** Distinguishes one chant stack's resources from another's. */
+  stack: string;
+  /** Optional environment identity. */
+  env?: string;
+}
+
+/**
+ * The native metadata channel a target stamps into. Tag-key syntax differs:
+ * Kubernetes/GCP labels allow a `prefix/name` form; AWS tag keys allow `:`;
+ * Azure tag keys forbid `/`, so they use a hyphenated form.
+ */
+export type OwnershipChannel = "label" | "aws-tag" | "azure-tag";
+
+interface ChannelKeys {
+  readonly managedBy: string;
+  readonly stack: string;
+  readonly env: string;
+}
+
+const CHANNEL_KEYS: Record<OwnershipChannel, ChannelKeys> = {
+  label: {
+    managedBy: "app.kubernetes.io/managed-by",
+    stack: "chant.intentius.io/stack",
+    env: "chant.intentius.io/env",
+  },
+  "aws-tag": {
+    managedBy: "chant:managed-by",
+    stack: "chant:stack",
+    env: "chant:env",
+  },
+  "azure-tag": {
+    managedBy: "chant-managed-by",
+    stack: "chant-stack",
+    env: "chant-env",
+  },
+};
+
+/** The marker key names used in a given channel. */
+export function ownershipKeys(channel: OwnershipChannel): ChannelKeys {
+  return CHANNEL_KEYS[channel];
+}
+
+/**
+ * The key/value entries to stamp for a channel: the managed-by marker, the
+ * stack identity, and the env identity when present.
+ */
+export function ownershipEntries(
+  channel: OwnershipChannel,
+  marker: OwnershipMarker,
+): Record<string, string> {
+  const keys = CHANNEL_KEYS[channel];
+  const entries: Record<string, string> = {
+    [keys.managedBy]: OWNERSHIP_MANAGED_BY_VALUE,
+    [keys.stack]: marker.stack,
+  };
+  if (marker.env) entries[keys.env] = marker.env;
+  return entries;
+}
+
+/**
+ * Ownership test: does this resource carry chant's managed-by marker? Other
+ * tools may co-stamp; only the managed-by marker is required to count as owned.
+ */
+export function hasOwnershipMarker(
+  tagsOrLabels: Record<string, unknown> | undefined,
+  channel: OwnershipChannel,
+): boolean {
+  if (!tagsOrLabels) return false;
+  return tagsOrLabels[CHANNEL_KEYS[channel].managedBy] === OWNERSHIP_MANAGED_BY_VALUE;
+}
+
+/**
+ * The two live-side ownership verdicts a marker query can produce.
+ *
+ * - `owned` — carries chant's marker; an undeclared owned resource is a safe
+ *   delete candidate.
+ * - `foreign` — no marker; can be adopted but never auto-deleted.
+ *
+ * The third verdict, `unknown`, is reserved for when no marker channel was
+ * queried at all (see the `Ownership` type in the change set).
+ */
+export function classifyOwnership(
+  tagsOrLabels: Record<string, unknown> | undefined,
+  channel: OwnershipChannel,
+): "owned" | "foreign" {
+  return hasOwnershipMarker(tagsOrLabels, channel) ? "owned" : "foreign";
+}
+
+/**
+ * Convert a tag array of `{Key, Value}` (AWS/CloudFormation form) into the
+ * key→value map the ownership helpers expect.
+ */
+export function tagArrayToMap(
+  tags: ReadonlyArray<{ Key?: string; Value?: unknown }> | undefined,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const t of tags ?? []) {
+    if (typeof t.Key === "string") out[t.Key] = t.Value;
+  }
+  return out;
+}
+
+/**
+ * Read the stack/env identity from a marked resource's tags/labels. Returns
+ * undefined when the managed-by marker is absent.
+ */
+export function readOwnership(
+  tagsOrLabels: Record<string, unknown> | undefined,
+  channel: OwnershipChannel,
+): OwnershipMarker | undefined {
+  if (!hasOwnershipMarker(tagsOrLabels, channel)) return undefined;
+  const keys = CHANNEL_KEYS[channel];
+  const stack = tagsOrLabels![keys.stack];
+  const env = tagsOrLabels![keys.env];
+  return {
+    stack: typeof stack === "string" ? stack : "",
+    env: typeof env === "string" ? env : undefined,
+  };
+}

package/src/serializer.ts

@@ -1,5 +1,18 @@
 import type { Declarable } from "./declarable";
 import type { LexiconOutput } from "./lexicon-output";
+import type { OwnershipMarker } from "./ownership";
+
+/**
+ * Build-time context passed to a serializer. Optional — serializers that don't
+ * need it ignore the parameter.
+ */
+export interface SerializeContext {
+  /**
+   * When set, the serializer stamps this ownership marker into the target's
+   * native metadata channel (AWS/Azure tags, K8s/GCP labels).
+   */
+  ownership?: OwnershipMarker;
+}
 
 /**
  * Result of serialization that may include additional files (e.g. nested stack templates).
@@ -29,8 +42,13 @@ export interface Serializer {
    * Serializes the entities to a string representation
    * @param entities - Map of entity name to Declarable entity
    * @param outputs - Optional array of LexiconOutputs produced by this lexicon
+   * @param context - Optional build-time context (e.g. ownership marker)
    */
-  serialize(entities: Map<string, Declarable>, outputs?: LexiconOutput[]): string | SerializerResult;
+  serialize(
+    entities: Map<string, Declarable>,
+    outputs?: LexiconOutput[],
+    context?: SerializeContext,
+  ): string | SerializerResult;
 
   /**
    * Serialize a cross-lexicon reference to a foreign output.

package/src/toml-parse.ts

@@ -10,8 +10,8 @@ import { unescapeString, stripInlineComment } from "./toml-utils";
 /**
  * Parse a TOML document string into a plain object.
  *
- * Uses a built-in parser that handles the TOML subset used by Flyway
- * configuration files.
+ * Uses a built-in parser that handles the common TOML subset used by tool
+ * configuration files (tables, dotted keys, inline tables, and arrays).
  */
 export function parseTOML(content: string): Record<string, unknown> {
   const result: Record<string, unknown> = {};
@@ -106,7 +106,7 @@ function findEquals(line: string): number {
 }
 
 /**
- * Parse a dotted key like `flyway.placeholders.name` into path segments.
+ * Parse a dotted key like `tool.placeholders.name` into path segments.
  */
 function parseDottedKey(raw: string): string[] {
   const parts: string[] = [];