@intentius/chant-lexicon-github 0.51.0 → 0.52.0

package/dist/composites/index.d.ts

@@ -26,4 +26,6 @@ export { GoCI } from "./go-ci.js";
 export type { GoCIProps } from "./go-ci.js";
 export { Dependabot, DependabotConfig } from "./dependabot.js";
 export type { DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem } from "./dependabot.js";
+export { PrPlanReport } from "./pr-plan-report.js";
+export type { PrPlanReportProps } from "./pr-plan-report.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/composites/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/composites/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/composites/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAClH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/composites/pr-plan-report.d.ts

@@ -0,0 +1,64 @@
+import { Job } from "../generated/index.js";
+export interface PrPlanReportProps {
+    /**
+     * Lifecycle environment to plan against — the `<environment>` argument of
+     * `chant lifecycle plan`.
+     */
+    environment: string;
+    /** Restrict the plan to one lexicon (the optional `[lexicon]` argument). */
+    lexicon?: string;
+    /** Plan against chant-owned resources only (passes `--owned`). */
+    ownedOnly?: boolean;
+    /** Runner label. Default: `"ubuntu-latest"` */
+    runsOn?: string;
+    /** Node.js version for chant's own toolchain. Default: `"22"` */
+    nodeVersion?: string;
+    /** Install command, run after checkout. Default: `"npm ci"` */
+    installCommand?: string;
+    /**
+     * Commands to run before the plan — typically cloud-credential setup, since
+     * the plan queries the live system to classify create/update/delete.
+     */
+    before?: string[];
+    /**
+     * Post the plan as a sticky PR comment. Default: `true` — the point of this
+     * composite is that the compiled diff reaches the reviewer without being
+     * asked for, so the manual step it replaces stops being skippable because
+     * it stops being manual. Set `false` to run the plan without posting —
+     * the explicit opt-out.
+     */
+    postComment?: boolean;
+    /**
+     * Hidden marker that makes the comment findable across pushes. Defaults to
+     * one keyed on `environment`, so a repo planning two environments gets two
+     * comments and each updates in place; override only to share one comment
+     * across environments.
+     */
+    marker?: string;
+    /** Per-member defaults for customizing the generated job. */
+    defaults?: {
+        job?: Partial<ConstructorParameters<typeof Job>[0]>;
+    };
+}
+/**
+ * A CI job that builds, plans, and posts `chant lifecycle plan --report
+ * markdown` as a sticky PR comment (#1983) — the compiled diff reaches the
+ * reviewer without being asked for.
+ *
+ * A sibling of the gitlab lexicon's `MrPlanReport`, but where GitLab renders
+ * a native merge-request widget from a counts artifact, GitHub has no such
+ * widget: the mechanism is the sticky-comment recipe `examples/github-pr-preview`
+ * proved (#1223), reused here rather than reinvented. The forgejo lexicon
+ * inherits this composite through its github re-export, since Forgejo Actions
+ * runs the same workflow shape and the Forgejo API accepts the same `gh api`
+ * calls against its GitHub-compatible surface.
+ *
+ * Only meaningful on a `pull_request`-triggered workflow — the job guards on
+ * `github.event_name` since the comment targets `github.event.number`, which
+ * a push-triggered run does not have. The plan reads the live system, so wire
+ * cloud credentials via `before` or CI variables.
+ */
+export declare const PrPlanReport: import("@intentius/chant").CompositeDefinition<PrPlanReportProps, {
+    job: import("@intentius/chant").Declarable & Record<string, string>;
+}>;
+//# sourceMappingURL=pr-plan-report.d.ts.map

package/dist/composites/pr-plan-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr-plan-report.d.ts","sourceRoot":"","sources":["../../src/composites/pr-plan-report.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAqB,MAAM,oBAAoB,CAAC;AAI5D,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE;QACT,GAAG,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KACrD,CAAC;CACH;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY;;EAkEP,CAAC"}

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export { githubPlugin } from "./plugin.js";
 export { Expression, github, runner, secrets, matrix, steps, needs, inputs, vars, env, always, failure, success, cancelled, contains, startsWith, toJSON, fromJSON, format, branch, tag, } from "./expression.js";
 export { GitHub, Runner } from "./variables.js";
 export * from "./generated/index.js";
