@aws/cloudformation-validate 1.5.0-beta → 1.6.0-beta

package/README.md

@@ -1,31 +1,46 @@
-# CloudFormation Validate WASM Bindings
+# CloudFormation Validate for Node.js
 
-WASM bindings for [`cloudformation-validate`](https://github.com/aws-cloudformation/cloudformation-validate). Compiles
-the full validation pipeline —
-template parser, schema validator, Rego engine, and CEL engine — into a single `.wasm` module for Node.js.
+Validate AWS CloudFormation templates from JavaScript or TypeScript and catch schema violations, security risks, and
+best-practice findings before deployment — in your editor, build, or CI.
 
-All WASM objects must be explicitly freed via `.free()` to release memory.
+- **Offline** — all rules and resource schemas are bundled.
+- **Fast** — sub-second validation per template.
 
-For a complete, runnable example, see
-[examples](https://github.com/aws-cloudformation/cloudformation-validate/tree/main/src/bindings-wasm/examples).
+## Installation
 
-## Engine
+Available on [npm](https://www.npmjs.com/package/@aws/cloudformation-validate) as `@aws/cloudformation-validate`.
 
-`RegoEngine` and `CelEngine` both implement the `Engine` interface. They are interchangeable — both produce identical
-diagnostics for the same template and config.
+```bash
+npm install @aws/cloudformation-validate
+```
+
+## Quick start
+
+Engines, models, and validators hold off-heap memory — call `.free()` when done with each object:
 
 ```typescript
-import { RegoEngine, CelEngine, TemplateFile } from "@aws/cloudformation-validate";
+import { RegoEngine, TemplateFile } from "@aws/cloudformation-validate";
 
 const engine = new RegoEngine();
-const report = engine.validateStandard(new TemplateFile("template.yaml"));
-
-for (const d of report.diagnostics) {
-    console.log(`[${d.severity}] ${d.ruleId}: ${d.message}`);
+try {
+    const report = engine.validateStandard(new TemplateFile("template.yaml"));
+    for (const d of report.diagnostics) {
+        console.log(`[${d.severity}] ${d.ruleId}: ${d.message}`);
+    }
+} finally {
+    engine.free();
 }
-engine.free();
 ```
 
+Each diagnostic identifies the rule, severity, affected resource and property, and source location — see
+[StandardDiagnostic](#standarddiagnostic). A complete, runnable project is in
+[examples](https://github.com/aws-cloudformation/cloudformation-validate/tree/main/src/bindings-wasm/examples).
+
+## Engine
+
+`RegoEngine` and `CelEngine` both implement the `Engine` interface and are interchangeable — they produce identical
+diagnostics for the same template and config.
+
 ### `Engine` interface
 
 | Method                                | Returns          | Description                                                                                                      |
@@ -34,7 +49,7 @@ engine.free();
 | `validateDetailed(template, config?)` | `DetailedReport` | Validates and returns diagnostics with documentation URLs, rule descriptions, phase tags, and `ViolationContext` |
 | `listRules()`                         | `RuleInfo[]`     | Returns metadata for every built-in and loaded custom rule                                                       |
 | `engineName()`                        | `string`         | `"rego"` or `"cel"`                                                                                              |
-| `free()`                              | `void`           | Releases WASM memory                                                                                             |
+| `free()`                              | `void`           | Releases the engine's off-heap memory                                                                            |
 
 ### `EngineConfig`
 
@@ -42,8 +57,14 @@ Passed to the constructor. All fields optional, default to empty arrays.
 
 ```typescript
 interface EngineConfig {
-    customRules?: ExternalRuleSource[];  // engine-native rules (Rego for RegoEngine, CEL for CelEngine)
-    guardRules?: ExternalRuleSource[];   // CloudFormation Guard DSL rules — translated internally by each engine
+    customRules?: RuleSource[];  // engine-native rules (Rego for RegoEngine, CEL for CelEngine)
+    guardRules?: RuleSource[];   // CloudFormation Guard DSL rules — translated internally by each engine
+}
+
+type RuleSource = ExternalRuleSource | RuleFile;
+
+class RuleFile {
+    constructor(path: string);   // rule file read from disk; the path becomes the rule source name
 }
 
 interface ExternalRuleSource {
@@ -52,6 +73,16 @@ interface ExternalRuleSource {
 }
 ```
 
+Pass a `RuleFile` to load a rule from disk — the same pattern as `TemplateFile` for templates — or an
+`ExternalRuleSource` when you already have the rule text in memory. The two can be mixed freely:
+
+```typescript
+const engine = new CelEngine({
+    customRules: [new RuleFile("rules/s3_encryption.json")],
+    guardRules: [new RuleFile("rules/compliance.guard")],
+});
+```
+
 ## ValidateConfig
 
 Controls filtering, severity, parameter overrides, and behavior. All fields optional — omitting the config or passing
@@ -90,13 +121,15 @@ interface RuleFilterConfig {
     idRanges?: IdRange[];              // numeric ranges, e.g. { prefix: "E", start: 3000, end: 3099 }
     idPatterns?: string[];             // regex patterns matched against rule IDs
     resourceIds?: ResourceIdFilter[];  // a rule (or every rule) on a logical resource ID
+    logicalIds?: LogicalIdFilter[];    // a rule (or every rule) on a named template entity
     resourceTypes?: ResourceTypeFilter[]; // a rule (or every rule) on a resource type
     services?: ServiceFilter[];        // a rule (or every rule) on a service, e.g. "AWS::AutoScaling"
 }
 
-// resourceIds / resourceTypes / services each carry an optional ruleId:
+// resourceIds / logicalIds / resourceTypes / services each carry an optional ruleId:
 // set it to scope the filter to one rule, or omit it for every rule on the target.
 interface ResourceIdFilter   { ruleId?: string; resourceId: string; }
+interface LogicalIdFilter    { ruleId?: string; logicalId: string; entityType?: EntityType; }
 interface ResourceTypeFilter { ruleId?: string; resourceType: string; }
 interface ServiceFilter      { ruleId?: string; service: string; }
 ```
@@ -104,6 +137,11 @@ interface ServiceFilter      { ruleId?: string; service: string; }
 The `service` is matched verbatim against the `service-provider::service-name` prefix of the resource type — its first
 two `::`-delimited segments (e.g. `AWS::AutoScaling` in `AWS::AutoScaling::LaunchConfiguration`).
 
+The `resourceIds` dimension matches only diagnostics attributed to a resource; `logicalIds` additionally matches
+diagnostics on parameters, outputs, mappings, conditions, and template rules (for resource diagnostics the two carry
+the same value). An optional `entityType` scopes a `LogicalIdFilter` to entities of one type, so `MyThing` as a
+`"Parameter"` is matched without touching a same-named entity of another type.
+
 ### PseudoParameterOverrides
 
 Override CloudFormation pseudo-parameters used during intrinsic function resolution. All fields optional — when
@@ -185,7 +223,7 @@ interface StandardReport {
 ```
 
 `DetailedReport` has the same structure but its diagnostics include additional fields: `documentationUrl`,
-`ruleDescription`, `phase` (`PARSE` | `SCHEMA` | `LINT`), `section`, and `context` (`ViolationContext` with
+`ruleDescription`, `phase` (`PARSE` | `SCHEMA` | `LINT`), and `context` (`ViolationContext` with
 `actualValue`, `expectedConstraint`, `resolutionSource`, etc.).
 
 ### StandardDiagnostic
@@ -196,9 +234,8 @@ interface StandardDiagnostic {
     severity: Severity;                // "FATAL" | "ERROR" | "WARN" | "INFO" | "DEBUG"
     message: string;
     source: RuleOrigin;                // "SCHEMA" | "CFN_LINT" | "ENGINE" | "CUSTOM" | "GUARD"
-    resourceId?: string;               // logical resource ID
-    resourceType?: string;             // e.g. "AWS::S3::Bucket"
-    propertyPath?: string;             // e.g. "Properties/BucketName"
+    entity?: Entity;                   // the named template entity the finding targets, if any
+    propertyPath?: string;             // e.g. "Properties.BucketName", or section-absolute like "Parameters/MyParam/Type"
     suggestedFix?: string;
     category?: string;
     startLine?: number;
@@ -208,4 +245,15 @@ interface StandardDiagnostic {
     relatedResources?: RelatedResource[];
     conditionScenario?: Record<string, boolean>;  // condition truth assignment that triggers this diagnostic
 }
+
+// The named template entity a diagnostic is attributed to. The entity type is the
+// singular form of the top-level template section the entity is declared in.
+interface Entity {
+    logicalId: string;                 // logical ID as declared in the template
+    entityType: EntityType;
+    resourceType?: string;             // CloudFormation type, when the entity is a resource whose type is known
+}
+
+type EntityType = "Resource" | "Parameter" | "Output" | "Mapping" | "Metadata"
+                | "Rule" | "Condition" | "Transform" | "FormatVersion" | "Description";
 ```

package/bindings_wasm.d.ts

@@ -191,6 +191,18 @@ export interface DiagnosticResource {
      * Property paths containing ${...} text that is not an Fn::Sub variable and is left as a literal.
      */
     unsubstitutedVariables: PathVariable[];
+    /**
+     * Fn::Sub map keys not referenced in the template string, each with its path and the unused key name.
+     */
+    unusedSubKeys: PathVariable[];
+    /**
+     * Property values that are a raw pseudo-parameter string instead of using Ref, each with its path and the pseudo-parameter name.
+     */
+    rawPseudoParams: PathVariable[];
+    /**
+     * Property paths containing a {{resolve:secretsmanager:...}} dynamic reference.
+     */
+    secretsmanagerRefPaths: string[];
     /**
      * References whose target does not resolve to any resource or parameter, each with its path and unresolved target.
      */
@@ -235,6 +247,7 @@ export interface RuleFilterConfig {
      */
     idPatterns?: string[];
     resourceIds?: ResourceIdFilter[];
+    logicalIds?: LogicalIdFilter[];
     resourceTypes?: ResourceTypeFilter[];
     services?: ServiceFilter[];
 }
@@ -386,6 +399,25 @@ export interface ResolvedResource {
     diagnostics: ResourceDiagnostics;
 }
 
+/**
+ * A top-level CloudFormation template section, as documented in the template
+ * anatomy (<https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html>).
+ *
+ * This is the canonical, single definition of the section names — section
+ * constants in other crates derive from it.
+ */
+export type TopLevelSection =
+    | 'Resources'
+    | 'Parameters'
+    | 'Outputs'
+    | 'Mappings'
+    | 'Metadata'
+    | 'Rules'
+    | 'Conditions'
+    | 'Transform'
+    | 'FormatVersion'
+    | 'Description';
+
 /**
  * Advanced introspection view of a parsed CloudFormation template: its reference graph,
  * conditions, and resolved resources and outputs.
@@ -661,6 +693,18 @@ export interface ResourceDiagnostics {
      * Occurrences of ${...} placeholders outside an Fn::Sub that will not be substituted; each pairs the property path with the placeholder text.
      */
     unsubstitutedVariables: PathValuePair[];
+    /**
+     * Fn::Sub map keys not referenced in the template string; each pairs the property path with the unused key name.
+     */
+    unusedSubKeys: PathValuePair[];
+    /**
+     * Property values that are a raw pseudo-parameter string (e.g. \"AWS::Region\") instead of using Ref.
+     */
+    rawPseudoParams: PathValuePair[];
+    /**
+     * Property paths containing a {{resolve:secretsmanager:...}} dynamic reference.
+     */
+    secretsmanagerRefPaths: string[];
     /**
      * References whose target is not a defined resource, parameter, or pseudo parameter; each pairs the property path with the missing target name.
      */
@@ -705,6 +749,19 @@ export interface ResourceIdFilter {
     resourceId: string;
 }
 
+/**
+ * Suppress a rule for a specific named template entity — a resource,
+ * parameter, output, mapping, condition, or template rule — identified by its
+ * logical ID. An absent `rule_id` scopes the filter to every rule on that
+ * entity; an absent `entity_type` scopes it to entities of every type with
+ * that logical ID.
+ */
+export interface LogicalIdFilter {
+    ruleId?: string;
+    logicalId: string;
+    entityType?: EntityType;
+}
+
 /**
  * Suppress a rule for a specific resource type. An absent `rule_id` scopes the
  * filter to every rule on that type.
@@ -729,6 +786,43 @@ export interface ServiceFilter {
     service: string;
 }
 
+/**
+ * The kind of template entity a diagnostic targets — the singular form of the
+ * top-level section the entity is declared in. Every documented section has a
+ * variant; the ones whose children are addressable by logical ID (resources,
+ * parameters, outputs, mappings, conditions, rules, and metadata keys) are
+ * the ones diagnostics attribute findings to today.
+ */
+export type EntityType =
+    | 'Resource'
+    | 'Parameter'
+    | 'Output'
+    | 'Mapping'
+    | 'Metadata'
+    | 'Rule'
+    | 'Condition'
+    | 'Transform'
+    | 'FormatVersion'
+    | 'Description';
+
+/**
+ * The named template entity a diagnostic is attributed to, when it targets
+ * one. The entity type is the singular form of the top-level template
+ * section the entity is declared in.
+ */
+export interface Entity {
+    /**
+     * Logical ID of the entity as declared in the template.
+     */
+    logicalId: string;
+    entityType: EntityType;
+    /**
+     * CloudFormation resource type, when the entity is a resource whose type
+     * is known.
+     */
+    resourceType?: string;
+}
+
 /**
  * The template resource a diagnostic is attributed to, when it targets one.
  */
@@ -810,7 +904,7 @@ export interface PseudoParameterOverrides {
 export type RuleOrigin = 'SCHEMA' | 'CFN_LINT' | 'ENGINE' | 'CUSTOM' | 'GUARD';
 
 /**
- *r" A single validation finding with its resource and source location flattened into individual fields.
+ *r" A single validation finding with its source location flattened into individual fields.
  */
 export interface StandardDiagnostic {
     /**
@@ -824,10 +918,9 @@ export interface StandardDiagnostic {
      */
     source: RuleOrigin;
     /**
-     * Logical ID of the resource this finding targets, if any.
+     * The named template entity this finding targets — a resource, parameter, output, mapping, condition, or template rule — if any.
      */
-    resourceId?: string;
-    resourceType?: string;
+    entity?: Entity;
     /**
      * Path to the offending property within the resource, such as \'Properties.Name\'.
      */
@@ -863,10 +956,9 @@ export interface DetailedDiagnostic {
      */
     source: RuleOrigin;
     /**
-     * Logical ID of the resource this finding targets, if any.
+     * The named template entity this finding targets — a resource, parameter, output, mapping, condition, or template rule — if any.
      */
-    resourceId?: string;
-    resourceType?: string;
+    entity?: Entity;
     /**
      * Path to the offending property within the resource, such as \'Properties.Name\'.
      */
@@ -888,10 +980,6 @@ export interface DetailedDiagnostic {
     documentationUrl?: string;
     ruleDescription?: string;
     phase?: Phase;
-    /**
-     *r" Top-level template section the finding falls under, such as 'Resources' or 'Parameters'.
-     */
-    section?: string;
     context?: ViolationContext;
 }
 

package/index.d.ts

@@ -1,7 +1,7 @@
 import type {
     DetailedReport,
     DiagnosticModel,
-    EngineConfig,
+    ExternalRuleSource,
     ParameterInfo,
     ResolvedOutput,
     ResolvedResource,
@@ -17,11 +17,14 @@ export type {
     RuleOrigin,
     IdRange,
     ResourceIdFilter,
+    LogicalIdFilter,
     ResourceTypeFilter,
     ServiceFilter,
     RuleFilterConfig,
     RuleInfo,
     SourceSpan,
+    Entity,
+    EntityType,
     ResourceRef,
     RelatedResource,
     ViolationContext,
@@ -34,7 +37,6 @@ export type {
     StandardReport,
     DetailedReport,
     PseudoParameterOverrides,
-    EngineConfig,
     ValidateConfig,
     ExternalRuleSource,
     ResolvedValue,
@@ -87,6 +89,18 @@ export declare class TemplateFile {
     constructor(path: string);
     readBytes(): Uint8Array;
 }
+export declare class RuleFile {
+    readonly path: string;
+    constructor(path: string);
+    readContent(): string;
+}
+export type RuleSource = ExternalRuleSource | RuleFile;
+export interface EngineConfig {
+    /** Engine-native rules (Rego for RegoEngine, CEL for CelEngine). */
+    customRules?: RuleSource[];
+    /** CloudFormation Guard DSL rules, usable with either engine. */
+    guardRules?: RuleSource[];
+}
 export declare class TemplateModel {
     private readonly inner;
     constructor(template: TemplateFile);

package/index.js

@@ -4,6 +4,7 @@ exports.CelEngine =
     exports.RegoEngine =
     exports.SchemaValidator =
     exports.TemplateModel =
+    exports.RuleFile =
     exports.TemplateFile =
         void 0;
 exports.version = version;
@@ -18,6 +19,26 @@ class TemplateFile {
     }
 }
 exports.TemplateFile = TemplateFile;
+class RuleFile {
+    constructor(path) {
+        this.path = path;
+    }
+    readContent() {
+        return (0, fs_1.readFileSync)(this.path, 'utf8');
+    }
+}
+exports.RuleFile = RuleFile;
+function toExternalRuleSources(sources) {
+    return (sources ?? []).map((source) =>
+        source instanceof RuleFile ? { name: source.path, content: source.readContent() } : source,
+    );
+}
+function toWasmEngineConfig(config) {
+    return {
+        customRules: toExternalRuleSources(config?.customRules),
+        guardRules: toExternalRuleSources(config?.guardRules),
+    };
+}
 class TemplateModel {
     constructor(template) {
         this.inner = bridge.WasmSemanticModel.parse(template.readBytes());
@@ -80,7 +101,7 @@ exports.SchemaValidator = SchemaValidator;
 function createEngineClass(WasmClass) {
     return class {
         constructor(config) {
-            this.inner = new WasmClass(config ?? {});
+            this.inner = new WasmClass(toWasmEngineConfig(config));
         }
         validateStandard(template, config) {
             return this.inner.validateStandard(template.readBytes(), config ?? {}, template.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/cloudformation-validate",
-  "version": "1.5.0-beta",
+  "version": "1.6.0-beta",
   "description": "AWS CloudFormation Validate",
   "keywords": [
     "aws",
@@ -19,8 +19,7 @@
   },
   "license": "Apache-2.0",
   "engines": {
-    "node": "^22.15.0",
-    "npm": ">=10.5.0"
+    "node": ">=20.0.0"
   },
   "repository": {
     "type": "git",