feat: custom type mapping configuration (v1.1.0)

Add TypeConfig class allowing users to override default type mappings
per format via YAML/JSON config files with template variable support.

- TypeConfig: load from .yaml/.yml/.json, merge, template variable
  resolution ({length}, {precision}, {scale}, {values})
- CLI: --type-map option for schemaforge convert
- All 7 generators (SQL, Prisma, Drizzle, TypeORM, Django, SQLAlchemy,
  Alembic) forward type_config through resolve_type/build_type_string
- has_type_override helper lets generators skip special-case formatting
  when an override is active
- 282-line test suite: unit tests, file loading, merge, integration
  tests across 3 formats, roundtrip fidelity verification
- Sample fixture: fixtures/sample-type-overrides.yaml
- 160/160 tests passing

Author: Coding-Dev-Tools

README.md

@@ -191,6 +191,48 @@ Each fixture demonstrates the same blog schema so you can compare ORM syntax sid
 - **Inline ENUM** — `ENUM('small', 'medium', 'large')` column types parsed and roundtripped
 - **Relation preservation** — indexes, unique constraints maintained across all conversions
 - **Custom type handling** — dialect-specific types (JSONB, etc.) pass through via CUSTOM type
+- **Custom type mapping overrides** — override type mappings per format with YAML/JSON config files
+
+## Custom Type Mappings
+
+Override the default type mappings with a YAML or JSON configuration file. This is useful when you need format-specific types not covered by the defaults.
+
+### Config file format
+
+```yaml
+# schemaforge-types.yaml
+overrides:
+  sql:
+    STRING: "VARCHAR({length})"
+    UUID: "UUID"
+  prisma:
+    STRING: "String @db.VarChar({length})"
+    UUID: "String @uuid"
+  sqlalchemy:
+    STRING: "Unicode({length})"
+    UUID: "Uuid"
+  django:
+    STRING: "CharField(max_length={length})"
+  typeorm:
+    UUID: "uuid"
+```
+
+**Placeholders:** `{length}`, `{precision}`, `{scale}`, `{values}` — these are replaced with the column's type arguments when generating.
+
+### Usage
+
+```bash
+schemaforge convert --from sql --to prisma --input schema.sql --type-map schemaforge-types.yaml
+schemaforge convert --from sql --to sqlalchemy --input schema.sql --type-map my-types.json
+```
+
+A sample config file is provided at `fixtures/sample-type-overrides.yaml`.
+
+### Override precedence
+
+1. Custom type overrides from `--type-map` config file take highest priority
+2. Built-in type mappings in each generator are the fallback
+3. `ColumnType.CUSTOM` with explicit `custom_type` always passes through directly
 
 ## Roadmap
 

fixtures/sample-type-overrides.yaml

@@ -0,0 +1,38 @@
+# SchemaForge Custom Type Mapping Configuration
+# 
+# Override default type mappings per format.
+# Placeholders: {length}, {precision}, {scale}, {values}
+#
+# Usage: schemaforge convert --from sql --to prisma --input schema.sql --type-map schemaforge-types.yaml
+
+overrides:
+  # SQL DDL — use VARCHAR for all strings instead of TEXT fallback
+  sql:
+    STRING: "VARCHAR({length})"
+    UUID: "UUID"
+    DATETIME: "TIMESTAMP"
+
+  # Prisma — custom type annotations
+  prisma:
+    STRING: "String @db.VarChar({length})"
+    UUID: "String @uuid"
+    DECIMAL: "Decimal"
+    DATETIME: "DateTime @db.Timestamp"
+
+  # SQLAlchemy — use Unicode instead of String
+  sqlalchemy:
+    STRING: "Unicode({length})"
+    UUID: "Uuid"
+    DATETIME: "DateTime(timezone=True)"
+
+  # Django — custom field types
+  django:
+    STRING: "CharField(max_length={length})"
+    UUID: "UUIDField"
+    DATETIME: "DateTimeField(auto_now_add=True)"
+
+  # TypeORM — custom column types
+  typeorm:
+    STRING: "varchar"
+    UUID: "uuid"
+    DATETIME: "timestamptz"

