@intentius/chant 0.124.13 → 0.124.15

package/dist/owner-chain.js

@@ -0,0 +1,74 @@
+/**
+ * Owner-chain classification (chant #1077).
+ *
+ * `describeResources()` already lets a lexicon report a live object it never
+ * asked about by name — that is how `orphan` has always worked (a resource
+ * present in `observedNow` that is not in `declared`). Every existing consumer
+ * treats every such object the same way: undeclared, so a delete/adopt
+ * candidate.
+ *
+ * On Kubernetes that conflates two different things. A console-added SNS
+ * subscription (the AWS case #1014/#1015 was built for) really is out-of-band
+ * drift. A Pod a declared Deployment's controller created is not drift at
+ * all — it is the runtime doing its job, and it will be recreated the moment
+ * it is deleted. `ownerReferences` is what tells them apart: the Pod's chain
+ * of owners terminates at the Deployment, which is declared.
+ *
+ * This module owns the *category* — the four possible answers to "where does
+ * this object's owner chain lead" — and the pure algorithm that walks a chain
+ * to one of them. A lexicon supplies the chain (reading `ownerReferences`,
+ * possibly across several API reads to walk past an intermediate object chant
+ * never declared, e.g. a ReplicaSet between a Pod and its Deployment); this
+ * module supplies the bounded, cycle-safe interpretation, so that logic is
+ * written and tested once rather than once per lexicon.
+ */
+/** Default bound on how many owner hops {@link classifyOwnerChain} will walk
+ * before giving up conservatively. Kubernetes' own garbage collector does not
+ * bound this at all, but a live read has to — a bound this generous is well
+ * past any real ownership depth (Pod → ReplicaSet → Deployment is 2 hops) and
+ * exists only to turn a corrupt or adversarial chain into `unknown` rather
+ * than an infinite walk. */
+export const DEFAULT_MAX_OWNER_CHAIN_DEPTH = 12;
+/**
+ * Walk the owner chain starting at `startId` through `nodes`, bounded and
+ * cycle-safe. Pure — the caller has already done whatever I/O was needed to
+ * populate `nodes`; this function only interprets the graph it was given.
+ *
+ * `nodes` need not contain every ancestor: a node the caller never resolved
+ * (because it gave up, hit the caller's own fetch bound, or the read failed)
+ * is simply absent from the map, and a reference to an absent node classifies
+ * as `unknown` — the conservative answer, same as an explicit
+ * `ownerUnreadable`.
+ */
+export function classifyOwnerChain(startId, nodes, maxDepth = DEFAULT_MAX_OWNER_CHAIN_DEPTH) {
+    const start = nodes.get(startId);
+    if (!start)
+        return { root: "unknown" };
+    if (start.declaredEntity)
+        return { root: "declared", entity: start.declaredEntity };
+    if (start.ownerUnreadable)
+        return { root: "unknown" };
+    if (start.ownerId === undefined)
+        return { root: "unowned" };
+    const visited = new Set([startId]);
+    let currentId = start.ownerId;
+    for (let depth = 0; depth < maxDepth; depth++) {
+        if (visited.has(currentId))
+            return { root: "unknown" }; // cycle
+        visited.add(currentId);
+        const node = nodes.get(currentId);
+        if (!node)
+            return { root: "unknown" }; // referenced but never resolved
+        if (node.declaredEntity)
+            return { root: "declared", entity: node.declaredEntity };
+        if (node.ownerUnreadable)
+            return { root: "unknown" };
+        if (node.ownerId === undefined)
+            return { root: "foreign" }; // a real, live, undeclared root
+        currentId = node.ownerId;
+    }
+    // The bound was hit without resolving to a declared entity or a definite
+    // root. Conservative: not a confirmed `foreign` either, since one more hop
+    // might have reached a declared entity — see the type doc on `unknown`.
+    return { root: "unknown" };
+}

package/dist/ownership.js

