@typed-sql/compiler 1.0.0-rc.0 → 2.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # @typed-sql/compiler
 
+## 2.0.0-rc.1
+
+### Minor Changes
+
+- 9c72dab: Use live MySQL catalog origins to preserve enum result evidence, and compare parameter metadata in
+  the safe input direction so compiler-enforced literal subsets do not become false mismatches.
+
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 3f063f6: Add deterministic, secret-free query manifests with bounded structural variants, inferred result
+  and parameter descriptions, semantic evidence, runtime-correlatable fingerprints, unresolved
+  entries, compatible parsing, canonical serialization, incremental per-file reuse, tsconfig project
+  discovery, and a dedicated CLI command.
+- 6a7ae58: Add opt-in live query verification through grammar-owned PostgreSQL PREPARE and MySQL
+  COM_STMT_PREPARE adapters, bounded neutral comparison, deterministic secret-free proof artifacts,
+  offline cache validation, explicit unsupported classifications, CLI workflows, real database E2E,
+  and performance budgets.
+- 3050209: Add the dialect contract v4 semantic query evidence foundation. PostgreSQL and MySQL now report operation, dependencies, cardinality, volatility, locking, connection affinity, and required capabilities; compiler results add deterministic query and structural-variant fingerprints and conservatively merged source-mapped semantics. Schema snapshots can record function volatility, and the AST package exposes a neutral statement walker for grammar implementations.
+- b4f1b6e: Add deterministic migration compatibility analysis across before/after schema snapshots and query
+  manifests. Reports classify both rolling-deployment directions, retain exact source and dependency
+  evidence, fail closed for unknown semantics, redact defaults and paths, and support configurable CI
+  severity through `typed-sql compat`.
+- b2ec119: Add opt-in, grammar-neutral query-plan governance with PostgreSQL and MySQL structured EXPLAIN
+  adapters, transient application-owned samples, redacted fingerprint-keyed artifacts, absolute and
+  comparable regression budgets, explicit uncertainty, CLI capture and review, documentation, and
+  performance coverage.
+
+### Patch Changes
+
+- Updated dependencies [29afc3d]
+- Updated dependencies [3f063f6]
+- Updated dependencies [6a7ae58]
+- Updated dependencies [b06fd0a]
+- Updated dependencies [3050209]
+- Updated dependencies [1b054b6]
+- Updated dependencies [b4f1b6e]
+- Updated dependencies [87189c3]
+- Updated dependencies [e654fae]
+- Updated dependencies [b2ec119]
+  - @typed-sql/core@2.0.0-rc.0
+  - @typed-sql/schema@2.0.0-rc.0
+
+## 1.0.0
+
+### Major Changes
+
+- 7ca256b: Release the first public typed-sql beta: exact TypeScript 7 row inference from static PostgreSQL and
+  MySQL, versioned schema introspection, application-owned drivers, config-driven grammar plugins,
+  CLI verification, editor language-server integration, versioned diagnostics, bounded parsing, and
+  real-database plus packed-tarball verification.
+
+### Patch Changes
+
+- 1563a7a: Declare and enforce the 1.0 package stability boundary. Core SQL, compiler, schema, config, AST,
+  PostgreSQL, MySQL, and CLI packages form the stable train; the TypeScript preview bridge and
+  language server remain explicitly experimental. Freeze public entrypoints and query type contracts,
+  and remove internal compiler/type helpers from stable package-root exports before 1.0.
+- 16e2475: Prove npm trusted publishing and provenance after the initial registry bootstrap.
+- bd26d6e: Replace potentially expensive parser regular expressions with bounded scanners, tighten editor
+  completion matching, and prevent releases while high-severity CodeQL alerts remain open.
+- 69c7d87: Report `TSQ004` for bare nested templates used as conditional SQL structure and offer an alias-aware
+  language-server quick fix that prefixes the template with `sql.fragment`. Ordinary and nested
+  values remain parameterized across the edit.
+- 3e2c75c: Infer ordered query parameter tuples and let TypeScript reject interpolation values that do not
+  match their SQL context. Dialect contract version 2 adds explicit parameter analysis; unresolved
+  positions remain `unknown`. Add typed nullable predicate composition through `sql.fragment()`,
+  `sql.and()`, `sql.or()`, `sql.where()`, and `sql.append()` while preserving row and parameter tuples.
+  Direct append fragments are grammar-analyzed cumulatively against their static base, so TypeScript
+  rejects fragment interpolation values that disagree with the referenced database columns.
+  Add `sql.empty` and SQL-template-native conditional structural fragments. The compiler analyzes
+  complete branch variants, preserves literal boolean-dependent result rows, and type-checks nested
+  fragment parameters without adding a query-builder DSL. Bound independent structural expansion at
+  64 variants by default, correlate repeated conditions, merge diagnostics and fragment expectations
+  across variants, and fail closed on incompatible contexts. Share indexed catalog and conservative
+  parameter-resolution primitives across grammars, harden cooked-template scanning, and add runtime,
+  resolver, scanner, and structural performance gates.
+- Updated dependencies [eb16de7]
+- Updated dependencies [b6389e4]
+- Updated dependencies [eb16de7]
+- Updated dependencies [b6389e4]
+- Updated dependencies [eb16de7]
+- Updated dependencies [1563a7a]
+- Updated dependencies [9dd6bc4]
+- Updated dependencies [7ca256b]
+- Updated dependencies [16e2475]
+- Updated dependencies [69c7d87]
+- Updated dependencies [3e2c75c]
+  - @typed-sql/core@1.0.0
+
 ## 1.0.0-rc.0
 
 ### Patch Changes

