@intentius/chant 0.41.20 → 0.44.1

package/dist/terraform/parse.d.ts

@@ -8,8 +8,14 @@
  * advisor fails with a one-line install hint.
  */
 import type { Hcl2JsonTree, TfGraph } from "./types.js";
-/** Minimal shape of the parser export we depend on. */
-type Hcl2JsonParse = (filename: string, hcl: string) => Promise<Hcl2JsonTree>;
+/** 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);
 }
@@ -17,7 +23,7 @@ export declare class Hcl2JsonNotInstalled extends Error {
  * 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<Hcl2JsonParse>;
+export declare function loadHcl2json(): Promise<Hcl2Json>;
 export interface ParseTerraformOptions {
     /** Opt-in `.tfstate` path (#214 T2): overlays state-expanded instance counts. */
     statePath?: string;
@@ -29,5 +35,4 @@ export interface ParseTerraformOptions {
  * instance counts become accurate (see `state.ts`).
  */
 export declare function parseTerraformDir(dir: string, opts?: ParseTerraformOptions): Promise<TfGraph>;
-export {};
 //# sourceMappingURL=parse.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/terraform/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,uDAAuD;AACvD,KAAK,aAAa,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE9E,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,KAAK,EAAE,OAAO;CAQ3B;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAO3D;AAuBD,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAWvG"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/terraform/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAErD,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;gBACjC,KAAK,EAAE,OAAO;CAQ3B;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,QAAQ,CAAC,CAMtD;AA+CD,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAWvG"}

package/dist/terraform/tier-map.d.ts

@@ -29,9 +29,10 @@ export declare const TIER_MAP: Record<string, TierInfo>;
  */
 export declare const FOLDS_INTO: Record<string, string>;
 /**
- * The HCL attribute carrying a resource's physical name, per type — derived
- * from the AWS carve-out table. Used for the graph's identity and the
- * live-import hint. Absent → fall back to the TF logical name.
+ * The HCL attribute carrying a resource's physical name, per type — AWS entries
+ * derived from the carve-out table, non-AWS listed directly. A dotted entry is
+ * a path into nested blocks (`manifest.metadata.name`). Used for the graph's
+ * identity and the live-import hint. Absent → fall back to the TF logical name.
  */
 export declare const IDENTITY_ATTR: Record<string, string>;
 export declare function resolveTier(tfType: string): TierInfo | null;

package/dist/terraform/tier-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tier-map.d.ts","sourceRoot":"","sources":["../../src/terraform/tier-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAK7C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO7C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAEhD,CAAC;AAEF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D"}
+{"version":3,"file":"tier-map.d.ts","sourceRoot":"","sources":["../../src/terraform/tier-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AA0CD,sEAAsE;AACtE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAK7C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiB7C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGhD,CAAC;AAEF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAE3D"}

package/dist/terraform/types.d.ts

@@ -46,6 +46,13 @@ export interface TfEdge {
     to: string;
     /** The attribute path(s) referenced, e.g. `["id", "arn"]`. */
     attrs: string[];
+    /**
+     * The referring block's own top-level attribute(s) the reference sits in,
+     * e.g. `["vpc_id"]` for a subnet reading its VPC (#998). This is what a
+     * deferred outbound input is named after when emit turns it into a build
+     * parameter. Empty when the reference came from a non-object block shape.
+     */
+    via: string[];
 }
 export interface TfGraph {
     nodes: TfNode[];

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/terraform/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,MAAM;IACrB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/terraform/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,MAAM;IACrB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC5B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;OAKG;IACH,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB"}

package/dist/terraform/unified-diff.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal unified-diff generator for the carve bridge patch (#998). Emits
+ * git-applyable hunks (`git apply`, or plain `patch -p1`) so the whole survivor
+ * edit — data sources plus rewired references — lands in one reviewable file.
+ * LCS-based; bridge inputs are hand-sized `.tf` files, so O(n·m) is fine.
+ */
+/** One file's diff, `a/<path>` → `b/<path>`, with git headers. Empty when unchanged. */
+export declare function unifiedDiff(path: string, oldText: string, newText: string, context?: number): string;
+/** A new-file diff (`/dev/null` → `b/<path>`), git-applyable. */
+export declare function newFileDiff(path: string, text: string): string;
+//# sourceMappingURL=unified-diff.d.ts.map

package/dist/terraform/unified-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-diff.d.ts","sourceRoot":"","sources":["../../src/terraform/unified-diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wFAAwF;AACxF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,MAAM,CA0B/F;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAa9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.41.20",
+  "version": "0.44.1",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/__snapshots__/okf.test.ts.snap

@@ -0,0 +1,381 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`buildOkfBundle over shipped examples > aws lambda-s3 emits a conformant, snapshot-stable bundle 1`] = `
+[
+  {
+    "content": "---
+type: AWS::S3::Bucket
+title: appBucket
+description: aws resource of type AWS::S3::Bucket
+name: appBucket
+lexicon: aws
+kind: resource
+source: main.ts
+composite: LambdaS3
+composite_instance: app
+---
+Declared in \`main.ts\`.
+
+## Referenced by
+
+- [appFunc](/aws/appFunc.md)
+- [appRole](/aws/appRole.md)
+",
+    "path": "aws/appBucket.md",
+  },
+  {
+    "content": "---
+type: AWS::Lambda::Function
+title: appFunc
+description: aws resource of type AWS::Lambda::Function
+name: appFunc
+lexicon: aws
+kind: resource
+source: main.ts
+composite: LambdaS3
+composite_instance: app
+---
+Declared in \`main.ts\`.
+
+## Depends on
+
+- [appBucket](/aws/appBucket.md)
+- [appRole](/aws/appRole.md)
+",
+    "path": "aws/appFunc.md",
+  },
+  {
+    "content": "---
+type: AWS::IAM::Role
+title: appRole
+description: aws resource of type AWS::IAM::Role
+name: appRole
+lexicon: aws
+kind: resource
+source: main.ts
+composite: LambdaS3
+composite_instance: app
+---
+Declared in \`main.ts\`.
+
+## Depends on
+
+- [appBucket](/aws/appBucket.md)
+
+## Referenced by
+
+- [appFunc](/aws/appFunc.md)
+",
+    "path": "aws/appRole.md",
+  },
+  {
+    "content": "---
+type: Output
+title: bucketArn
+description: aws output of type Output
+name: bucketArn
+lexicon: aws
+kind: output
+source: outputs.ts
+---
+Declared in \`outputs.ts\`.
+",
+    "path": "aws/bucketArn.md",
+  },
+  {
+    "content": "---
+type: AWS::CloudFormation::Parameter
+title: environment
+description: aws resource of type AWS::CloudFormation::Parameter
+name: environment
+lexicon: aws
+kind: resource
+source: params.ts
+---
+Declared in \`params.ts\`.
+",
+    "path": "aws/environment.md",
+  },
+  {
+    "content": "---
+type: chant:aws:defaultTags
+title: tags
+description: aws resource of type chant:aws:defaultTags
+name: tags
+lexicon: aws
+kind: resource
+source: tags.ts
+---
+Declared in \`tags.ts\`.
+",
+    "path": "aws/tags.md",
+  },
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Lexicon: aws
+
+* [appBucket](/aws/appBucket.md) - aws resource of type AWS::S3::Bucket
+* [appFunc](/aws/appFunc.md) - aws resource of type AWS::Lambda::Function
+* [appRole](/aws/appRole.md) - aws resource of type AWS::IAM::Role
+* [bucketArn](/aws/bucketArn.md) - aws output of type Output
+* [environment](/aws/environment.md) - aws resource of type AWS::CloudFormation::Parameter
+* [tags](/aws/tags.md) - aws resource of type chant:aws:defaultTags
+",
+    "path": "index.md",
+  },
+]
+`;
+
+exports[`buildOkfBundle over shipped examples > gitlab node-pipeline emits a conformant, snapshot-stable bundle 1`] = `
+[
+  {
+    "content": "---
+type: GitLab::CI::Job
+title: appBuild
+description: gitlab resource of type GitLab::CI::Job
+name: appBuild
+lexicon: gitlab
+kind: resource
+source: pipeline.ts
+composite: NodePipeline
+composite_instance: app
+---
+Declared in \`pipeline.ts\`.
+",
+    "path": "gitlab/appBuild.md",
+  },
+  {
+    "content": "---
+type: GitLab::CI::Default
+title: appDefaults
+description: gitlab resource of type GitLab::CI::Default
+name: appDefaults
+lexicon: gitlab
+kind: resource
+source: pipeline.ts
+composite: NodePipeline
+composite_instance: app
+---
+Declared in \`pipeline.ts\`.
+",
+    "path": "gitlab/appDefaults.md",
+  },
+  {
+    "content": "---
+type: GitLab::CI::Job
+title: appTest
+description: gitlab resource of type GitLab::CI::Job
+name: appTest
+lexicon: gitlab
+kind: resource
+source: pipeline.ts
+composite: NodePipeline
+composite_instance: app
+---
+Declared in \`pipeline.ts\`.
+",
+    "path": "gitlab/appTest.md",
+  },
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Lexicon: gitlab
+
+* [appBuild](/gitlab/appBuild.md) - gitlab resource of type GitLab::CI::Job
+* [appDefaults](/gitlab/appDefaults.md) - gitlab resource of type GitLab::CI::Default
+* [appTest](/gitlab/appTest.md) - gitlab resource of type GitLab::CI::Job
+",
+    "path": "index.md",
+  },
+]
+`;
+
+exports[`buildOkfBundle over shipped examples > k8s layered-config emits a conformant, snapshot-stable bundle 1`] = `
+[
+  {
+    "content": "---
+okf_version: '0.2'
+---
+
+# Lexicon: k8s
+
+* [devAppDeployment](/k8s/devAppDeployment.md) - k8s resource of type K8s::Apps::Deployment
+* [devAppService](/k8s/devAppService.md) - k8s resource of type K8s::Core::Service
+* [prodAppDeployment](/k8s/prodAppDeployment.md) - k8s resource of type K8s::Apps::Deployment
+* [prodAppIngress](/k8s/prodAppIngress.md) - k8s resource of type K8s::Networking::Ingress
+* [prodAppPdb](/k8s/prodAppPdb.md) - k8s resource of type K8s::Policy::PodDisruptionBudget
+* [prodAppService](/k8s/prodAppService.md) - k8s resource of type K8s::Core::Service
+* [stagingAppDeployment](/k8s/stagingAppDeployment.md) - k8s resource of type K8s::Apps::Deployment
+* [stagingAppIngress](/k8s/stagingAppIngress.md) - k8s resource of type K8s::Networking::Ingress
+* [stagingAppPdb](/k8s/stagingAppPdb.md) - k8s resource of type K8s::Policy::PodDisruptionBudget
+* [stagingAppService](/k8s/stagingAppService.md) - k8s resource of type K8s::Core::Service
+",
+    "path": "index.md",
+  },
+  {
+    "content": "---
+type: K8s::Apps::Deployment
+title: devAppDeployment
+description: k8s resource of type K8s::Apps::Deployment
+name: devAppDeployment
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: devApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/devAppDeployment.md",
+  },
+  {
+    "content": "---
+type: K8s::Core::Service
+title: devAppService
+description: k8s resource of type K8s::Core::Service
+name: devAppService
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: devApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/devAppService.md",
+  },
+  {
+    "content": "---
+type: K8s::Apps::Deployment
+title: prodAppDeployment
+description: k8s resource of type K8s::Apps::Deployment
+name: prodAppDeployment
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppDeployment.md",
+  },
+  {
+    "content": "---
+type: K8s::Networking::Ingress
+title: prodAppIngress
+description: k8s resource of type K8s::Networking::Ingress
+name: prodAppIngress
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppIngress.md",
+  },
+  {
+    "content": "---
+type: K8s::Policy::PodDisruptionBudget
+title: prodAppPdb
+description: k8s resource of type K8s::Policy::PodDisruptionBudget
+name: prodAppPdb
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppPdb.md",
+  },
+  {
+    "content": "---
+type: K8s::Core::Service
+title: prodAppService
+description: k8s resource of type K8s::Core::Service
+name: prodAppService
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: prodApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/prodAppService.md",
+  },
+  {
+    "content": "---
+type: K8s::Apps::Deployment
+title: stagingAppDeployment
+description: k8s resource of type K8s::Apps::Deployment
+name: stagingAppDeployment
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppDeployment.md",
+  },
+  {
+    "content": "---
+type: K8s::Networking::Ingress
+title: stagingAppIngress
+description: k8s resource of type K8s::Networking::Ingress
+name: stagingAppIngress
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppIngress.md",
+  },
+  {
+    "content": "---
+type: K8s::Policy::PodDisruptionBudget
+title: stagingAppPdb
+description: k8s resource of type K8s::Policy::PodDisruptionBudget
+name: stagingAppPdb
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppPdb.md",
+  },
+  {
+    "content": "---
+type: K8s::Core::Service
+title: stagingAppService
+description: k8s resource of type K8s::Core::Service
+name: stagingAppService
+lexicon: k8s
+kind: resource
+source: web.ts
+composite: WebApp
+composite_instance: stagingApp
+---
+Declared in \`web.ts\`.
+",
+    "path": "k8s/stagingAppService.md",
+  },
+]
+`;

package/src/audit/rules-doc.ts

@@ -14,7 +14,7 @@ const GROUPS: Array<{ heading: string; prefixes: string[]; blurb: string }> = [
   { heading: "GitHub Actions (GHA)", prefixes: ["GHA"], blurb: "Also applied to Forgejo workflows, which are GitHub-dialect." },
   { heading: "GitLab CI (WGL)", prefixes: ["WGL"], blurb: "" },
   { heading: "Forgejo (WFJ)", prefixes: ["WFJ"], blurb: "" },
-  { heading: "Kubernetes (WK8 / ARGO)", prefixes: ["WK8", "ARGO"], blurb: "Run against Kubernetes manifests." },
+  { heading: "Kubernetes (WK8 / ARGO / FLUX)", prefixes: ["WK8", "ARGO", "FLUX"], blurb: "Run against Kubernetes manifests." },
   { heading: "Docker (DKRD)", prefixes: ["DKRD"], blurb: "Run against Dockerfiles and Compose files." },
   { heading: "AWS CloudFormation (WAW / COR / EXT)", prefixes: ["WAW", "COR", "EXT"], blurb: "Run against CloudFormation templates (JSON or YAML)." },
   { heading: "Azure ARM (AZR)", prefixes: ["AZR"], blurb: "Run against ARM deployment templates (JSON)." },

package/src/build.test.ts

@@ -257,6 +257,101 @@ export const testEntity = {
   });
 });
 
+describe("build-root contributors (#1548 piece 3)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-buildroots-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  const entity = (entityType: string): Declarable =>
+    ({
+      lexicon: "test",
+      entityType,
+      kind: "resource",
+      props: {},
+      [DECLARABLE_MARKER]: true,
+    }) as unknown as Declarable;
+
+  const recordingSerializer = (seen: string[][]): Serializer => ({
+    name: "test",
+    rulePrefix: "TEST",
+    serialize: (entities) => {
+      seen.push([...entities.keys()]);
+      return "out";
+    },
+  });
+
+  test("contributed entities join the entity set and reach the serializer", async () => {
+    const seen: string[][] = [];
+    const result = await build(testDir, [recordingSerializer(seen)], undefined, {
+      buildRoots: [
+        async () => ({
+          entities: new Map([["overlays/prod/deploymentApp", entity("TestEntity")]]),
+          warnings: ["rendered a stray doc"],
+        }),
+      ],
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.entities.has("overlays/prod/deploymentApp")).toBe(true);
+    expect(seen).toEqual([["overlays/prod/deploymentApp"]]);
+    expect(result.warnings).toContain("rendered a stray doc");
+  });
+
+  test("a contributor that throws becomes a build error carrying its message, not a thrown stack", async () => {
+    const result = await build(testDir, [], undefined, {
+      buildRoots: [
+        async () => {
+          throw new Error("neither the `kustomize` binary nor `kubectl` was found on PATH");
+        },
+      ],
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].message).toContain("neither the `kustomize` binary nor `kubectl`");
+  });
+
+  test("a contributed name colliding with a discovered entity is a build error, never an overwrite", async () => {
+    await writeFile(
+      join(testDir, "app.infra.ts"),
+      `
+export const discovered = {
+  lexicon: "test",
+  entityType: "Discovered",
+  props: {},
+  [Symbol.for("chant.declarable")]: true,
+};
+      `,
+    );
+
+    const result = await build(testDir, [recordingSerializer([])], undefined, {
+      buildRoots: [async () => ({ entities: new Map([["discovered", entity("Contributed")]]) })],
+    });
+
+    expect(result.errors.some((e) => e.message.includes('"discovered" collides'))).toBe(true);
+    expect(result.entities.get("discovered")?.entityType).toBe("Discovered");
+  });
+
+  test("contributors run exactly once per build", async () => {
+    let calls = 0;
+    await build(testDir, [], undefined, {
+      buildRoots: [
+        async () => {
+          calls++;
+          return { entities: new Map() };
+        },
+      ],
+    });
+    expect(calls).toBe(1);
+  });
+});
+
 describe("partitionByLexicon", () => {
   test("partitions entities by lexicon", () => {
     const entities = new Map<string, Declarable>([

package/src/build.ts

@@ -2,7 +2,7 @@ import type { Declarable } from "./declarable";
 import type { Serializer, SerializerResult } from "./serializer";
 import type { OwnershipMarker } from "./ownership";
 import type { BuildError, DiscoveryErrorType } from "./errors";
-import type { IntrinsicDef } from "./lexicon";
+import type { IntrinsicDef, BuildRootContribution } from "./lexicon";
 import type { BuildParamProvenance } from "./provenance";
 import { DiscoveryError, BuildError as BuildErrorClass } from "./errors";
 import { LexiconOutput, isLexiconOutput } from "./lexicon-output";
@@ -215,6 +215,21 @@ export interface BuildOptions {
    * carries the already-resolved records for provenance.
    */
   buildParams?: BuildParamProvenance[];
+
+  /**
+   * chant #1548 piece 3 — lexicon-contributed build roots: closures the CLI
+   * binds from each configured plugin's `buildRoots(ctx)` hook (see
+   * `collectBuildRootContributors` in ./cli/plugins.ts), each rendering a
+   * non-chant-source root (a kustomize overlay dir) into entities. Run once,
+   * at the TOP-LEVEL build only (never repeated for nested child projects),
+   * after discovery and before partitioning — so contributed entities are
+   * serialized, ownership-stamped, post-synth-checked and observed exactly
+   * like discovered ones. A contributor that throws becomes a build error
+   * carrying its message (the k8s hook's missing-binary refusal names the
+   * binaries); a contributed name colliding with a discovered entity is a
+   * build error, never a silent overwrite.
+   */
+  buildRoots?: Array<() => Promise<BuildRootContribution>>;
 }
 
 export interface BuildResult {
@@ -657,6 +672,36 @@ async function buildFromDiscoveryResult(
     }
   }
 
+  // Step 4b (#1548 piece 3): lexicon-contributed build roots — rendered
+  // non-source roots (kustomize dirs) joining the entity set before
+  // partitioning, so everything downstream (serialization with ownership
+  // stamping, post-synth checks, observation) treats them as declared.
+  // Top-level build only: nested child builds receive the same options
+  // object, and re-running the contributors there would duplicate every
+  // contributed entity once per child.
+  if (!parentBuildStack && options?.buildRoots) {
+    for (const contribute of options.buildRoots) {
+      try {
+        const contribution = await contribute();
+        for (const w of contribution.warnings ?? []) warnings.push(w);
+        for (const [name, entity] of contribution.entities) {
+          if (discoveryResult.entities.has(name)) {
+            errors.push(
+              new BuildErrorClass(
+                "",
+                `Build-root entity "${name}" collides with a discovered entity of the same name`,
+              ),
+            );
+            continue;
+          }
+          discoveryResult.entities.set(name, entity);
+        }
+      } catch (error) {
+        errors.push(new BuildErrorClass("", error instanceof Error ? error.message : String(error)));
+      }
+    }
+  }
+
   // Step 5: Partition entities by lexicon
   const partitions = partitionByLexicon(discoveryResult.entities);