src/schemaforge/cli.py

@@ -8,15 +8,16 @@
 
 from .convert import convert_schema
 from .diff import diff_schemas
+from .type_config import TypeConfig
 
 
 @click.group()
 @click.version_option()
 def main() -> None:
     """SchemaForge — bidirectional ORM schema converter.
 
-    Convert between SQL DDL, Prisma, Drizzle, TypeORM, and Django models
-    with zero-loss roundtripping.
+    Convert between SQL DDL, Prisma, Drizzle, TypeORM, Django, SQLAlchemy models,
+    and Alembic migration scripts with zero-loss roundtripping.
     """
 
 
@@ -33,11 +34,24 @@ def main() -> None:
 @click.option("--output", "-o", "output_path",
               type=click.Path(writable=True),
               help="Output file path (default: stdout)")
-def convert(from_fmt: str, to_fmt: str, input_path: str, output_path: str | None) -> None:
+@click.option("--type-map", "type_map_path",
+              type=click.Path(exists=True, readable=True),
+              help="Custom type mapping config file (.yaml or .json)")
+def convert(from_fmt: str, to_fmt: str, input_path: str,
+            output_path: str | None, type_map_path: str | None) -> None:
     """Convert schema between formats."""
+    # Load custom type mapping if specified
+    type_config: TypeConfig | None = None
+    if type_map_path:
+        try:
+            type_config = TypeConfig.from_file(type_map_path)
+        except (FileNotFoundError, ValueError, ImportError) as e:
+            click.echo(f"Error loading type map: {e}", err=True)
+            sys.exit(1)
+
     input_text = Path(input_path).read_text(encoding="utf-8")
     try:
-        result = convert_schema(input_text, from_fmt, to_fmt)
+        result = convert_schema(input_text, from_fmt, to_fmt, type_config=type_config)
     except ValueError as e:
         click.echo(f"Error: {e}", err=True)
         sys.exit(1)

src/schemaforge/convert.py

@@ -1,6 +1,8 @@
 """Schema conversion: all format pairs via the IR."""
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
 from .ir import Schema
 from .parsers.sql_parser import SQLParser
 from .generators.sql_generator import SQLGenerator
@@ -17,6 +19,9 @@
 from .parsers.alembic_parser import AlembicParser
 from .generators.alembic_generator import AlembicGenerator
 
+if TYPE_CHECKING:
+    from .type_config import TypeConfig
+
 
 _registry: dict[str, tuple[type, type]] = {
     "sql": (SQLParser, SQLGenerator),
@@ -29,8 +34,26 @@
 }
 
 
-def convert_schema(input_text: str, from_fmt: str, to_fmt: str) -> str:
-    """Convert schema text from one format to another via the IR."""
+def convert_schema(
+    input_text: str,
+    from_fmt: str,
+    to_fmt: str,
+    type_config: TypeConfig | None = None,
+) -> str:
+    """Convert schema text from one format to another via the IR.
+
+    Args:
+        input_text: Schema text in the source format.
+        from_fmt: Source format name (e.g. 'sql', 'prisma').
+        to_fmt: Target format name (e.g. 'django', 'alembic').
+        type_config: Optional type mapping overrides.
+
+    Returns:
+        Schema text in the target format.
+
+    Raises:
+        ValueError: If either format is not supported.
+    """
     if from_fmt == to_fmt:
         return input_text
 
@@ -45,7 +68,7 @@ def convert_schema(input_text: str, from_fmt: str, to_fmt: str) -> str:
     parser = parser_cls()
     schema = parser.parse(input_text)
 
-    generator = generator_cls()
+    generator = generator_cls(type_config=type_config)
     return generator.generate(schema)
 
 