package/README.md

@@ -1,15 +1,19 @@
 # @typed-sql/compiler
 
-The dialect-neutral TypeScript source compiler behind [typed-sql](https://github.com/Lojhan/typed-sql).
-It finds static SQL templates, asks the configured grammar for row and parameter shapes, injects them into
-an in-memory TypeScript program, and preserves source mappings for diagnostics and editor tooling.
+The stable, grammar-neutral TypeScript source compiler behind
+[typed-sql](https://github.com/Lojhan/typed-sql). It finds static SQL templates, asks the configured
+grammar for row and parameter shapes, creates an in-memory TypeScript overlay, preserves source
+mappings, emits deterministic query manifests, and compares them with grammar-owned native database
+evidence for CI and production correlation. It also compares before/after snapshots and manifests to
+find query-level migration breaks in both rolling-deployment directions, and captures fingerprint-keyed
+structured plans for explicit regression review.
 
 ```sh
-pnpm add @typed-sql/compiler@next
+pnpm add @typed-sql/compiler
 ```
 
 ```ts
-import { checkFile, compileSource, extractStaticQueries, mapSqlRange } from "@typed-sql/compiler";
+import { compileSource } from "@typed-sql/compiler";
 import { postgres } from "@typed-sql/postgres";
 
 const result = compileSource({
@@ -19,38 +23,32 @@ const result = compileSource({
 });
 ```
 
-`compileSource` does not branch on PostgreSQL, MySQL, package names, or database drivers. It only
-consumes the public `DialectPlugin` contract from `@typed-sql/core`. Unsupported, dynamic, invalid,
-or ambiguous SQL remains a diagnostic or an `unknown` position—never `any`. The resulting overlay
-uses `Query<Row, readonly [Param1, Param2, ...]>`, which lets TypeScript report incorrect `${...}`
-values at their original source locations.
-
-Direct `sql.append(base, ...fragments)` expressions are analyzed cumulatively. The compiler resolves
-the statically bound base query, adds each visible `sql.fragment` in source order, and injects the
-grammar-derived parameter tuple into that fragment. Composed values are therefore checked against
-their referenced columns even when a preceding fragment introduces structure such as
-`WHERE 1 = 1`. Indirect function-returned fragments and arbitrary mutable collections remain at the
-core runtime's parameter-safe boundary rather than being guessed.
-
-Structural fragment interpolations inside a complete `sql` template are expanded as correlated,
-finite branches. The compiler analyzes each resulting complete SQL statement, emits a conditional
-row for generic boolean property selections, and injects expected parameter types into nested
-fragments. `sql.empty` represents the absent branch without turning it into a driver parameter.
-The expansion is a grammar-neutral intermediate representation: SQL parsing and resolution still
-belong exclusively to `DialectPlugin.analyze()`.
-
-`compileSource` accepts `maxStructuralVariants`, defaulting to 64. The compiler counts independent
-conditions and returns `TSQ003` before invoking the grammar when the bound would be exceeded.
-Repeated uses of the same condition are correlated and do not multiply the branch count. A shared
-fragment that receives incompatible parameter expectations across valid branches fails closed with
-`TSQ205`.
-
-Before grammar analysis, the scanner rejects an untagged template paired with `sql.empty` or a
-trusted fragment as `TSQ004`. This produces one focused source diagnostic instead of a downstream
-SQL parse error. Ordinary value templates remain parameters; the compiler never interprets their
-runtime strings as SQL structure.
-
-Application projects normally use this through `typed-sql check` or the language server. It is
-public for grammar, editor, and build-tool integrations.
+`compileSource` consumes only `DialectPlugin`; it does not branch on a database, grammar package,
+or driver. Compiled queries expose path-independent SHA-256 fingerprints, variant fingerprints,
+variant descriptions, and source-mapped semantics merged conservatively across conditional
+structure. `buildQueryManifest` turns the same evidence into canonical, secret-free JSON without
+generating an application API. Its public options include the structural-variant bound used for
+conditional fragments. Application projects normally use the compiler through `typed-sql check`
+or the language server.
+
+Live verification APIs collect transient SQL only after sources still match the manifest, schedule
+grammar-owned adapters with bounded concurrency, compare native field evidence, and emit canonical
+proofs that contain no SQL, values, URLs, absolute paths, or driver errors.
+
+Plan-governance APIs schedule grammar-owned inspectors, normalize redacted plan evidence, and apply
+absolute or environment-comparable relative budgets. Version, schema, settings, statistics, and sample
+changes remain explicit uncertainty instead of being treated as a pass.
+
+Migration compatibility APIs consume deterministic artifacts only. They classify source, runtime,
+deployment-order, compatible, and unknown outcomes; link affected variants to source and dependency
+ranges; and emit canonical reports without SQL, default expressions, credentials, or absolute paths.
+
+Read [Architecture](https://github.com/Lojhan/typed-sql/blob/main/docs/concepts/architecture.md),
+[Compose conditional SQL](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/composition.md),
+[Query manifests](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/query-manifests.md), and
+[Live verification](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/live-verification.md),
+[Query plan governance](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/query-plan-governance.md),
+[Migration compatibility](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/migration-compatibility.md), and
+[Inference and safety](https://github.com/Lojhan/typed-sql/blob/main/docs/concepts/type-safety.md).
 
 MIT © typed-sql contributors

package/dist/packages/compiler/src/compatibility.d.ts

@@ -0,0 +1,66 @@
+import type { SchemaSnapshot, SourceRange } from "@typed-sql/core";
+import type { QueryManifest, QueryManifestLocation } from "./manifest.js";
+export declare const SCHEMA_COMPATIBILITY_FORMAT_VERSION: 1;
+export declare const SCHEMA_COMPATIBILITY_ANALYZER_VERSION: "typed-sql-v1";
+export type DeploymentDirection = "before-app-after-database" | "after-app-before-database";
+export type CompatibilityClassification = "compatible" | "deployment-order-sensitive" | "source-breaking" | "runtime-breaking" | "unknown";
+export type CompatibilitySeverity = "info" | "warning" | "error";
+export type SchemaCompatibilityChangeKind = "relation-added" | "relation-removed" | "column-added" | "column-removed" | "column-database-type" | "column-typescript-type" | "column-nullability" | "column-array" | "column-default" | "enum-added" | "enum-removed" | "enum-values" | "domain-added" | "domain-removed" | "domain-database-type" | "domain-typescript-type" | "domain-nullability" | "function-added" | "function-removed" | "function-return-type" | "function-nullability" | "function-set-returning" | "function-volatility" | "dialect-version" | "server-version" | "query-contract";
+export interface SchemaCompatibilityTarget {
+    readonly kind: "schema" | "relation" | "column" | "enum" | "domain" | "function" | "query";
+    readonly key: string;
+    readonly name: string;
+    readonly schema?: string;
+    readonly parent?: string;
+}
+export type CompatibilityEvidenceValue = string | boolean | null | readonly string[];
+export type CompatibilityEvidence = Readonly<Record<string, CompatibilityEvidenceValue>>;
+export interface SchemaCompatibilityChange {
+    readonly id: string;
+    readonly kind: SchemaCompatibilityChangeKind;
+    readonly target: SchemaCompatibilityTarget;
+    readonly before?: CompatibilityEvidence;
+    readonly after?: CompatibilityEvidence;
+}
+export interface CompatibilityQueryReference {
+    readonly queryId: string;
+    readonly variantFingerprint: string;
+    readonly source: QueryManifestLocation;
+    readonly dependencyRange?: SourceRange;
+}
+export interface SchemaCompatibilityAssessment {
+    readonly direction: DeploymentDirection;
+    readonly changeId?: string;
+    readonly classification: CompatibilityClassification;
+    readonly severity: CompatibilitySeverity;
+    readonly reason: string;
+    readonly queries: readonly CompatibilityQueryReference[];
+}
+export interface SchemaCompatibilityReport {
+    readonly formatVersion: typeof SCHEMA_COMPATIBILITY_FORMAT_VERSION;
+    readonly analyzerVersion: typeof SCHEMA_COMPATIBILITY_ANALYZER_VERSION;
+    readonly dialect: string;
+    readonly before: {
+        readonly schemaHash: string;
+        readonly manifestHash: string;
+        readonly version?: string;
+    };
+    readonly after: {
+        readonly schemaHash: string;
+        readonly manifestHash: string;
+        readonly version?: string;
+    };
+    readonly changes: readonly SchemaCompatibilityChange[];
+    readonly assessments: readonly SchemaCompatibilityAssessment[];
+    readonly summary: Readonly<Record<CompatibilitySeverity, number>>;
+}
+export interface AnalyzeSchemaCompatibilityOptions {
+    readonly before: SchemaSnapshot;
+    readonly after: SchemaSnapshot;
+    readonly beforeManifest: QueryManifest;
+    readonly afterManifest: QueryManifest;
+}
+export declare function analyzeSchemaCompatibility(options: AnalyzeSchemaCompatibilityOptions): SchemaCompatibilityReport;
+export declare function serializeSchemaCompatibilityReport(report: SchemaCompatibilityReport): string;
+export declare function parseSchemaCompatibilityReport(value: unknown): SchemaCompatibilityReport;
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/packages/compiler/src/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../../../src/compatibility.ts"],"names":[],"mappings":"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"}