-export { Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, BunPipeline, PnpmPipeline, YarnPipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot, DependabotConfig, } from "./composites/index.js";
-export type { CheckoutProps, SetupNodeProps, SetupGoProps, SetupPythonProps, CacheActionProps, UploadArtifactProps, DownloadArtifactProps, NodeCIProps, NodePipelineProps, PythonCIProps, DockerBuildProps, DeployEnvironmentProps, GoCIProps, DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem, } from "./composites/index.js";
+export { Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, BunPipeline, PnpmPipeline, YarnPipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot, DependabotConfig, PrPlanReport, } from "./composites/index.js";
+export type { CheckoutProps, SetupNodeProps, SetupGoProps, SetupPythonProps, CacheActionProps, UploadArtifactProps, DownloadArtifactProps, NodeCIProps, NodePipelineProps, PythonCIProps, DockerBuildProps, DeployEnvironmentProps, GoCIProps, DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem, PrPlanReportProps, } from "./composites/index.js";
 export { fetchWorkflowSchema, fetchSchemas } from "./spec/fetch.js";
 export { parseWorkflowSchema, githubShortName, githubServiceName } from "./codegen/parse.js";
 export type { GitHubParseResult, ParsedResource, ParsedProperty, ParsedPropertyType, ParsedEnum } from "./codegen/parse.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EACL,UAAU,EACV,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAChE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EACnC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAC9C,MAAM,EAAE,GAAG,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI7C,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EACL,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EACzC,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAC7C,MAAM,EACN,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EACrD,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,IAAI,EACJ,UAAU,EAAE,gBAAgB,GAC7B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAC7D,gBAAgB,EAAE,mBAAmB,EAAE,qBAAqB,EAC5D,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,mBAAmB,GAC9E,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGzH,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EACL,UAAU,EACV,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAChE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EACnC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAC9C,MAAM,EAAE,GAAG,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAI7C,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EACL,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EACzC,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAC7C,MAAM,EACN,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EACrD,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,IAAI,EACJ,UAAU,EAAE,gBAAgB,EAC5B,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,aAAa,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAC7D,gBAAgB,EAAE,mBAAmB,EAAE,qBAAqB,EAC5D,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,eAAe,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,mBAAmB,EAC7E,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGzH,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "0176b6c24d0c74fb0a47f195e3bdff6c352773f0851059bd8d04d0d7ee02e86e",
+    "manifest.json": "f34639b85f5e99781f6774eb1855b1988b7da79dbe2f03650e2e1d7af7d64b2c",
     "meta.json": "e891b1214d530fd676172e3f7e0734995b9f839b7659eb2d53f43ffc97dcd21b",
     "types/index.d.ts": "7eab3c62c76bff65d68765609e9b6151844a1f581b0c648d0eda779b4252adaf",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -77,5 +77,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "9076b43c33423ff863fda81cd91ea7c61d17f99a59676c599fa425c5e4ffa2e9"
+  "composite": "d29354b7bf24d3c4017d583c09798d87ace0c5d51ad9cc63573cd8ca3e73958c"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.51.0",
+    "@intentius/chant": "^0.52.0",
     "typescript": "^5.9.3"
   }
 }

package/src/codegen/docs.ts

@@ -25,7 +25,7 @@ npm install --save-dev @intentius/chant-lexicon-github
 
 {{file:docs-snippets/src/quickstart.ts}}
 
