@intentius/chant-lexicon-terraform 0.57.0 → 0.58.0

package/dist/describe-resources.d.ts

@@ -1,12 +1,19 @@
 /**
- * Live observation for declared terraform entities (#2087).
+ * Live observation for declared terraform entities (#2087, #2104).
  *
  * `buildRoots()` turns each configured root module into one entity per HCL
  * block, keyed `<root>/<address>` (`./hcl/parse.ts`). This reader answers the
- * lifecycle question for those entities by running `terraform show -json` over
- * the root's current state and matching addresses.
+ * lifecycle question for those entities, and how it answers depends on one
+ * fact the parse already recorded on every entity: the root's `mode`.
  *
- * ## The state file is the ownership answer
+ * A **stock** root is read with `terraform show -json` over its state, and
+ * state membership is the ownership answer. A **live** root, meaning
+ * `terraform.binary` is `"choudoufu"` and the root declares an estate
+ * (#2103), has no state to show: it is read with `choudoufu live-plan -json`,
+ * and the marker on the resource is the ownership answer. The two halves are
+ * two adapters over the same `observeEntities` harness, picked per root.
+ *
+ * ## The state file is the ownership answer, on a stock root
  *
  * Every other lexicon in chant stamps a tag or a label at synthesis and reads
  * it back off the live resource. Terraform stamps nothing, and there is
@@ -24,10 +31,58 @@
  * escalates to a delete, which is the correct posture for a thing chant did
  * not read a verdict for.
  *
- * That places terraform on the trusted-state-file row of the third axis in
- * docs/src/content/docs/concepts/lifecycle-models.mdx, where chant elsewhere
- * sits on the live-marker row. `docs/pages/observation.mdx` is the reader's
- * version of this paragraph.
+ * That places a stock terraform root on the trusted-state-file row of the
+ * third axis in docs/src/content/docs/concepts/lifecycle-models.mdx, where
+ * chant elsewhere sits on the live-marker row. `docs/pages/observation.mdx`
+ * is the reader's version of this paragraph.
+ *
+ * ## The marker is the ownership answer, on a live root
+ *
+ * choudoufu keeps no authoritative state file. Every taggable resource it
+ * manages carries `tofu-estate` and `tofu-address` tags written in the create
+ * call, prior state is rebuilt from the live system each run, and the state
+ * file, where one exists at all, is a disposable cache. So a live root is on
+ * the live-marker row, the row every other chant lexicon sits in.
+ *
+ * chant does not re-derive that verdict from the tags. `live-plan -json`
+ * (choudoufu issue #788) already splits every declared instance four ways,
+ * and those four are the classification:
+ *
+ * | live-plan section | chant |
+ * |---|---|
+ * | `bound[]`, `source: "marker"` | present, `owned`; the marker named this estate and this address, and it is surfaced as `ResourceMetadata.marker` |
+ * | `bound[]`, any other source | present, `owned` by derivation, record, or cache; noted as such, and no marker is surfaced because none was read |
+ * | `unowned[]` with `adopt_*` | present, `unknown`; an adoptable match, carrying the exact two tag values #2105 would write |
+ * | `unowned[]` without | present, `foreign`; a live resource is in the way at a declared identity and the plan will not touch it |
+ * | `omissions[]` | not-observed, `ABSENT` excepted (see below) |
+ *
+ * The ownership channel this declares is `./live-ownership.ts`'s
+ * `TERRAFORM_LIVE_MARKER_KEYS`, and its module doc holds the record of why
+ * the keys are declared while the verdicts are set here by hand rather than
+ * core's `OwnershipChannel` growing a classifier for them.
+ *
+ * ### `ABSENT` is absence, and the rest of the omissions are not
+ *
+ * An omission is choudoufu saying an instance is missing from prior state,
+ * with a reason. Most of those reasons are claims of ignorance and become
+ * NOT-OBSERVED, which is what the tri-state exists for. One is not:
+ * `ABSENT` means "the instance has a usable import identity and the provider
+ * reported, normally, that no such object exists", which is exactly chant's
+ * OBSERVED-ABSENT, spelled "in neither map". Reporting it as not-observed
+ * instead would mean a live root could never propose a create for a resource
+ * that genuinely is not there yet, which is the opposite of the honesty the
+ * contract is for. `UNOWNED` is the other exception, in the other direction:
+ * the `unowned[]` section answers for that address with a real verdict, so
+ * the paired omission is never read on its own.
+ *
+ * ### A block's instances, aggregated
+ *
+ * chant's entity is the HCL block, `aws_eip.pool`; the document's rows are
+ * instances, `aws_eip.pool[0]`. So a block's verdict is the aggregate of its
+ * instances, in this precedence: any instance not-observed makes the block
+ * not-observed, then foreign, then adoptable, then owned, and a block whose
+ * instances are all absent is absent. Partial knowledge is not knowledge,
+ * which is the same rule choudoufu applies to its own `INCOMPLETE_BLOCK`.
  *
  * ## What is readable at all
  *
@@ -37,13 +92,28 @@
  * That is honest, not a gap to close by inventing an address for something
  * that has none.
  *
+ * A live root reads one block narrower. `live-plan`'s document is prior state
+ * for managed resources, so a `data` block has no row in it either and reads
+ * `unsupported-kind` there, where the stock reader can answer for it.
+ *
  * ## Tri-state (#1089)
  *
- * A root whose `init` or `show` fails reports EVERY entity declared in that
- * root as not-observed with reason `read-failed` and the root named, never
- * absent. A failed read must never render as a list of creates. Roots are
- * read independently and merged (`mergeObservations`), so one broken backend
- * does not un-observe a root that answered.
+ * A root whose `init` or `show` fails, or whose `live-plan` fails, reports
+ * EVERY entity declared in that root as not-observed with the mapped reason
+ * and the root named, never absent. A failed read must never render as a list
+ * of creates. Roots are read independently and merged (`mergeObservations`),
+ * so one broken backend does not un-observe a root that answered.
+ *
+ * ## Beyond the declared estate, on a live root
+ *
+ * `live-ls -estate -json` lists the whole estate off the Resource Groups
+ * Tagging API with no configuration read at all, which is a question a state
+ * file cannot answer: what does this estate hold that nothing declares? That
+ * is what makes `ambientKinds()`, `observeAmbient()` and `teardownOwned()`
+ * implementable on this lexicon for the first time. `-consistent` is always
+ * passed, because that index lags a tag write by about a minute
+ * (`live-ls`'s own help text) and a listing taken right after an apply can
+ * otherwise show a resource under both its old and new estate, or neither.
  *
  * ## Nothing from `values` is surfaced
  *
@@ -53,9 +123,12 @@
  * (address, type, mode, provider, root) and nothing from `values` except the
  * `id`, which is the physical id every observation carries.
  */
