+17

README.md

··· 86 86 - ✅ **Circular Dependency Detection**: prevents infinite reference loops 87 87 - ✅ **Detailed Error Messages**: validation errors with path information 88 88 89 89 + ## CLI Usage 90 90 + 91 91 + Validate lexicon files from the command line: 92 92 + 93 93 + ```sh 94 94 + # Validate a single file 95 95 + gleam run -m honk check ./lexicons/xyz/statusphere/status.json 96 96 + 97 97 + # Validate all .json files in a directory 98 98 + gleam run -m honk check ./lexicons/ 99 99 + 100 100 + # Show help 101 101 + gleam run -m honk help 102 102 + ``` 103 103 + 104 104 + When validating a directory, all lexicons are loaded together to resolve cross-lexicon references 105 105 + 89 106 ## API Overview 90 107 91 108 ### Main Functions

+2

gleam.toml

··· 8 8 gleam_json = ">= 3.0.0 and < 4.0.0" 9 9 gleam_regexp = ">= 1.0.0 and < 2.0.0" 10 10 gleam_time = ">= 1.5.0 and < 2.0.0" 11 11 + simplifile = ">= 2.3.1 and < 3.0.0" 12 12 + argv = ">= 1.0.2 and < 2.0.0" 11 13 12 14 [dev-dependencies] 13 15 gleeunit = ">= 1.0.0 and < 2.0.0"

+5

manifest.toml

··· 2 2 # You typically do not need to edit this file 3 3 4 4 packages = [ 5 5 + { name = "argv", version = "1.0.2", build_tools = ["gleam"], requirements = [], otp_app = "argv", source = "hex", outer_checksum = "BA1FF0929525DEBA1CE67256E5ADF77A7CDDFE729E3E3F57A5BDCAA031DED09D" }, 6 6 + { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" }, 5 7 { name = "gleam_json", version = "3.1.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_json", source = "hex", outer_checksum = "44FDAA8847BE8FC48CA7A1C089706BD54BADCC4C45B237A992EDDF9F2CDB2836" }, 6 8 { name = "gleam_regexp", version = "1.1.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_regexp", source = "hex", outer_checksum = "9C215C6CA84A5B35BB934A9B61A9A306EC743153BE2B0425A0D032E477B062A9" }, 7 9 { name = "gleam_stdlib", version = "0.65.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "7C69C71D8C493AE11A5184828A77110EB05A7786EBF8B25B36A72F879C3EE107" }, 8 10 { name = "gleam_time", version = "1.5.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_time", source = "hex", outer_checksum = "D560E672C7279C89908981E068DF07FD16D0C859DCA266F908B18F04DF0EB8E6" }, 9 11 { name = "gleeunit", version = "1.9.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "DA9553CE58B67924B3C631F96FE3370C49EB6D6DC6B384EC4862CC4AAA718F3C" }, 12 12 + { name = "simplifile", version = "2.3.1", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "957E0E5B75927659F1D2A1B7B75D7B9BA96FAA8D0C53EA71C4AD9CD0C6B848F6" }, 10 13 ] 11 14 12 15 [requirements] 16 16 + argv = { version = ">= 1.0.2 and < 2.0.0" } 13 17 gleam_json = { version = ">= 3.0.0 and < 4.0.0" } 14 18 gleam_regexp = { version = ">= 1.0.0 and < 2.0.0" } 15 19 gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" } 16 20 gleam_time = { version = ">= 1.5.0 and < 2.0.0" } 17 21 gleeunit = { version = ">= 1.0.0 and < 2.0.0" } 22 22 + simplifile = { version = ">= 2.3.1 and < 3.0.0" }

+285 -23

src/honk.gleam

