declarative-config

Declarative Configuration

Overview

When implementing validation rules, constraints, or configuration logic, prefer declarative data structures over hardcoded conditionals. This makes rules explicit, easier to maintain, and easier to track for removal.

Pattern

❌ WRONG: Hardcoded logic in config generator

// dependency-cruiser.config.mjs
const createPlaneRules = () => {
  for (const sourceGroup of moduleGroups) {
    if (sourceGroup.plane === 'migration') {
      for (const targetGroup of moduleGroups) {
        if (targetGroup.plane === 'runtime') {
          // Hardcoded exception check
          if (isCompatPrismaToSql(sourceGroup, targetGroup)) {
            continue;
          }
          pushRule(...);
        }
      }
    }
  }
};

✅ CORRECT: Declarative configuration

// architecture.config.json
{
  "planeRules": {
    "migration": {
      "forbid": ["runtime"],
      "exceptions": []
    }
  }
}

// dependency-cruiser.config.mjs
const createPlaneRules = () => {
  for (const [sourcePlaneName, planeRule] of Object.entries(planeRules)) {
    for (const forbiddenPlaneName of planeRule.forbid) {
      // Read from config, check exceptions declaratively
      const isException = planeRule.exceptions?.some((exception) => {
        return matchesGlobPattern(sourceGroup, exception.from) &&
               matchesGlobPattern(targetGroup, exception.to);
      });
      if (isException) continue;
      pushRule(...);
    }
  }
};

Benefits

1. Explicit: Rules and exceptions are visible in the config file
2. Maintainable: Easy to add/remove exceptions without code changes
3. Trackable: Exceptions include reasons and can be tracked for removal
4. Testable: Config can be validated independently of the generator logic

When to Use

• Validation rules with exceptions
• Constraint definitions (e.g., plane boundaries, layer rules)
• Configuration that changes frequently
• Rules that need to be documented and tracked