@intentius/chant-lexicon-pulumi 0.0.0-stage → 0.124.54

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @intentius/chant-lexicon-pulumi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pulumi lexicon for [chant](https://intentius.io/chant/). It declares no resource types. It supplies the `pulumi` workspace member kind and reads a Pulumi program four ways:
+
+| Read | Source | Module |
+|---|---|---|
+| the member's graph | the `pulumi stack export` checked in as `stack-export.json` | `src/workspace-member.ts` |
+| its change-set part | `pulumi preview --json` | `src/change-set.ts` |
+| its drift records | `pulumi refresh --preview-only --json --target <urn>`, one resource at a time | `src/drift-record.ts`, `src/drift-read.ts` |
+| its stack outputs, for another member's parameters | `pulumi stack output --json --show-secrets=false` (applied) and `pulumi preview --json` (planned) | `src/stack-outputs.ts`, `src/member-outputs.ts` |
+| engine facts, for a member on plunge | `plunge graph --json --stack <stack>` (`describeResources`), or the checked-in `engine-graph.json` (the graph read) | `src/describe-resources.ts`, `src/engine-graph.ts` |
+
+The graph read never runs `pulumi`. The change set and drift run `preview` and `refresh --preview-only`, and the outputs read adds `stack output --json --show-secrets=false`. A member on plunge runs `plunge preview`, `plunge stack output --json --show-secrets=false` and `plunge drift --resource <urn> --stream`. For its engine facts it runs one of exactly four argv: `plunge graph --json`, `plunge graph --json --stack <stack>`, `plunge graph --json --versions` and `plunge graph --json --stack <stack> --versions` ([#4529](https://github.com/INTENTIUS/chant/issues/4529)). An outputs or secrets flag on `plunge graph` is refused. That is the whole list, as ruled on [#4476](https://github.com/INTENTIUS/chant/issues/4476) (2026-10-25), which widened the [#4450](https://github.com/INTENTIUS/chant/issues/4450) ruling's `preview` and `refresh --preview-only` to keep the outputs read and the plunge commands. Nothing else runs (`runAllowedPulumi` and `runAllowedPlunge` refuse any other argv), so chant never changes a stack. With `CHANT_PULUMI_APPLIED_OUTPUTS=export`, the outputs read runs nothing either.
+
+## Drift: `chant workspace drift`
+
+`chant workspace drift --member <pulumi member> [--resource <urn>] [--stream]` runs `chant lifecycle drift` in the member's reader project, which calls this lexicon's `readDrift`. A stock member is read with one `pulumi refresh --preview-only --json --target <urn>` per resource in its checked-in `stack-export.json`. A member on plunge is read with `plunge drift --resource <urn> --stream` per resource. `--resource` reads one URN. The only read is `refresh`.
+
+A member runs on plunge when its config says `engine: "plunge"`, or when `Pulumi.yaml` names a backend URL starting with `plunge` (`plunge+file://...`, `plunge://...`). Only `Pulumi.yaml` is read, never `PULUMI_BACKEND_URL` or login state.
+
+## Engine facts for a member on plunge
+
+plunge keeps a record per resource, and `plunge graph --json` prints the stack's graph from those records in the engine graph document chant#4520 designed. It makes no provider call and prints no output value. chant reads it two ways ([#4529](https://github.com/INTENTIUS/chant/issues/4529)):
+
+- `describeResources` runs `plunge graph --json --stack <stack>` once per member, with the stack the other reads use. Each node becomes a resource keyed like the member graph's node, with plunge's facts on `ResourceMetadata.facts`. Every resource has `ownership: "unknown"` and no marker, so no change set or teardown decides from it.
+- The graph read takes a checked-in `engine-graph.json` beside `stack-export.json`. Its facts go on the nodes (`nodes[].facts`) and its `property` edges join the graph with `grain: "property"`. The export's `dependencies` and `parent` edges carry `grain: "instance"`.
+
+plunge's markers say `source: "record"`: what its record says it wrote, not a read of the object. A stock member gets neither read, and chant runs nothing new for it. Record versions (`--versions`) cost one listing per record, so `describeResources` leaves them off.
+
+## Outputs into another member's parameters
+
+A chant member reads a Pulumi member's outputs with core's `member-outputs` verb (chant#4455):
+
+```ts
+import { memberOutputsComponent } from "@intentius/chant/components/verbs/member-outputs";
+
+export const aws = memberOutputsComponent("aws");
+export const records: Component = {
+  name: "records",
+  dependsOn: ["aws"],
+  deploy: [phase("Apply", [cfnDeploy({ template: "dist/dns.json", inputs: { awsEndpoint: stackOutput("aws", "awsEndpoint") } })])],
+};
+```
+
+The consumer lists `pulumi` among its lexicons, which brings `pulumiCapabilityPlugin` and its source, `pulumiOutputSource`, for members of kind `pulumi`.
+
+- Applied values come from `pulumi stack output --json --show-secrets=false` in the member's directory. With `CHANT_PULUMI_APPLIED_OUTPUTS=export`, chant runs nothing and reads them from the checked-in `stack-export.json`.
+- Planned values come from `pulumi preview --json --show-sames`. A real preview carries no outputs on the stack's `pulumi:pulumi:Stack` step (recorded, #4475), so a preview with nothing to apply gives the checked-in export's outputs and one with changes leaves every output unknown. An output a stack step does carry is read, and one holding Pulumi's unknown sentinel is unknown. The consumer is planned without an unknown output, gets a hole on `aws#outputs` naming it, and is held back on merge until the member applied, then planned again.
+- The plan digest is the member part's `pulumi-preview` digest, so a preview that moves after review moves the consumer's digest.
+- While the preview still has changes, `run` refuses and the consumer is blocked behind the member.
+- Secret outputs are left out of both reads. chant never carries or prints their values.
+- A member on plunge runs the same commands under `plunge`.
+- Both commands run against the member's selected stack.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-pulumi
+```
+
+## License
+
+See the main project LICENSE file.

package/dist/capability-plugin.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+export declare const pulumiCapabilityPlugin: CapabilityPlugin;
+//# sourceMappingURL=capability-plugin.d.ts.map

package/dist/capability-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../src/capability-plugin.ts"],"names":[],"mappings":"AASA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAIzG,eAAO,MAAM,sBAAsB,EAAE,gBAWpC,CAAC"}

package/dist/capability-plugin.js

@@ -0,0 +1,14 @@
+import { ownPackageVersion } from "@intentius/chant/components/capability-plugin";
+import { pulumiStackOutputSource } from "./member-outputs.js";
+export const pulumiCapabilityPlugin = {
+    name: "pulumi",
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities() {
+        return [];
+    },
+    engineOutputSources() {
+        return [pulumiStackOutputSource];
+    },
+};

package/dist/change-set.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The change-set adapter for a Pulumi member (#4453): `pulumi preview --json`
+ * into an `@intentius/chant/change-set` part, planner `pulumi`.
+ *
+ * ## Steps to entries
+ *
+ * The preview prints one step per resource the program registered, `same`
+ * included, and a replace as two or three steps on one URN
+ * (`create-replacement`, `replace`, `delete-replaced`). The adapter keeps one
+ * entry per URN, at the URN, so `node` comes from the one URN rule
+ * (`@intentius/chant/pulumi-urn`, #4456):
+ *
+ * | step op | action | disruption |
+ * |---|---|---|
+ * | `create` | create | |
+ * | `update` | update | in-place |
+ * | `delete` | delete | destroy |
+ * | `replace`, `create-replacement`, `delete-replaced` | replace | replace, or destroy when the delete comes first (`deleteBeforeReplace`) |
+ * | `same` | no-op | |
+ * | `read`, `read-replacement`, `refresh` | read | |
+ * | `import` | no-op, importing | |
+ * | `import-replacement` | replace, importing | replace |
+ * | `discard`, `remove-pending-replace` | forget | |
+ *
+ * An op the table does not hold is a hole on the member, never a guess.
+ *
+ * Attributes are top-level inputs, as the change set wants them. A create
+ * writes every input. An update or replace writes the keys `detailedDiff`
+ * and `diffReasons` name, and every input whose new value holds an unknown.
+ * `replaceReasons` and a `detailedDiff` kind ending in `-replace` mark
+ * `forcesReplacement`. An input that holds Pulumi's unknown sentinel is
+ * `unknown: true` with no `after`: a resource that reads an output of one
+ * being created shows its dependent input as unknown. A value that holds a
+ * secret is `sensitive: true` with neither side.
+ *
+ * ## What preview cannot list: `mayAppear`
+ *
+ * A program may register resources inside an `apply()`. At preview an
+ * `apply()` whose input is unknown does not run, so what it would register
+ * is never in the steps. Dropping it would make the set look smaller than
+ * the apply, so the adapter marks it `mayAppear` instead, on two signals:
+ *
+ * 1. A component (a step whose state is `custom: false`, not the root stack)
+ *    whose subtree in the preview holds an unknown, in any input or output,
+ *    or a create or replace, whose outputs are unknown until apply. Its code
+ *    may be waiting on that value to register children. It gets one entry
+ *    at `pulumiMayAppearAddress(<component urn>)`, action `create`, type
+ *    `unknown`, no attributes, on the component's node.
+ * 2. With the last deployment's `pulumi stack export` (`prior`): a resource
+ *    the export holds and the preview has no step for gets an `update`
+ *    entry with disruption `unknown`, since a full preview lists every
+ *    registered resource and only an `apply()` that did not run leaves one
+ *    out. A `delete` step for a resource under a component signal 1 marks
+ *    keeps its `delete` and gets `mayAppear`, since the `apply()` may
+ *    register it again. A preview narrowed with `--target` (`targeted`)
+ *    lists only its targets, and a failed one stops part way, so signal 2's
+ *    first half is off for both.
+ *
+ * A resource registered inside an `apply()` directly under the stack, with
+ * no export that holds it, has no component to stand under and is not
+ * detected. When the export does hold it and its input is unknown, the
+ * preview prints a `delete` for it, which reads as a plain delete. Those are
+ * the two cases left out.
+ *
+ * ## The digest
+ *
+ * {@link pulumiPreviewDigest}: `computePlanDigest("pulumi-preview", …)` over
+ * each step's op, URN, provider, id, inputs before and after, `diffReasons`,
+ * `replaceReasons` and `detailedDiff`, sorted by URN and op. It leaves out
+ * `config`, `duration`, `diagnostics` and `changeSummary`, and the states'
+ * outputs, which at preview are the last deployment's or unknown.
+ *
+ * The fixtures under `testdata/pulumi-preview` are recorded from pulumi
+ * 3.272.0 against the plunge corpus's aws-ts program on floci (#4475). What
+ * the recording showed: `preview --json` lists no unchanged resource unless
+ * `--show-sames` is passed, which chant's argv does, since signal 2 reads a
+ * missing resource as one an `apply()` may register; a replace is one
+ * `replace` step at preview, not three; the stack's step carries no planned
+ * outputs; a secret is the blinded string `"[secret]"`; and a resource
+ * registered inside an `apply()` directly under the stack whose input is
+ * unknown (the corpus's `vpc-id` parameter, named after a VPC being
+ * replaced) is printed as a `delete`, which this adapter keeps as a plain
+ * delete since nothing tells it apart from a removed resource.
+ *
+ * ## The import graph
+ *
+ * Like the terraform lexicon's `change-set`, this imports chant's
+ * `change-set` types, `lifecycle/plan-digest`, `pulumi-urn` and `./values`,
+ * so it bundles without TypeScript, node's process modules or zod (#3421).
+ */
+import type { ChangeSetPart } from "@intentius/chant/change-set";
+import { type Json } from "./values.js";
+/** One resource state on a preview step, `apitype.ResourceV3`, as far as the adapter reads it. */
+export interface PulumiStepState {
+    urn?: string;
+    custom?: boolean;
+    delete?: boolean;
+    id?: string;
+    type?: string;
+    parent?: string;
+    inputs?: Json;
+    outputs?: Json;
+}
+/** One step of `pulumi preview --json` or `pulumi refresh --preview-only --json`. */
+export interface PulumiStep {
+    op?: string;
+    urn?: string;
+    provider?: string;
+    oldState?: PulumiStepState;
+    newState?: PulumiStepState;
+    diffReasons?: string[];
+    replaceReasons?: string[];
+    detailedDiff?: Record<string, {
+        kind?: string;
+        inputDiff?: boolean;
+    }> | null;
+}
+/** The steps of a preview or refresh document, or undefined when it has none. */
+export declare function pulumiSteps(doc: unknown): PulumiStep[] | undefined;
+/** One resource of a `pulumi stack export`, as far as the adapter reads it. */
+export interface PulumiExportedResource {
+    urn: string;
+    type: string;
+    custom?: boolean;
+    id?: string;
+    parent?: string;
+}
+/** The resources of a `pulumi stack export` document (`deployment.resources`). Not one: an empty list. */
+export declare function pulumiExportResources(doc: unknown): PulumiExportedResource[];
+/**
+ * The member's plan digest: `computePlanDigest("pulumi-preview", …)` over
+ * what each step proposes, sorted by URN and op, so two renderings of one
+ * preview agree. See the module comment for what it leaves out.
+ */
+export declare function pulumiPreviewDigest(preview: unknown): string;
+export interface PulumiPreviewPartInput {
+    /** The workspace member's name, which names its graph nodes (`<member>/<key>`). */
+    member: string;
+    /** `pulumi preview --json`, parsed. */
+    preview: unknown;
+    /** The stack the preview ran against, recorded as `scope`. */
+    stack?: string;
+    /**
+     * The last deployment, as `pulumi stack export` prints it: the member's
+     * checked-in `stack-export.json`. With it, a resource the preview leaves
+     * out is a `mayAppear` entry rather than silence.
+     */
+    prior?: unknown;
+    /** The preview was narrowed with `--target`, so it lists only its targets. */
+    targeted?: boolean;
+    /** The preview failed: the member is failed with this error, and keeps whatever steps it printed. */
+    error?: string;
+}
+/**
+ * A Pulumi member's part, from its `pulumi preview --json`. Throws when the
+ * document has no `steps` and no `error` says why.
+ */
+export declare function pulumiPreviewPart(input: PulumiPreviewPartInput): ChangeSetPart;
+//# sourceMappingURL=change-set.d.ts.map

package/dist/change-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../src/change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyFG;AAEH,OAAO,KAAK,EAMV,aAAa,EACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAA6E,KAAK,IAAI,EAAE,MAAM,UAAU,CAAC;AAEhH,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;CAC9E;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,EAAE,GAAG,SAAS,CAGlE;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,sBAAsB,EAAE,CAI5E;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAe5D;AAyFD,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qGAAqG;IACrG,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,aAAa,CAyH9E"}

package/dist/change-set.js

@@ -0,0 +1,347 @@
+/**
+ * The change-set adapter for a Pulumi member (#4453): `pulumi preview --json`
+ * into an `@intentius/chant/change-set` part, planner `pulumi`.
+ *
+ * ## Steps to entries
+ *
+ * The preview prints one step per resource the program registered, `same`
+ * included, and a replace as two or three steps on one URN
+ * (`create-replacement`, `replace`, `delete-replaced`). The adapter keeps one
+ * entry per URN, at the URN, so `node` comes from the one URN rule
+ * (`@intentius/chant/pulumi-urn`, #4456):
+ *
+ * | step op | action | disruption |
+ * |---|---|---|
+ * | `create` | create | |
+ * | `update` | update | in-place |
+ * | `delete` | delete | destroy |
+ * | `replace`, `create-replacement`, `delete-replaced` | replace | replace, or destroy when the delete comes first (`deleteBeforeReplace`) |
+ * | `same` | no-op | |
+ * | `read`, `read-replacement`, `refresh` | read | |
+ * | `import` | no-op, importing | |
+ * | `import-replacement` | replace, importing | replace |
+ * | `discard`, `remove-pending-replace` | forget | |
+ *
+ * An op the table does not hold is a hole on the member, never a guess.
+ *
+ * Attributes are top-level inputs, as the change set wants them. A create
+ * writes every input. An update or replace writes the keys `detailedDiff`
+ * and `diffReasons` name, and every input whose new value holds an unknown.
+ * `replaceReasons` and a `detailedDiff` kind ending in `-replace` mark
+ * `forcesReplacement`. An input that holds Pulumi's unknown sentinel is
+ * `unknown: true` with no `after`: a resource that reads an output of one
+ * being created shows its dependent input as unknown. A value that holds a
+ * secret is `sensitive: true` with neither side.
+ *
+ * ## What preview cannot list: `mayAppear`
+ *
+ * A program may register resources inside an `apply()`. At preview an
+ * `apply()` whose input is unknown does not run, so what it would register
+ * is never in the steps. Dropping it would make the set look smaller than
+ * the apply, so the adapter marks it `mayAppear` instead, on two signals:
+ *
+ * 1. A component (a step whose state is `custom: false`, not the root stack)
+ *    whose subtree in the preview holds an unknown, in any input or output,
+ *    or a create or replace, whose outputs are unknown until apply. Its code
+ *    may be waiting on that value to register children. It gets one entry
+ *    at `pulumiMayAppearAddress(<component urn>)`, action `create`, type
+ *    `unknown`, no attributes, on the component's node.
+ * 2. With the last deployment's `pulumi stack export` (`prior`): a resource
+ *    the export holds and the preview has no step for gets an `update`
+ *    entry with disruption `unknown`, since a full preview lists every
+ *    registered resource and only an `apply()` that did not run leaves one
+ *    out. A `delete` step for a resource under a component signal 1 marks
+ *    keeps its `delete` and gets `mayAppear`, since the `apply()` may
+ *    register it again. A preview narrowed with `--target` (`targeted`)
+ *    lists only its targets, and a failed one stops part way, so signal 2's
+ *    first half is off for both.
+ *
+ * A resource registered inside an `apply()` directly under the stack, with
+ * no export that holds it, has no component to stand under and is not
+ * detected. When the export does hold it and its input is unknown, the
+ * preview prints a `delete` for it, which reads as a plain delete. Those are
+ * the two cases left out.
+ *
+ * ## The digest
+ *
+ * {@link pulumiPreviewDigest}: `computePlanDigest("pulumi-preview", …)` over
+ * each step's op, URN, provider, id, inputs before and after, `diffReasons`,
+ * `replaceReasons` and `detailedDiff`, sorted by URN and op. It leaves out
+ * `config`, `duration`, `diagnostics` and `changeSummary`, and the states'
+ * outputs, which at preview are the last deployment's or unknown.
+ *
+ * The fixtures under `testdata/pulumi-preview` are recorded from pulumi
+ * 3.272.0 against the plunge corpus's aws-ts program on floci (#4475). What
+ * the recording showed: `preview --json` lists no unchanged resource unless
+ * `--show-sames` is passed, which chant's argv does, since signal 2 reads a
+ * missing resource as one an `apply()` may register; a replace is one
+ * `replace` step at preview, not three; the stack's step carries no planned
+ * outputs; a secret is the blinded string `"[secret]"`; and a resource
+ * registered inside an `apply()` directly under the stack whose input is
+ * unknown (the corpus's `vpc-id` parameter, named after a VPC being
+ * replaced) is printed as a `delete`, which this adapter keeps as a plain
+ * delete since nothing tells it apart from a removed resource.
+ *
+ * ## The import graph
+ *
+ * Like the terraform lexicon's `change-set`, this imports chant's
+ * `change-set` types, `lifecycle/plan-digest`, `pulumi-urn` and `./values`,
+ * so it bundles without TypeScript, node's process modules or zod (#3421).
+ */
+import { computePlanDigest } from "@intentius/chant/lifecycle/plan-digest";
+import { isPulumiNodeless, parsePulumiUrn, pulumiMayAppearAddress, PULUMI_STACK_TYPE } from "@intentius/chant/pulumi-urn";
+import { holdsSecret, holdsUnknown, isObject, isUnknown, propertyKeys, topLevelKey } from "./values.js";
+/** The steps of a preview or refresh document, or undefined when it has none. */
+export function pulumiSteps(doc) {
+    if (!isObject(doc) || !Array.isArray(doc.steps))
+        return undefined;
+    return doc.steps.filter((s) => isObject(s) && typeof s.urn === "string");
+}
+/** The resources of a `pulumi stack export` document (`deployment.resources`). Not one: an empty list. */
+export function pulumiExportResources(doc) {
+    const deployment = isObject(doc) && isObject(doc.deployment) ? doc.deployment : undefined;
+    const list = deployment && Array.isArray(deployment.resources) ? deployment.resources : [];
+    return list.filter((r) => isObject(r) && typeof r.urn === "string" && typeof r.type === "string");
+}
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * The member's plan digest: `computePlanDigest("pulumi-preview", …)` over
+ * what each step proposes, sorted by URN and op, so two renderings of one
+ * preview agree. See the module comment for what it leaves out.
+ */
+export function pulumiPreviewDigest(preview) {
+    const steps = (pulumiSteps(preview) ?? [])
+        .map((s) => ({
+        op: s.op ?? null,
+        urn: s.urn ?? null,
+        provider: s.provider ?? null,
+        id: s.newState?.id ?? s.oldState?.id ?? null,
+        before: s.oldState?.inputs ?? null,
+        after: s.newState?.inputs ?? null,
+        diffReasons: [...(s.diffReasons ?? [])].sort(),
+        replaceReasons: [...(s.replaceReasons ?? [])].sort(),
+        detailedDiff: s.detailedDiff ?? null,
+    }))
+        .sort((a, b) => byString(`${a.urn}\u0000${a.op}`, `${b.urn}\u0000${b.op}`));
+    return computePlanDigest("pulumi-preview", steps);
+}
+const REPLACE_OPS = new Set(["replace", "create-replacement", "delete-replaced"]);
+/** The action and disruption one URN's steps mean, or undefined for an op the change set has no action for. */
+function actionOf(steps) {
+    const ops = steps.map((s) => s.op ?? "");
+    if (ops.includes("import-replacement"))
+        return { action: "replace", disruption: "replace", importing: true };
+    if (ops.some((o) => REPLACE_OPS.has(o))) {
+        const del = ops.indexOf("delete-replaced");
+        const create = ops.indexOf("create-replacement");
+        return { action: "replace", disruption: del >= 0 && create >= 0 && del < create ? "destroy" : "replace" };
+    }
+    if (ops.length !== 1)
+        return undefined;
+    switch (ops[0]) {
+        case "create": return { action: "create" };
+        case "update": return { action: "update", disruption: "in-place" };
+        case "delete": return { action: "delete", disruption: "destroy" };
+        case "same": return { action: "no-op" };
+        case "read":
+        case "read-replacement":
+        case "refresh": return { action: "read" };
+        case "import": return { action: "no-op", importing: true };
+        case "discard":
+        case "remove-pending-replace": return { action: "forget" };
+        default: return undefined;
+    }
+}
+/** The state before and after across one URN's steps: the first old state and the last new one. */
+function statesOf(steps) {
+    const before = steps.find((s) => isObject(s.oldState))?.oldState;
+    const after = [...steps].reverse().find((s) => isObject(s.newState) && s.op !== "delete-replaced" && s.op !== "delete")?.newState;
+    return { ...(before ? { before } : {}), ...(after ? { after } : {}) };
+}
+function attributesOf(steps, action, states) {
+    if (action !== "create" && action !== "update" && action !== "replace")
+        return [];
+    const before = isObject(states.before?.inputs) ? states.before.inputs : {};
+    const after = isObject(states.after?.inputs) ? states.after.inputs : {};
+    const forcing = new Set();
+    const named = new Set();
+    for (const s of steps) {
+        for (const k of s.replaceReasons ?? [])
+            forcing.add(topLevelKey(k));
+        for (const k of s.diffReasons ?? [])
+            named.add(topLevelKey(k));
+        for (const [path, d] of Object.entries(s.detailedDiff ?? {})) {
+            named.add(topLevelKey(path));
+            if (typeof d?.kind === "string" && d.kind.endsWith("-replace"))
+                forcing.add(topLevelKey(path));
+        }
+    }
+    const keys = action === "create"
+        ? propertyKeys(after)
+        : [...new Set([...named, ...propertyKeys(after).filter((k) => holdsUnknown(after[k]))])].filter((k) => !k.startsWith("__"));
+    const beforeOut = isObject(states.before?.outputs) ? states.before.outputs : {};
+    const afterOut = isObject(states.after?.outputs) ? states.after.outputs : {};
+    const present = (v) => v !== undefined && v !== null;
+    const out = [];
+    for (const k of keys.sort()) {
+        let b = before[k];
+        let a = after[k];
+        let unknown = holdsUnknown(a);
+        // On an update a key the diff names is listed even when both sides read the same: the provider said it changes.
+        if (action === "create" && !present(a) && !unknown)
+            continue;
+        // A key the diff names with no input on either side is an output the provider computes (an SSM parameter's
+        // `version`, recorded, #4475): before is the last deployment's output, after the planned output, which a
+        // preview leaves empty when the value is known only after apply.
+        if (action !== "create" && !present(b) && !present(a) && !unknown && named.has(k)) {
+            b = beforeOut[k];
+            a = afterOut[k];
+            unknown = !present(a) || holdsUnknown(a);
+        }
+        const hasBefore = action !== "create" && present(b);
+        const hasAfter = present(a);
+        const sensitive = holdsSecret(b) || holdsSecret(a);
+        out.push({
+            path: k,
+            ...(sensitive
+                ? { sensitive: true }
+                : {
+                    ...(hasBefore ? { before: b } : {}),
+                    ...(hasAfter && !unknown ? { after: a } : {}),
+                }),
+            ...(unknown ? { unknown: true } : {}),
+            ...(forcing.has(k) ? { forcesReplacement: true } : {}),
+        });
+    }
+    return out;
+}
+const knownId = (id) => (typeof id === "string" && id !== "" && !isUnknown(id) ? id : undefined);
+/**
+ * A Pulumi member's part, from its `pulumi preview --json`. Throws when the
+ * document has no `steps` and no `error` says why.
+ */
+export function pulumiPreviewPart(input) {
+    const steps = pulumiSteps(input.preview);
+    if (steps === undefined && input.error === undefined)
+        throw new Error('not a pulumi preview --json document: no top-level "steps"');
+    const scope = input.stack ? { scope: input.stack } : {};
+    const base = { member: input.member, lexicon: "pulumi", planner: "pulumi" };
+    // One URN's steps, in the order the preview printed them.
+    const byUrn = new Map();
+    for (const s of steps ?? []) {
+        const list = byUrn.get(s.urn) ?? [];
+        list.push(s);
+        byUrn.set(s.urn, list);
+    }
+    const entries = [];
+    const holes = [];
+    const actions = new Map();
+    const states = new Map();
+    for (const [urn, list] of byUrn) {
+        const parsed = parsePulumiUrn(urn);
+        const st = statesOf(list);
+        states.set(urn, st);
+        const type = st.after?.type ?? st.before?.type ?? parsed?.type ?? "unknown";
+        const mapped = actionOf(list);
+        if (!mapped) {
+            holes.push({ address: urn, type, reason: `pulumi printed ${list.map((s) => s.op ?? "no op").join(", ")} for the URN, which the change set has no action for` });
+            continue;
+        }
+        actions.set(urn, mapped.action);
+        const id = knownId(st.after?.id) ?? knownId(st.before?.id);
+        entries.push({
+            ...base,
+            address: urn,
+            type,
+            ...(parsed ? { name: parsed.name } : {}),
+            ...(id ? { id } : {}),
+            action: mapped.action,
+            ...(mapped.importing ? { importing: true } : {}),
+            ...(mapped.disruption ? { disruption: mapped.disruption } : {}),
+            ...scope,
+            attributes: attributesOf(list, mapped.action, st),
+        });
+    }
+    // Signal 1: components whose subtree waits on a value preview does not know.
+    const parentOf = new Map();
+    for (const [urn, st] of states) {
+        const parent = st.after?.parent ?? st.before?.parent;
+        if (typeof parent === "string")
+            parentOf.set(urn, parent);
+    }
+    const isComponent = (urn) => {
+        const st = states.get(urn);
+        const state = st?.after ?? st?.before;
+        const type = state?.type ?? parsePulumiUrn(urn)?.type ?? "";
+        return state?.custom === false && type !== PULUMI_STACK_TYPE && !isPulumiNodeless(type);
+    };
+    const waits = (urn) => {
+        const action = actions.get(urn);
+        if (action === "create" || action === "replace")
+            return true;
+        const st = states.get(urn);
+        return holdsUnknown(st?.after?.inputs) || holdsUnknown(st?.after?.outputs);
+    };
+    const flagged = new Set();
+    for (const urn of byUrn.keys()) {
+        if (actions.get(urn) === "delete" || !waits(urn))
+            continue;
+        // The resource and every component above it, up to the stack.
+        const seen = new Set();
+        for (let at = urn; at !== undefined && !seen.has(at); at = parentOf.get(at)) {
+            seen.add(at);
+            if (isComponent(at) && actions.get(at) !== "delete")
+                flagged.add(at);
+        }
+    }
+    for (const component of [...flagged].sort()) {
+        entries.push({ ...base, address: pulumiMayAppearAddress(component), type: "unknown", action: "create", mayAppear: true, ...scope, attributes: [] });
+    }
+    const underFlagged = (urn) => {
+        const seen = new Set();
+        for (let at = parentOf.get(urn); at !== undefined && !seen.has(at); at = parentOf.get(at)) {
+            seen.add(at);
+            if (flagged.has(at))
+                return true;
+        }
+        return false;
+    };
+    for (const e of entries) {
+        if (e.action === "delete" && e.mayAppear !== true && underFlagged(e.address))
+            e.mayAppear = true;
+    }
+    // Signal 2: what the last deployment holds and the preview never listed.
+    // A failed preview stopped part way, so what it did not list says nothing.
+    if (input.prior !== undefined && !input.targeted && input.error === undefined) {
+        for (const r of pulumiExportResources(input.prior)) {
+            if (byUrn.has(r.urn) || isPulumiNodeless(r.type))
+                continue;
+            const parsed = parsePulumiUrn(r.urn);
+            const id = knownId(r.id);
+            entries.push({
+                ...base,
+                address: r.urn,
+                type: r.type,
+                ...(parsed ? { name: parsed.name } : {}),
+                ...(id ? { id } : {}),
+                action: "update",
+                disruption: "unknown",
+                mayAppear: true,
+                ...scope,
+                attributes: [],
+            });
+        }
+    }
+    const failed = input.error !== undefined;
+    return {
+        member: {
+            ...base,
+            ...scope,
+            status: failed ? "failed" : "planned",
+            ...(failed ? { error: input.error } : {}),
+            planDigest: failed ? null : pulumiPreviewDigest(input.preview),
+            holes,
+        },
+        entries,
+    };
+}

package/dist/codegen/docs-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=docs-cli.d.ts.map

package/dist/codegen/docs-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-cli.d.ts","sourceRoot":"","sources":["../../src/codegen/docs-cli.ts"],"names":[],"mappings":""}

package/dist/codegen/docs-cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+import { generateDocs } from "./docs.js";
+await generateDocs({ verbose: true });

package/dist/codegen/docs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generate the docs section for the pulumi lexicon (#4468). Authored pages
+ * come from `docs/pages/`; the overview, the rules page and the sidebar are
+ * the pipeline's.
+ */
+export declare function generateDocs(options?: {
+    verbose?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=docs.d.ts.map

package/dist/codegen/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjF"}