··· 1 1 // Main public API for the ATProtocol lexicon validator 2 2 3 3 + import argv 3 4 import gleam/dict.{type Dict} 5 5 + import gleam/dynamic/decode 6 6 + import gleam/int 7 7 + import gleam/io 4 8 import gleam/json.{type Json} 5 9 import gleam/list 6 10 import gleam/option.{None, Some} 7 11 import gleam/result 12 12 + import gleam/string 8 13 import honk/errors 9 14 import honk/internal/json_helpers 10 15 import honk/types 11 16 import honk/validation/context 12 17 import honk/validation/formats 18 18 + import simplifile 13 19 14 20 // Import validators 15 21 import honk/validation/field as validation_field ··· 67 73 Ok(_) -> errors_acc 68 74 Error(e) -> { 69 75 // Include def name in error for better context 70 70 - let error_msg = 71 71 - lex_id 72 72 - <> "#" 73 73 - <> def_name 74 74 - <> ": " 75 75 - <> errors.to_string(e) 76 76 + // Extract just the message without wrapper text 77 77 + let message = case e { 78 78 + errors.InvalidSchema(msg) -> msg 79 79 + errors.DataValidation(msg) -> msg 80 80 + errors.LexiconNotFound(msg) -> "Lexicon not found: " <> msg 81 81 + } 82 82 + // Clean up leading ": " if present 83 83 + let clean_message = case string.starts_with(message, ": ") { 84 84 + True -> string.drop_start(message, 2) 85 85 + False -> message 86 86 + } 87 87 + let error_msg = lex_id <> "#" <> def_name <> ": " <> clean_message 76 88 case dict.get(errors_acc, lex_id) { 77 89 Ok(existing_errors) -> 78 90 dict.insert(errors_acc, lex_id, [ ··· 185 197 } 186 198 } 187 199 188 188 - /// Entry point for the honk lexicon validator. 200 200 + /// CLI entry point for the honk lexicon validator 189 201 /// 190 190 - /// This function serves as an example entry point and can be used 191 191 - /// for basic CLI or testing purposes. For actual validation, 192 192 - /// use the `validate()` or `validate_record()` functions. 193 193 - /// 194 194 - /// ## Example 195 195 - /// 196 196 - /// ```gleam 197 197 - /// import honk 198 198 - /// 199 199 - /// pub fn main() { 200 200 - /// honk.main() 201 201 - /// } 202 202 - /// ``` 202 202 + /// Usage: 203 203 + /// gleam run -m honk check <path> 204 204 + /// gleam run -m honk help 203 205 pub fn main() -> Nil { 204 204 - // This would typically be called from tests or CLI 205 205 - let _example_result = is_valid_nsid("com.example.record") 206 206 - Nil 206 206 + case argv.load().arguments { 207 207 + ["check", path] -> validate_path(path) 208 208 + ["help"] | [] -> show_help() 209 209 + _ -> { 210 210 + io.println_error("Unknown command. Use 'help' for usage information.") 211 211 + Nil 212 212 + } 213 213 + } 214 214 + } 215 215 + 216 216 + /// Validate a path (auto-detects file or directory) 217 217 + fn validate_path(path: String) -> Nil { 218 218 + case simplifile.is_file(path) { 219 219 + Ok(True) -> validate_file(path) 220 220 + Ok(False) -> 221 221 + case simplifile.is_directory(path) { 222 222 + Ok(True) -> validate_directory(path) 223 223 + Ok(False) -> { 224 224 + io.println_error("Error: Path is neither a file nor a directory: " <> path) 225 225 + Nil 226 226 + } 227 227 + Error(_) -> { 228 228 + io.println_error("Error: Cannot access path: " <> path) 229 229 + Nil 230 230 + } 231 231 + } 232 232 + Error(_) -> { 233 233 + io.println_error("Error: Cannot access path: " <> path) 234 234 + Nil 235 235 + } 236 236 + } 237 237 + } 238 238 + 239 239 + /// Validate a single lexicon file 240 240 + fn validate_file(file_path: String) -> Nil { 241 241 + case read_and_validate_file(file_path) { 242 242 + Ok(_) -> { 243 243 + io.println("✓ " <> file_path <> " - valid") 244 244 + Nil 245 245 + } 246 246 + Error(msg) -> { 247 247 + io.println_error("✗ " <> file_path) 248 248 + io.println_error(" " <> msg) 249 249 + Nil 250 250 + } 251 251 + } 252 252 + } 253 253 + 254 254 + /// Validate all .json files in a directory 255 255 + fn validate_directory(dir_path: String) -> Nil { 256 256 + case simplifile.get_files(dir_path) { 257 257 + Error(_) -> { 258 258 + io.println_error("Error: Cannot read directory: " <> dir_path) 259 259 + Nil 260 260 + } 261 261 + Ok(all_files) -> { 262 262 + // Filter for .json files 263 263 + let json_files = 264 264 + all_files 265 265 + |> list.filter(fn(path) { string.ends_with(path, ".json") }) 266 266 + 267 267 + case json_files { 268 268 + [] -> { 269 269 + io.println("No .json files found in " <> dir_path) 270 270 + Nil 271 271 + } 272 272 + files -> { 273 273 + // Read and parse all files 274 274 + let file_results = 275 275 + files 276 276 + |> list.map(fn(file) { 277 277 + case read_json_file(file) { 278 278 + Ok(json_value) -> #(file, Ok(json_value)) 279 279 + Error(msg) -> #(file, Error(msg)) 280 280 + } 281 281 + }) 282 282 + 283 283 + // Separate successful parses from failures 284 284 + let #(parse_errors, parsed_files) = 285 285 + list.partition(file_results, fn(result) { 286 286 + case result { 287 287 + #(_, Error(_)) -> True 288 288 + #(_, Ok(_)) -> False 289 289 + } 290 290 + }) 291 291 + 292 292 + // Display parse errors 293 293 + parse_errors 294 294 + |> list.each(fn(result) { 295 295 + case result { 296 296 + #(file, Error(msg)) -> { 297 297 + io.println_error("✗ " <> file) 298 298 + io.println_error(" " <> msg) 299 299 + } 300 300 + _ -> Nil 301 301 + } 302 302 + }) 303 303 + 304 304 + // Get all successfully parsed lexicons 305 305 + let lexicons = 306 306 + parsed_files 307 307 + |> list.filter_map(fn(result) { 308 308 + case result { 309 309 + #(_, Ok(json)) -> Ok(json) 310 310 + _ -> Error(Nil) 311 311 + } 312 312 + }) 313 313 + 314 314 + // Validate all lexicons together (allows cross-lexicon references) 315 315 + case validate(lexicons) { 316 316 + Ok(_) -> { 317 317 + // All lexicons are valid 318 318 + parsed_files 319 319 + |> list.each(fn(result) { 320 320 + case result { 321 321 + #(file, Ok(_)) -> io.println("✓ " <> file) 322 322 + _ -> Nil 323 323 + } 324 324 + }) 325 325 + } 326 326 + Error(error_map) -> { 327 327 + // Some lexicons have errors - map errors back to files 328 328 + parsed_files 329 329 + |> list.each(fn(result) { 330 330 + case result { 331 331 + #(file, Ok(json)) -> { 332 332 + // Get the lexicon ID for this file 333 333 + case json_helpers.get_string(json, "id") { 334 334 + Some(lex_id) -> { 335 335 + case dict.get(error_map, lex_id) { 336 336 + Ok(errors) -> { 337 337 + io.println_error("✗ " <> file) 338 338 + errors 339 339 + |> list.each(fn(err) { 340 340 + io.println_error(" " <> err) 341 341 + }) 342 342 + } 343 343 + Error(_) -> io.println("✓ " <> file) 344 344 + } 345 345 + } 346 346 + None -> { 347 347 + io.println_error("✗ " <> file) 348 348 + io.println_error(" Missing lexicon id") 349 349 + } 350 350 + } 351 351 + } 352 352 + _ -> Nil 353 353 + } 354 354 + }) 355 355 + } 356 356 + } 357 357 + 358 358 + // Summary 359 359 + let total = list.length(files) 360 360 + let parse_error_count = list.length(parse_errors) 361 361 + let validation_error_count = case validate(lexicons) { 362 362 + Ok(_) -> 0 363 363 + Error(error_map) -> dict.size(error_map) 364 364 + } 365 365 + let total_errors = parse_error_count + validation_error_count 366 366 + 367 367 + case total_errors { 368 368 + 0 -> 369 369 + io.println( 370 370 + "\nAll " <> int.to_string(total) <> " schemas validated successfully.", 371 371 + ) 372 372 + _ -> 373 373 + io.println_error( 374 374 + "\n" 375 375 + <> int.to_string(total_errors) 376 376 + <> " of " 377 377 + <> int.to_string(total) 378 378 + <> " schemas failed validation.", 379 379 + ) 380 380 + } 381 381 + 382 382 + Nil 383 383 + } 384 384 + } 385 385 + } 386 386 + } 387 387 + } 388 388 + 389 389 + /// Read and parse a JSON file (without validation) 390 390 + fn read_json_file(file_path: String) -> Result(Json, String) { 391 391 + use content <- result.try( 392 392 + simplifile.read(file_path) 393 393 + |> result.map_error(fn(_) { "Cannot read file" }), 394 394 + ) 395 395 + 396 396 + use json_dynamic <- result.try( 397 397 + json.parse(content, decode.dynamic) 398 398 + |> result.map_error(fn(_) { "Invalid JSON" }), 399 399 + ) 400 400 + 401 401 + json_helpers.dynamic_to_json(json_dynamic) 402 402 + |> result.map_error(fn(_) { "Failed to convert JSON" }) 403 403 + } 404 404 + 405 405 + /// Read a file and validate it as a lexicon 406 406 + fn read_and_validate_file(file_path: String) -> Result(Nil, String) { 407 407 + use content <- result.try( 408 408 + simplifile.read(file_path) 409 409 + |> result.map_error(fn(_) { "Cannot read file" }), 410 410 + ) 411 411 + 412 412 + use json_dynamic <- result.try( 413 413 + json.parse(content, decode.dynamic) 414 414 + |> result.map_error(fn(_) { "Invalid JSON" }), 415 415 + ) 416 416 + 417 417 + use json_value <- result.try( 418 418 + json_helpers.dynamic_to_json(json_dynamic) 419 419 + |> result.map_error(fn(_) { "Failed to convert JSON" }), 420 420 + ) 421 421 + 422 422 + use _ <- result.try( 423 423 + validate([json_value]) 424 424 + |> result.map_error(fn(error_map) { format_validation_errors(error_map) }), 425 425 + ) 426 426 + 427 427 + Ok(Nil) 428 428 + } 429 429 + 430 430 + /// Format validation errors from the error map 431 431 + fn format_validation_errors(error_map: Dict(String, List(String))) -> String { 432 432 + error_map 433 433 + |> dict.to_list 434 434 + |> list.map(fn(entry) { 435 435 + let #(_key, errors) = entry 436 436 + string.join(errors, "\n ") 437 437 + }) 438 438 + |> string.join("\n ") 439 439 + } 440 440 + 441 441 + /// Show help text 442 442 + fn show_help() -> Nil { 443 443 + io.println( 444 444 + " 445 445 + honk - ATProtocol Lexicon Validator 446 446 + 447 447 + USAGE: 448 448 + gleam run -m honk check <path> 449 449 + gleam run -m honk help 450 450 + 451 451 + COMMANDS: 452 452 + check <path> Check a lexicon file or directory 453 453 + - If <path> is a file: validates that single lexicon 454 454 + - If <path> is a directory: recursively validates all .json files 455 455 + 456 456 + help Show this help message 457 457 + 458 458 + EXAMPLES: 459 459 + gleam run -m honk check ./lexicons/xyz/statusphere/status.json 460 460 + gleam run -m honk check ./lexicons 461 461 + 462 462 + VALIDATION: 463 463 + - Validates lexicon structure (id, defs) 464 464 + - Validates ALL definitions in each lexicon 465 465 + - Checks types, constraints, and references 466 466 + - Reports errors with definition context (lex.id#defName) 467 467 + ", 468 468 + ) 207 469 }

