External foundations (RC6) + Unified Types (Bridge) + DSL/CLI rework + site overhaul

[oyvindberg]

Summary

This PR is one tightly-coupled chunk of work — every layer touches every other, so it didn't split cleanly. The pieces:

1. foundations becomes external (RC6)

foundations-jdbc{,-dsl,-hikari,-scala,-kotlin} were in-repo bleep projects. They're now published as dev.typr.foundations:*:1.0.0-RC6 and the in-repo modules are deleted. Foundations itself reshaped on the way out:

• Connection (writable) split from ConnectionRead (read-only).
• Sealed Operation / OperationRead hierarchy. OperationRead declares run(ConnectionRead) and overrides run(Connection) so Scala 3's overload resolver picks the most-specific candidate without ambiguity.
• Kotlin wrapper exposes Bijection.of publicly and exposes Connection.javaConnection so typr-dsl-kotlin can unwrap when delegating.

2. Codegen rewrite

DbLibFoundations.scala (~2400 LOC) rebuilt around the Connection split:

• Read methods take (using c: ConnectionRead); write methods take (using c: Connection).
• Single runOn(connParam) helper emits .run(using c) (Scala) or .run(c) (Java/Kotlin) via jvm.ApplyNullary.
• dbTypeArray now generated as pgType.array() (PG) / duckDbType.list() (DuckDB) — the inner Bijection is reused rather than duplicated. pgType emitted before pgTypeArray to satisfy Java's static-field forward-reference rule.

Six new database adapters replace inline dialect logic: PostgresAdapter, OracleAdapter, MariaDbAdapter, DuckDbAdapter, SqlServerAdapter, Db2Adapter — each ~250–350 LOC, centralising quoting, type casting, null-safe equality (IS NOT DISTINCT FROM, <=>, IS b), and pagination.

db.scala (~530 LOC) defines a typed model of every DB column type. FilePreciseType (~2200 LOC) and FilePgCompositeType (~250 LOC) handle precise-type and composite-type rendering.

3. Unified Types / Bridge — headline feature

New typr/src/scala/typr/bridge/ tree introduces the domain model:

• Model: DomainTypeDefinition, DomainField, PrimarySource, AlignedSource, FieldOverride (Forward / Drop / MergeFrom / SplitFrom / ComputedFrom / Enrichment), TypePolicy (Exact / AllowWidening / AllowNarrowing / AllowPrecisionLoss / AllowTruncation / AllowNullableToRequired), CompatibilityMode (Exact / Superset / Subset).
• Validation: FlowValidator, TypePolicyValidator, SmartDefaults.
• Public API: BridgeApi.{check, resolveFlows}.
• Inference: ColumnTokenizer, ColumnStemmer, ColumnGrouper, TypeSuggester, CompositeTypeSuggester. Suggests domain types from column naming patterns across sources.
• Codegen: FileBridgeCompositeType (record + JSON codecs), FileBridgeProjectionMapper (fromXxx / toXxx mappers per aligned source).
• External-record adapters: BridgeAvroAdapter, BridgeProtoAdapter translate ComputedAvroRecord / proto messages into Bridge's ExternalRecord so domain types align across DB rows, OpenAPI models, Avro records, and gRPC messages alike.

Tests at tests/src/scala/typr/bridge/ (~67 cases / 1k LOC): FlowValidatorTest, SmartDefaultsTest, TypePolicyValidatorTest, TypeNarrowerIntegrationTest.

4. typr DSL renamed and expanded

foundations-jdbc-dsl{,-scala,-kotlin} → typr-dsl{,-scala,-kotlin}, significantly expanded.

• Java core (~3.5k LOC): Dialect.java (~860 LOC) with unified null-safe operators, per-dialect pagination, composite-type support; SelectBuilder, DeleteBuilder, UpdateBuilder, GroupedBuilder, SqlExpr, RenderCtx, GenericDbTypes, RowCodecDbType.
• Scala wrapper (~1.5k LOC) and Kotlin wrapper (~1k LOC) as separate published artifacts.

5. CLI tool

typr/src/scala/typr/cli/ rewritten. Main.scala exposes:

• generate — two-phase parallel pipeline across six boundary kinds (Database, DuckDB, OpenAPI, JSON Schema, Avro, gRPC) with a per-output progress tracker.
• watch — re-runs Generate on schema/SQL changes.
• check — validates that domain types align across configured sources via BridgeApi.

