no-target-branches

No Target-Specific Branches

CRITICAL: Never name a target in target-agnostic code. This covers two forms of the same mistake: branching on a target value, and embedding target-named constants, helpers, or data in framework/core packages. Target-specific logic and target-specific facts belong in adapters and target packages.

❌ WRONG: Branch on target in core packages

function canonicalizeColumnType(scalar: string, target: string): string {
  if (target === 'postgres') {
    const scalarMap: Record<string, string> = {
      int4: 'pg/int4@1',
      text: 'pg/text@1',
    };
    return scalarMap[scalar] ?? scalar;
  }
  return scalar;
}

✅ CORRECT: Put target-specific logic behind an adapter interface

interface Adapter {
  canonicalizeType(scalar: string): string;
}

class PostgresAdapter implements Adapter {
  canonicalizeType(scalar: string): string {
    const scalarMap: Record<string, string> = {
      int4: 'pg/int4@1',
      text: 'pg/text@1',
    };
    return scalarMap[scalar] ?? scalar;
  }
}

Named-target constants and data are the same violation

The branch is the obvious form. The subtler form is a target-agnostic package that names a target in a constant, a helper name, or static data — even with no if in sight. A POSTGRES_DEFAULT_NAMESPACE_ID constant or a defaultNamespaceIdForSqlTarget() helper sitting in the framework core is just a branch that has been pre-evaluated: the framework now knows a Postgres-specific fact.

❌ WRONG: Target-named constant / helper in a target-agnostic package

// in packages/1-framework/** (target-agnostic)
export const POSTGRES_DEFAULT_NAMESPACE_ID = 'public';

export function defaultNamespaceIdForSqlTarget(targetId: string): string {
  return targetId === 'postgres' ? 'public' : '__unbound__';
}

✅ CORRECT: The target declares the fact on its descriptor; the framework reads it generically

// in the target package's descriptor (static data the target owns)
const postgresDescriptorMeta = {
  // …
  defaultNamespaceId: 'public',
};

// in the target-agnostic consumer — reads the fact, never names the target
const defaultNamespaceId = target.defaultNamespaceId;