@intentius/chant 0.102.0 → 0.104.1

package/dist/plan-summary.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The grouped plan summary (#3188): a view over a change-set document
+ * (`./change-set.ts`) that says how many members take the same change, which
+ * take something more, and every destroy, replacement, failure and hole by
+ * name. It is what reviewers read in an MR or PR note. Gates never bind it;
+ * they bind the document's digest.
+ *
+ * ## What "the same change" means
+ *
+ * A unit is a member of the document, or, when the document has one member,
+ * one resource instance of it; instances group only with instances of the
+ * same expansion (the address with its instance keys removed). Two units
+ * take the same change when their normalized changes are equal as
+ * multisets. A normalized change is:
+ *
+ * - the action. `no-op` entries are dropped.
+ * - the address, with every instance key removed and the unit's tokens
+ *   stripped from module call names and the resource name. The type is
+ *   never touched.
+ * - each attribute the entry carries (the change-set adapters carry only
+ *   the attributes a change writes), with the unit's tokens stripped from
+ *   every string value. A sensitive attribute compares by its path alone,
+ *   since the document carries no value for it.
+ *
+ * A unit's tokens are what names it: for a member, its scope (the estate or
+ * environment) and the last path segment of its name; for an instance, its
+ * own instance keys. Each is also tried with `-` and `_` swapped. A token
+ * is stripped only where it stands as a whole word, and one under three
+ * characters must also touch a `-` or `_`, so the key `1` leaves
+ * `10.1.0.0/16` alone. choudoufu's `tofu-estate` and `tofu-address` markers
+ * normalize away only when they hold the unit's own estate or address.
+ * Nothing else is stripped.
+ *
+ * An `import` block, a forget (a `removed` block or `destroy = false`, the
+ * plan action `forget`) and a triggered Terraform action (`action_invocations`)
+ * each get a named list of their own. A forget is not a destroy and is never
+ * in `destroys`; an import is part of its entry's change, so an entry that
+ * imports never groups with the same change without the import, and a triggered
+ * action is part of its unit's change the same way.
+ *
+ * A provisional member (one planned before what it reads applied, #3416)
+ * groups only with other provisional members, and its group says so: the
+ * flag is part of the group's id, so the same change planned for real and
+ * planned on stand-in values never share a group.
+ *
+ * These are choudoufu's rules for `live-summary` (choudoufu#1753). The two
+ * implementations are kept together by one table of test vectors both run
+ * (`__fixtures__/plan-summary/normalization-vectors.json`), per the ruling
+ * recorded on #3188.
+ *
+ * ## The import graph
+ *
+ * terragucci runs this in customer CI from one bundled file (#3421). It
+ * imports `./lifecycle/plan-digest` and types only, as `./change-set` does,
+ * and `change-set-bundle.test.ts` holds that.
+ */
+import type { ChangeSetAction, ChangeSetDocument, ChangeSetSideEffect } from "./change-set.js";
+/** The schema a plan summary names in `$schema`. */
+export declare const PLAN_SUMMARY_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/plan-summary/v1/plan-summary.schema.json";
+/** The read-contract version the summary follows. */
+export declare const PLAN_SUMMARY_CONTRACT = 1;
+/**
+ * The most characters a GitHub issue or pull request comment body may hold.
+ * The REST API refuses a longer one with "Body is too long (maximum is 65536
+ * characters)". GitHub documents no figure; this is the refusal's own.
+ */
+export declare const GITHUB_COMMENT_LIMIT = 65536;
+/**
+ * The most characters a GitLab note may hold, merge-request notes included:
+ * "Limited to 1,000,000 characters" (https://docs.gitlab.com/api/notes/).
+ */
+export declare const GITLAB_NOTE_LIMIT = 1000000;
+/** What a group's units are: whole members, or the instances of one member. */
+export type PlanSummaryUnit = "member" | "instance";
+/** One distinct normalized change of a group. */
+export interface PlanSummaryChange {
+    /** What a reader sees: the action's symbol, the normalized address and the attributes written. */
+    line: string;
+    action: ChangeSetAction;
+    /** How many times one unit makes this change. */
+    count: number;
+    /** The baseline group whose change at the same address and action this one differs from. */
+    differsFrom?: string;
+    /** The attributes it differs in. Values are never printed. */
+    differsIn?: string[];
+}
+/** One destroy or replacement, by its real address. */
+export interface PlanSummaryDestroy {
+    member: string;
+    address: string;
+    type: string;
+    action: "delete" | "replace";
+    deposed?: string;
+}
+/** One resource an `import` block brings into state. */
+export interface PlanSummaryImport {
+    member: string;
+    address: string;
+    type: string;
+    /** What else the plan does to it: `no-op` when the import changes nothing, else `update`, `create` and so on. */
+    action: ChangeSetAction;
+}
+/** One resource a plan stops tracking and leaves running (`removed` with `destroy = false`). It is not a destroy. */
+export interface PlanSummaryForget {
+    member: string;
+    address: string;
+    type: string;
+    deposed?: string;
+}
+/** A provider-defined side effect an apply runs: a triggered Terraform action. */
+export type PlanSummarySideEffect = ChangeSetSideEffect;
+export interface PlanSummaryGroup {
+    /** Twelve hex characters over the group's normalized changes: the same change gets the same id in every run. */
+    id: string;
+    /** For instance groups, the expansion the instances belong to. */
+    resource?: string;
+    /** Member names, or instance addresses. */
+    units: string[];
+    /** A group of one beside other groups of the same expansion. */
+    outlier: boolean;
+    /** Units whose plans change nothing. */
+    noChanges: boolean;
+    changes: PlanSummaryChange[];
+    /** The group whose whole change this one contains; `plus` is what it adds. */
+    extends?: string;
+    plus?: PlanSummaryChange[];
+    /** Every destroy and replacement any unit of the group makes. */
+    destroys: PlanSummaryDestroy[];
+    /** Every triggered action any unit of the group runs. */
+    sideEffects: PlanSummarySideEffect[];
+    /** Its units are provisional plans: previews no approval covers. Absent on a group of real plans. */
+    provisional?: true;
+}
+/** A member that failed to plan. It is never in a group. */
+export interface PlanSummaryFailure {
+    member: string;
+    scope?: string;
+    reason: string;
+}
+/** An address a member's planner could not read. */
+export interface PlanSummaryHole {
+    member: string;
+    address: string;
+    type?: string;
+    reason: string;
+}
+export interface PlanSummary {
+    $schema: typeof PLAN_SUMMARY_SCHEMA_ID;
+    contract: typeof PLAN_SUMMARY_CONTRACT;
+    /** The digest of the change-set document summarized. */
+    changeSet: string;
+    unit: PlanSummaryUnit;
+    /** Members, failed ones included, or the changing instances of the one member. */
+    units: number;
+    groups: PlanSummaryGroup[];
+    failed: PlanSummaryFailure[];
+    /** Every destroy and replacement in the document, failed members' included, sorted by member and address. */
+    destroys: PlanSummaryDestroy[];
+    /** Every import, in the document, sorted by member and address. Imports are never destroys. */
+    imports: PlanSummaryImport[];
+    /** Every forget in the document, sorted by member and address. A forget is never in `destroys`. */
+    forgets: PlanSummaryForget[];
+    /** Every triggered action in the document, sorted by member and address. */
+    sideEffects: PlanSummarySideEffect[];
+    holes: PlanSummaryHole[];
+}
+export interface GroupChangeSetOptions {
+    /** `member` groups whole members; `instance` groups one member's instances. Default: `instance` for a one-member document, else `member`. */
+    unit?: PlanSummaryUnit;
+}
+/** An address without its instance keys, and the keys, decoded: `module.a["x"].b.c[0]` is `module.a.b.c` with `["x", "0"]`. */
+export declare function splitInstanceKeys(address: string): {
+    bare: string;
+    keys: string[];
+};
+/** The value a `tofu-address` marker holds for `address`. */
+export declare function escapeMarkerAddress(address: string): string;
+/**
+ * Group a change-set document's units by their normalized changes. Failed
+ * members are listed with their reasons and never grouped. Every delete and
+ * replace the document holds is in `destroys`, and each also in its unit's
+ * group; every hole is in `holes`.
+ */
+export declare function groupChangeSet(doc: ChangeSetDocument, options?: GroupChangeSetOptions): PlanSummary;
+/** The first line: units, groups, failures, destroys and holes. */
+export declare function planSummaryHeadline(s: PlanSummary): string;
+/** The summary for a terminal. Destroys, failures and holes come first, then every group. */
+export declare function renderPlanSummaryText(s: PlanSummary): string;
+export interface RenderMarkdownOptions {
+    /** The most characters (code points) the note may hold. Default {@link GITHUB_COMMENT_LIMIT}. */
+    limit?: number;
+    /** The command that prints the whole summary, named when the note is cut. */
+    command?: string;
+}
+/**
+ * The summary as an MR or PR note of at most `limit` characters.
+ *
+ * Blocks come in a fixed order: the headline, every destroy and
+ * replacement, every forget, import and triggered action, every failed member, every hole, then the groups largest
+ * first. When the whole does not fit, groups are dropped from the end, never
+ * cut in the middle, and a closing line names how many groups, units and
+ * destroys it left out. The destroy, failure and hole lines are cut only
+ * when they alone exceed the limit, from the end, and the closing line
+ * counts those too.
+ */
+export declare function renderPlanSummaryMarkdown(s: PlanSummary, options?: RenderMarkdownOptions): string;
+//# sourceMappingURL=plan-summary.d.ts.map

package/dist/plan-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-summary.d.ts","sourceRoot":"","sources":["../src/plan-summary.ts"],"names":[],"mappings":"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"}

package/dist/pr-forge.d.ts

@@ -0,0 +1,105 @@
+/**
+ * What the pull-request loop (#3183) asks of a forge: keep one note on the
+ * pull request up to date, set a commit status per stage, list who approved
+ * the pull request, and find the pull request that merged a commit.
+ *
+ * GitHub and Forgejo speak the same REST shapes for the first three, at
+ * different base URLs (`$GITHUB_API_URL` is right on both, #2305); they part
+ * on the commit-to-pull-request lookup and on review states. GitLab has its
+ * own API for all four. Each client takes a `fetch`, so the tests drive them
+ * with a recording fake and no network.
+ *
+ * A reviewer is named the way #3163 names a person: `github:<login>`,
+ * `gitlab:<login>`, or `<forge>@<host>:<login>` off the forge's default host.
+ * The apply compares that string with the approval's `resolvedBy`.
+ *
+ * Like `./pr-loop.ts`, this bundles without the TypeScript toolchain (#3421):
+ * it imports nothing.
+ */
+export type ForgeKind = "github" | "gitlab" | "forgejo";
+export declare const FORGE_KINDS: readonly ForgeKind[];
+/** The subset of the WHATWG `fetch` the clients use. */
+export type ForgeFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+export interface ForgeStatus {
+    /** `chant/plan` or `chant/apply`. */
+    context: string;
+    state: "pending" | "success" | "failure";
+    description: string;
+    /** The pipeline run, linked from the status. */
+    url?: string;
+}
+export interface PrForge {
+    kind: ForgeKind;
+    /** Lower-cased, such as `github.com`. */
+    host: string;
+    /** The URL of the run this process is part of, when the environment says. */
+    runUrl?: string;
+    /** How #3163 names `login` on this forge. */
+    principalOf(login: string): string;
+    /** Update the note on `pr` whose body starts with `marker`, or add one. */
+    upsertNote(pr: number, marker: string, body: string): Promise<void>;
+    setStatus(sha: string, status: ForgeStatus): Promise<void>;
+    /** Logins whose standing review approves `pr`. */
+    approvers(pr: number): Promise<string[]>;
+    /** The merged pull request that produced `sha`, or null. */
+    pullRequestFor(sha: string): Promise<number | null>;
+}
+/** Thrown when a forge answers a call with an error status. */
+export declare class ForgeApiError extends Error {
+    readonly method: string;
+    readonly url: string;
+    readonly status: number;
+    constructor(method: string, url: string, status: number, detail: string);
+}
+/** `<forge>:<login>` on the forge's default host, `<forge>@<host>:<login>` elsewhere, lower-cased (#3163's form). */
+export declare function forgePrincipalOf(kind: ForgeKind, host: string, login: string): string;
+export interface GithubForgeOptions {
+    /** `$GITHUB_API_URL`: `https://api.github.com`, `<host>/api/v3`, or Forgejo's `<host>/api/v1`. */
+    apiBase: string;
+    /** `owner/name`. */
+    repo: string;
+    token: string;
+    /** The forge's host, for naming reviewers. Default github.com. */
+    host?: string;
+    runUrl?: string;
+    fetch?: ForgeFetch;
+}
+/** A GitHub client (github.com or GitHub Enterprise Server). */
+export declare function githubForge(opts: GithubForgeOptions): PrForge;
+/** A Forgejo (or Gitea) client. `host` is required: Forgejo has no default host. */
+export declare function forgejoForge(opts: GithubForgeOptions & {
+    host: string;
+}): PrForge;
+export interface GitlabForgeOptions {
+    /** `$CI_API_V4_URL`. */
+    apiBase: string;
+    /** `$CI_PROJECT_ID`, or the URL-encoded path. */
+    project: string;
+    token: string;
+    /** Default gitlab.com. */
+    host?: string;
+    runUrl?: string;
+    fetch?: ForgeFetch;
+}
+/** A GitLab client. The token needs the `api` scope: a job token cannot write merge-request notes. */
+export declare function gitlabForge(opts: GitlabForgeOptions): PrForge;
+/** Thrown when the environment lacks what a forge client needs. */
+export declare class ForgeEnvironmentError extends Error {
+    constructor(kind: ForgeKind, missing: string[]);
+}
+/**
+ * A client for `kind` from the CI job's environment. The token is
+ * `CHANT_FORGE_TOKEN` when set, else the forge's own: `GITHUB_TOKEN` (also
+ * set on Forgejo Actions) or `GITLAB_TOKEN`. GitLab's `CI_JOB_TOKEN` cannot
+ * write notes, so a GitLab pipeline names a project access token.
+ */
+export declare function forgeFromEnv(kind: ForgeKind, env?: Record<string, string | undefined>, fetchImpl?: ForgeFetch): PrForge;
+//# sourceMappingURL=pr-forge.d.ts.map

package/dist/pr-forge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-forge.d.ts","sourceRoot":"","sources":["../src/pr-forge.ts"],"names":[],"mappings":"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"}

package/dist/pr-loop.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The pull-request loop (#3183): plan the members a change reaches, show the
+ * plan on the pull request, and apply it on merge only when the plan is the
+ * one a reviewer approved.
+ *
+ * `chant components pr-plan` and `chant components pr-apply` run it, and the
+ * generated CI for GitHub, GitLab and Forgejo calls them
+ * (`components/pr-pipeline.ts`). This module holds the parts that need no
+ * runner: the gate's names, the report both commands write, the pull-request
+ * note rendered from it and the status line. terragucci reads the report and
+ * renders the note from one bundled file with no TypeScript toolchain
+ * (#3421), so this imports `./change-set` and `./plan-summary` and nothing
+ * else; `pr-loop-bundle.test.ts` holds that.
+ *
+ * ## What the gate binds
+ *
+ * One gate per pull request: op `pr-<number>`, gate `pr-apply` unless the
+ * pipeline names another. It binds the digest of the change-set document over
+ * every planned member (`changeSetDigest`, #3181), the same digest a gated
+ * wave binds over its members (#3049). A reviewer approves it with `chant
+ * approve pr-<number> pr-apply --plan <digest>`. The op carries the number so
+ * that one pull request's approval never answers another's, and the gate name
+ * stays fixed so a workspace can require signed approvals for it under
+ * `identity.gates` (#3163).
+ *
+ * On merge the apply plans the same members again, before anything applies,
+ * and decides the gate against the new digest. The same plan applies; a moved
+ * plan stops with both digests named and nothing applied.
+ */
+import type { ChangeSetDocument } from "./change-set.js";
+/** The schema a pull-request report names in `$schema`. */
+export declare const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json";
+/** The read-contract version the report follows. */
+export declare const PR_REPORT_CONTRACT = 1;
+/** The gate a pull request's apply waits on, unless the pipeline names another. */
+export declare const PR_APPLY_GATE = "pr-apply";
+/** The op a pull request's gate is recorded under: `pr-<number>`. */
+export declare function prOp(pr: number): string;
+/** The hidden line that marks the pull request's note, one per environment. */
+export declare function prNoteMarker(env: string): string;
+/** The status contexts the two stages set on the commit. */
+export declare const PR_STATUS_CONTEXTS: {
+    readonly plan: "chant/plan";
+    readonly apply: "chant/apply";
+};
+/** Changes a member's plan proposes, by the actions a reviewer reads. */
+export interface PrMemberCounts {
+    create: number;
+    update: number;
+    replace: number;
+    delete: number;
+}
+/** Where one member got to. */
+export type PrMemberStatus = 
+/** Planned, nothing applied (the plan stage, or an apply that stopped). */
+"planned"
+/** The plan failed. */
+ | "plan-failed"
+/** Applied the approved plan. */
+ | "applied"
+/** The apply failed. */
+ | "failed"
+/** Not applied because a member it depends on failed. */
+ | "blocked";
+export interface PrMember {
+    /** The member's name in the change set: a root, for a terraform-family step. */
+    member: string;
+    /** The component whose step planned it. */
+    component: string;
+    /** What a gate on this member alone binds. `null` when it failed to plan. */
+    planDigest: string | null;
+    status: PrMemberStatus;
+    counts: PrMemberCounts;
+    error?: string;
+    /**
+     * Components this one depends on whose outputs changed when they applied
+     * (apply stage). Its applied plan read the values from before, so the next
+     * run plans it again.
+     */
+    inputsMoved?: string[];
+}
+/** Where the approval stands for the planned digest. */
+export interface PrApproval {
+    /**
+     * `approved`: an approval stands for this digest. `changed`: one stands for
+     * another digest, so the plan moved since someone approved it. `pending`:
+     * none stands.
+     */
+    status: "approved" | "changed" | "pending";
+    /** Who approved this digest. */
+    approvedBy?: string[];
+    /** With `changed`: the digest that was approved. */
+    approved?: string;
+}
+/** How a stage ended. */
+export type PrStatus = 
+/** Plan stage: every member planned. */
+"planned"
+/** Plan stage: a member failed to plan. Apply stage: the same, so nothing applied. */
+ | "plan-failed"
+/** Nothing the change touches is deployed by a component. */
+ | "nothing"
+/** Apply stage: every member applied. */
+ | "applied"
+/** Apply stage: a member failed to apply. Its dependents did not run. */
+ | "failed"
+/** Apply stage: nothing applied, see `refusal`. */
+ | "refused";
+/** Why an apply refused. */
+export type PrRefusal = 
+/** No approval stands for any plan of this pull request. */
+"not-approved"
+/** The approval stands for another digest: the plan changed after review. */
+ | "plan-changed"
+/** The approval names someone who has not approved the pull request on the forge. */
+ | "not-a-reviewer"
+/** No pull request merged this commit, so there is no approval to read. */
+ | "no-pull-request";
+/**
+ * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
+ * The terragucci plan report (#3349) reads it; fields are only ever added.
+ */
+export interface PrReport {
+    $schema: typeof PR_REPORT_SCHEMA_ID;
+    contract: typeof PR_REPORT_CONTRACT;
+    stage: "plan" | "apply";
+    /** The pull or merge request number, when known. */
+    pr: number | null;
+    env: string;
+    /** The commit the change is measured from: the merge base of the given base and `head`. */
+    base: string;
+    head: string;
+    /** The gate's ledger entry: `_gates/<op>.jsonl` on `chant/lifecycle`. */
+    op: string;
+    gate: string;
+    /** The change-set digest of what this stage planned. What the gate binds. */
+    digest: string;
+    status: PrStatus;
+    refusal?: PrRefusal;
+    /** The refusal or failure, as printed. */
+    message?: string;
+    approval: PrApproval;
+    /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
+    selection: {
+        changed: string[];
+        dependents: string[];
+        unclaimed: string[];
+        indeterminate: string[];
+        /** The components in dependency order, a wave per entry. */
+        waves: string[][];
+    };
+    members: PrMember[];
+    changeSet: ChangeSetDocument;
+}
+/** The counts a member's entries add up to. */
+export declare function memberCounts(doc: Pick<ChangeSetDocument, "summary">, member: string): PrMemberCounts;
+/** The approve command a reviewer runs for this report's digest. */
+export declare function prApproveCommand(report: Pick<PrReport, "op" | "gate" | "digest">, approver?: string): string;
+/**
+ * The refusal when the approved digest is not the planned one: both digests,
+ * that nothing applied, and how to close it.
+ */
+export declare function describePlanChanged(report: Pick<PrReport, "op" | "gate" | "digest" | "approval">): string;
+/**
+ * The pull-request note: the stage's headline, a row per member, the digest
+ * and the approval, then the grouped plan summary (#3188) in whatever room
+ * `limit` leaves. The note starts with {@link prNoteMarker}, so the same
+ * comment is updated by every push and by the apply.
+ */
+export declare function renderPrNote(report: PrReport, options?: {
+    limit?: number;
+    approver?: string;
+}): string;
+/** A commit status's description, at most 140 characters (GitHub's limit). */
+export declare function prStatusDescription(report: PrReport): string;
+/** The commit status state for a report: success, failure, or pending while it waits on approval. */
+export declare function prStatusState(report: PrReport): "success" | "failure" | "pending";
+//# sourceMappingURL=pr-loop.d.ts.map

package/dist/pr-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-loop.d.ts","sourceRoot":"","sources":["../src/pr-loop.ts"],"names":[],"mappings":"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"}

package/dist/telemetry-attribution.d.ts

@@ -74,4 +74,35 @@ export declare function telemetryEnvironment(attribution: TelemetryAttribution,
  * overwritten; a key it didn't set is appended.
  */
 export declare function mergeResourceAttributes(existing: string, extra: string): string;
+/**
+ * The environment variable a deploy sets to the release attributes, as a
+ * suffix for `OTEL_RESOURCE_ATTRIBUTES`. A stamped workload's generated
+ * output appends it where the platform expands variables (Compose
+ * interpolation, a Kubernetes `$(VAR)` reference), so the committed files are
+ * the same bytes whatever is released.
+ */
+export declare const RELEASE_ATTRIBUTES_VARIABLE = "CHANT_RELEASE_ATTRIBUTES";
+/**
+ * The pod-template annotation a Kubernetes release writes the suffix to. A
+ * stamped container reads it into {@link RELEASE_ATTRIBUTES_VARIABLE} through
+ * the downward API; an absent annotation reads as empty.
+ */
+export declare const RELEASE_ATTRIBUTES_ANNOTATION = "chant.intentius.io/release-attributes";
+/** What the step that deploys a release knows: the artifact it promoted and the commit it came from. */
+export interface ReleaseIdentity {
+    /** `service.version`: the digest of the artifact the run promoted, the release record's `digest`. */
+    version?: string;
+    /** `vcs.ref.head.revision`: the commit, the release record's `gitSha`. */
+    revision?: string;
+}
+/**
+ * The release attributes as a suffix for `OTEL_RESOURCE_ATTRIBUTES`: each
+ * pair preceded by a comma and percent-encoded the way
+ * {@link telemetryEnvironment} encodes, or `""` when the release knows
+ * neither. The build-time list always has `chant.decl`, so the suffix never
+ * starts the list.
+ */
+export declare function releaseAttributesSuffix(release: ReleaseIdentity | undefined): string;
+/** The variables a deploy step exports for a release: {@link RELEASE_ATTRIBUTES_VARIABLE}, or nothing. */
+export declare function releaseEnvironment(release: ReleaseIdentity | undefined): Record<string, string>;
 //# sourceMappingURL=telemetry-attribution.d.ts.map

package/dist/telemetry-attribution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry-attribution.d.ts","sourceRoot":"","sources":["../src/telemetry-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,oBAAoB,EAAE,SAAS,sBAAsB,EAQjE,CAAC;AAUF;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAuB3C;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8GAA8G;AAC9G,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,oBAAoB,EAAE,QAAQ,EAAE,iBAAiB,GAAG;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAE,CAepK;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/E"}
+{"version":3,"file":"telemetry-attribution.d.ts","sourceRoot":"","sources":["../src/telemetry-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,mGAAmG;IACnG,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,oBAAoB,EAAE,SAAS,sBAAsB,EAQjE,CAAC;AAUF;;;;;;;;;;;GAWG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAuB3C;AAED,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8GAA8G;AAC9G,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,oBAAoB,EAAE,QAAQ,EAAE,iBAAiB,GAAG;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,wBAAwB,EAAE,MAAM,CAAA;CAAE,CAepK;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/E;AAID;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,0CAA0C,CAAC;AAErF,wGAAwG;AACxG,MAAM,WAAW,eAAe;IAC9B,qGAAqG;IACrG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAUpF;AAED,0GAA0G;AAC1G,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG/F"}

package/dist/terraform/hcl2json.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The optional HCL parser, loaded lazily. Kept apart from `parse.ts` so a
+ * caller that only needs the loader (the terraform lexicon's HCL reader) does
+ * not pull in the dependency graph, the state reader and the carve tables.
+ *
+ * `@cdktn/hcl2json` is NOT a chant dependency: it carries a ~1.8 MB wasm blob
+ * and only HCL users need it. If it is absent the loader fails with a
+ * one-line install hint.
+ */
+import type { Hcl2JsonTree } from "./types.js";
+/** Minimal shape of the parser exports we depend on. */
+export interface Hcl2Json {
+    parse: (filename: string, hcl: string) => Promise<Hcl2JsonTree>;
+    /** Expression-AST reference extraction (#998) — one traversal accessor per reference. */
+    getReferencesInExpression: (filename: string, expression: string) => Promise<Array<{
+        value: string;
+    }>>;
+}
+export declare class Hcl2JsonNotInstalled extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * The environment variable that turns on parser-input recording (chant #2483).
+ *
+ * When set to a file path, every `parse(filename, source)` and every
+ * `getReferencesInExpression(filename, expression)` this process makes is
+ * appended to that file as one JSON line before the real call runs. That is
+ * how `scripts/check-hcl-parser-parity.ts` gets hold of the inline HCL the
+ * test suite parses, which no corpus walk on disk would find: run the suite
+ * with this set, then replay the file through two parsers and compare. Off
+ * unless set, and never changes a result.
+ */
+export declare const HCL2JSON_RECORD_ENV = "CHANT_HCL2JSON_RECORD";
+/** One recorded parser input, as {@link HCL2JSON_RECORD_ENV} writes it. */
+export interface Hcl2JsonRecordLine {
+    kind: "parse" | "refs";
+    filename: string;
+    text: string;
+}
+/**
+ * Lazy-load the optional HCL parser. Throws `Hcl2JsonNotInstalled` with an
+ * install hint when the package is missing, rather than a raw MODULE_NOT_FOUND.
+ */
+export declare function loadHcl2json(): Promise<Hcl2Json>;
+//# sourceMappingURL=hcl2json.d.ts.map

package/dist/terraform/hcl2json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hcl2json.d.ts","sourceRoot":"","sources":["../../src/terraform/hcl2json.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,yFAAyF;IACzF,yBAAyB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACxG;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,KAAK,EAAE,OAAO,EAOzB;CACF;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAkBD;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAStD"}