+32 -1

src/honk/validation/field/reference.gleam

··· 40 40 use ref_str <- result.try(ref_value) 41 41 42 42 // Validate reference syntax 43 43 - validate_ref_syntax(ref_str, def_name) 43 43 + use _ <- result.try(validate_ref_syntax(ref_str, def_name)) 44 44 + 45 45 + // Validate that the reference can be resolved (only for global refs with full context) 46 46 + case string.starts_with(ref_str, "#") { 47 47 + True -> Ok(Nil) // Local ref - will be validated in same lexicon 48 48 + False -> { 49 49 + // Global ref - check it exists in catalog if we have a current lexicon 50 50 + case context.current_lexicon_id(ctx) { 51 51 + Some(lex_id) -> { 52 52 + // We have a full validation context, so validate reference resolution 53 53 + use resolved <- result.try(resolution.resolve_reference( 54 54 + ref_str, 55 55 + ctx, 56 56 + lex_id, 57 57 + )) 58 58 + 59 59 + case resolved { 60 60 + Some(_) -> Ok(Nil) 61 61 + None -> 62 62 + Error(errors.invalid_schema( 63 63 + def_name <> ": reference not found: " <> ref_str, 64 64 + )) 65 65 + } 66 66 + } 67 67 + None -> { 68 68 + // No current lexicon (e.g., unit test context) 69 69 + // Just validate syntax, can't check if reference exists 70 70 + Ok(Nil) 71 71 + } 72 72 + } 73 73 + } 74 74 + } 44 75 } 45 76 46 77 /// Validates data against the referenced schema

