@aws/cloudformation-validate 1.7.0-beta → 1.8.0-beta

package/NOTICE

@@ -0,0 +1,8 @@
+AWS CloudFormation Validate
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+This product includes software developed at
+Amazon Web Services (https://aws.amazon.com/).
+
+This software includes components licensed under various open source licenses.
+You can find a full list of third-party licenses in the THIRD-PARTY-LICENSES.txt file included with this distribution.

package/README.md

@@ -1,10 +1,10 @@
 # CloudFormation Validate 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.
+best-practice findings before deployment - in your editor, build, or CI.
 
-- **Offline** — all rules and resource schemas are bundled.
-- **Fast** — sub-second validation per template.
+- **Offline** - all rules and resource schemas are bundled.
+- **Fast** - sub-second validation per template.
 
 ## Installation
 
@@ -16,7 +16,7 @@ npm install @aws/cloudformation-validate
 
 ## Quick start
 
-Engines, models, and validators hold off-heap memory — call `.free()` when done with each object:
+Engines, models, and validators hold off-heap memory - call `.free()` when done with each object:
 
 ```typescript
 import { RegoEngine, TemplateFile } from "@aws/cloudformation-validate";
@@ -32,13 +32,13 @@ try {
 }
 ```
 
-Each diagnostic identifies the rule, severity, affected resource and property, and source location — see
+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
+`RegoEngine` and `CelEngine` both implement the `Engine` interface and are interchangeable - they produce identical
 diagnostics for the same template and config.
 
 ### `Engine` interface
@@ -59,7 +59,7 @@ Passed to the constructor. All fields are optional; omitted rule arrays are empt
 ```typescript
 interface EngineConfig {
     customRules?: RuleSource[];                       // engine-native rules (Rego for RegoEngine, CEL for CelEngine)
-    guardRules?: RuleSource[];                        // CloudFormation Guard DSL rules — translated internally
+    guardRules?: RuleSource[];                        // CloudFormation Guard DSL rules - translated internally
     schemaValidatorConfig?: SchemaValidatorConfig;   // schema validation and overlay configuration
 }
 
@@ -89,7 +89,7 @@ interface AdditionalSchemaSource {
 }
 ```
 
-Pass a `RuleFile` to load a rule from disk — the same pattern as `TemplateFile` for templates — or an
+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. `SchemaFile` does the same for an additional
 resource provider schema. Its optional constructor `typeName` may be omitted when the schema JSON contains its own
 `typeName`.
@@ -109,7 +109,7 @@ const engine = new CelEngine({
 
 ## ValidateConfig
 
-Controls filtering, severity, parameter overrides, and behavior. All fields optional — omitting the config or passing
+Controls filtering, severity, parameter overrides, and behavior. All fields optional - omitting the config or passing
 `{}` uses defaults.
 
 ```typescript
@@ -136,7 +136,7 @@ interface ValidateConfig {
 
 ### RuleFilterConfig
 
-Both `include` and `exclude` use this structure. All fields are additive — a rule matches if it hits any criterion.
+Both `include` and `exclude` use this structure. All fields are additive - a rule matches if it hits any criterion.
 
 ```typescript
 interface RuleFilterConfig {
@@ -158,7 +158,7 @@ interface ResourceTypeFilter { ruleId?: string; resourceType: string; }
 interface ServiceFilter      { ruleId?: string; service: string; }
 ```
 
-The `service` is matched verbatim against the `service-provider::service-name` prefix of the resource type — its first
+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
@@ -168,7 +168,7 @@ the same value). An optional `entityType` scopes a `LogicalIdFilter` to entities
 
 ### PseudoParameterOverrides
 
-Override CloudFormation pseudo-parameters used during intrinsic function resolution. All fields optional — when
+Override CloudFormation pseudo-parameters used during intrinsic function resolution. All fields optional - when
 `undefined`, the engine uses built-in defaults (e.g. region defaults to `us-east-1`).
 
 ```typescript
@@ -193,7 +193,7 @@ const template = new TemplateFile("path/to/template.yaml");
 
 ## TemplateModel
 
-Parses a template into the resolved `SemanticModel` for direct inspection — the same model the engines evaluate rules
+Parses a template into the resolved `SemanticModel` for direct inspection - the same model the engines evaluate rules
 against.
 
 ```typescript
@@ -238,7 +238,7 @@ validator.free();
 ```typescript
 interface StandardReport {
     filePath: string;
-    status: "OK" | "ERROR";           // ERROR when the template fails to parse
+    status: "OK" | "ANALYSIS_INCOMPLETE" | "ERROR"; // ERROR is a pipeline failure; ANALYSIS_INCOMPLETE may omit findings
     version: string;
     metadata: ReportMetadata;
     performance: PerformanceMetrics;
@@ -250,6 +250,11 @@ interface StandardReport {
 `ruleDescription`, `phase` (`PARSE` | `SCHEMA` | `LINT`), and `context` (`ViolationContext` with
 `actualValue`, `expectedConstraint`, `resolutionSource`, etc.).
 
+Each optional budget-exhaustion record retains a stable machine-readable kind and also includes a
+human-readable description sentence, the numeric limit, and whether that specific exhaustion makes analysis
+incomplete. `requiredPropertyCombinations` is context-only, so its `analysisIncomplete` value is `false` and the
+report can remain `"OK"`.
+
 ### StandardDiagnostic
 
 ```typescript

package/bindings_wasm.d.ts

@@ -306,6 +306,28 @@ export interface DiagnosticRuleAssertion {
     assertDescription?: string;
 }
 
+/**
+ * A single budget-exhaustion record in report metadata.
+ */
+export interface BudgetExhaustionRecord {
+    /**
+     * Stable lower camelCase budget kind identifier.
+     */
+    kind: string;
+    /**
+     * Human-readable explanation of the exhausted budget.
+     */
+    description?: string;
+    /**
+     * The numeric limit that was exhausted.
+     */
+    limit: number;
+    /**
+     * Whether exhausting this budget makes the overall analysis incomplete.
+     */
+    analysisIncomplete: boolean;
+}
+
 /**
  * A single edge in the template\'s reference graph, from a referencing resource to its target.
  */
@@ -428,7 +450,7 @@ export interface ResolvedResource {
  * 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
+ * This is the canonical, single definition of the section names - section
  * constants in other crates derive from it.
  */
 export type TopLevelSection =
@@ -692,10 +714,12 @@ export interface IdRange {
 }
 
 /**
- * Outcome of a validation run. `Ok` means the engine completed; `Error` means
- * the pipeline could not run (e.g. parse failure).
+ * Outcome of a validation run. `Ok` means validation completed without
+ * correctness-affecting curtailment. `AnalysisIncomplete` means a deterministic
+ * budget curtailed analysis in a way that could omit findings. `Error` means
+ * the validation pipeline could not run, such as when parsing fails.
  */
-export type ReportStatus = 'OK' | 'ERROR';
+export type ReportStatus = 'OK' | 'ANALYSIS_INCOMPLETE' | 'ERROR';
 
 /**
  * Per-resource observations collected while resolving intrinsics, used to drive lint checks.
@@ -788,8 +812,8 @@ export interface ResourceIdFilter {
 }
 
 /**
- * Suppress a rule for a specific named template entity — a resource,
- * parameter, output, mapping, condition, or template rule — identified by its
+ * 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.
@@ -810,7 +834,7 @@ export interface ResourceTypeFilter {
 }
 
 /**
- * Suppress a rule for every resource belonging to a service — the
+ * Suppress a rule for every resource belonging to a service - the
  * `service-provider::service-name` prefix of the resource type (its first two
  * `::`-delimited segments, for example `AWS::AutoScaling` in
  * `AWS::AutoScaling::LaunchConfiguration`, or `Alexa::ASK` in
@@ -825,7 +849,7 @@ export interface ServiceFilter {
 }
 
 /**
- * The kind of template entity a diagnostic targets — the singular form of the
+ * 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
@@ -956,7 +980,7 @@ export interface StandardDiagnostic {
      */
     source: RuleOrigin;
     /**
-     * The named template entity this finding targets — a resource, parameter, output, mapping, condition, or template rule — if any.
+     * The named template entity this finding targets - a resource, parameter, output, mapping, condition, or template rule - if any.
      */
     entity?: Entity;
     /**
@@ -994,7 +1018,7 @@ export interface DetailedDiagnostic {
      */
     source: RuleOrigin;
     /**
-     * The named template entity this finding targets — a resource, parameter, output, mapping, condition, or template rule — if any.
+     * The named template entity this finding targets - a resource, parameter, output, mapping, condition, or template rule - if any.
      */
     entity?: Entity;
     /**
@@ -1048,7 +1072,15 @@ export interface ReportMetadata {
     /**
      * Number of rules that were active for this run after any category exclusions.
      */
-    rulesEvaluated?: number;
+    rulesEvaluated: number;
+    /**
+     * Source-qualified cfn-lint version used to sync bundled derived data.
+     */
+    cfnLintVersion: string;
+    /**
+     * Source-qualified enhanced resource-schema version used for the bundled provider schemas.
+     */
+    resourceSchemaVersion: string;
     resourcesScanned: number;
     /**
      * Tally of reported diagnostics by severity.
@@ -1066,6 +1098,11 @@ export interface ReportMetadata {
      * Minimum severity included in the report; lower-severity findings are omitted.
      */
     severityLevel: Severity;
+    /**
+     * Records of deterministic validation budgets exhausted during this run.
+     * Absent when no budget was exhausted.
+     */
+    budgetExhaustions?: BudgetExhaustionRecord[] | undefined;
 }
 
 export interface Summary {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws/cloudformation-validate",
-  "version": "1.7.0-beta",
-  "description": "AWS CloudFormation Validate",
+  "version": "1.8.0-beta",
+  "description": "Fast, offline, embeddable validation for AWS CloudFormation templates",
   "keywords": [
     "aws",
     "amazon",
@@ -17,6 +17,9 @@
     "name": "Amazon Web Services",
     "url": "https://aws.amazon.com"
   },
+  "bugs": {
+    "url": "https://github.com/aws-cloudformation/cloudformation-validate/issues"
+  },
   "license": "Apache-2.0",
   "engines": {
     "node": ">=20.0.0"