src/schemaforge/generators/_base.py

@@ -5,20 +5,63 @@
 """
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
 from ..ir import Column, ColumnType
 
+if TYPE_CHECKING:
+    from ..type_config import TypeConfig
+
 
-def resolve_type(col: Column, type_map: dict[ColumnType, str]) -> str:
+def resolve_type(
+    col: Column,
+    type_map: dict[ColumnType, str],
+    *,
+    fmt: str = "",
+    type_config: TypeConfig | None = None,
+) -> str:
     """Resolve a column's base type string from the type map.
 
-    Handles CUSTOM types (drops through to col.custom_type)
-    and unknown types (falls back to "String").
+    Handles CUSTOM types (drops through to col.custom_type),
+    custom type overrides from TypeConfig, and unknown types
+    (falls back to "String").
+
+    Args:
+        col: The column to resolve.
+        type_map: Default ColumnType → format-specific type string mapping.
+        fmt: Format name for TypeConfig override lookup (e.g. 'sql').
+        type_config: Optional custom type overrides.
+
+    Returns:
+        Format-specific type string.
     """
+    # CUSTOM type takes priority
     if col.type == ColumnType.CUSTOM and col.custom_type:
         return col.custom_type
+
+    # Check TypeConfig overrides first (full resolution including type_args)
+    if type_config and fmt:
+        overridden = type_config.get_override(col, fmt)
+        if overridden:
+            return overridden
+
     return type_map.get(col.type, "String")
 
 
+def has_type_override(col: Column, fmt: str, type_config: TypeConfig | None) -> bool:
+    """Check if a column has a custom type override for a given format.
+
+    Generators can use this to skip their special-case formatting
+    when an override is active (e.g. String with @db.VarChar).
+    """
+    if not type_config or not fmt:
+        return False
+    fmt_overrides = type_config._overrides.get(fmt)  # type: ignore[union-attr]
+    if not fmt_overrides:
+        return False
+    return col.type.name in fmt_overrides
+
+
 def build_type_string(
     col: Column,
     type_map: dict[ColumnType, str],
@@ -30,6 +73,8 @@ def build_type_string(
     decimal_precision: int = 10,
     decimal_scale: int = 2,
     enum_fmt: str = "Enum({})",
+    fmt: str = "",
+    type_config: TypeConfig | None = None,
 ) -> str:
     """Build a full type string including type arguments.
 