+20

test/fixtures/com.atproto.repo.strongRef.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "com.atproto.repo.strongRef", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "object", 7 7 + "required": ["uri", "cid"], 8 8 + "properties": { 9 9 + "uri": { 10 10 + "type": "string", 11 11 + "format": "at-uri" 12 12 + }, 13 13 + "cid": { 14 14 + "type": "string", 15 15 + "format": "cid" 16 16 + } 17 17 + } 18 18 + } 19 19 + } 20 20 + }

+46

test/fixtures/com.example.post.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "com.example.post", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "record", 7 7 + "key": "tid", 8 8 + "record": { 9 9 + "type": "object", 10 10 + "required": ["text", "createdAt"], 11 11 + "properties": { 12 12 + "text": { 13 13 + "type": "string", 14 14 + "maxLength": 300 15 15 + }, 16 16 + "author": { 17 17 + "type": "ref", 18 18 + "ref": "com.example.user#profile" 19 19 + }, 20 20 + "createdAt": { 21 21 + "type": "string", 22 22 + "format": "datetime" 23 23 + }, 24 24 + "reply": { 25 25 + "type": "ref", 26 26 + "ref": "#replyRef" 27 27 + } 28 28 + } 29 29 + } 30 30 + }, 31 31 + "replyRef": { 32 32 + "type": "object", 33 33 + "required": ["parent", "root"], 34 34 + "properties": { 35 35 + "parent": { 36 36 + "type": "ref", 37 37 + "ref": "com.atproto.repo.strongRef" 38 38 + }, 39 39 + "root": { 40 40 + "type": "ref", 41 41 + "ref": "com.atproto.repo.strongRef" 42 42 + } 43 43 + } 44 44 + } 45 45 + } 46 46 + }

