feat: implement generic module contract verification library

Author: bbopen

README.md

@@ -13,5 +13,42 @@ gleam add gleam_contracts
 
 ## Usage
 
-See [SPEC.md](SPEC.md) for the complete technical specification.
+Create a contract check entrypoint in your package:
 
+```gleam
+import gleam_contracts
+import gleam_contracts/rule
+
+pub fn main() {
+  gleam_contracts.check(
+    interface_path: "build/dev/docs/my_package/package-interface.json",
+    rules: [
+      gleam_contracts.mirror_rule(
+        source: "my_package/headless/button",
+        target: "my_package/button",
+        prefix_params: [rule.Labeled(label: "context")],
+      )
+        |> gleam_contracts.with_exceptions(exceptions: ["button"]),
+      gleam_contracts.shared_types(
+        module_a: "my_package/headless/button",
+        module_b: "my_package/button",
+        type_names: ["ButtonConfig"],
+      ),
+    ],
+  )
+}
+```
+
+Then run it in your build chain:
+
+```sh
+gleam export package-interface --out build/dev/docs/my_package/package-interface.json
+gleam run -m contract_test
+```
+
+Dogfooding belongs in the consuming package repository. Keep any stack-specific
+contract rules and CI wiring in that consumer repo rather than this library.
+
+## Spec
+
+See [SPEC.md](SPEC.md) for the full technical specification.

SPEC.md

@@ -21,7 +21,7 @@ Today this is caught by manual review or by users who discover the gap.
 - Run as a verification gate in CI, like `gleam format --check` or grep-gates
 - Provide clear, actionable error messages identifying exactly which function
   is missing or which parameter doesn't match
-- Work with any Gleam package, not just weft_lustre_ui
+- Work with any Gleam package
 - Stay pure Gleam, cross-target compatible
 
 ## Non-Goals
@@ -94,6 +94,12 @@ pub type ExportSpec {
   )
 }
 
+/// Errors produced while loading package-interface JSON.
+pub type LoadError {
+  ReadError(path: String, reason: simplifile.FileError)
+  DecodeError(path: String, reason: json.DecodeError)
+}
+
 /// A single contract violation.
 pub type Violation {
   /// Function exists in source but not in target.
@@ -132,6 +138,11 @@ pub type Violation {
   ModuleNotFound(
     module: String,
   )
+  /// Package-interface file could not be loaded.
+  InterfaceLoadFailure(
+    path: String,
+    error: LoadError,
+  )
 }
 
 /// Verification result.
@@ -145,7 +156,7 @@ pub type ContractResult =
 /// Load and decode a package interface from a JSON file path.
 pub fn load_package_interface(
   path path: String,
-) -> Result(PackageInterface, String)
+) -> Result(PackageInterface, LoadError)
 
 /// Verify a list of rules against a package interface.
 /// Returns Ok(Nil) if all rules pass, or Error with a list