@@ -49,11 +94,13 @@ def build_type_string(
         decimal_scale: Default scale when not in type_args.
         enum_fmt: Format for inline ENUM values (e.g. 'Enum({})' for
             'Enum(small, medium, large)').
+        fmt: Format name for TypeConfig override lookup (e.g. 'sql').
+        type_config: Optional custom type overrides.
 
     Returns:
         Full type string (e.g. 'VARCHAR(255)', 'Numeric(10, 2)').
     """
-    base = resolve_type(col, type_map)
+    base = resolve_type(col, type_map, fmt=fmt, type_config=type_config)
 
     if col.type == ColumnType.STRING and "length" in col.type_args:
         return string_fmt.format(base, col.type_args["length"])

src/schemaforge/generators/alembic_generator.py

@@ -8,11 +8,16 @@
 from ..ir import Schema, Column, ColumnType, Table
 
 from ._base import resolve_type, build_type_string, resolve_fn_default, format_literal_default
+from ..type_config import TypeConfig
 
 
 class AlembicGenerator:
     """Convert Schema IR to an Alembic migration script."""
 
+    def __init__(self, type_config: TypeConfig | None = None) -> None:
+        """Initialize with optional custom type overrides."""
+        self._type_config = type_config
+
     _TYPE_MAP: dict[ColumnType, str] = {
         ColumnType.STRING: "sa.String",
         ColumnType.INTEGER: "sa.Integer",
@@ -166,6 +171,8 @@ def _column_def(self, col: Column) -> str:
             decimal_precision=10,
             decimal_scale=2,
             enum_fmt="{}({})",
+            fmt="alembic",
+            type_config=self._type_config,
         )
 
         kwargs: list[str] = [sa_type]

src/schemaforge/generators/django_generator.py

@@ -4,11 +4,16 @@
 from ..ir import Schema, Column, ColumnType
 
 from ._base import resolve_type
+from ..type_config import TypeConfig
 
 
 class DjangoGenerator:
     """Convert Schema IR to Django model Python format."""
 
+    def __init__(self, type_config: TypeConfig | None = None) -> None:
+        """Initialize with optional custom type overrides."""
+        self._type_config = type_config
+
     _FIELD_MAP: dict[ColumnType, str] = {
         ColumnType.STRING: "CharField",
         ColumnType.INTEGER: "IntegerField",
@@ -98,7 +103,7 @@ def _generate_model(self, table) -> str:
 
     def _field_def(self, col: Column) -> str:
         """Generate a Django model field definition."""
-        django_field = resolve_type(col, self._FIELD_MAP)
+        django_field = resolve_type(col, self._FIELD_MAP, fmt="django", type_config=self._type_config)
         if not django_field.endswith("Field"):
             django_field = django_field + "Field"
 

src/schemaforge/generators/drizzle_generator.py

@@ -4,6 +4,7 @@
 from ..ir import Schema, Table, Column, ColumnType, EnumType, Index
 
 from ._base import resolve_fn_default
+from ..type_config import TypeConfig
 
 
 # ColumnType -> Drizzle type function mapping
@@ -28,9 +29,15 @@
 class DrizzleGenerator:
     """Generate Drizzle ORM TypeScript schema from Schema IR."""
 
-    def __init__(self, dialect: str = "pg") -> None:
-        """Initialize with dialect (pg, mysql, or sqlite)."""
+    def __init__(self, dialect: str = "pg", type_config: TypeConfig | None = None) -> None:
+        """Initialize with dialect and optional custom type overrides.
+
+        Args:
+            dialect: Database dialect ('pg', 'mysql', or 'sqlite').
+            type_config: Optional custom type mapping overrides.
+        """
         self.dialect = dialect
+        self._type_config = type_config
 
     def generate(self, schema: Schema) -> str:
         lines: list[str] = []

src/schemaforge/generators/prisma_generator.py

@@ -3,12 +3,17 @@
 
 from ..ir import Schema, Column, ColumnType
 
-from ._base import resolve_type, build_type_string, resolve_fn_default
+from ._base import resolve_type, build_type_string, resolve_fn_default, has_type_override
+from ..type_config import TypeConfig
 
 
 class PrismaGenerator:
     """Convert Schema IR to Prisma schema format."""
 
+    def __init__(self, type_config: TypeConfig | None = None) -> None:
+        """Initialize with optional custom type overrides."""
+        self._type_config = type_config
+
     _TYPE_MAP = {
         ColumnType.STRING: "String",
         ColumnType.INTEGER: "Int",
@@ -60,10 +65,11 @@ def _generate_model(self, table) -> str:
 
     def _field_def(self, col: Column) -> str:
         """Generate a Prisma field definition."""
-        prisma_type = resolve_type(col, self._TYPE_MAP)
+        prisma_type = resolve_type(col, self._TYPE_MAP, fmt="prisma", type_config=self._type_config)
 
-        # Handle String with length (Prisma uses @db.VarChar)
-        if col.type == ColumnType.STRING and "length" in col.type_args:
+        # Handle String with length (Prisma uses @db.VarChar) — skip if overridden
+        if col.type == ColumnType.STRING and "length" in col.type_args \
+                and not has_type_override(col, "prisma", self._type_config):
             prisma_type = f"String @db.VarChar({col.type_args['length']})"
 
         annotations: list[str] = []