{"id":32150383,"url":"https://github.com/truewebber/swift-protoparser","last_synced_at":"2026-03-08T00:01:37.263Z","repository":{"id":262333098,"uuid":"886431251","full_name":"truewebber/swift-protoparser","owner":"truewebber","description":"A native Swift library for parsing Protocol Buffer (proto3) files into descriptors. SwiftProtoParser offers full proto3 syntax support, including services, RPC definitions, and custom options, with detailed error reporting and cross-platform compatibility. Designed as a Swift-idiomatic alternative to protoc with seamless Swift Protobuf integration.","archived":false,"fork":false,"pushed_at":"2026-02-26T22:28:52.000Z","size":3416,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-27T01:58:58.743Z","etag":null,"topics":["ast","code-generation","cross-platform","developer-tools","file-descriptor","grpc","lexer-parser","parser","proto3","protobuf","protocol-buffers","swift","swift-package","swift-protobuf","validation"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/truewebber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-11-11T00:36:31.000Z","updated_at":"2026-02-26T22:26:34.000Z","dependencies_parsed_at":"2024-11-11T22:18:49.888Z","dependency_job_id":"a6b817a6-4a23-49c2-a897-8c6d04b8d7db","html_url":"https://github.com/truewebber/swift-protoparser","commit_stats":null,"previous_names":["truewebber/swift-protoparse","truewebber/swift-protoparser"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/truewebber/swift-protoparser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truewebber%2Fswift-protoparser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truewebber%2Fswift-protoparser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truewebber%2Fswift-protoparser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truewebber%2Fswift-protoparser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/truewebber","download_url":"https://codeload.github.com/truewebber/swift-protoparser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truewebber%2Fswift-protoparser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30238062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T23:52:25.683Z","status":"ssl_error","status_checked_at":"2026-03-07T23:52:25.373Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ast","code-generation","cross-platform","developer-tools","file-descriptor","grpc","lexer-parser","parser","proto3","protobuf","protocol-buffers","swift","swift-package","swift-protobuf","validation"],"created_at":"2025-10-21T10:01:27.862Z","updated_at":"2026-03-08T00:01:37.243Z","avatar_url":"https://github.com/truewebber.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwiftProtoParser\n\nA Swift library for parsing Protocol Buffers `.proto` files into AST and descriptors without `protoc`.\n\n[![Platform](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Ftruewebber%2Fswift-protoparser%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/truewebber/swift-protoparser)\n[![Swift Package Index](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Ftruewebber%2Fswift-protoparser%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/truewebber/swift-protoparser)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](LICENSE)\n[![Coverage](https://img.shields.io/badge/Test%20Coverage-93%25-green.svg?style=flat)](#testing)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/truewebber/swift-protoparser)\n\n## Overview\n\nSwiftProtoParser enables native parsing of Protocol Buffers schema files directly in Swift without requiring the `protoc` compiler. This is useful for building code generation tools, schema analyzers, API documentation generators, and other applications that need to process `.proto` files at runtime.\n\n## Installation\n\nAdd to your `Package.swift`:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/truewebber/swift-protoparser.git\", from: \"0.6.0\")\n]\n```\n\n## Basic Usage\n\n### Parsing Proto Files\n\n```swift\nimport SwiftProtoParser\n\n// Parse a single .proto file\nlet result = SwiftProtoParser.parseFile(\"user.proto\")\nswitch result {\ncase .success(let descriptorSet):\n    let file = descriptorSet.file.last!\n    print(\"Package: \\(file.package)\")\n    print(\"Messages: \\(file.messageType.map { $0.name })\")\n    print(\"Services: \\(file.service.map { $0.name })\")\ncase .failure(let error):\n    print(\"Parse error: \\(error.localizedDescription)\")\n}\n```\n\n### Working with Imports\n\n```swift\n// Parse with import resolution\nlet result = SwiftProtoParser.parseFile(\n    \"api.proto\",\n    importPaths: [\n        \"/path/to/proto/files\",\n        \"/path/to/google/protobuf\"\n    ]\n)\n\n// Parse entire directory\nlet result = SwiftProtoParser.parseDirectory(\n    \"/path/to/proto/files\",\n    recursive: true,\n    importPaths: [\"/path/to/imports\"]\n)\n```\n\n### Working with Descriptors\n\n```swift\n// parseFile returns a FileDescriptorSet — all files in topological order\nlet result = SwiftProtoParser.parseFile(\"user.proto\")\nswitch result {\ncase .success(let descriptorSet):\n    // Iterate over all resolved files (dependencies first, requested file last)\n    for file in descriptorSet.file {\n        print(\"File: \\(file.name)\")\n        print(\"Package: \\(file.package)\")\n        for message in file.messageType {\n            print(\"  message \\(message.name): \\(message.field.count) fields\")\n        }\n    }\ncase .failure(let error):\n    print(\"Error: \\(error)\")\n}\n```\n\n## Features\n\n- **Complete Proto3 Support**: All standard proto3 syntax and semantics\n- **AST Generation**: Parse files into structured Abstract Syntax Tree\n- **Descriptor Building**: Generate `Google_Protobuf_FileDescriptorProto` compatible with SwiftProtobuf\n- **Map Fields**: Full support for map types with automatic synthetic entry message generation (protoc-compatible)\n- **Dependency Resolution**: Handle `import` statements and multi-file dependencies\n- **Extend Statements**: Support for proto3 custom options (`extend google.protobuf.*`)\n- **Scope-Aware Enum Resolution**: Strict protobuf scoping rules enforcement (matches `protoc` behavior)\n- **Qualified Types**: Well-known types and nested message references\n- **Performance Caching**: Content-based caching with 85%+ hit rates\n- **Incremental Parsing**: Only re-parse changed files in large projects\n- **Streaming Support**: Memory-efficient parsing of large files (\u003e50MB)\n\n## Supported Proto3 Features\n\nThe library supports the complete proto3 specification including:\n\n### Core Features\n```protobuf\nsyntax = \"proto3\";\npackage example.v1;\n\nimport \"google/protobuf/timestamp.proto\";\n\n// Messages with all field types\nmessage User {\n  string name = 1;\n  int32 age = 2;\n  repeated string emails = 3;\n  map\u003cstring, string\u003e metadata = 4;\n  google.protobuf.Timestamp created_at = 5;\n  \n  // Nested messages\n  message Address {\n    string street = 1;\n    string city = 2;\n  }\n  \n  // Oneof groups\n  oneof contact {\n    string email = 10;\n    string phone = 11;\n  }\n}\n\n// Enums\nenum Status {\n  STATUS_UNSPECIFIED = 0;\n  STATUS_ACTIVE = 1;\n}\n\n// Services with streaming\nservice UserService {\n  rpc GetUser(GetUserRequest) returns (User);\n  rpc StreamUsers(stream GetUserRequest) returns (stream User);\n}\n```\n\n### Custom Options (Extend)\n```protobuf\nimport \"google/protobuf/descriptor.proto\";\n\nextend google.protobuf.FileOptions {\n  string api_version = 50001;\n}\n\nextend google.protobuf.MessageOptions {\n  bool enable_validation = 50002;\n}\n\noption (api_version) = \"v1.0\";\n\nmessage ValidatedMessage {\n  option (enable_validation) = true;\n  string email = 1;\n}\n```\n\n## Performance Features\n\n### Caching\n\nContent-based AST caching is built into the library. Repeated parsing of the same file content\nreturns a cached result without re-running the Lexer and Parser, achieving 85%+ hit rates in\ntypical workflows. Cache management is automatic and requires no configuration.\n\n### Incremental Parsing\n\nAn incremental parsing engine tracks file modification timestamps and content hashes across\nmultiple calls. Only files that have actually changed — and their direct dependents — are\nre-parsed. This reduces parsing time by 60–80% for large proto directories with infrequent\nchanges.\n\n### Benchmarking\n\nAn internal benchmarking system measures single-file, string, directory, and descriptor\ngeneration throughput with statistical analysis (mean, median, standard deviation). It is used\nfor regression detection in the development workflow.\n\n## Requirements\n\n- Swift 5.10+\n- macOS 12.0+ / iOS 15.0+ / watchOS 8.0+ / tvOS 15.0+\n- Linux (Ubuntu 20.04+)\n\n## Dependencies\n\n- [SwiftProtobuf](https://github.com/apple/swift-protobuf) 1.29.0+ (for descriptor generation)\n\n## Documentation\n\n- **[Architecture Guide](docs/ARCHITECTURE.md)**: Technical implementation details and module design\n- **[Performance Guide](docs/PERFORMANCE_GUIDE.md)**: Caching, incremental parsing, and optimization\n- **[Quick Reference](docs/QUICK_REFERENCE.md)**: API summary and common patterns\n\n## Use Cases\n\n- Protocol Buffer code generators for Swift\n- Schema validation and linting tools\n- API documentation generators from `.proto` files\n- Proto file analysis and visualization tools\n- Dynamic proto file processing without `protoc`\n- Build systems requiring schema introspection\n\n## Testing\n\nThe library has comprehensive test coverage with 1263 tests covering all functionality:\n\n```bash\n# Run all tests\nswift test\n\n# Run with coverage\nmake test\nmake coverage\n```\n\nTest coverage: **92.59%** (lines), **92.23%** (functions), **95.04%** (regions)\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n\n- Code style and formatting\n- Testing requirements (90%+ coverage for new code)\n- Pull request process\n- Development workflow\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruewebber%2Fswift-protoparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruewebber%2Fswift-protoparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruewebber%2Fswift-protoparser/lists"}