// Copyright 2020-2025 Buf Technologies, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package buf.alpha.module.v1alpha1;

import "buf/alpha/breaking/v1/config.proto";
import "buf/alpha/lint/v1/config.proto";

enum DigestType {
  DIGEST_TYPE_UNSPECIFIED = 0;
  DIGEST_TYPE_SHAKE256 = 1;
}

// Digest represents a hash function's value.
message Digest {
  // digest_type describes the hash algorithm. e.g. "SHAKE256"
  DigestType digest_type = 1;
  // digest is the hash's output without encoding.
  bytes digest = 2;
}

// Blob represents some module content with an associated digest.
message Blob {
  // Digest of the content.
  Digest digest = 1;
  // Content of the blob.
  bytes content = 2;
}

// Module is a module.
message Module {
  // files are the files that make up the set.
  //
  // Sorted by path.
  // Path must be unique.
  // Only the target files. No imports.
  //
  // Maximum total size of all content: 32MB.
  repeated ModuleFile files = 1;
  // dependencies are the dependencies.
  repeated ModulePin dependencies = 2;
  // documentation is the string representation of the contents of the file at documentation_path.
  //
  // string is used to enforce UTF-8 encoding or 7-bit ASCII text.
  string documentation = 3;
  // breaking_config is the breaking change detection configuration set for the module.
  buf.alpha.breaking.v1.Config breaking_config = 4;
  // lint_config is the lint configuration set for the module.
  buf.alpha.lint.v1.Config lint_config = 5;
  // license is the string representation of the contents of the `LICENSE` file.
  //
  // string is used to enforce UTF-8 encoding or 7-bit ASCII text.
  string license = 6;
  // documentation_path is the path of the file which contains the module documentation.
  //
  // either `buf.md`, `README.md` or `README.markdown`.
  // if empty, assumes buf.md.
  string documentation_path = 7;
}

// ModuleFile is a file within a FileSet.
message ModuleFile {
  // path is the relative path of the file.
  // Path can only use '/' as the separator character, and includes no ".." components.
  string path = 1;
  // content is the content of the file.
  bytes content = 2;
}

// ModuleReference is a module reference.
message ModuleReference {
  string remote = 1;
  string owner = 2;
  string repository = 3;
  // either tag, or commit
  string reference = 4;
}

// ModulePin is a module pin.
message ModulePin {
  reserved 4, 6, 7;
  reserved "branch", "create_time", "digest";

  string remote = 1;
  string owner = 2;
  string repository = 3;
  string commit = 5;
  // Module's manifest digest. Replacement for previous b1/b3 digests.
  // This is in the format '<digest_type>:<digest>`, where '<digest_type>' is the lowercase digest name ('shake256'),
  // and '<digest>' is the lowercase hex-encoded digest.
  // This value is persisted directly to the buf.lock file (https://buf.build/docs/configuration/v1/buf-lock) as the 'digest' key.
  string manifest_digest = 8;
}