TyprConfig (circe-driven) accepts both legacy boundaries: and new sources: keys, loads types: for Bridge domain types, and supports ${ENV_VAR} substitution.

New helpers: ConfigParser, ConfigToOptions, ConfigWriter, EnvSubstitution, PatternMatcher (glob → typr.Selector), SourceEntityLoader, ProjectionFieldFormat.

6. Boundary expansion: OpenAPI, Avro, gRPC

OpenAPI: full parser/computed/codegen split — OpenApiParser, ModelExtractor, TypeResolver, SpecValidator → computed ApiService/Endpoint/Model/Parameter/Property → OpenApiCodegen/ModelCodegen/ApiCodegen. JSON Schema added alongside (JsonSchemaParser, JsonSchemaCodegen).

Avro: parallel computed-types layer (ComputedAvroRecord, ComputedAvroField, ComputedProtocol, ComputedEventGroup) plus KafkaFrameworkCats for Cats Effect.

gRPC: ComputedGrpcMethod, ComputedGrpcService, GrpcFrameworkCats.

New boundaries/ framework abstraction replaces ad-hoc per-framework branching: Framework → HttpFramework / MessagingFramework / RpcFramework → SpringFramework / QuarkusFramework / CatsFramework.

7. Build tool: Gradle → Bleep

Rewrote the Kotlin build from Gradle to Bleep. Single-tool monorepo, one project list, one compile graph across Java / Kotlin / Scala / Scala-2.13 cross-builds.

Note: bleep is currently pinned to 1.0.0-M3. Will bump to the latest bleep release before merge.

8. Documentation site overhaul

Site rebuilt around the new "every boundary, unified" narrative.

• docusaurus.config.js collapses to a single /typr/ route served from site/docs-typr/.
• 75 newly-written pages: Unified Types tutorials, Databases (setup + type-safety + customization + patterns + advanced + testing), REST APIs, Events with Kafka producers/consumers/RPC + type-safety.
• Sidebar (sidebars-typr.js, ~200 LOC, 68 entries grouped by boundary).
• Landing page (site/src/pages/index.js) replaced wholesale with an Engineering Blueprint × Editorial Print theme: cream paper, deep ink, vermillion accent; Fraunces (variable serif), Bricolage Grotesque (variable grotesque), JetBrains Mono. Manifesto section ships with a real drafting-table schematic of the unified-types story (domain card, four boundary stations with policy chips, orthogonal connectors, dimensional callouts, register marks, title block).
• The same theme is applied site-wide via site/src/css/custom.css (~370 lines of overrides) so every docs page matches.
• New components: BoundaryDiagram, CodeSample, ShowcaseSnippet, StackSelector, UsageExample, TypoLogo.
• Showcase pipeline (site/scripts/extract-snippets.js + generate-showcase bleep script + site/showcase-generated/) lets docs reference real generated code by stable markers, so doc snippets stay in sync with what the generator actually produces.
• site/usage-examples/ hosts cross-language runnable examples (Java/Kotlin/Scala) shown inline.

9. Tester sweeps & misc

• oracle/scala tests use summon[Connection] after the context-function conversion of withConnection helpers.
• sqlserver tests use compareToIgnoreCase to match SQL Server's CI collation under READ_UNCOMMITTED parallel runs.
• Per-test-class distinct Random seeds (hashed file paths → 31-bit) to dodge MariaDB deadlocks from shared-seed parallelism.
• .javafmt.conf added at repo root to skip **/generated-and-checked-in/** from Java formatting.
• testers/combined/{java,kotlin} added — bundle Avro+Kafka+Mutiny+REST in one tester to exercise cross-boundary type unification.
• New per-DB Kotlin testers (testers/{db2,duckdb,mariadb}/kotlin) under template-kotlin-db-tester.

---

Why one PR

The foundations split forces the codegen rewrite, the codegen rewrite enables the Connection/ConnectionRead split, that split surfaces in every generated repo across every tester, the Bridge work needs new computed-type layers in OpenAPI/Avro/gRPC and new file generators in codegen, the new boundary types need Kafka/Avro/Mutiny deps, and the site is rewritten to document the unified result. Splitting cleanly was not practical.

Test plan

• bleep --no-color compile — all 79 projects compile (0 failed, 0 skipped)
• bleep --no-color run typr -- generate — all 36 outputs regenerate cleanly
• bleep --no-color test — full test suite with restarted containers (sqlserver in isolation: 243/243 passing)
• Docusaurus dev server runs cleanly and renders the new theme in light + dark mode

🤖 Generated with Claude Code