-The lexicon provides **3 resources** (Workflow, Job, Dependabot config), **14 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **49 post-synth checks** (including a CI/CD supply-chain security pass, GHA029–062).
+The lexicon provides **3 resources** (Workflow, Job, Dependabot config), **15 composites** (Checkout, SetupNode, SetupGo, SetupPython, CacheAction, UploadArtifact, DownloadArtifact, NodeCI, NodePipeline, PythonCI, DockerBuild, DeployEnvironment, GoCI, Dependabot, PrPlanReport) + **3 presets** (BunPipeline, PnpmPipeline, YarnPipeline), a typed **Expression** system with 24 GitHub and 5 Runner context variables, and **13 lint rules** + **49 post-synth checks** (including a CI/CD supply-chain security pass, GHA029–062).
 `;
 
 const outputFormat = `The GitHub Actions lexicon serializes resources into **\`.github/workflows/*.yml\`** YAML files.

package/src/composites/index.ts

@@ -26,3 +26,5 @@ export { GoCI } from "./go-ci";
 export type { GoCIProps } from "./go-ci";
 export { Dependabot, DependabotConfig } from "./dependabot";
 export type { DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem } from "./dependabot";
+export { PrPlanReport } from "./pr-plan-report";
+export type { PrPlanReportProps } from "./pr-plan-report";

package/src/composites/pr-plan-report.test.ts

@@ -0,0 +1,109 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { PrPlanReport } from "./pr-plan-report";
+import { githubPlugin } from "../plugin";
+import { githubSerializer } from "../serializer";
+import { Workflow } from "../generated/index";
+import type { SerializerResult } from "@intentius/chant/serializer";
+
+/**
+ * `Job`/`Step` (`../generated/index`) come from core's `createResource`/
+ * `createProperty` (`packages/core/src/runtime.ts`), whose constructor type
+ * is `new (...) => Declarable & Record<string, string>` — every property,
+ * `.props` included, reads back as `string` regardless of what was actually
+ * passed in. That is a known, tracked gap (chant #1388's shrinking
+ * typecheck baseline; `composites.test.ts` in this same directory is
+ * grandfathered into it for exactly this reason). This file is new, so
+ * rather than add to that backlog, these two interfaces describe the real
+ * runtime shape for the fields this file asserts on, and `asJob` narrows the
+ * composite's output into it once instead of reading `.props` off the
+ * loosely-typed instance directly.
+ */
+interface StepLike {
+  props: { name?: string; run?: string };
+}
+interface JobLike {
+  props: {
+    "runs-on": string;
+    if?: string;
+    permissions?: unknown;
+    env?: Record<string, string>;
+    steps?: StepLike[];
+  };
+}
+
+function asJob(job: unknown): JobLike {
+  return job as JobLike;
+}
+
+function steps(job: unknown): StepLike[] {
+  return asJob(job).props.steps ?? [];
+}
+
+describe("PrPlanReport composite (#1983)", () => {
+  test("defaults: guarded on pull_request, posts by default, marker keyed on environment", () => {
+    const { job } = PrPlanReport({ environment: "prod" });
+    expect(asJob(job).props["runs-on"]).toBe("ubuntu-latest");
+    expect(asJob(job).props.if).toBe("github.event_name == 'pull_request'");
+    expect(asJob(job).props.permissions).toMatchObject({ props: { contents: "read", "pull-requests": "write" } });
+    expect(asJob(job).props.env?.MARKER).toBe("<!-- chant-pr-plan-report:prod -->");
+    const names = steps(job).map((s) => s.props.name);
+    expect(names).toContain("Post or update PR comment");
+  });
+
+  test("two environments get two distinct markers", () => {
+    const prod = PrPlanReport({ environment: "prod" }).job;
+    const staging = PrPlanReport({ environment: "staging" }).job;
+    expect(asJob(prod).props.env?.MARKER).not.toBe(asJob(staging).props.env?.MARKER);
+  });
+
+  test("postComment: false is the explicit opt-out — no comment step, plan still runs", () => {
+    const { job } = PrPlanReport({ environment: "prod", postComment: false });
+    const names = steps(job).map((s) => s.props.name);
+    expect(names).not.toContain("Post or update PR comment");
+    expect(names.some((n) => n?.startsWith("Plan "))).toBe(true);
+  });
+
+  test("lexicon and --owned reach the plan command", () => {
+    const { job } = PrPlanReport({ environment: "prod", lexicon: "aws", ownedOnly: true });
+    const planStep = steps(job).find((s) => s.props.name === "Plan prod")!;
+    expect(planStep.props.run).toContain("lifecycle plan prod aws --owned --report markdown");
+  });
+
+  test("before commands become their own credential-setup steps, in order, ahead of the plan", () => {
+    const { job } = PrPlanReport({ environment: "prod", before: ["aws sts get-caller-identity", "echo ready"] });
+    const names = steps(job).map((s) => s.props.name);
+    const planIndex = names.indexOf("Plan prod");
+    const credIndexes = names.reduce<number[]>((acc, n, i) => (n === "Live credentials" ? [...acc, i] : acc), []);
+    expect(credIndexes).toHaveLength(2);
+    expect(Math.max(...credIndexes)).toBeLessThan(planIndex);
+  });
+
+  test("the emitted workflow passes the github lexicon's own lint — no errors, pinned actions included", () => {
+    const { job } = PrPlanReport({ environment: "prod", before: ["aws sts get-caller-identity"] });
+    const workflow = new Workflow({
+      name: "pr-plan",
+      on: { pull_request: { types: ["opened", "synchronize", "reopened"] } },
+    });
+    const result = githubSerializer.serialize(
+      new Map<string, unknown>([["workflow", workflow], ["plan", job]]) as never,
+    ) as SerializerResult;
+    const yaml = typeof result === "string" ? result : result.primary!;
+    expect(yaml).toContain("Post or update PR comment");
+
+    const ctx: PostSynthContext = {
+      outputs: new Map([["github", yaml]]),
+      entities: new Map(),
+      buildResult: {
+        outputs: new Map([["github", yaml]]),
+        entities: new Map(),
+        warnings: [],
+        errors: [],
+        sourceFileCount: 1,
+      },
+    };
+    const diagnostics = githubPlugin.postSynthChecks!().flatMap((check) => check.check(ctx));
+    const errors = diagnostics.filter((d) => d.severity === "error");
+    expect(errors).toEqual([]);
+  });
+});

package/src/composites/pr-plan-report.ts

@@ -0,0 +1,150 @@
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Job, Step, Permissions } from "../generated/index";
+import { Checkout } from "./checkout";
+import { SetupNode } from "./setup-node";
+
+export interface PrPlanReportProps {
+  /**
+   * Lifecycle environment to plan against — the `<environment>` argument of
+   * `chant lifecycle plan`.
+   */
+  environment: string;
+  /** Restrict the plan to one lexicon (the optional `[lexicon]` argument). */
+  lexicon?: string;
+  /** Plan against chant-owned resources only (passes `--owned`). */
+  ownedOnly?: boolean;
+  /** Runner label. Default: `"ubuntu-latest"` */
+  runsOn?: string;
+  /** Node.js version for chant's own toolchain. Default: `"22"` */
+  nodeVersion?: string;
+  /** Install command, run after checkout. Default: `"npm ci"` */
+  installCommand?: string;
+  /**
+   * Commands to run before the plan — typically cloud-credential setup, since
+   * the plan queries the live system to classify create/update/delete.
+   */
+  before?: string[];
+  /**
+   * Post the plan as a sticky PR comment. Default: `true` — the point of this
+   * composite is that the compiled diff reaches the reviewer without being
+   * asked for, so the manual step it replaces stops being skippable because
+   * it stops being manual. Set `false` to run the plan without posting —
+   * the explicit opt-out.
+   */
+  postComment?: boolean;
+  /**
+   * Hidden marker that makes the comment findable across pushes. Defaults to
+   * one keyed on `environment`, so a repo planning two environments gets two
+   * comments and each updates in place; override only to share one comment
+   * across environments.
+   */
+  marker?: string;
+  /** Per-member defaults for customizing the generated job. */
+  defaults?: {
+    job?: Partial<ConstructorParameters<typeof Job>[0]>;
+  };
+}
+
+/**
+ * Sticky-comment script (#1223's mechanism, reused as-is): find the comment
+ * whose body starts with `$MARKER`, PATCH it if found, POST otherwise. No
+ * marketplace action, nothing extra to pin — `gh` ships on GitHub's hosted
+ * runners. `-f body=@plan.md` reads the comment body from the file the plan
+ * step wrote, so a large or multi-line plan never has to survive shell
+ * quoting.
+ */
+const stickyCommentScript = [
+  'comment_id=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments" --paginate ' +
+    '--jq "map(select(.body | startswith(\\"$MARKER\\"))) | .[0].id // empty")',
+  'if [ -n "$comment_id" ]; then',
+  '  gh api -X PATCH "repos/$REPO/issues/comments/$comment_id" -f body=@plan.md > /dev/null',
+  "else",
+  '  gh api -X POST "repos/$REPO/issues/$PR_NUMBER/comments" -f body=@plan.md > /dev/null',
+  "fi",
+].join("\n");
+
+/**
+ * A CI job that builds, plans, and posts `chant lifecycle plan --report
+ * markdown` as a sticky PR comment (#1983) — the compiled diff reaches the
+ * reviewer without being asked for.
+ *
+ * A sibling of the gitlab lexicon's `MrPlanReport`, but where GitLab renders
+ * a native merge-request widget from a counts artifact, GitHub has no such
+ * widget: the mechanism is the sticky-comment recipe `examples/github-pr-preview`
+ * proved (#1223), reused here rather than reinvented. The forgejo lexicon
+ * inherits this composite through its github re-export, since Forgejo Actions
+ * runs the same workflow shape and the Forgejo API accepts the same `gh api`
+ * calls against its GitHub-compatible surface.
+ *
+ * Only meaningful on a `pull_request`-triggered workflow — the job guards on
+ * `github.event_name` since the comment targets `github.event.number`, which
+ * a push-triggered run does not have. The plan reads the live system, so wire
+ * cloud credentials via `before` or CI variables.
+ */
+export const PrPlanReport = Composite((props: PrPlanReportProps) => {
+  const {
+    environment,
+    lexicon,
+    ownedOnly = false,
+    runsOn = "ubuntu-latest",
+    nodeVersion = "22",
+    installCommand = "npm ci",
+    before,
+    postComment = true,
+    marker = `<!-- chant-pr-plan-report:${environment} -->`,
+    defaults: defs,
+  } = props;
+
+  const planArgs = [
+    "lifecycle",
+    "plan",
+    environment,
+    ...(lexicon ? [lexicon] : []),
+    ...(ownedOnly ? ["--owned"] : []),
+    "--report",
+    "markdown",
+  ].join(" ");
+
+  const steps = [
+    Checkout({}).step,
+    SetupNode({ nodeVersion, cache: "npm" }).step,
+    new Step({ name: "Install", run: installCommand }),
+    ...(before ?? []).map((cmd) => new Step({ name: "Live credentials", run: cmd })),
+    new Step({ name: "Build", run: "npx chant build" }),
+    new Step({
+      name: `Plan ${environment}`,
+      // The marker (and an "updated for" footer, same spirit as the preview
+      // tutorial's) is prepended to the rendered plan before anything is
+      // posted, so the comment body itself carries the identity the search
+      // step below keys on.
+      run: [
+        `npx chant ${planArgs} > plan-body.md`,
+        '{ printf \'%s\\n\\n\' "$MARKER"; printf \'_Updated for %s._\\n\\n\' "$HEAD_SHA"; cat plan-body.md; } > plan.md',
+      ].join("\n"),
+    }),
+    ...(postComment
+      ? [
+          new Step({
+            name: "Post or update PR comment",
+            env: { GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}" },
+            run: stickyCommentScript,
+          }),
+        ]
+      : []),
+  ];
+
+  const job = new Job(mergeDefaults({
+    "runs-on": runsOn,
+    if: "github.event_name == 'pull_request'",
+    permissions: new Permissions({ contents: "read", "pull-requests": "write" }),
+    env: {
+      MARKER: marker,
+      HEAD_SHA: "${{ github.event.pull_request.head.sha }}",
+      PR_NUMBER: "${{ github.event.number }}",
+      REPO: "${{ github.repository }}",
+    },
+    steps,
+  }, defs?.job));
+
+  return { job };
+}, "PrPlanReport");

package/src/index.ts

@@ -31,6 +31,7 @@ export {
   DeployEnvironment,
   GoCI,
   Dependabot, DependabotConfig,
+  PrPlanReport,
 } from "./composites/index";
 export type {
   CheckoutProps, SetupNodeProps, SetupGoProps, SetupPythonProps,
@@ -42,6 +43,7 @@ export type {
   DeployEnvironmentProps,
   GoCIProps,
   DependabotProps, DependabotConfigProps, DependabotUpdate, DependabotEcosystem,
+  PrPlanReportProps,
 } from "./composites/index";
 
 // Spec utilities (for tooling)