Validate Blocks

A Deno tool to validate that all occurrences of Sections, Loaders, and Actions (in deco.cx blocks and pages) have data structures compatible with their TypeScript types.

Unused Detection Features

The tool detects several types of unused code:

Type	Detection	Auto-Removal
Unused Sections	✅ Detected	✅ With `-rm-sections`
Unused Loaders	✅ Detected	❌ Manual only*
Unused Actions	✅ Detected	❌ Manual only*
Unused Properties	✅ With `-unused`	✅ With `-rm-vars`

*Loaders and actions are not auto-removed because they may be imported dynamically or called programmatically.

How to Run

Run directly (recommended)

No installation needed - just run from any deco site directory:

# Validate all sections, loaders, and actions
deno run -A https://deco.cx/validate

# Generate a JSON report
deno run -A https://deco.cx/validate -report validation-report.json

Add as a deno task (optional)

Add to your site’s deno.json for convenience:

{
  "tasks": {
    "validate-blocks": "deno run -A https://deco.cx/validate"
  }
}

Then run:

deno task validate-blocks

Usage Examples

Validate all sections, loaders, and actions:

deno run -A https://deco.cx/validate

Validate a specific section:

deno run -A https://deco.cx/validate sections/Footer/Footer.tsx

You can use relative or absolute paths.

Use custom blocks directory:

By default, the script searches for JSONs in .deco/blocks. You can specify another path:

deno run -A https://deco.cx/validate -blocks /full/path/to/jsons

This allows running the script in one project and validating blocks from another project.

Available flags:

`-unused`

By default, the script does not show warnings for properties not defined in the types. Use this flag to include them:

deno run -A https://deco.cx/validate -unused

`-blocks <path>` or `-b <path>`

Specifies a custom path for the directory containing JSON blocks. Defaults to .deco/blocks:

deno run -A https://deco.cx/validate -blocks /full/path/to/jsons

`-rm-vars`

⚠️ WARNING: Automatically modifies JSON files!

Removes all properties that are not defined in the types:

deno run -A https://deco.cx/validate -rm-vars

The script:

Identifies properties in the JSON that don’t exist in the Props interface
Removes these properties automatically
Saves the modified JSON file

Example:

If the JSON has:

{
  "__resolveType": "site/sections/Footer/Footer.tsx",
  "title": "Footer",
  "teste": "unused value" // <- not in Props interface
}

After running -rm-vars, the JSON becomes:

{
  "__resolveType": "site/sections/Footer/Footer.tsx",
  "title": "Footer"
}

`-rm-sections`

⚠️ WARNING: Permanently deletes files!

Removes all section files that are not referenced in any JSON:

deno run -A https://deco.cx/validate -rm-sections

The script:

Identifies sections/loaders that have no occurrences in JSONs
Lists the files that will be removed
Asks for confirmation (type yes to confirm)
Permanently deletes the files

Example output:

🗑️  Removing unused sections/loaders...

📋 15 file(s) will be removed:

  - sections/Category/CategoryGrid.tsx
  - sections/Institutional/NumbersWithImage.tsx
  - sections/Product/ProductShelf.tsx
  ...

⚠️  This action is irreversible!
Type 'yes' to confirm removal:

Note: This flag only works for full validation (without specifying a file), it doesn’t work when validating a specific section.

What it does

The script:

Iterates through all files in sections/, loaders/, and actions/
Generates the __resolveType for each section/loader/action
Searches for ALL occurrences of that __resolveType in .deco/blocks (including inside pages)
Extracts the Props interface from the TypeScript file
Deeply validates each occurrence against the types
Reports errors and warnings with exact path in the JSON
Detects unused files that aren’t referenced anywhere

Features

Intelligent Props Detection

✅ Follows re-exports (export { default } from "./other-file")
✅ Resolves Deno import aliases from deno.json ($store/, $home/, site/, etc.)
✅ Extracts type from the component parameter exported as default
✅ Fallback to interface/type named “Props”
✅ Supports type aliases and interfaces
✅ Supports utility types (Omit, Pick, Partial)
✅ Supports arrow function components and function declarations

Deep Validation

✅ Primitive types: string, number, boolean, null
✅ Arrays with element validation
✅ Nested objects recursively
✅ Optional properties (?)
✅ Union types (string | number)
✅ Special types: ImageWidget, Product, RichText, etc
✅ Respects @ignore annotation on properties
⚠️ Detects extra properties not defined in types (warnings)

Protections

✅ Ignores blocks from external apps (vtex, commerce, shopify, etc)
✅ Ignores Theme blocks
✅ Protection against infinite recursion in circular types

Severity System

✅ Valid - Block is correct
⚠️ Warning - Props not found OR extra properties not defined in types OR section is not being used (doesn’t fail the build)
❌ Error - Required properties missing or incorrect types (fails the build)

