Add detection for outer DECLARE statements and update documentation

.github/copilot-instructions.md

@@ -49,6 +49,9 @@ For `operations`, the SQL is often set via `.queries(["SQL"])`. This method can
 ### 4. Assertions
 Assertions in Dataform are strict. They expect a single `SELECT` statement. Prepending a `SET` statement will cause a syntax error in BigQuery because assertions are often wrapped in subqueries or views by Dataform. We explicitly skip assertions in this package.
 
+### 5. Outer DECLARE Detection
+Operations where `DECLARE` is the first statement at the outer level are automatically skipped. BigQuery requires `DECLARE` before any other statements in a script, so prepending `SET @@reservation` would fail. The package strips leading whitespace and SQL comments (`--`, `#`, `/* */`) to reliably detect this case. `DECLARE` inside `BEGIN...END` or `EXECUTE IMMEDIATE` is not flagged — reservation is applied normally in those cases.
+
 ## Release Process
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md#release-process) for the full release workflow steps.

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        dataform-version: ['2.4.2', '3.0.43']
+        dataform-version: ['2.4.2', '3.0.48']
 
     steps:
       - name: Checkout code

CHANGELOG.md

@@ -27,13 +27,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **SQL statement prepending logic refactored**
 - **Reservation lookup performance improved** - Refactored to use a Set for O(1) lookups instead of array iteration, significantly improving performance for large reservation lists
+- **Updated test version for v3.0 from 3.0.43 to 3.0.48** - Updated the Dataform version used in matrix testing to ensure compatibility with the latest stable release.
+
 
 ## [0.2.0] - 2026-01-20
 
 ### Added
 
 - **`autoAssignActions()` method** - Primary integration approach that automatically assigns actions to reservations to all Dataform actions globally without requiring manual code in each action file
-- **Matrix testing infrastructure** - Automated testing across multiple Dataform versions (currently - v2.4.2 and v3.0.43)
+- **Matrix testing** - Automated testing across multiple Dataform versions (currently - v2.4.2 and v3.0.43)
 - **API Reference section** in README with comprehensive documentation of all exported methods
 
 ## [0.1.0] - 2025-10-27

CONTRIBUTING.md

@@ -4,57 +4,68 @@ We welcome contributions to the Dataform package! This document provides guideli
 
 ## Development Setup
 
-1. **Clone the repository:**
+### 1. **Clone the repository:**
 
    ```bash
    git clone https://github.com/masthead-data/dataform-package.git
    cd dataform-package
    ```
 
-2. **Install dependencies:**
+### 2. **Install dependencies:**
 
    ```bash
    npm install
    ```
 
-3. **Run tests:**
+### 3. **Run tests:**
+
+#### 3.1 Matrix Testing (Default)
 
-   #### Matrix Testing (Default)
    Run from the root to test all supported versions:
+
    ```bash
    npm test
    ```
+
    This command iterates through all supported Dataform versions (currently v2.4.2 and v3.X.X), managing configuration file conflicts automatically.
 
-   #### Single Version (Fast Iteration)
+#### 3.2 Single Version (Fast Iteration)
+
    For rapid development on the version currently installed in `test-project`:
+
    ```bash
    npm run test:single
    ```
+
    This runs:
    1. `jest`: Unit tests for helper functions.
    2. `dataform compile`: Generates the actual project graph.
    3. `verify_compilation.js`: In-depth JSON inspection.
 
-   #### Specific Version
+#### 3.3 Specific Version
+
    Test a single Dataform version:
+
    ```bash
    npm test -- 2.4.2
    ```
 
-4. **Run linting:**
+### 4. **Run linting:**
 
    ```bash
    npm run lint
    ```
 
 ### Local Integration Testing
+
 The `test-project` is configured to use the local version of the package. In `test-project/package.json`:
+
 ```json
 "dependencies": {
   "@masthead-data/dataform-package": "file:../"
 }
 ```
+
 **Note:** `npm ci` or `npm install` in the `test-project` caches the local package. If you make changes to `index.js` and don't see them reflected, you may need to force an update or avoid `npm ci` during rapid iteration.
 
 ## Project Structure
@@ -66,8 +77,7 @@ dataform-package/
 │   └── index.test.js     # Test suite
 ├── package.json          # Package configuration
 ├── README.md             # Main documentation
-├── CHANGELOG.md          # Version history
-└── .eslintrc.js          # ESLint configuration
+└── CHANGELOG.md          # Version history
 ```
 
 ## Making Changes
@@ -80,6 +90,7 @@ This project uses `npm ci` in CI/CD pipelines, which requires `package-lock.json
 The project includes optional platform-specific dependencies (e.g., `@unrs/resolver-binding-*`). If you update dependencies on macOS, `npm` might "clean" other platform bindings from the lockfile, causing CI to fail on Linux.
 
 If CI fails with `npm error EUSAGE` related to missing platform bindings:
+
 1. Restore the `package-lock.json` to a known good state.
 2. Run `npm install` to update the version/dependencies without removing optional bindings.
 3. Verify that the lockfile still contains entries for `@unrs/resolver-binding-linux-*` before committing.

README.md

@@ -61,6 +61,13 @@ autoAssignActions(RESERVATION_CONFIG);
 
 With automated assignement, you don't need to edit your individual action files — the package handles everything globally.
 
+#### Limitations of Automated Assignment
+
+* `DECLARE` at the top level of the SQL (the first real statement after whitespace/comments).
+    The automation skips operations where `DECLARE` is the first statement at the outer level. BigQuery requires `DECLARE` to appear before any other statements in a script, so prepending `SET @@reservation` would cause a syntax error. This detection works automatically without any configuration needed.
+
+    Use manual assignment for any actions that require top-level `DECLARE` statements.
+
 ### Manual Assignment (Optional)
 
 For more granular control, you can manually apply reservations per file. Create a setter function in your global scope under `/includes` directory:
@@ -218,8 +225,8 @@ Extracts the action name from a Dataform context object.
 
 This package is tested and compatible with:
 
-* **Dataform v2.4.2**
-* **Dataform v3 - latest version**
+* **Dataform v2.x** (e.g., v2.4.2)
+* **Dataform v3.x**
 
 ## Under the Hood
 
@@ -234,13 +241,15 @@ The package supports various Dataform contexts for action name detection:
 
 Actions are matched against the `RESERVATION_CONFIG` using exact string matching. The action is assigned to the first matching reservation. If no match is found, the actions is assigned to the default reservation (first entry with `null` reservation). If no default is defined, no reservation override is applied.
 
-### SQL Generation
+### Reservation Assignment Implementation
+
+Based on the matched reservation, the package automatically prepends the `SET @@reservation` SQL statement to your queries or pre-operations.
 
-Based on the matched reservation, the system generates appropriate SQL:
+The specific reservation value applied follows this logic:
 
-* **Specific Reservation**: `SET @@reservation='projects/{project}/locations/{location}/reservations/{name}';`
-* **On-demand**: `SET @@reservation='none';`
-* **Default/Null**: Empty string (no reservation override)
+* **Specific Reservation**: `projects/{project}/locations/{location}/reservations/{name}`
+* **On-demand**: `none`
+* **Default/Null**: No reservation override applied
 
 ### Limitations