@@ -0,0 +1,92 @@
+/**
+ * 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";
+/**
+ * The label-based ownership convention (`app.kubernetes.io/managed-by` +
+ * `chant.intentius.io/{stack,env}`) — the default, shared by every label-based
+ * lexicon (k8s, gcp, helm, and the `k8sApply` activity's `kubectl --prune`
+ * selector). AWS and Azure tag keys are defined in their own lexicons.
+ */
+export const LABEL_OWNERSHIP_KEYS = {
+    managedBy: "app.kubernetes.io/managed-by",
+    stack: "chant.intentius.io/stack",
+    env: "chant.intentius.io/env",
+};
+/**
+ * The key/value entries to stamp: the managed-by marker, the stack identity,
+ * and the env identity when present.
+ */
+export function ownershipEntries(keys, marker) {
+    const entries = {
+        [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, keys) {
+    if (!tagsOrLabels)
+        return false;
+    return tagsOrLabels[keys.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, keys) {
+    return hasOwnershipMarker(tagsOrLabels, keys) ? "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) {
+    const out = {};
+    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, keys) {
+    if (!hasOwnershipMarker(tagsOrLabels, keys))
+        return undefined;
+    const stack = tagsOrLabels[keys.stack];
+    const env = tagsOrLabels[keys.env];
+    return {
+        stack: typeof stack === "string" ? stack : "",
+        env: typeof env === "string" ? env : undefined,
+    };
+}
+/** Whether this lexicon resolves a real verdict on `path`, or can only say `unknown`. */
+export function resolvesOwnershipOn(channel, path) {
+    return channel?.reads.includes(path) ?? false;
+}

package/dist/params.js

@@ -0,0 +1,61 @@
+/**
+ * Build-time parameters — the runtime binding source references (chant #1064,
+ * follow-up to epic #1019's fold work).
+ *
+ * This is deliberately NOT `Parameter` (`lexicons/aws/src/parameter.ts`), which
+ * is a deploy-time CloudFormation parameter: it emits a `Parameters:` block and
+ * resolves when the STACK deploys. A build-time parameter resolves before the
+ * template is even synthesized — its value can change WHICH resources are
+ * produced at all (a `tier` parameter selecting `light` vs `production` vs
+ * `production-ha`), which a deploy-time `Parameter` structurally cannot do.
+ *
+ * Project source never reads `process.env` directly to vary a build — that
+ * reads ambient state at module-evaluation time, which `fold()` correctly
+ * cannot reduce to a value (see ../fold/fold.ts). Instead it imports this
+ * module's `params` object:
+ *
+ * ```ts
+ * import { params } from "@intentius/chant/params";
+ * export const tier = params.tier as Tier;
+ * ```
+ *
+ * `params` is declared, validated (type + optional `enum`), and resolved by
+ * the CLI BEFORE discovery ever touches a project file (../build-params.ts's
+ * `resolveBuildParams`, driven by `chant build --param`/`--params-file`/a
+ * declared `env` mapping/`chant.config.ts`'s `buildParams` defaults). Two
+ * consumers read the resolved values, and both see the identical object:
+ *
+ *  - The FOLD path (../discovery/fold-import.ts's `buildExternals`) recognizes
+ *    a named `params` import resolving to *this* module and substitutes the
+ *    already-resolved values directly, with zero import performed — so
+ *    `params.tier` folds to a LITERAL, not a symbolic node. This is the entire
+ *    point: the value is known at build invocation, so there is nothing left
+ *    to defer.
+ *  - The RUN path (a run-fallback file that imports this module for real)
+ *    gets the exact same values, because `setBuildParams` below is called
+ *    once, in-process, before ANY project file is imported or folded —
+ *    mutating this shared object in place rather than replacing the binding,
+ *    so a live-imported reference always observes the current build's values.
+ */
+/**
+ * The current build's resolved parameter values, keyed by declared name.
+ * Empty until a build populates it via {@link setBuildParams}. Mutated IN
+ * PLACE (never reassigned) so a real `import { params }` in a run-fallback
+ * file — which captures this exact object reference at import time — always
+ * observes whatever the current build resolved, even though the import
+ * happens after this module was first loaded.
+ */
+export const params = {};
+/**
+ * Replace the shared {@link params} object's contents in place. Called once
+ * per build (../discovery/index.ts's `discover()`), before any project file
+ * is imported or folded, with the CLI/config-resolved values
+ * (../build-params.ts's `resolveBuildParams`). Never called from project
+ * source — this is chant's own build-invocation plumbing, not a public
+ * authoring API.
+ */
+export function setBuildParams(values) {
+    for (const key of Object.keys(params))
+        delete params[key];
+    Object.assign(params, values);
+}