+41

test/fixtures/com.example.user.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "com.example.user", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "record", 7 7 + "key": "tid", 8 8 + "record": { 9 9 + "type": "object", 10 10 + "required": ["handle", "displayName"], 11 11 + "properties": { 12 12 + "handle": { 13 13 + "type": "string", 14 14 + "format": "handle" 15 15 + }, 16 16 + "displayName": { 17 17 + "type": "string", 18 18 + "maxLength": 64 19 19 + }, 20 20 + "bio": { 21 21 + "type": "string", 22 22 + "maxLength": 256 23 23 + } 24 24 + } 25 25 + } 26 26 + }, 27 27 + "profile": { 28 28 + "type": "object", 29 29 + "required": ["handle"], 30 30 + "properties": { 31 31 + "handle": { 32 32 + "type": "string", 33 33 + "format": "handle" 34 34 + }, 35 35 + "displayName": { 36 36 + "type": "string" 37 37 + } 38 38 + } 39 39 + } 40 40 + } 41 41 + }

+19

test/fixtures/invalid-ref.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "com.example.invalidref", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "record", 7 7 + "key": "tid", 8 8 + "record": { 9 9 + "type": "object", 10 10 + "properties": { 11 11 + "brokenRef": { 12 12 + "type": "ref", 13 13 + "ref": "com.example.nonexistent#thing" 14 14 + } 15 15 + } 16 16 + } 17 17 + } 18 18 + } 19 19 + }

+19

test/fixtures/invalid.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "com.example.invalid", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "record", 7 7 + "key": "tid", 8 8 + "record": { 9 9 + "type": "object", 10 10 + "properties": {} 11 11 + } 12 12 + }, 13 13 + "badDef": { 14 14 + "type": "string", 15 15 + "minLength": 10, 16 16 + "maxLength": 5 17 17 + } 18 18 + } 19 19 + }

+26

test/fixtures/valid.json

··· 1 1 + { 2 2 + "lexicon": 1, 3 3 + "id": "xyz.statusphere.status", 4 4 + "defs": { 5 5 + "main": { 6 6 + "type": "record", 7 7 + "key": "tid", 8 8 + "record": { 9 9 + "type": "object", 10 10 + "required": ["status", "createdAt"], 11 11 + "properties": { 12 12 + "status": { 13 13 + "type": "string", 14 14 + "minLength": 1, 15 15 + "maxGraphemes": 1, 16 16 + "maxLength": 32 17 17 + }, 18 18 + "createdAt": { 19 19 + "type": "string", 20 20 + "format": "datetime" 21 21 + } 22 22 + } 23 23 + } 24 24 + } 25 25 + } 26 26 + }