api-contracts/buf.yaml at main · geniustechspace/api-contracts · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
version: v2

# =============================================================================
# Buf Configuration - Enterprise API Contracts
# =============================================================================
# This configuration enforces enterprise-grade standards for:
# - Code quality and consistency
# - Breaking change detection
# - Package organization
# - Documentation requirements
# =============================================================================

modules:
  - path: proto
    name: buf.build/geniustechspace/api-contracts

# =============================================================================
# Dependencies
# =============================================================================
# External proto dependencies for enterprise features
# Strategy: Use latest stable with no version pin for automatic updates
# Buf always uses semantically versioned releases from BSR
deps:
  # Google APIs - HTTP annotations, field behavior, resource definitions
  # Always use latest stable (Google maintains excellent backward compatibility)
  - buf.build/googleapis/googleapis

  # Protobuf validation - Input validation rules
  # Always use latest stable (automatically updated by buf)
  - buf.build/envoyproxy/protoc-gen-validate

  # gRPC Gateway - REST/HTTP to gRPC transcoding
  # Always use latest stable (automatically updated by buf)
  - buf.build/grpc-ecosystem/grpc-gateway

# =============================================================================
# Linting Configuration
# =============================================================================
# Strict linting rules to ensure consistency and best practices
lint:
  use:
    # Standard rules
    - STANDARD

    # Documentation requirements
    - COMMENTS                                  # All public elements must be documented
    - COMMENT_FIELD                            # All fields require comments
    - COMMENT_ENUM                             # All enums require comments
    - COMMENT_ENUM_VALUE                       # All enum values require comments
    - COMMENT_MESSAGE                          # All messages require comments
    - COMMENT_ONEOF                            # All oneofs require comments
    - COMMENT_RPC                              # All RPCs require comments
    - COMMENT_SERVICE                          # All services require comments

    # Naming conventions
    - FILE_LOWER_SNAKE_CASE                    # Files: snake_case.proto
    - PACKAGE_LOWER_SNAKE_CASE                 # Packages: lower.snake.case
    - PACKAGE_DIRECTORY_MATCH                  # Package must match directory
    - PACKAGE_SAME_DIRECTORY                   # One package per directory

    # RPC standards
    - RPC_REQUEST_STANDARD_NAME                # Request: {RPC}Request
    - RPC_RESPONSE_STANDARD_NAME               # Response: {RPC}Response
    - RPC_REQUEST_RESPONSE_UNIQUE              # Unique request/response types

    # Service standards
    - SERVICE_SUFFIX                           # Services end with "Service"

    # Field standards
    - FIELD_LOWER_SNAKE_CASE                   # Fields: snake_case
    - ONEOF_LOWER_SNAKE_CASE                   # Oneofs: snake_case

    # Enum standards
    - ENUM_PASCAL_CASE                         # Enums: PascalCase
    - ENUM_VALUE_UPPER_SNAKE_CASE             # Enum values: UPPER_SNAKE_CASE
    - ENUM_ZERO_VALUE_SUFFIX                   # First value ends with _UNSPECIFIED
    - ENUM_NO_ALLOW_ALIAS                      # No enum aliases

    # Package versioning
    - PACKAGE_VERSION_SUFFIX                   # Packages end with version (v1, v2)

  # Exceptions to standard rules
  except:
    []

  # Enum zero value must be {ENUM_NAME}_UNSPECIFIED
  enum_zero_value_suffix: _UNSPECIFIED

  # RPC methods cannot use same type for request and response
  rpc_allow_same_request_response: false

  # RPC methods cannot use google.protobuf.Empty
  rpc_allow_google_protobuf_empty_requests: false
  rpc_allow_google_protobuf_empty_responses: false

  # Service names must end with "Service"
  service_suffix: Service

# =============================================================================
# Breaking Change Detection
# =============================================================================
# Protects API consumers from unexpected breaking changes
breaking:
  use:
    # File-level changes
    - FILE                                      # Track all file changes

    # Wire format compatibility (binary)
    - WIRE                                      # Protobuf wire format compatibility
    - WIRE_JSON                                 # JSON wire format compatibility

    # Package changes
    - PACKAGE                                   # Package name changes

  # Exceptions
  except:
    # Allow certain non-breaking changes
    - FIELD_SAME_DEFAULT                       # Allow default value changes
    - FIELD_SAME_JSON_NAME                     # Allow json_name changes

  # Ignore breaking changes in experimental APIs
  ignore:
    - proto/experimental
    - proto/**/experimental