@intentius/chant-lexicon-aws 0.58.0 → 0.60.0

package/dist/codegen/enum-overlay.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Curated enum overlay (chant #1497).
+ *
+ * The CloudFormation Registry spec declares `enum` on some properties and not
+ * on others, and the split does not follow how often a property is written:
+ * `AWS::SageMaker::NotebookInstance.InstanceType` is a union while
+ * `AWS::EC2::Instance.InstanceType` is a bare `string`. Where the spec is
+ * silent the generated type stops teaching the API, and a wrong value survives
+ * `tsc` and `chant build` to fail at deploy.
+ *
+ * This overlay is a checked-in list of `(CFN type, JSON pointer, values)`
+ * entries merged into the raw schema before parsing, so a curated enum reaches
+ * the generated `.d.ts` and the lexicon registry by exactly the path a spec
+ * enum reaches them. Nothing here is fetched at build time: the values live in
+ * `enum-overlay.json` beside this file, each with the source it was read from
+ * and the date it was read, so `scripts/refresh-enum-overlay.ts` can diff them
+ * later.
+ *
+ * Precedence: the overlay only fills gaps. An entry whose target already
+ * declares `enum` (from the Registry spec or from a cfn-lint patch) leaves the
+ * spec alone and reports itself as redundant. Upstream is refreshed on every
+ * `generate`, so it is the source that keeps tracking AWS; a hand list allowed
+ * to win would rot invisibly and would make the generated type depend on which
+ * of two sources happened to be newer. Reporting the overlap instead surfaces
+ * the entry for retirement the moment upstream catches up.
+ *
+ * An entry that matches nothing is an error, not a shrug: a renamed or removed
+ * property means the curated values are being applied to a property that no
+ * longer exists, and silence there is how an overlay goes stale.
+ */
+/** Where an entry's values were read from, and enough detail to read them again. */
+export type EnumOverlaySource = {
+    kind: "botocore";
+    /** Directory under `botocore/data`, e.g. `elbv2`. */
+    service: string;
+    /** API version directory, e.g. `2015-12-01`. */
+    apiVersion: string;
+    /** Shape name carrying the `enum`, e.g. `ProtocolEnum`. */
+    shape: string;
+} | {
+    kind: "docs";
+    /** Page the values were transcribed from. */
+    url: string;
+};
+/** One curated enum. */
+export interface EnumOverlayEntry {
+    /** CloudFormation type name, e.g. `AWS::EC2::Instance`. */
+    type: string;
+    /**
+     * JSON pointer to the property inside that type's Registry schema, either
+     * `/properties/<Name>` or `/definitions/<Def>/properties/<Name>`.
+     */
+    pointer: string;
+    /**
+     * Name for the `definitions` entry this creates. The generator turns it into
+     * an exported type named `<class>_<enumName>`, e.g. `Function_Runtime`.
+     */
+    enumName: string;
+    /** Why this property earned a place in the first curated set. */
+    note: string;
+    source: EnumOverlaySource;
+    /** ISO date the values were last read from `source`. */
+    reviewed: string;
+    values: string[];
+}
+/** What happened to one entry during a generation run. */
+export interface EnumOverlayApplication {
+    entry: EnumOverlayEntry;
+    /**
+     * `applied` narrowed the property; `redundant` left an upstream enum in
+     * place; `absent` means the schema in hand does not declare the property,
+     * which only a non-strict (fixture) run tolerates.
+     */
+    outcome: "applied" | "redundant" | "absent";
+    /** For `redundant`, the values upstream already declared. */
+    upstreamValues?: string[];
+}
+/** The curated entries, in file order. */
+export declare function enumOverlayEntries(): EnumOverlayEntry[];
+/** Entries grouped by CloudFormation type name. */
+export declare function enumOverlayByType(entries?: EnumOverlayEntry[]): Map<string, EnumOverlayEntry[]>;
+/**
+ * Apply the entries for one CloudFormation type to its raw schema bytes.
+ *
+ * Returns the (possibly rewritten) schema and one {@link EnumOverlayApplication}
+ * per entry. Throws when an entry cannot be honoured, which is always a
+ * curation bug rather than a spec quirk.
+ *
+ * `strict` is on for a run over the real schema zip and off for a run over the
+ * trimmed fixtures under `src/testdata/schemas`, which legitimately drop
+ * properties the overlay names. Only a strict run treats a missing property as
+ * an error.
+ */
+export declare function applyEnumOverlay(typeName: string, data: Buffer | string, entries: EnumOverlayEntry[], opts?: {
+    strict?: boolean;
+}): {
+    data: Buffer | string;
+    applications: EnumOverlayApplication[];
+};
+/**
+ * Fail on any entry the run never reached.
+ *
+ * `strict` is on for a run over the real schema zip and off for a run over a
+ * fixture subset, where most types are legitimately absent. A missing type in
+ * a full run means the resource left the Registry and the entry is dead.
+ */
+export declare function assertOverlayCoverage(entries: EnumOverlayEntry[], seenTypes: Set<string>, strict: boolean): void;
+/** One warning line per entry upstream has caught up with. */
+export declare function redundantOverlayWarnings(applications: EnumOverlayApplication[]): Array<{
+    file: string;
+    error: string;
+}>;
+//# sourceMappingURL=enum-overlay.d.ts.map

package/dist/codegen/enum-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-overlay.d.ts","sourceRoot":"","sources":["../../src/codegen/enum-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,oFAAoF;AACpF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEN,wBAAwB;AACxB,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;OAIG;IACH,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC5C,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,0CAA0C;AAC1C,wBAAgB,kBAAkB,IAAI,gBAAgB,EAAE,CAEvD;AAED,mDAAmD;AACnD,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,gBAAgB,EAAyB,GACjD,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAQjC;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B;IAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,YAAY,EAAE,sBAAsB,EAAE,CAAA;CAAE,CAiEnE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,MAAM,EAAE,OAAO,GACd,IAAI,CAUN;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,sBAAsB,EAAE,GACrC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAUxC"}