@@ -159,6 +170,12 @@ pub fn verify(
 pub fn format_violations(
   violations violations: List(Violation),
 ) -> String
+
+/// Load interface and verify rules in one call.
+pub fn check_result(
+  interface_path interface_path: String,
+  rules rules: List(Rule),
+) -> ContractResult
 ```
 
 ### Rule Constructors
@@ -168,7 +185,7 @@ pub fn format_violations(
 /// public functions, each gaining the specified prefix parameters.
 ///
 /// Example: headless badge -> styled badge, where styled adds
-/// a leading `theme` parameter.
+/// a leading `context` parameter.
 pub fn mirror_rule(
   source source: String,
   target target: String,
@@ -200,13 +217,10 @@ pub fn shared_types(
 ### Convenience
 
 ```gleam
-/// Shorthand for [Labeled("theme")] — the common prefix for
-/// styled wrappers.
-pub fn theme_prefix() -> List(ParamSpec)
-
-/// Load interface from default path and verify rules in one call.
-/// Exits with code 1 and prints violations if any are found.
-/// Intended for use in scripts/check.sh.
+/// Print violations for terminal usage.
+///
+/// `check` is a convenience wrapper around `check_result`.
+/// It does not force a process exit.
 pub fn check(
   interface_path interface_path: String,
   rules rules: List(Rule),
@@ -231,6 +245,7 @@ creates a verification entry point:
 ```gleam
 // test/contract_test.gleam (or a standalone script)
 import gleam_contracts
+import gleam_contracts/rule
 
 pub fn main() {
   gleam_contracts.check(
@@ -239,12 +254,12 @@ pub fn main() {
       gleam_contracts.mirror_rule(
         source: "my_package/headless/badge",
         target: "my_package/badge",
-        prefix_params: gleam_contracts.theme_prefix(),
+        prefix_params: [rule.Labeled(label: "context")],
       ),
       gleam_contracts.mirror_rule(
         source: "my_package/headless/button",
         target: "my_package/button",
-        prefix_params: gleam_contracts.theme_prefix(),
+        prefix_params: [rule.Labeled(label: "context")],
       )
         |> gleam_contracts.with_exceptions(exceptions: ["button"]),
     ],
@@ -282,13 +297,13 @@ pub fn contract_tests() {
 
 ## MirrorRule Semantics
 
-Given `MirrorRule(source: "a/headless/foo", target: "a/foo", prefix_params: [Labeled("theme")], exceptions: [])`:
+Given `MirrorRule(source: "a/headless/foo", target: "a/foo", prefix_params: [Labeled("context")], exceptions: [])`:
 
 1. For every public function `f` in `a/headless/foo`:
    - `a/foo` must have a public function also named `f`
    - If `f` is in `exceptions`: only existence is checked, not parameters
    - Otherwise: `a/foo.f`'s parameter labels must equal
-     `["theme"] ++ labels_of(a/headless/foo.f)`
+     `["context"] ++ labels_of(a/headless/foo.f)`
 
 2. Extra functions in the target (not present in source) are allowed.
    The target is a superset, not an exact mirror.
@@ -301,15 +316,15 @@ Given `MirrorRule(source: "a/headless/foo", target: "a/foo", prefix_params: [Lab
 Violations produce messages like:
 
 ```
-FAIL: weft_lustre_ui/badge is missing function "badge_variant"
-      from weft_lustre_ui/headless/badge
+FAIL: my_package/badge is missing function "badge_variant"
+      from my_package/headless/badge
 
-FAIL: weft_lustre_ui/button.button has parameter mismatch
-      expected: [theme, config, label]
-      actual:   [theme, config, child]
+FAIL: my_package/button.button has parameter mismatch
+      expected: [context, config, label]
+      actual:   [context, config, child]
 
-FAIL: weft_lustre_ui/toggle is missing type "ToggleConfig"
-      from weft_lustre_ui/headless/toggle
+FAIL: my_package/toggle is missing type "ToggleConfig"
+      from my_package/headless/toggle
 ```
 
 ## Verification
@@ -320,6 +335,12 @@ Run the full verification chain:
 bash scripts/check.sh
 ```
 
+## Dogfooding (Optional)
+
+Dogfooding should live in the consuming package repository, where real module
+pairs and CI constraints are known. Keep this library repository focused on the
+generic engine and deterministic fixtures.
+
 ## Test Plan
 
 - MirrorRule: source function present in target -> Ok
@@ -336,4 +357,5 @@ bash scripts/check.sh
 - format_violations: produces readable output
 - load_package_interface: valid JSON -> Ok(interface)
 - load_package_interface: invalid path -> Error
-- Integration: real package-interface.json from weft_lustre_ui
+- check_result: load failure -> InterfaceLoadFailure
+- Dogfood (optional): consumer-owned integration checks in consuming repos

gleam.toml

@@ -7,7 +7,7 @@ gleam = ">= 1.14.0"
 
 [dependencies]
 gleam_stdlib = ">= 0.69.0"
-gleam_json = ">= 2.0.0 and < 3.0.0"
+gleam_json = ">= 3.0.0 and < 4.0.0"
 gleam_package_interface = ">= 3.0.0 and < 4.0.0"
 simplifile = ">= 2.0.0 and < 3.0.0"
 
@@ -16,5 +16,5 @@ startest = ">= 0.8.0"
 
 [documentation]
 pages = [
-  { title = "Technical Specification", path = "SPEC.md" },
+  { title = "Technical Specification", path = "SPEC.html", source = "./SPEC.md" },
 ]

manifest.toml

@@ -0,0 +1,32 @@
+# This file was generated by Gleam
+# You typically do not need to edit this file
+
+packages = [
+  { name = "argv", version = "1.0.2", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "BA1FF0929525DEBA1CE67256E5ADF77A7CDDFE729E3E3F57A5BDCAA031DED09D" },
+  { name = "bigben", version = "2.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib", "gleam_time", "interior"], otp_app = "bigben", source = "hex", outer_checksum = "4B0D9F2514C06AE577F284532270A6F89007781620E4B12A843388BA549C17D2" },
+  { name = "exception", version = "2.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "exception", source = "hex", outer_checksum = "329D269D5C2A314F7364BD2711372B6F2C58FA6F39981572E5CA68624D291F8C" },
+  { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" },
+  { name = "gleam_community_ansi", version = "1.4.4", build_tools = ["gleam"], requirements = ["gleam_community_colour", "gleam_regexp", "gleam_stdlib"], otp_app = "gleam_community_ansi", source = "hex", outer_checksum = "1B3AEA6074AB34D5F0674744F36DDC7290303A03295507E2DEC61EDD6F5777FE" },
+  { name = "gleam_community_colour", version = "2.0.4", build_tools = ["gleam"], requirements = ["gleam_json", "gleam_stdlib"], otp_app = "gleam_community_colour", source = "hex", outer_checksum = "6DB4665555D7D2B27F0EA32EF47E8BEBC4303821765F9C73D483F38EE24894F0" },
+  { name = "gleam_erlang", version = "1.3.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "1124AD3AA21143E5AF0FC5CF3D9529F6DB8CA03E43A55711B60B6B7B3874375C" },
+  { name = "gleam_javascript", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_javascript", source = "hex", outer_checksum = "EF6C77A506F026C6FB37941889477CD5E4234FCD4337FF0E9384E297CB8F97EB" },
+  { name = "gleam_json", version = "3.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "44FDAA8847BE8FC48CA7A1C089706BD54BADCC4C45B237A992EDDF9F2CDB2836" },
+  { name = "gleam_otp", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "gleam_otp", source = "hex", outer_checksum = "BA6A294E295E428EC1562DC1C11EA7530DCB981E8359134BEABC8493B7B2258E" },
+  { name = "gleam_package_interface", version = "3.0.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_package_interface", source = "hex", outer_checksum = "8F2D19DE9876D9401BB0626260958A6B1580BB233489C32831FE74CE0ACAE8B4" },
+  { name = "gleam_regexp", version = "1.1.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_regexp", source = "hex", outer_checksum = "9C215C6CA84A5B35BB934A9B61A9A306EC743153BE2B0425A0D032E477B062A9" },
+  { name = "gleam_stdlib", version = "0.69.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "AAB0962BEBFAA67A2FBEE9EEE218B057756808DC9AF77430F5182C6115B3A315" },
+  { name = "gleam_time", version = "1.7.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_time", source = "hex", outer_checksum = "56DB0EF9433826D3B99DB0B4AF7A2BFED13D09755EC64B1DAAB46F804A9AD47D" },
+  { name = "glint", version = "1.2.1", build_tools = ["gleam"], requirements = ["gleam_community_ansi", "gleam_community_colour", "gleam_stdlib", "snag"], otp_app = "glint", source = "hex", outer_checksum = "2214C7CEFDE457CEE62140C3D4899B964E05236DA74E4243DFADF4AF29C382BB" },
+  { name = "interior", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_otp", "gleam_stdlib"], otp_app = "interior", source = "hex", outer_checksum = "EE2728791E34400CB3CD986B6AD0E02A2F970F50B5ED59896E2820702C7DDD29" },
+  { name = "simplifile", version = "2.3.2", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "E049B4DACD4D206D87843BCF4C775A50AE0F50A52031A2FFB40C9ED07D6EC70A" },
+  { name = "snag", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "snag", source = "hex", outer_checksum = "274F41D6C3ECF99F7686FDCE54183333E41D2C1CA5A3A673F9A8B2C7A4401077" },
+  { name = "startest", version = "0.8.0", build_tools = ["gleam"], requirements = ["argv", "bigben", "exception", "gleam_community_ansi", "gleam_erlang", "gleam_javascript", "gleam_regexp", "gleam_stdlib", "gleam_time", "glint", "simplifile", "tom"], otp_app = "startest", source = "hex", outer_checksum = "47362F1D9DFEFC2F81C590F73A5BFBE902F427408EFBFB48765A05512AED02DC" },
+  { name = "tom", version = "2.0.1", build_tools = ["gleam"], requirements = ["gleam_stdlib", "gleam_time"], otp_app = "tom", source = "hex", outer_checksum = "90791DA4AACE637E30081FE77049B8DB850FBC8CACC31515376BCC4E59BE1DD2" },
+]
+
+[requirements]
+gleam_json = { version = ">= 3.0.0 and < 4.0.0" }
+gleam_package_interface = { version = ">= 3.0.0 and < 4.0.0" }
+gleam_stdlib = { version = ">= 0.69.0" }
+simplifile = { version = ">= 2.0.0 and < 3.0.0" }
+startest = { version = ">= 0.8.0" }

src/gleam_contracts.gleam

@@ -1 +1,121 @@
 //// Build-time module contract verification for Gleam — enforce that paired modules stay in sync.
+
+import gleam/io
+import gleam/package_interface.{type Package}
+import gleam/result
+import gleam_contracts/loader
+import gleam_contracts/rule
+import gleam_contracts/verify as contract_verify
+import gleam_contracts/violation
+
+/// Decoded package-interface model exported by the compiler.
+pub type PackageInterface =
+  Package
+
+/// Errors that can occur while loading a package-interface file.
+pub type LoadError =
+  loader.LoadError
+
+/// A single contract rule to verify.
+pub type Rule =
+  rule.Rule
+
+/// Expected parameter specification.
+pub type ParamSpec =
+  rule.ParamSpec
+
+/// Expected function export specification.
+pub type ExportSpec =
+  rule.ExportSpec
+
+/// A single contract violation.
+pub type Violation =
+  violation.Violation
+
+/// Verification result.
+pub type ContractResult =
+  contract_verify.ContractResult
+
+/// Load and decode a package interface from a JSON file path.
+pub fn load_package_interface(
+  path path: String,
+) -> Result(PackageInterface, LoadError) {
+  loader.load_package_interface(path:)
+}
+
+/// Verify a list of rules against a package interface.
+pub fn verify(
+  interface interface: PackageInterface,
+  rules rules: List(Rule),
+) -> ContractResult {
+  contract_verify.verify(interface:, rules:)
+}
+
+/// Format violations as human-readable lines for terminal output.
+pub fn format_violations(violations violations: List(Violation)) -> String {
+  violation.format_violations(violations:)
+}
+
+/// Create a mirror rule.
+pub fn mirror_rule(
+  source source: String,
+  target target: String,
+  prefix_params prefix_params: List(ParamSpec),
+) -> Rule {
+  rule.mirror_rule(source:, target:, prefix_params:)
+}
+
+/// Add function-name exceptions to a mirror rule.
+pub fn with_exceptions(
+  rule rule: Rule,
+  exceptions exceptions: List(String),
+) -> Rule {
+  rule.with_exceptions(rule:, exceptions:)
+}
+
+/// Create a require-exports rule.
+pub fn require_exports(
+  module module: String,
+  exports exports: List(ExportSpec),
+) -> Rule {
+  rule.require_exports(module:, exports:)
+}
+
+/// Create a shared-types rule.
+pub fn shared_types(
+  module_a module_a: String,
+  module_b module_b: String,
+  type_names type_names: List(String),
+) -> Rule {
+  rule.shared_types(module_a:, module_b:, type_names:)
+}
+
+/// Load and verify in one step.
+pub fn check_result(
+  interface_path interface_path: String,
+  rules rules: List(Rule),
+) -> ContractResult {
+  use interface <- result.try(
+    load_package_interface(path: interface_path)
+    |> result.map_error(fn(error) {
+      [
+        violation.InterfaceLoadFailure(path: interface_path, error: error),
+      ]
+    }),
+  )
+  verify(interface:, rules:)
+}
+
+/// Convenience terminal helper for scripts.
+pub fn check(
+  interface_path interface_path: String,
+  rules rules: List(Rule),
+) -> Nil {
+  case check_result(interface_path:, rules:) {
+    Ok(Nil) -> Nil
+    Error(violations) ->
+      violations
+      |> format_violations
+      |> io.println_error
+  }
+}