`-report [path]` or `-r [path]`

Generates a JSON report file with validation results:

# Default: creates validation-report.json
deno run -A https://deco.cx/validate -report

# Custom path
deno run -A https://deco.cx/validate -report my-report.json

The report includes:

Summary with total counts (sections, errors, warnings, unused)
Detailed list of sections with errors (including file, line, property, message)
Detailed list of sections with warnings
List of unused sections

Example report structure:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "projectRoot": "/path/to/project",
  "summary": {
    "totalSections": 133,
    "totalOccurrences": 1606,
    "totalErrors": 15,
    "totalWarnings": 4,
    "sectionsWithErrors": 5,
    "sectionsWithWarnings": 10,
    "unusedSections": 8,
    "validSections": 110
  },
  "sectionsWithErrors": [...],
  "sectionsWithWarnings": [...],
  "unusedSections": [...]
}

File Structure

validate-blocks/
├── main.ts              # Main entrypoint
├── deno.json            # Deno configuration and tasks
├── src/
│   ├── type-mapper.ts   # Maps __resolveType to paths
│   ├── ts-parser.ts     # TypeScript parser (extracts Props)
│   ├── validator.ts     # Recursive type validator
│   └── validate-blocks.ts # Orchestrator and reporting
├── tests/
│   ├── ts-parser_test.ts    # Tests for TypeScript parser
│   ├── validator_test.ts    # Tests for validator
│   ├── type-mapper_test.ts  # Tests for type mapper
│   └── fixtures/            # Test fixtures
└── README.md            # This documentation

Running Tests

# Run all tests
deno test -A

# Run specific test file
deno test -A tests/validator_test.ts

# Run with verbose output
deno test -A --reporter=verbose

Example Output

🔍 Validating sections and loaders...

✅ sections/Header/Header.tsx - 15 occurrence(s)
✅ sections/Footer/Footer.tsx - 1 occurrence(s)

⚠️  sections/Footer/Footer.tsx - 1 occurrence(s), 2 warning(s)

Footer.json

  - property not defined in types (can be removed) (.deco/blocks/Footer.json:265)
  - property not defined in types (can be removed) (.deco/blocks/Footer.json:273)

❌ sections/Category/CategoryGrid.tsx - 1 occurrence(s), 1 error(s)

Preview%20%2Fsections%2FCategory%2FCategoryGrid.tsx.json

  - "items": required property missing (.deco/blocks/Preview%20%2Fsections%2FCategory%2FCategoryGrid.tsx.json:2)

❌ sections/Sac/Stores.tsx - 2 occurrence(s), 2 error(s)

pages-Lojas-735837.json

  - expected array, received object (.deco/blocks/pages-Lojas-735837.json:57)
  - expected array, received object (.deco/blocks/pages-Lojas-735837.json:73)

═══════════════════════════════════════
📊 SUMMARY
═══════════════════════════════════════
Total sections/loaders/actions: 95
Total occurrences: 284
✅ No issues: 85
⚠️ With warnings: 3
⚠️ Unused: 3
❌ With errors: 4

⚠️  Unused sections:
  - sections/Example/Unused.tsx
  - sections/Test/OldComponent.tsx

❌ Sections with errors:
  - sections/Category/CategoryGrid.tsx (1 error(s))

Note: The script shows the path and line of the JSON file in clickable format (ex: .deco/blocks/pages-Lojas-735837.json:61). In most modern terminals (VSCode, Cursor, iTerm2), you can click directly on the link to open the file at the exact line of the problem.

Usage Examples

Validate all sections

deno task validate-blocks

Validate specific section during development

deno task validate-blocks sections/Header/Header.tsx

Validate specific loader

deno task validate-blocks loaders/Product/categoryTabs.ts

Show unused properties

# All sections with warnings for extra props
deno task validate-blocks -unused

# Specific section with warnings for extra props
deno task validate-blocks sections/Footer/Footer.tsx -unused

Portability

All code is organized in the src folder to facilitate migration to another repository.

Validate Blocks

Unused Detection Features

How to Run

Run directly (recommended)

Add as a deno task (optional)

Usage Examples

Validate all sections, loaders, and actions:

Validate a specific section:

Use custom blocks directory:

Available flags:

-unused

-blocks <path> or -b <path>

-rm-vars

-rm-sections

What it does

Features

Intelligent Props Detection

Deep Validation

Protections

Severity System

-report [path] or -r [path]

File Structure

Running Tests

Example Output

Usage Examples

Validate all sections

Validate specific section during development

Validate specific loader

Show unused properties

Portability

`-unused`

`-blocks <path>` or `-b <path>`

`-rm-vars`

`-rm-sections`

`-report [path]` or `-r [path]`