feat: DbC contracts

Author: alexekdahl

LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 alexekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,40 @@
+# Design by Contract for Nim
+
+A lightweight Design by Contract implementation for Nim allowing you to enforce preconditions and postconditions
+
+## Installation
+
+```
+nimble install assert
+```
+
+## Usage
+
+```nim
+import assert
+import math
+
+proc divide(a, b: int): int {.contract.} =
+  ## Integer division of a by b.
+  ## Requires:
+  ##   b != 0
+  ## Ensures:
+  ##   result * b == a
+  result = a div b
+```
+
+## Compile Options
+
+- **Regular Build**: Contracts fully enabled
+  ```
+  nim c program.nim
+  ```
+
+- **Production Build**: No contract checks (zero overhead)
+  ```
+  nim c -d:noContracts program.nim
+  ```
+
+## Note
+
+When a contract is violated, the program terminates with an error message

assert.nimble

@@ -0,0 +1,8 @@
+version       = "0.1.2"
+author        = "alexekdahl"
+description   = "DbC library for Nim providing precondition and postcondition assertions"
+license       = "MIT"
+srcDir        = "src"
+
+# Dependencies
+requires "nim >= 2.2.2"

src/assert.nim

@@ -0,0 +1,4 @@
+# Main module that exports all submodules
+import assert/contracts
+
+export contracts

src/assert/contracts.nim

@@ -0,0 +1,105 @@
+import macros, strutils
+
+const moduleName = "assert/contracts"
+
+
+proc contractViolation(msg: string) {.noreturn.} =
+  stderr.writeLine("CONTRACT VIOLATION:\n\t" & msg)
+
+  when compileOption("stacktrace"):
+    let trace = getStackTrace()
+    for line in trace.splitLines():
+      if not line.contains(moduleName) and line.len > 0:
+        stderr.writeLine(line)
+
+  quit(QuitFailure)
+
+
+proc extractContracts(docComment: string): tuple[requires, ensures,
+    invariants: seq[string]] =
+  result.requires = @[]
+  result.ensures = @[]
+
+  let lines = docComment.splitLines()
+  var currentSection = ""
+
+  for line in lines:
+    let trimmedLine = line.strip()
+    if trimmedLine.startsWith("Requires:"):
+      currentSection = "requires"
+      continue
+    elif trimmedLine.startsWith("Ensures:"):
+      currentSection = "ensures"
+      continue
+
+    if currentSection == "requires" and trimmedLine.len > 0:
+      result.requires.add(trimmedLine)
+    elif currentSection == "ensures" and trimmedLine.len > 0:
+      result.ensures.add(trimmedLine)
+
+
+macro contract*(procDef: untyped): untyped =
+  ## Applies Design by Contract principles to a procedure based on its documentation.
+  result = procDef
+  # For production builds, don't add contract checks
+  if defined(noContracts):
+    return
+
+  var docComment = ""
+  if procDef.kind == nnkProcDef:
+
+    # Extract doc comment if it exists
+    if procDef[6].kind == nnkStmtList and procDef[6].len > 0:
+      if procDef[6][0].kind == nnkCommentStmt:
+        docComment = procDef[6][0].strVal
+
+  if docComment == "":
+    return # No documentation, so no contracts to apply
+  
+  # Extract contracts from the documentation
+  let contracts = extractContracts(docComment)
+
+  # Create the contract checking code
+  var preconditions = newStmtList()
+  for req in contracts.requires:
+    let condExpr = parseExpr(req)
+    preconditions.add(quote do:
+      if not(`condExpr`):
+        let info = instantiationInfo()
+        contractViolation(info.filename & ":" & $info.line &
+          "\n\t\tPrecondition failed: " & `req`)
+    )
+
+  var postconditions = newStmtList()
+  for ens in contracts.ensures:
+    let condExpr = parseExpr(ens)
+    postconditions.add(quote do:
+      if not(`condExpr`):
+        let info = instantiationInfo()
+        contractViolation(info.filename & ":" & $info.line &
+          "\n\t\tPostcondition failed: " & `ens`)
+    )
+
+  # Insert the contract checking code into the procedure
+  let procBody = procDef[6]
+  var newBody = newStmtList()
+
+  # Copy the comment if it exists
+  if procBody.len > 0 and procBody[0].kind == nnkCommentStmt:
+    newBody.add(procBody[0])
+
+  # Add precondition checks
+  for precheck in preconditions:
+    newBody.add(precheck)
+
+  # Copy the original body except the first statement if it's a comment
+  for i in 0..<procBody.len:
+    if i > 0 or procBody[0].kind != nnkCommentStmt:
+      newBody.add(procBody[i])
+
+  # Add postcondition checks
+  for postcheck in postconditions:
+    newBody.add(postcheck)
+
+  # Replace the procedure body with the new one
+  procDef[6] = newBody

src/example.nim

@@ -0,0 +1,22 @@
+import assert
+import math
+
+proc divide(a, b: int): int {.contract.} =
+  ## Integer division
+  ## Requires:
+  ##   b != 0
+  ## Ensures:
+  ##   result * b == a
+
+  result = a div b
+
+proc add5to5(x: int): int {.contract.} =
+  ## Adds 5 to 5
+  ## Requires:
+  ##   x == 5
+
+  result = x + 5
+
+when isMainModule:
+  echo "10 / 2 = ", divide(10, 2) # Works fine
+  echo "adding 5 to 10 = ", add5to5(10) # This will panic if contracts are enabled