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

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @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

package/README.md

@@ -2,8 +2,11 @@
 
 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, and preserves source
-mappings for diagnostics and editor tooling.
+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
@@ -21,11 +24,31 @@ const result = compileSource({
 ```
 
 `compileSource` consumes only `DialectPlugin`; it does not branch on a database, grammar package,
-or driver. 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.
+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), and
+[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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"}