-import type { DescribeResourcesResult } from "@intentius/chant/lexicon";
-import { terraformInit, terraformShow } from "./op/activities/terraform.js";
+import type { DescribeResourcesResult, ResourceMetadata, TeardownEnumeration } from "@intentius/chant/lexicon";
+import { type UnobservedReason } from "@intentius/chant/observation";
+import type { OwnershipMarker } from "@intentius/chant/ownership";
+import { choudoufuLiveLs, choudoufuLivePlan, terraformInit, terraformShow } from "./op/activities/terraform.js";
 export { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
+export { TERRAFORM_LIVE_MARKER_KEYS } from "./live-ownership.js";
 /** One row out of `values.root_module.resources[]`, at any module depth. */
 export interface StateResourceRow {
     /** Fully qualified terraform address, `module.<name>.` prefixes included. */
@@ -93,11 +166,178 @@ export declare function indexStateResources(showJson: unknown): StateIndex;
  * function to point at.
  */
 export declare function classifyStateOwnership(address: string, index: StateIndex): "owned" | "unknown";
-/** The activity pair this reader drives. Injectable so tests never run terraform. */
+/** One `bound[]` entry: a declared instance the plan admitted into prior state. */
+export interface LivePlanBoundRow {
+    addr: string;
+    type?: string;
+    /** The import id it bound to, when the resolver produced one. */
+    identity?: string;
+    /** Which admission path supplied the identity: `marker`, `record`, `derived` or `cache`. */
+    source?: string;
+}
+/** One `omissions[]` entry: a declared instance the plan could not read, and why. */
+export interface LivePlanOmissionRow {
+    addr: string;
+    /** choudoufu's own machine-readable code (`ABSENT`, `FAILED`, `UNOWNED`, …). */
+    reason: string;
+    detail: string;
+}
+/** One `unowned[]` entry: a live resource at a declared identity without this estate's marker. */
+export interface LivePlanUnownedRow {
+    addr: string;
+    type?: string;
+    identity?: string;
+    /** `tofu_estate`: the marker it does carry, when it carries one. Empty means no marker at all. */
+    heldBy?: string;
+    /** `adopt_tofu_estate`: present exactly when adoption is this run's to offer. */
+    adoptEstate?: string;
+    /** `adopt_tofu_address`: the escaped address the adopting tag write would carry. */
+    adoptAddress?: string;
+}
+/** A `live-plan -json` document, indexed by declared instance address. */
+export interface LivePlanIndex {
+    /** `estate`: the estate every section was computed against. */
+    estate: string;
+    bound: Map<string, LivePlanBoundRow>;
+    omissions: Map<string, LivePlanOmissionRow>;
+    unowned: Map<string, LivePlanUnownedRow>;
+    /** Every address any section named, so a block can find its own instances. */
+    addresses: string[];
+    /** `diagnostics[]` summaries, for the observation's run-level notes. */
+    diagnostics: string[];
+}
+/**
+ * Index choudoufu issue #788's document. Unknown fields are ignored and a
+ * missing section reads as empty: a document from a newer choudoufu must
+ * degrade to "this section said nothing", never to a throw.
+ */
+export declare function indexLivePlan(document: unknown): LivePlanIndex;
+/**
+ * choudoufu's omission reason codes, mapped onto chant's total vocabulary
+ * (`internal/live/projection/result.go`). `"absent"` is not an
+ * {@link UnobservedReason}: it is the tri-state's OBSERVED-ABSENT, the one
+ * omission that is a claim of knowledge rather than of ignorance.
+ *
+ * A code this table does not know maps to `read-failed`, which is the safe
+ * direction: no NOT-OBSERVED verdict ever becomes a create or a delete.
+ */
+export declare const LIVE_PLAN_OMISSION_REASONS: Readonly<Record<string, UnobservedReason | "absent">>;
+/** One `items[]` entry of a `live-ls -json` listing. */
+export interface LiveLsItem {
+    /** ARN or other stable identity. */
+    id: string;
+    /** Resource type, e.g. `aws_vpc`. */
+    type: string;
+    /** The configuration address decoded from the marker, when the listing could decode one. */
+    address?: string;
+    /** `tofu-slot`, on a `count` instance. */
+    slot?: string;
+    /** Whether the cross-referenced configuration directory still declares it. */
+    declared: boolean;
+    /** Which read found it: `tagging`, or a per-service pass. */
+    source?: string;
+    /** Every marker tag it carries. */
+    tags: Record<string, string>;
+}
+/** One `gaps[]` entry: a declared instance this listing's mechanism cannot reach. */
+export interface LiveLsGap {
+    address: string;
+    type: string;
+    /** `record` or `declaration-carried`, choudoufu's own rung vocabulary. */
+    rung: string;
+    detail: string;
+}
+/** A `live-ls -json` listing, parsed. */
+export interface LiveLsListing {
+    estate: string;
+    items: LiveLsItem[];
+    gaps: LiveLsGap[];
+}
+/** Parse a `live-ls -json` document. A missing section reads as empty, never as a throw. */
+export declare function readLiveLs(document: unknown): LiveLsListing;
+/**
+ * The entity key `buildRoots()` would have produced for a live resource's
+ * address.
+ *
+ * A live address is fully qualified with dots, `module.cdn.null_resource.edge`;
+ * the build keys a descended child module's block with a slash per call,
+ * `app/module.cdn/null_resource.edge` (#2112). Splitting the `module.<name>.`
+ * prefixes back out is what keeps a live row and the block that declared it
+ * on the same key.
+ */
+export declare function entityKeyFor(root: string, address: string): string;
+/**
+ * The entity types this lexicon can enumerate beyond the declared estate
+ * (#1278). One: a `resource` block, whose live counterparts `live-ls` lists
+ * off the tag index. A `data`, `module` or `provider` block has no live
+ * counterpart to enumerate at all.
+ */
+export declare function ambientKinds(): string[];
+/** Shared options for the two estate-wide reads. */
+export interface LiveEstateOptions {
+    /** Directory the activities start the `chant.config.*` search from. Default: the process cwd. */
+    cwd?: string;
+    /** Restrict to these root names. Default: every live root the project declares. */
+    roots?: string[];
+}
+/**
+ * Every live root the project declares, in config order. Reads the project
+ * config the same way the activities do, so `terraform.roots` is read once
+ * and the same answer reaches both.
+ */
+export declare function liveRootNames(cwd?: string): Promise<Array<{
+    root: string;
+    estate: string;
+}>>;
+/**
+ * Report the resources this estate owns that nothing declares (#1278) — the
+ * owned-orphan set, which is `live-ls`'s `declared: false` rows.
+ *
+ * This is the question a state file cannot answer at all, because a state
+ * file knows only what it created. The tag index knows what the estate holds,
+ * whether or not any configuration still mentions it.
+ */
+export declare function observeAmbient(options: {
+    environment: string;
+    kinds: string[];
+    observed: Record<string, ResourceMetadata>;
+} & LiveEstateOptions, deps?: TerraformReadDeps): Promise<Record<string, ResourceMetadata>>;
+/**
+ * Name what a teardown of this environment would remove from every live root
+ * (#1222): the estate's owned orphans, which are exactly the set choudoufu's
+ * own default `policy` verb (`undeclared_tagged = "delete"`) removes on the
+ * next apply.
+ *
+ * Candidates carry the requested identity verbatim, because that identity is
+ * what selected them: the roots enumerated here are this project's own, and
+ * their estates are what `terraform.roots` declares for this environment.
+ * The estate that actually answered rides `name`, so a reviewer of the plan
+ * can see which one it was.
+ *
+ * `live-ls`'s own `gaps[]` become holes rather than silence, per #1089: a
+ * declared instance the tag index can never serve is unknown, not clean.
+ */
+export declare function teardownOwned(options: {
+    environment: string;
+    marker: OwnershipMarker;
+} & LiveEstateOptions, deps?: TerraformReadDeps): Promise<TeardownEnumeration>;
+/** The activities this reader drives. Injectable so tests never run a binary. */
 export interface TerraformReadDeps {
     init: typeof terraformInit;
     show: typeof terraformShow;
+    livePlan: typeof choudoufuLivePlan;
+    liveLs: typeof choudoufuLiveLs;
 }
+/**
+ * The address the live system knows a block by. For a root-module block that
+ * is the block's own address; for one inside a child module it is what
+ * `terraform show -json` writes in `child_modules[]` and what choudoufu's
+ * markers carry, the call chain and the address joined with dots:
+ * `module.cdn.null_resource.edge` (#2112). The entity KEY keeps its slashes
+ * (`app/module.cdn/null_resource.edge`), so what a build declares and what a
+ * read observes still line up one to one.
+ */
+export declare function qualifiedAddress(address: string, callers: readonly string[]): string;
 export interface DescribeResourcesOptions {
     environment: string;
     buildOutput: string;

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAUxE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAMzE,OAAO,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC;AAEnE,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,iEAAiE;IACjE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IACpC,wFAAwF;IACxF,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACtB;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CA6BjE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,CAE9F;AASD,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,aAAa,CAAC;IAC3B,IAAI,EAAE,OAAO,aAAa,CAAC;CAC5B;AA+GD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,iBAA6B,GAClC,OAAO,CAAC,uBAAuB,CAAC,CAgDlC"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"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"}

package/dist/hcl/descend.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Descend into local child modules (chant #2112).
+ *
+ * `parseTerraformRootDir` reads one directory, non-recursively, which is
+ * Terraform's own root-module scoping and the right unit for a root-scoped
+ * check like TF001. Four rules need more than that: TF014 and TF015 are about
+ * what a CHILD module may contain, and TF020 needs every reference in a scope
+ * before it can call a declaration unused. This module supplies the missing
+ * half: a `module` block whose `source` is a local path names a directory,
+ * and that directory parses with the same `blocksToEntities` into entities
+ * keyed `<root>/module.<name>/<address>` carrying `props.callers`.
+ *
+ * ## What is followed, and what is not
+ *
+ * tflint's `--call-module-type` (three states, defaulting to `local`,
+ * https://github.com/terraform-linters/tflint/blob/master/docs/user-guide/calling-modules.md)
+ * is the model:
+ *
+ * - `local` (the default): only `./` and `../` sources are read. A registry
+ *   or git source is NOT fetched, so its contents are never linted and every
+ *   finding about it is reported against the call site instead, which is
+ *   where TF004 and TF005 already report. The skipped call sites are named in
+ *   a warning rather than passed over in silence.
+ * - `none`: no descent at all. A root then parses exactly as it did before
+ *   this module existed.
+ * - `all`: reserved. tflint means "fetch registry and git modules too", which
+ *   needs a `terraform init`/`terraform get` first so the modules are on disk
+ *   under `.terraform`. chant fetches nothing, so this is refused with a
+ *   message rather than quietly behaving like `local`.
+ *
+ * Two more refusals, both about staying inside the repository being read:
+ *
+ * - A source that resolves outside the project root is refused. `../` is a
+ *   legal Terraform source and a repository may legitimately share modules
+ *   between sibling roots, but reading above the project root means linting
+ *   files the project does not own, so the boundary is the project root and
+ *   crossing it is a warning, not a parse.
+ * - A source already on the current call chain is a cycle (`a` calls `b`
+ *   calls `a`) and stops there. The visited set is per chain, on RESOLVED
+ *   paths, so one module called from two different places is still read once
+ *   per call site, each under its own `module.<name>` key, the way
+ *   `terraform show -json` reports two `child_modules[]` entries for it.
+ *
+ * Everything here is best effort, like `./roots.ts`: an unreadable or
+ * unparseable child module is a warning and no entities, never a throw, since
+ * half a root parsed is more useful than none of it.
+ */
+import type { Declarable } from "@intentius/chant/declarable";
+import type { Hcl2Json } from "@intentius/chant/terraform/parse";
+import { type TerraformRootModeOptions } from "./parse.js";
+/** tflint's `--call-module-type`, with the same three states and the same default. */
+export type CallModuleType = "local" | "none" | "all";
+/** What a caller gets when it asks for a mode chant cannot serve. */
+export interface ResolvedCallModuleType {
+    /** The mode actually used. `"all"` never survives here. */
+    effective: "local" | "none";
+    /** Set when the requested mode was refused, ready to push onto a warning list. */
+    warning?: string;
+}
+/**
+ * Resolve the configured `callModuleType` into one this lexicon implements.
+ * `"all"` is refused with a message naming what it would need; everything
+ * else passes through, and an absent value is `"local"`, tflint's default.
+ */
+export declare function resolveCallModuleType(value?: CallModuleType): ResolvedCallModuleType;
+/** Options for {@link descendModules}. */
+export interface DescendOptions {
+    /** Directory the scope's own `.tf` files were read from. */
+    dir: string;
+    /** Root name, the first segment of every entity key. */
+    root: string;
+    /** Boundary: a source resolving outside this directory is refused. */
+    projectRoot: string;
+    /** Resolved mode. `"none"` returns immediately with nothing. */
+    callModuleType?: "local" | "none";
+    /** Injectable parser (tests); defaults to core's lazy-loaded `@cdktf/hcl2json`. */
+    hcl2json?: Hcl2Json;
+    /** Mode facts stamped onto the child's entities, exactly as on the root's. */
+    modeOptions?: TerraformRootModeOptions;
+    /** How deep to follow calls. A guard against a pathological tree, not a policy. */
+    maxDepth?: number;
+}
+export interface DescendResult {
+    /** The child modules' entities, keyed `<root>/module.<name>/<address>`. */
+    entities: Map<string, Declarable>;
+    /** One line per refusal or skip, in the order they were met. */
+    warnings: string[];
+}
+/**
+ * Parse every local child module reachable from `scope`, recursively.
+ *
+ * `scope` is one already-parsed module scope: the root's own entities on the
+ * first call, a child's on a recursive one. Returned entities are the
+ * children's only, never the scope's own, so a caller merges them into the
+ * map it already has.
+ */
+export declare function descendModules(scope: Map<string, Declarable>, opts: DescendOptions): Promise<DescendResult>;
+//# sourceMappingURL=descend.d.ts.map

package/dist/hcl/descend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descend.d.ts","sourceRoot":"","sources":["../../src/hcl/descend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAGjE,OAAO,EAKL,KAAK,wBAAwB,EAC9B,MAAM,SAAS,CAAC;AAEjB,sFAAsF;AACtF,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtD,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,2DAA2D;IAC3D,SAAS,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,sBAAsB,CAYpF;AAED,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAuDD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC9B,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,aAAa,CAAC,CA2FxB"}

package/dist/hcl/marker.d.ts

@@ -0,0 +1,130 @@
+/**
+ * choudoufu's live resource markers, as chant reads them (#2104).
+ *
+ * On a live root the ownership record is not a state file and not a chant
+ * stamp: it is two AWS tags on the resource itself, `tofu-estate` and
+ * `tofu-address`, specified in `live/MARKERS.md` in
+ * https://github.com/INTENTIUS/choudoufu. That file calls itself the one
+ * integration surface external tools may rely on, so this module implements
+ * exactly what it specifies and nothing beyond it. The spec's own tables are
+ * this module's tests (`./marker.test.ts`).
+ *
+ * ## Escape, then compare. Never decode a tag blind
+ *
+ * A canonical terraform address uses `[`, `]` and `"` to write an instance
+ * key, and AWS allows none of the three in a tag value. So an address is
+ * escaped before it is written, and the spec's comparison rule is one
+ * sentence: escape the address you already know and compare strings. The
+ * reverse, decoding a tag and hoping to recover the address, is ambiguous
+ * (`this[2]` and `this["2"]` escape alike) and the spec says not to do it
+ * where a verdict depends on the answer.
+ *
+ * The rule itself, from "Escaping rule":
+ *
+ *   1. escape the content of every instance key first (see
+ *      {@link escapeForEachKey}); a `count` index is only ever digits, so
+ *      this is a no-op for one;
+ *   2. replace every `[` with `:`;
+ *   3. delete every `]`;
+ *   4. delete every `"`.
+ *
+ * Step 1 first is what makes a `:` in an escaped value always mean "an index
+ * starts here": a key's own `.` and `:` are already gone by the time steps
+ * 2 to 4 run.
+ *
+ * ## Three escapings on the declared side
+ *
+ * The key escaping gained a layer twice, and neither change rewrote the
+ * markers already on live resources. A marker stamped before choudoufu's
+ * issue #178 escaped no key at all; one stamped between #178 and #210
+ * doubled `@`, `.` and `:` but did not carry out-of-charset characters into
+ * the AWS-legal set. So {@link addressMatches} escapes the declared address
+ * three ways and accepts any of them, which is what `AddressMatches` does in
+ * choudoufu itself. Writing always uses {@link escapeAddress}, the current
+ * form.
+ */
+/** `tofu-estate`: the estate that owns the resource. The entire ownership claim. */
+export declare const MARKER_TAG_ESTATE = "tofu-estate";
+/** `tofu-address`: the resource's escaped canonical address, or its first 256-character chunk. */
+export declare const MARKER_TAG_ADDRESS = "tofu-address";
+/** `tofu-slot`: the stable, opaque cardinality slot a `count` instance carries. */
+export declare const MARKER_TAG_SLOT = "tofu-slot";
+/**
+ * `tofu-address-2` through `tofu-address-4`, in order. A reader concatenates
+ * `tofu-address` and whichever of these are present; they are never
+ * meaningful on their own.
+ */
+export declare const MARKER_TAG_ADDRESS_CONTINUATIONS: readonly ["tofu-address-2", "tofu-address-3", "tofu-address-4"];
+/**
+ * Escape one `for_each` instance key, both layers in the specified order:
+ * out-of-charset escaping first, then the `@` / `.` / `:` doubling over its
+ * output. Order is load-bearing: the first layer's introducer is `+`, none of
+ * the three characters the second layer scans for, so the second never
+ * mistakes the first's output for its own escape sequences.
+ *
+ * Six characters cannot be carried at all and are refused at choudoufu's own
+ * lint rather than here (`"`, `\`, any non-printable, `$`, `%`, `[`, `]`);
+ * this function escapes what it is given without judging it, because chant
+ * never writes a marker, and a key chant meets in a `tofu-address` tag has
+ * already passed that lint.
+ */
+export declare function escapeForEachKey(key: string): string;
+/**
+ * The `tofu-address` value for a canonical terraform address: the current
+ * escaping, which is the only one anything ever writes.
+ */
+export declare function escapeAddress(address: string): string;
+/**
+ * Every escaping a live marker could have been written under, current first:
+ * the current one, the pre-#210 one (the doubling alone), and the pre-#178
+ * one (no key escaping at all). Duplicates are collapsed, so the common
+ * address with no `for_each` key yields exactly one string.
+ */
+export declare function escapeAddressVariants(address: string): string[];
+/**
+ * Does a live resource's `tofu-address` value name this declared address?
+ * The declared side is escaped and the strings are compared, three escapings
+ * deep for the migration windows; the tag is never decoded.
+ */
+export declare function addressMatches(declaredAddress: string, tagValue: string): boolean;
+/** What {@link readMarker} found on one live resource's tags. */
+export type MarkerVerdict = 
+/** Carries `tofu-estate` and a readable `tofu-address`: it belongs to that estate. */
+{
+    kind: "owned";
+    estate: string;
+    address: string;
+    slot?: string;
+}
+/** Carries neither key: outside every estate's ownership, reported and never auto-deleted. */
+ | {
+    kind: "foreign";
+}
+/**
+ * Carries `tofu-estate` but no readable `tofu-address`: missing, empty, or
+ * a continuation chain with a gap in it. A named error, never guessed at
+ * and never read as either "belongs to no one" or "close enough".
+ */
+ | {
+    kind: "malformed";
+    estate: string;
+    detail: string;
+};
+/**
+ * Concatenate `tofu-address` and whatever continuation tags follow it, which
+ * is the only sanctioned way to read a split address.
+ *
+ * A chain with a gap in it (`tofu-address-3` present while `tofu-address-2`
+ * is not) cannot be concatenated into anything and returns `undefined` rather
+ * than the address up to the gap.
+ */
+export declare function joinMarkerAddress(tags: Record<string, string | undefined>): string | undefined;
+/**
+ * The ownership verdict `live/MARKERS.md`'s "Ownership semantics" section
+ * defines, read off one live resource's tags. Three outcomes, and no fourth:
+ * a `tofu-estate` value is the entire ownership claim with no secondary
+ * check, neither key present is foreign, and an estate without a readable
+ * address is malformed rather than either of the two.
+ */
+export declare function readMarker(tags: Record<string, string | undefined> | undefined): MarkerVerdict;
+//# sourceMappingURL=marker.d.ts.map

package/dist/hcl/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/hcl/marker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAE/C,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD,mFAAmF;AACnF,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,iEAInC,CAAC;AA4CX;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AAkBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAO/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa;AACvB,sFAAsF;AACpF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE;AACnE,8FAA8F;GAC5F;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE;AACrB;;;;GAIG;GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAgB9F;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,GAAG,aAAa,CAe9F"}