Bỏ qua để đến nội dung
AggregaAggrega
Chọn ngôn ngữ: Tiếng Việt
Trang này được dịch bằng máy. Đọc bản gốc tiếng Anh.

aggrega validate

aggrega validate kiểm tra tính đúng đắn — schema, cấu trúc pillar, việc phân giải tham chiếu giữa các tài liệu, các chuỗi extends, khả năng input-kind của provider, và (đối với một entity có render) việc nó thực sự render được. Lệnh có ba chế độ, được chọn theo đối số, áp dụng cùng một nguyên tắc kiểm tra tính đúng đắn ở ba phạm vi: toàn bộ catalog (không có đối số), bao đóng phụ thuộc của một Release (--release), và một tệp entity (một đường dẫn entity). Mỗi phạm vi trả lời cùng một câu hỏi — “nội dung này có đúng không?” — trên một phần khác nhau của catalog.

Tính đúng đắn khác với các quy ước. aggrega validate hỏi liệu nội dung có đúng định dạng và có biên dịch được không; aggrega lint hỏi liệu nội dung có tuân theo nguyên tắc xuất bản của catalog không (đặt tên, sự khớp giữa danh mục và thư mục, mức tăng phiên bản, và các mục khác). Hai lệnh phản chiếu ba phạm vi của nhau để bạn có thể kiểm tra một trong hai khía cạnh ở bất kỳ mức chi tiết nào bạn cần.

aggrega validate không ghi gì xuống đĩa và không đọc trạng thái runtime nào. Lệnh chạy cùng quá trình phân giải và kiểm tra hợp lệ mà một lần build chạy, dừng lại trước bước render (hoặc, với một entity đơn lẻ, cô lập bước render).

Có thể truyền đường dẫn entity dưới dạng đối số vị trí. --release được truyền cùng một đường dẫn entity không chọn phạm vi Release: entity vẫn được kiểm tra riêng, theo các điều kiện của Release đó — xem Kiểm tra một entity theo các điều kiện của một Release.

Tính đúng đắn của toàn bộ catalog (không có đối số)

aggrega validate khi không có đối số sẽ tải mọi entity của catalog trong các thư mục catalog đã cấu hình và kiểm tra từ đầu đến cuối. Trước khi tải bất cứ thứ gì, lệnh đọc mọi tệp YAML trong các thư mục đó, và một tài liệu Aggrega trong số đó mà lệnh không tải được sẽ dừng lần chạy, như mô tả bên dưới. Sau đó:

  • Cấu trúc schema pillar — khối spec.schema: của mỗi Component và Feature được mở rộng và xác thực (cùng phép kiểm tra schema pillar mà bản build áp dụng), bao gồm cả việc mở rộng dạng rút gọn.
  • Phân giải tham chiếu giữa các tài liệu — các tham chiếu $ref và $import tới các mục của SchemaLibrary được phân giải, và một SchemaLibrary không thể phân giải hoặc không hợp lệ theo cách khác sẽ bị từ chối.
  • Chuỗi extends — mọi thực thể khai báo extends đều được phân giải theo thực thể cha của nó, và hình dạng hợp nhất cha+con được kiểm tra. Một thực thể cha mà các thư mục catalog không chứa được đọc ở nơi một bản build đọc nó: từ bộ nhớ đệm artifact, theo bản ghim mà lockfile của một Release ghi lại cho nó — lockfile của các Releases mà lượt kiểm tra được chạy cho, hoặc của mọi Release mà workspace chứa khi workspace được xác thực trong một lượt. Vì vậy, một thực thể cơ sở được xuất bản lên registry sẽ qua xác thực khi aggrega pull đã tải và ghim nó, còn một thực thể cha mà cả hai đều không chứa sẽ dừng lần chạy, nêu tên aggrega pull --release <release>. Không có gì được tải về.
  • Các selector được khai báo — mọi label selector mà một tài liệu Component hoặc Feature khai báo trên một socket phụ thuộc dưới spec.usesSchema, hoặc trên một slot attachment dưới spec.featuresSchema — kể cả, trên một Component, các slot mà một socket khai báo — đều được đọc theo ngữ pháp selector, dù có hay không có gì nối socket đó hoặc điền slot đó. Xem các selector được khai báo.
  • Xung đột vị trí OCI — hai định danh catalog khác nhau mà sẽ xuất bản tới cùng một vị trí registry sẽ bị từ chối một cách rõ ràng, để một bản build không bao giờ âm thầm ghi đè các byte đã xuất bản của một entity bằng của entity khác.
  • Khả năng xử lý loại đầu vào của Provider — một Recipe hoặc FeatureRecipe khai báo khối workload: được gắn với một provider không thể tổng hợp sẽ bị gắn cờ là lỗi, vì nó không bao giờ có thể build được.

Đây là bản đối ứng trên toàn catalog của việc xác thực theo từng Release trong một bản build — nơi một entity catalog bị hỏng được dự định sẽ lộ ra, trước khi bất kỳ Release nào chạm tới nó. Lệnh dừng rõ ràng khi gặp một tài liệu Aggrega không tải được, và khi gặp bất kỳ vi phạm schema pillar, thư viện không thể phân giải hoặc không hợp lệ, lỗi phân giải extends, selector được khai báo mà ngữ pháp từ chối, xung đột vị trí, hay lỗi khả năng input-kind nào. Các phát hiện về chồng lấn schema pillar và thu hẹp khi extend, cùng mỗi từ khóa x-aggrega-* mà một Component hoặc Feature viết trực tiếp trong nội dung schema của nó, là các dòng notice: mang tính khuyến nghị, không bao giờ thay đổi mã thoát.

Một tài liệu Aggrega không tải được sẽ dừng lần chạy. Một tệp YAML trong thư mục catalog là tài liệu Aggrega khi một trong các dòng của nó bắt đầu, không thụt lề, bằng apiVersion: và một giá trị bắt đầu bằng aggrega.ai/, có hay không có dấu ngoặc kép. Một tệp như vậy mà không đọc được, có YAML không phân tích cú pháp được, hoặc có kind hay metadata không mang hình dạng của envelope của entity — chẳng hạn một metadata viết dưới dạng danh sách — sẽ dừng lần chạy với E0175 sau khi các thư mục đã được đọc, nêu tên mọi tệp như vậy cùng lý do mà thao tác đọc hoặc trình phân tích đưa ra; không có gì được kiểm tra và không có dòng catalog validation passed nào được in ra. Một tài liệu tải được nhưng khai báo một kind mà không catalog nào chứa — chẳng hạn Componnent viết sai chính tả, hoặc hoàn toàn không có kind — sẽ dừng cùng lần chạy đó với E0371, được nêu tên bên cạnh các tệp kia cùng với loại mà nó khai báo; một Manifest, một Release, và một Workload mà một Recipe nhập từ thư mục của chính nó đều được bỏ qua. Mọi YAML khác — các template của một Helm chart, vốn không phân tích được cho đến khi được render, các giá trị chart, các định nghĩa workflow — đều được bỏ qua.

Những thư mục mà lệnh đọc phụ thuộc vào cấu trúc của workspace:

  • Một workspace mà cấu hình không đưa ra thư mục catalog Release riêng nào được xác thực một lần, trên ngăn xếp tìm kiếm của nó: các thư mục --catalog, sau đó workspace.catalog_dirs, rồi thư mục catalog ở gốc workspace nếu có.

  • Một workspace đặt tên các Releases trong workspace.releases có thể giữ một catalog ở nhiều biến thể song song, mỗi biến thể được Release riêng của nó đọc, và việc tải tất cả cùng lúc sẽ đặt mọi biến thể vào một catalog, khiến entity của biến thể này che khuất entity của biến thể khác. Vì vậy nó được xác thực một lần cho mỗi Release mà workspace chứa, trên các thư mục mà Release đó đọc, với các thư mục --catalog đứng đầu trong mọi lượt; một Release mà cấu hình không đặt tên sẽ đọc danh sách của workspace. Mỗi lượt được báo cáo dưới một dòng nêu tên Release của nó và các thư mục nó đã đọc, tiếp theo là kết quả của lượt đó:

    Release release-compose.yaml reads catalog-compose
    catalog validation passed (schema-pillar + library + extends + oci-location)
    Release release-helm-synth.yaml reads catalog-helm-synth
    catalog validation passed (schema-pillar + library + extends + oci-location)

    Các Releases đọc đúng cùng các thư mục sẽ dùng chung một lượt, lượt này nêu tên từng Release. Một Release không đọc thư mục nào — mục của nó ghi catalog_dirs: [] — được báo cáo là không có gì để kiểm tra, và các lượt khác chạy như bình thường. Mọi lượt đều được báo cáo bất kể lượt trước phát hiện gì, vì một entity bị hỏng ở một biến thể không nói lên điều gì về biến thể khác, và lệnh thất bại khi bất kỳ lượt nào thất bại, nêu tên các Releases có thư mục bị lỗi. Các Releases mà một workspace chứa là các tài liệu Release của nó — các tệp YAML có kind là Release, ở bất kỳ đâu dưới gốc workspace, ngoài các thư mục ẩn và node_modules, vendor và dist.

Một lần chạy không có gì để đọc trong bất kỳ lượt nào sẽ bị từ chối thay vì được báo cáo là một catalog sạch: hãy đặt các entity dưới catalog/, truyền --catalog, hoặc đặt workspace.catalog_dirs — hoặc, trong một workspace đặt tên các Releases, đặt catalog_dirs riêng của một Release trong workspace.releases. Lệnh không bao giờ ngầm liệt kê thư mục làm việc hiện tại, nên không bao giờ kéo vào các cây thư mục không liên quan.

Công cụ validate của aggrega mcp, khi được yêu cầu cho toàn bộ catalog, xác thực cùng các lượt đó; trong một workspace đặt tên các Releases, câu trả lời của nó mang từng lượt dưới passes — các Releases, các thư mục đã đọc và kết luận riêng của lượt đó — bên cạnh kết luận chung cho tất cả.

Một library chỉ có trong cache artifact

Cache artifact chứa những gì một lần tải về đặt vào đó, và một SchemaLibrary trong cache chỉ được tính là nội dung catalog khi một mục trong lockfile của một Release bảo đảm cho digest của nó — xem Cache là gì, và không phải là gì. Khi một $ref: không phân giải được thành gì trong khi cache chứa một library mà không mục lockfile nào ghim và không thư mục catalog nào mà bước kiểm tra đọc cung cấp, báo cáo sẽ được theo sau bởi một dòng remediation: nêu tên từng library như vậy và hành động có tác dụng cho phạm vi đã thất bại:

  • Khi không có đối số, và khi có đường dẫn thực thể dù có cung cấp --release hay không, validate chỉ đọc các library từ các thư mục catalog, không bao giờ thông qua một mục lockfile, nên một mục đã ghi nhận sẽ không thay đổi phán quyết của nó. Dòng này nói rõ như vậy, và chỉ tới việc viết library dưới một thư mục catalog, hoặc tới aggrega pull --release <release> rồi đến aggrega validate --release <release>, lệnh kiểm tra Release dựa trên các library mà lockfile của nó ghim.
  • Khi chỉ có --release, validate đọc lockfile của Release, nên dòng này nêu aggrega pull --release <release>, lệnh phân giải library và ghi nhận mục của nó, hoặc việc viết library dưới một thư mục catalog.

Dòng này không thay đổi phán quyết lẫn mã thoát.

Các selector được khai báo

Một Component hoặc Feature giới hạn những gì có thể được nối vào các socket phụ thuộc của nó, và những gì có thể điền các slot attachment của nó, bằng label selector — selector: của mỗi mục spec.usesSchema và mỗi mục spec.featuresSchema, và trên một Component là selector: của mỗi slot mà một socket khai báo dưới featuresSchema của chính nó. Một bản build chỉ đọc một selector ở nơi có thứ gì đó chạm tới nó: một cạnh đi qua socket, một attachment điền vào slot. Vì vậy phạm vi toàn catalog và phạm vi một thực thể đọc mọi selector mà một tài liệu Component hoặc Feature khai báo, dù có hay không có gì nối socket hoặc điền slot, và một selector mà ngữ pháp từ chối — một danh sách giá trị thiếu dấu ngoặc đóng, một dấu phẩy lặp đôi, một khóa chứa = hoặc ! — làm phép kiểm tra thất bại. Ngữ pháp này là ngữ pháp được trình bày trong ngữ pháp chuỗi.

Lời từ chối này chính là lời từ chối mà một bản build báo cáo khi nó chạm tới cùng selector đó, với cùng mã và cùng câu chữ: E0007 cho selector của một socket và E0008 cho selector của một slot, nêu tên selector, socket hoặc slot khai báo nó, và lý do ngữ pháp không đọc được nó. Nó được ghi nhận là một lỗi catalog tại tệp của thực thể:

selector violation ("<selector>", declared on socket "<socket>", which could not be evaluated: "<why it could not be read>"). Correct the selector on the socket’s declaration in the component type’s usesSchema. (vi phạm selector: selector được khai báo trên socket không thể được đánh giá. Hãy sửa selector trong phần khai báo socket ở usesSchema của kiểu component.)

Mỗi tài liệu được đọc đúng như tác giả của nó đã viết, nên một selector mà một thực thể cơ sở khai báo được báo cáo một lần, đối với chính tệp của thực thể cơ sở, thay vì một lần cho mỗi thực thể mở rộng nó. appliesTo và appliesToAnyOf của một Feature không được đọc ở đây: chúng được đọc ở bất cứ nơi nào một attachment của Feature được đánh giá.

Phạm vi toàn catalog báo cáo mỗi selector bị từ chối trên dòng selector: riêng của nó và thất bại kèm số lượng của chúng; phạm vi một thực thể báo cáo chúng như lỗi ở tầng hình dạng của nó — dù có hay không có --release bên cạnh đường dẫn thực thể, vì dạng đó là phạm vi một thực thể chạy theo các điều khoản của một Release (xem kiểm tra một thực thể theo các điều khoản của một Release). --release đứng riêng, vốn xác thực closure phụ thuộc của một Release, và một bản build chỉ đọc một selector ở nơi một cạnh hoặc một lần điền chạm tới nó, và dừng lại tại đó.

Tính đúng đắn trong phạm vi Release (--release)

aggrega validate --release <release-path> kiểm tra đúng những thực thể mà các phụ thuộc đã phân giải của một Release duy nhất chạm tới, thay vì toàn bộ catalog hay một thực thể. Lệnh tính bao đóng thông qua cùng cơ chế mà một lần build sử dụng, nên các thực thể được kiểm tra chính là những thực thể mà một lần build Release đó sẽ phân giải, và trên bao đóng đó lệnh:

  • phân giải các chuỗi extends trong phạm vi bao đóng, thất bại khi có lỗi phân giải;
  • kiểm tra các schema pillar của từng thực thể đã phân giải (trong phạm vi bao đóng), thất bại khi có lỗi schema pillar;
  • chạy cùng bước kiểm tra tính phù hợp của giá trị trước khi render mà một lần build chạy — lệnh phân giải các parameters của Release vào các giá trị đã viết (để một giá trị {{ .parameters.* }} được kiểm tra ở dạng đã phân giải, không phải ở dạng template) và kiểm tra kết quả theo các schema đã kết hợp của bao đóng, bao gồm kiểm tra tính phù hợp với schema cha+con đã kết hợp cho một thực thể dùng extends. Một giá trị vi phạm schema của nó sẽ thất bại với mã thoát khác không;
  • đánh giá mọi assertion của Recipe và FeatureRecipe dựa trên các giá trị mà Release phân giải ra, giống như một bản build đánh giá chúng trước khi render: Recipe của mỗi thành phần được ràng buộc theo cách Manifest ánh xạ nó, locals và provides của nó được phân giải, và assertion đầu tiên thất bại — một assertion gọi fail, hoặc một assertion có template dừng lại tại một khóa mà nó không tìm thấy — sẽ làm việc xác thực thất bại với cùng điều kiện và câu mà một bản build dùng khi dừng lại. Một template locals hoặc provides không thể đánh giá cũng làm việc xác thực thất bại, như nó làm một bản build thất bại. Giống như một bản build, việc xác thực hỏi provider mà mỗi Recipe render qua về tên mà provider đó đặt cho các tài nguyên của thành phần đó, vì provides của một Recipe có thể đọc tên đó; không có gì được render. Các assertion này chỉ được đánh giá khi chưa có mục nào ở trên thất bại, nên một Release báo cáo lỗi sớm nhất mà một bản build sẽ dừng lại;
  • hiển thị các phát hiện về chồng lấn schema pillar và thu hẹp khi extend dưới dạng các dòng notice: mang tính thông tin, không bao giờ thay đổi mã thoát;
  • hiển thị mỗi từ khóa x-aggrega-* mà một thực thể được nó đọc viết trực tiếp trong nội dung schema của thực thể đó dưới dạng một dòng warning:, một lần cho mỗi thực thể, như một bản build hiển thị nó — nó cũng không bao giờ thay đổi mã thoát.

Điều này khiến --release trở thành một bước kiểm tra trước build thực sự: nó bắt được những gì một lần build sẽ từ chối, trước khi build — bước kiểm tra phụ thuộc của build mà không có render. Lệnh không render và không kích hoạt việc tải qua mạng: bao đóng được phân giải từ catalog cục bộ (và các pin trong lockfile của Release, nếu có); một tập phụ thuộc được pin theo registry cần lockfile sẽ báo một lỗi tham chiếu không thể phân giải một cách trung thực thay vì tải về. Việc thu hẹp được hiển thị như lời khuyên, không bao giờ bị cưỡng chế.

Một lockfile không còn khớp với những gì Release phân giải thành sẽ từ chối việc xác thực bằng điểm dừng mà aggrega build in ra. Khi có một lockfile nằm cạnh Release, --release đối chiếu nó với những gì Release phân giải thành, bằng phép so sánh sai lệch mà một bản build chạy trước khi render, ngay khi các phụ thuộc của Release được phân giải và trước khi bất kỳ phép kiểm tra nào ở trên chạy. Một lockfile mà một entity, thư viện, plugin đã được pin hoặc chính tệp Release đã sai lệch khỏi sẽ dừng việc xác thực bằng lời từ chối E0130 của bản build — mọi mục đã sai lệch, rồi đến aggrega pull --release <release> để khắc phục — và một mã thoát khác không, nên việc xác thực không bao giờ bỏ qua một lockfile mà bản build từ chối vì sai lệch. Khi không có đối số, và khi có đường dẫn thực thể, validate không bị ràng buộc bởi lockfile: phép kiểm tra toàn bộ catalog chỉ đọc các bản ghim trong lockfile để tìm thực thể cha extends, và phép kiểm tra một thực thể không đọc lockfile nào.

Vì lệnh chạy cùng các bước kiểm tra mà một lần build chạy, nó cũng chạy cùng các gate plugin được gắn — nên nó chịu cùng bản ghi danh tính plugin tin cậy mà một lần build phải tuân theo. Một workspace gắn một plugin trả về phán quyết chấp nhận-hoặc-từ chối có một bản ghi tin cậy plugin bên cạnh Release của nó, và --release so sánh cấu hình với bản ghi đó trước khi bất kỳ plugin nào trong số đó chạy: một gate đã được ghi mà cấu hình không còn gắn sẽ dừng việc kiểm tra, và một plugin được phân giải từ bộ nhớ đệm do aggrega pull nạp mà artifact của nó không phải là artifact đã ghi sẽ bị từ chối thay vì được chạy. Một workspace chưa ghi gì thì không có bản ghi, điều này không thay đổi gì đối với phép so sánh đó. --release cũng nêu mọi lần rút lại được ghi nhận đối với những gì Release phụ thuộc vào, trên standard error dưới dạng một dòng deprecation: theo đúng lời mà aggrega build in ra: cả dấu mà lockfile ghi nhận đối với một tham chiếu đã ghim lẫn dấu mà bản ghi tin cậy ghi nhận đối với một plugin được gắn trong một vai trò phán quyết. Một lần rút lại không thay đổi phán quyết lẫn mã thoát, và một bản ghi tin cậy có tồn tại nhưng không đọc được sẽ dừng việc kiểm tra thay vì được coi như một bản ghi không ghi nhận gì.

Một plugin đọc từ bộ nhớ đệm cũng chịu chữ ký mà mục của nó ghi lại, như một lần build áp dụng, tại thời điểm nó được nạp. Khi mục của nó ghi một chữ ký đã xác minh, tài liệu chữ ký mà thông tin đó chỉ tới trong bộ nhớ đệm được kiểm tra lại, và một plugin có tài liệu bị thiếu hoặc khác sẽ bị từ chối — một plugin có tài liệu được tạo cho một plugin khác với plugin được đọc cũng vậy, đó là dấu hiệu của một signature được sao chép từ một mục khác, bất kể yêu cầu ký nói gì. Khi cấu hình tin cậy của workspace yêu cầu chữ ký, một plugin đọc từ bộ nhớ đệm mà mục của nó không ghi chữ ký nào — hoặc bản ghi không có mục nào cho nó, kể cả khi bản ghi đã bị xóa — cũng bị từ chối, theo cùng các thiết lập khiến aggrega pull từ chối nó vì không được ký, nên skip_signature_verification và một registry advisory cho phép nó chạy. Một lần từ chối làm việc kiểm tra thất bại và được báo cáo trong các chẩn đoán của nó, nêu tên plugin và aggrega pull --release <release>, lệnh xác minh chữ ký của plugin tại registry của nó, ghi lại và lưu đệm bundle mà chữ ký chỉ tới, ghi đè một bản sao đã lưu đệm không còn khớp với digest của nó; một plugin được cung cấp từ một trong các thư mục catalog của bạn, hoặc từ bản sao bên trong tệp nhị phân của trình biên dịch, không bao giờ chịu yêu cầu này. Hai phạm vi còn lại không chịu bất kỳ điều nào ở đây: chúng không đọc các plugin được gắn của workspace, nên không có plugin nào như vậy chạy trong đó.

Điều tương tự áp dụng cho các plugin thay đổi đồ thị thay vì đánh giá nó. Một attachment label-transform hoặc annotation-transform định hình đầu ra được render, nên lockfile pin cả danh tính của nó lẫn các tệp nguồn mà nó đọc — và --release chạy các attachment đó theo cách một lần build chạy chúng: được tái dựng từ lockfile, buộc mỗi attachment khớp với digest đã ghi, và đọc nội dung nguồn mà lockfile mang theo thay vì tệp trên đĩa. Có hai hệ quả đáng biết trước khi bạn gặp chúng:

  • Gắn một transform plugin trong .aggrega-config.yaml không thay đổi những gì --release làm cho đến khi bạn pull. Đây là cùng quy tắc mà một lần build tuân theo, và vì cùng lý do: tập attachment là một đầu vào quyết định byte, nên nó được áp dụng tại lần pull thay vì tại thời điểm được chỉnh sửa.
  • Một plugin đã lưu đệm có byte không còn khớp với digest mà lockfile đã ghi sẽ bị từ chối, đúng như khi build.

Nếu Release không có lockfile, --release vẫn kiểm tra — lệnh cảnh báo rằng nó không thể kiểm tra danh tính của một plugin và cho biết cần chạy gì, thay vì từ chối. Xem cảnh báo.

Trả lại đồ thị đã biên dịch

--ir-graph ghi đồ thị mà lần kiểm tra này đã phân giải ra đầu ra chuẩn dưới dạng JSON, trước dòng phán quyết. Cờ này chỉ bổ sung: cùng các bước kiểm tra được chạy, cùng các chẩn đoán được ghi, và mã thoát giống như khi không có nó. Đồ thị được trả lại chính là đồ thị mà việc kiểm tra được thực hiện trên đó, nên nó không thể mô tả một kết quả phân giải khác với kết quả mà phán quyết báo cáo.

Cờ này chỉ áp dụng cho phạm vi này — các phạm vi toàn catalog và một thực thể vận hành một harness tổng hợp thay vì một Release, và không phân giải đồ thị nào — và yêu cầu nó ở nơi khác sẽ bị từ chối thay vì bị bỏ qua một cách im lặng. Nếu lần chạy dừng trước khi đồ thị được phân giải, không có gì được ghi ra đầu ra chuẩn và chính các chẩn đoán của lệnh cho biết điều gì đã làm nó dừng.

Lưu ý cờ bên cạnh nó. --response-format đặt mức độ chi tiết của báo cáo riêng của lệnh này được ghi ra (detailed hoặc concise); --ir-graph yêu cầu một tài liệu thứ hai bên cạnh báo cáo đó. Một cờ là về lượng, cờ kia là về chủ đề, và không cờ nào thay đổi phán quyết.

Các giá trị mà tác giả khai báo là nhạy cảm được giữ lại khỏi đồ thị — kể cả values và infra của một kết nối, khi socket của component tiêu thụ khai báo một lá là nhạy cảm — theo dạng có cấu trúc được mô tả tại aggrega inspect. --unredacted bên cạnh --ir-graph sẽ in chúng ra, theo các điều kiện mà aggrega inspect --unredacted nêu: nó chỉ tác động tới đồ thị và không gì khác mà lệnh này ghi, và bất cứ nơi nào đầu ra tới khi đó sẽ mang các giá trị đó ở dạng rõ. Nếu truyền mà không có --ir-graph thì nó bị từ chối, vì sẽ không có gì để nó tiết lộ.

Tính đúng đắn của một thực thể (một đường dẫn thực thể)

aggrega validate <entity-path> kiểm tra một tệp thực thể của catalog. Lệnh áp dụng một tập kiểm tra theo từng tầng, dừng ở lỗi chặn đầu tiên để một lỗi schema hiện ra rõ ràng trước mọi công việc trên catalog:

  • Placeholder (mọi loại) — một giá trị mà loại thực thể yêu cầu nhưng tệp để là chuỗi rỗng. Tất cả được báo cáo cùng lúc, trước các kiểm tra khác, mỗi cái kèm theo giá trị nó cần; xem các placeholder còn thiếu.
  • Lớp vỏ schema (mọi loại) — chính kiểm tra JSON-Schema theo từng thực thể mà trình nạp catalog chạy ở mỗi ranh giới phân tích.
  • Hình dạng (mọi loại) — việc xác thực cấu trúc riêng cho từng loại. Với một Component hoặc Feature, việc này bao gồm đọc mọi label selector mà tệp khai báo trên một socket phụ thuộc hoặc một slot attachment theo ngữ pháp selector; xem các selector được khai báo.
  • Cấu trúc trụ cột (Component và Feature) — kiểm tra trụ cột spec.schema:, dùng các SchemaLibraries của catalog để mở rộng $ref xuyên tài liệu.

Một Component hoặc Feature dừng ở đó: lớp vỏ schema, hình dạng và cấu trúc trụ cột. Một Component đơn lẻ không có values hay infra được khai báo để render riêng, nên không có gì để render — tính đúng đắn của nó được bao phủ hoàn toàn bởi các tầng schema và trụ cột. Mỗi từ khóa x-aggrega-* mà nội dung schema của nó viết trực tiếp được báo cáo trong số các ghi chú khuyến nghị trên standard error dưới dạng một dòng warning: nêu tên từ khóa, vị trí của nó và bảng khai báo nên viết thay thế; nó không bao giờ thay đổi phán quyết hay mã thoát.

Một Recipe còn được render riêng lẻ. Đây là một khía cạnh của tính đúng đắn của một thực thể, không phải điểm chính của nó: sau khi các tầng schema và hình dạng vượt qua, validate phân giải Component implements của Recipe từ catalog, tổng hợp một Aggregate, Manifest và Release tối thiểu bao quanh một instance duy nhất của Component đó được gắn với Recipe đang kiểm tra, rồi chạy pipeline biên dịch thật trên đó — trước hết là phân giải và các guard (bỏ qua render), sau đó là một lần render thật đầu ra riêng lẻ. Mỗi giá trị bắt buộc và mỗi trường infra bắt buộc không có mặc định được điền một placeholder theo kiểu đã khai báo — các giá trị trong Aggregate tổng hợp, infra trong Release tổng hợp — và mọi giá trị và trường infra khác nhận mặc định schema của nó qua bộ phân giải; Release định tuyến instance vào một ranh giới mặc định tổng hợp và không khai báo values: nào cũng như không có compute nào mà Aggregate không khai báo. Một placeholder là một giá trị mà các ràng buộc khai báo của chính trường đó chấp nhận: hằng số hoặc giá trị đầu tiên mà một enum liệt kê, một số nằm trong giới hạn, một chuỗi đúng độ dài và đúng format, một phiên bản ngữ nghĩa khi pattern của nó yêu cầu, đủ số phần tử danh sách cần thiết, và mọi thuộc tính mà một đối tượng yêu cầu. Bất kỳ pattern nào khác, một điều kiện validate: hoặc when:, một tổ hợp schema và một ràng buộc về những phần tử mà danh sách chứa đều không được xét đến, nên một trường dựa vào chúng vẫn có thể từ chối placeholder của nó; khi đó validate báo cáo sự từ chối đó bằng chính lời của schema. Các artifact đã render được in ra để tác giả thấy đầu ra riêng lẻ trước khi nối thực thể vào một Aggregate đầy đủ. Vì một harness cho một thực thể chỉ điền những trường bắt buộc đó, không nối kết nối nào và không gắn Feature nào, một Recipe có template đọc một giá trị mà chỉ một kết nối hoặc một Feature được gắn mới cung cấp thì không thể render riêng lẻ; validate báo cáo lần render đó là chưa được thử chứ không phải thất bại. Một assertion gọi fail được báo cáo là cảnh báo thay vì làm kiểm tra thất bại — xem một assertion thất bại là một cảnh báo. Một lần render dừng vì bất kỳ lý do nào khác là chưa hoàn tất, và validate báo cáo nó kèm chẩn đoán render bên dưới, đến tận câu nêu tên điều đã làm nó dừng.

Một Recipe có source: phải được tải về thì hoàn toàn không được render, và một Recipe có lần render dừng khi đọc một giá trị mà chỉ một kết nối hoặc một Feature được gắn cung cấp thì lần render đó bị gác lại — xem những gì tính đúng đắn của một thực thể không kiểm tra bên dưới.

Một FeatureRecipe được kiểm tra schema và hình dạng; lần render của nó bị bỏ qua, vì một FeatureRecipe chỉ render khi được gắn vào một component chủ, và việc tổng hợp một component chủ vượt qua guard cho một Feature bất kỳ không được thử.

Kiểm tra một thực thể theo các điều kiện của một Release

Một workspace có thể cấp cho mỗi Release các thư mục catalog riêng — xem Cấp cho một Release các thư mục catalog riêng — và nhờ đó giữ song song một biến thể catalog cho mỗi Release. Một đường dẫn thực thể được đưa riêng lẻ sẽ được kiểm tra trên các thư mục catalog của chính workspace, nơi một tham chiếu vào một trong các biến thể đó — Component mà một Recipe hiện thực, một SchemaLibrary mà một trụ cột tham chiếu — không được tìm thấy. Đưa --release bên cạnh đường dẫn thực thể thì cùng các kiểm tra đó chạy theo các điều kiện của Release ấy: các tham chiếu của thực thể được phân giải qua các thư mục catalog mà cấu hình workspace cấp cho Release đó, với bất kỳ --catalog nào được thêm vào đầu, chính là các thư mục mà một bản build của Release đó đọc.

Ví dụ MariaDB + Adminer giữ bốn biến thể như vậy. Component của biến thể synth lấy các thiết lập lưu trữ từ một SchemaLibrary mà chỉ các biến thể synth và chart mang theo, nên nó hợp lệ theo các điều kiện của Release build với nó:

$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/component/mariadb.yaml
Kind: Component
Schema: valid
Pillars: valid

và thất bại, nêu tên thư viện không phân giải được, theo các điều kiện của một Release có các thư mục không mang thư viện đó — --release release-compose.yaml, hoặc không có --release nào trong một workspace không liệt kê thư mục catalog riêng nào.

Một Recipe được kiểm tra theo cùng cách. Recipe của biến thể synth hiện thực core/datastore/mariadb, thứ mà các thư mục catalog của chính workspace không chứa, nên khi đưa riêng lẻ nó thất bại với render: implements target "core/datastore/mariadb" not found in catalog. Khi được đưa kèm Release build với nó, nó phân giải Component của Release đó và render riêng lẻ:

$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yaml
Entity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: 3 artifact(s)

tiếp theo là ba artifact đã render. Mọi biến thể của ví dụ đó đều khai báo core/datastore/mariadb, nên Recipe hợp lệ theo các điều kiện của từng Releases trong bốn Releases của nó; theo các điều kiện của một Release có thư mục catalog không chứa Component như vậy, nó thất bại và nêu tên đích, như khi không có --release. Các dòng Attachments: được giải thích ở một slot gắn kèm bắt buộc hoặc một yêu cầu hiện diện.

Đây vẫn là phạm vi một thực thể. Các kiểm tra, báo cáo và mã thoát là những gì phần này mô tả — một Component hoặc Feature mang một selector của socket hoặc slot mà ngữ pháp từ chối sẽ thất bại ở đây đúng như khi không có --release, xem các selector được khai báo — và không có closure nào được kiểm tra: --release nêu tên Release mà qua các thư mục catalog của nó các tham chiếu của thực thể được đọc, chứ không phải một closure để kiểm tra, đó là lý do --ir-graph bị từ chối khi đi kèm một đường dẫn thực thể. Một --release nêu tên một tệp không tồn tại, hoặc nêu tên một thư mục, bị từ chối trước khi bất cứ thứ gì được kiểm tra.

Một thư mục mà cấu hình workspace liệt kê nhưng không phải là thư mục — chẳng hạn không có gì tồn tại ở đó — cho Release đó, hoặc cho workspace khi không có --release, bị từ chối trước khi bất kỳ thứ gì được kiểm tra, như mọi lệnh đọc danh mục đó đều từ chối nó (Nơi các thực thể cục bộ được đọc): lời từ chối nêu tên mục, tệp cấu hình và dòng liệt kê nó cùng thiết lập, và không đưa ra kết luận nào. Kiểm tra thực thể của trình soạn thảo qua aggrega serve đưa ra cùng lời từ chối đó như mục duy nhất trên tệp của thực thể, ở mức lỗi, và công cụ validate của aggrega mcp từ chối lời gọi kèm theo nó.

Các placeholder vẫn còn thiếu

Một giá trị mà loại yêu cầu nhưng tệp để là chuỗi rỗng là một placeholder, và validate báo cáo nó trước mọi thứ khác. Một tài liệu được soạn sẵn bởi aggrega scaffold chứa một placeholder ở bất cứ nơi nào loại của nó cần một giá trị mà chỉ bạn mới cung cấp được, vì vậy đây là nơi bạn biết những giá trị nào còn lại. Đây là một FeatureRecipe được soạn sẵn chỉ với phiên bản đã được điền:

Entity: my-feature-recipe.yaml
Kind: FeatureRecipe
2 placeholders still owed in my-feature-recipe.yaml; an empty required value is not a value, so each of these needs one before the document validates:
7:3: spec.capability takes what its schema describes: The explicit provider capability this recipe binds to (e.g., 'helm', 'terraform', 'compose') — the provider kind that renders it.
8:3: spec.implements takes what its schema describes: Declares which catalog Feature type this recipe is able to implement (including credential Features labeled feature.aggrega.ai/kind: secret; exact version, major-compatible range '^', or unversioned).

Mọi placeholder trong tệp được nêu tên cùng lúc, theo thứ tự trong tài liệu, cùng với dòng và cột của nó và với những gì nó nhận. Những gì nó nhận được đọc từ chính schema của loại: các giá trị nó chấp nhận khi schema liệt kê chúng, một phiên bản ngữ nghĩa như 1.0.0 khi schema yêu cầu, và nếu không thì là câu đầu tiên trong mô tả của chính schema về trường đó.

Những giá trị nào được tính cũng được đọc từ schema. Một giá trị được tính khi loại yêu cầu nó ở cấp cao nhất của tài liệu, hoặc bên trong một đối tượng mà loại cũng yêu cầu, và tệp đặt nó thành chuỗi rỗng. Một khóa mà tệp bỏ hẳn sẽ được kiểm tra schema báo cáo là thuộc tính bị thiếu. Một trường tùy chọn để trống không phải là placeholder, và một trường chỉ bắt buộc bên trong một danh sách hoặc một map mà bạn chọn viết cũng vậy. Khi chính schema liệt kê chuỗi rỗng trong số các giá trị mà một trường chấp nhận, một giá trị rỗng là một giá trị chứ không phải placeholder.

Một giá trị vẫn còn thiếu ngay cả khi schema chấp nhận nó rỗng. Schema cho phép chuỗi rỗng cho capability và implements của một Recipe hoặc FeatureRecipe, nhưng một giá trị rỗng không chỉ ra provider nào và loại nào, vì vậy validate báo cáo cả hai là placeholder như mọi placeholder khác. Khi kiểm tra schema cũng từ chối cùng tệp đó — một phiên bản rỗng, một nhãn loại không có giá trị — báo cáo mang mã của kiểm tra đó, E0215, như ví dụ trên aggrega scaffold cho thấy; khi kiểm tra schema chấp nhận nó, như ở trên, báo cáo không mang mã nào. Một phát hiện trong cùng tệp không liên quan đến giá trị rỗng vẫn được báo cáo, bằng chính lời của kiểm tra schema, trước danh sách.

Cách đọc này thuộc về xác thực một thực thể, dù có hay không có --release bên cạnh đường dẫn thực thể. Một lần chạy toàn catalog gặp cùng tài liệu đó sẽ báo cáo những gì kiểm tra schema báo cáo, vì vậy một FeatureRecipe có implements rỗng bên trong một thư mục catalog sẽ vượt qua nó; phạm vi Release và aggrega build cũng không áp dụng cách đọc này.

Một loại mà phạm vi này không nhận

Xác thực một thực thể chấp nhận Component, Feature, Recipe, FeatureRecipe, Workload và Plugin. Một tệp thuộc bất kỳ loại nào khác sẽ bị từ chối, và lời từ chối nêu tên các loại mà nó chấp nhận và, đối với một loại thực thể, phạm vi có kiểm tra tài liệu thuộc loại đó:

kind "Aggregate" in "aggregate.yaml" is not a single-entity validation target; the kinds this scope accepts are Component, Feature, Recipe, FeatureRecipe, Workload and Plugin. An Aggregate is checked by the whole-catalog scope when it sits in a catalog directory, and by the Release scope over a Release that deploys it

Phạm vi toàn catalog là một lần chạy không có đối số, và phạm vi Release là --release không có đường dẫn thực thể:

LoạiĐược kiểm tra bởi
Aggregatemột lần chạy toàn catalog, khi nó nằm trong một thư mục catalog; --release trên một Release triển khai nó
Manifest--release trên một Release nêu tên nó
Release--release <release-path>
SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrarymột lần chạy toàn catalog, khi nó nằm trong một thư mục catalog

Một lần chạy toàn catalog chỉ đọc những gì nằm bên trong các thư mục catalog đã cấu hình, vì vậy một Aggregate được giữ ở thư mục gốc của workspace bên cạnh Release của nó sẽ được kiểm tra qua --release trên Release đó.

Một assertion thất bại là một cảnh báo

Một assertion gọi fail — do Recipe khai báo, hoặc do Component implements của nó khai báo — được báo cáo là một cảnh báo, và việc kiểm tra không thất bại vì nó. Release được tổng hợp chứa các placeholder và giá trị mặc định của schema thay cho các giá trị mà một Release thực đặt, vì vậy một assertion trên một giá trị như vậy, một image hoặc sự hiện diện của một điều kiện tiên quyết, sẽ thất bại ở đây dù Recipe có đúng hay không, và validate không thể phân biệt một assertion đang chờ một Release với một assertion bị hỏng. Phán quyết về assertion được để lại cho một bản build, vốn luôn có một Release.

Cảnh báo được ghi ra standard error, mở đầu bằng warning:, sau mọi ghi chú tư vấn. Nó mang toàn bộ thông điệp của assertion — thực thể, instance, tên của assertion và câu mà tác giả của nó đã viết — kết thúc bằng một câu nữa:

A Release must satisfy this assertion before a build of it can pass.

Báo cáo trên standard output cho biết lần chạy dừng ở đâu, và lệnh thoát với 0. Assertion của chính một Recipe dừng việc render, vì vậy báo cáo ghi Render: stopped on a failed assertion, reported as a warning sau Resolution: valid. Assertion của một Component được đánh giá trước khi bất cứ thứ gì được render, vì vậy báo cáo ghi Resolution: stopped on a failed assertion, reported as a warning, tiếp theo là Render: not attempted (the run stopped on that assertion). Dù theo cách nào, không có gì được render, nên không artifact nào được in ra.

Chỉ một assertion gọi fail mới là cảnh báo. Một assertion dừng lại ở một khóa mà nó đọc nhưng không tìm thấy, hoặc không phân tích được, là lỗi trong chính văn bản của assertion chứ không phải một assertion thất bại, và được đánh giá như mọi lần dừng khác. Mọi lỗi khác vẫn giữ vị trí của nó là phán quyết của việc kiểm tra.

aggrega build của một Release không thỏa mãn assertion sẽ dừng lại với một lỗi, nêu tên assertion và mang câu của tác giả nó, như mọi khi, và aggrega validate --release trên Release đó cũng thất bại với cùng lỗi đó. Việc kiểm tra thực thể của trình soạn thảo qua aggrega serve đưa ra cùng cảnh báo, hiển thị trên chính khóa của assertion khi Recipe khai báo nó, và công cụ validate của aggrega mcp trả lời valid: true với cảnh báo nằm trong notices của nó.

Những gì tính đúng đắn của một thực thể không kiểm tra

Bốn kiểm tra của một bản build thực nằm ngoài tầm với của một bản build cho một thực thể, và validate từ chối từng kiểm tra thay vì báo cáo một phát hiện mà nó không thể bảo đảm.

Một nguồn phải được tải về

Xác thực một thực thể không đọc lockfile, không đọc và ghi cache, và không thực hiện yêu cầu mạng nào. Một Recipe có source: chỉ đến thứ được lấy qua một phương thức truyền tải — một kho chart OCI hoặc HTTPS, một kho Git — do đó không có mã hạ tầng để render: chart hoặc module không tồn tại ở bất kỳ đâu mà lần chạy có thể tiếp cận, và không có gì trong tệp đang được kiểm tra là có lỗi. Validate nói rõ điều đó, in nó ra như một kết quả khác biệt với một lần render, và thoát với 0:

Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Resolution: valid
Render: not attempted (this Recipe's source is fetched)
Validating one entity on its own reads no lockfile, reads and writes no
cache, and makes no network request, so the chart or module this Recipe
names is never retrieved and there is nothing to render from. To render
it, build a Release that deploys a component this Recipe implements.

Mọi thứ phía trên dòng đó đã được kiểm tra và được báo cáo là hợp lệ. Do đó, ý nghĩa của mã thoát đối với một Recipe như vậy hẹp hơn so với một Recipe đã render — schema, cấu trúc và việc phân giải đều đúng; việc render chưa được chứng minh — và báo cáo nêu rõ bạn đang đọc trường hợp nào trong hai trường hợp.

Một nguồn mà workspace đã có thì không bị từ chối. Một source: ./module tương đối không cần tải về, vì vậy việc render nó được thử như mọi nguồn khác, và một lỗi trong đó là một phát hiện thực được báo cáo là Render: not completed in isolation với mã thoát khác không. Dòng ở trên chỉ xuất hiện đối với một nguồn phải được tải về.

Để render thực sự một Recipe có nguồn tải về, hãy chạy aggrega build trên một Release triển khai một component mà Recipe đó hiện thực: một bản build phân giải nguồn thông qua lockfile của Release và cache cục bộ, chính là thứ cung cấp các byte mà validate không có cách nào lấy được.

Một socket uses bắt buộc

Điểm thứ hai là liệu các socket uses có required: true của Component implements đã được điền hay chưa.

Một socket bắt buộc được điền bằng cách nối một cạnh tới một component khác — từ khối uses của chính Aggregate, hoặc từ một Release nối một socket mà Component khai báo. Bộ khung tổng hợp chỉ chứa một instance duy nhất, nên không có component thứ hai nào để một cạnh như vậy trỏ tới, và không cách soạn thảo nào trên các tài liệu tổng hợp có thể tạo ra nó: bịa ra một peer đồng nghĩa với bịa ra tài nguyên tính toán mà bộ khung chưa từng khai báo. Vì vậy validate nêu tên các socket mà nó không kiểm tra và tiếp tục qua bước phân giải và render:

Sockets: required uses sockets not checked (backend, cache, registry)
Validating a Recipe on its own places its Component in a build of one,
so no other component exists for a required socket to be wired to. Whether
each of these sockets is populated is checked when the Component is deployed
in an Aggregate.

Dòng này chỉ xuất hiện khi Component khai báo ít nhất một socket bắt buộc, và nó chỉ nêu tên các socket bắt buộc — một socket tùy chọn không bao giờ được liệt kê, vì để nó không được nối không phải là một phát hiện ở bất kỳ phạm vi nào. Một Recipe có Component không khai báo socket bắt buộc nào sẽ không tạo ra dòng như vậy, và báo cáo của nó không thay đổi.

Bản thân quy tắc không bị nới lỏng cũng không bị lặp lại; nó được đặt ra ở phạm vi có thể trả lời nó. aggrega build áp dụng đầy đủ quy tắc này trên các bề mặt cạnh của cả Aggregate và Release, và dừng lại ở một socket bắt buộc không được nối. Vì vậy một Recipe vượt qua kiểm tra đơn thực thể vẫn phải thỏa mãn quy tắc socket bắt buộc khi Component của nó được triển khai, và báo cáo nói rõ điều đó thay vì để lại một khác biệt âm thầm giữa những gì validate đã kiểm tra và những gì một bản build sẽ kiểm tra.

Một slot đính kèm bắt buộc hoặc một yêu cầu hiện diện

Điểm thứ ba là liệu các slot đính kèm có required: true của Component implements — các điểm gắn kết có tên mà featuresSchema của nó khai báo — đã được lấp đầy hay chưa, và liệu có một phần đính kèm của từng loại Feature mà các yêu cầu hiện diện của nó đòi hỏi hay không.

Một slot bắt buộc được lấp đầy bằng cách đính kèm một Feature tại tên đó, trong Aggregate hoặc trong Release, trên component hoặc ở một phạm vi phía trên nó — nơi Component được triển khai, không phải trong Recipe. Bộ khung tổng hợp không đính kèm Feature nào, nên không thứ gì nó dựng lên có thể lấp đầy một slot như vậy. Vì vậy validate nêu tên các slot mà nó không kiểm tra và tiếp tục qua bước phân giải và render, đúng như cách nó làm với các socket bắt buộc:

Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.

Dòng này chỉ xuất hiện khi Component khai báo ít nhất một slot bắt buộc, và nó chỉ nêu tên các slot bắt buộc; một Recipe có Component không khai báo slot nào như vậy sẽ không tạo ra dòng này. Chỉ có yêu cầu bắt buộc được gác lại: ràng buộc nhãn của một slot và các cơ chế phân phối được phép của nó vẫn được giữ như đã khai báo. Một template không phân tích cú pháp được vẫn làm lần chạy thất bại, và một lỗi của chính Recipe cũng vậy, chẳng hạn một Workload mà provider không thể tổng hợp — trừ khi Recipe cũng đọc một giá trị mà chỉ một kết nối hoặc một Feature được đính kèm cung cấp, như phần tiếp theo mô tả.

Một yêu cầu hiện diện — một annotation features.aggrega.ai/requiredType.<label> trên Component, đòi hỏi một phần đính kèm nào đó mang loại Feature mà nó nêu tên — được gác lại vì cùng lý do: bộ khung không đính kèm gì, nên không thứ gì nó dựng lên có thể mang loại đó. Validate nêu tên từng yêu cầu mà nó không kiểm tra theo nhãn và loại mà yêu cầu đòi hỏi, và tiếp tục qua bước phân giải và render. example/compute/service của thư viện chuẩn khai báo một yêu cầu như vậy, nên Recipe của nó báo cáo, trước hai artifact đã render:

$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalog
Entity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: presence mandates not checked (monitoring: core/prometheus-exporter)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to carry a type the Component requires. Whether
an attachment of each of these types is present is checked when a Release
that deploys the Component is built.
Resolution: valid
Render: 2 artifact(s)

Một yêu cầu có phần khai báo không thể đánh giá được — tiền tố của annotation mà không có nhãn phía sau, hoặc một giá trị không phải là loại Feature — không được gác lại: đó là lỗi của chính Component, không phần đính kèm nào sửa được, và validate làm lần chạy thất bại vì nó giống như một bản build.

Mỗi quy tắc được đặt ra ở nơi nó có thể được trả lời. aggrega pull, aggrega build và aggrega validate --release đánh giá cả hai trên các phần đính kèm thực của Release, và mỗi lệnh dừng lại ở một slot bắt buộc không được lấp đầy và ở một loại được yêu cầu mà không phần đính kèm nào mang.

Một giá trị mà chỉ một kết nối hoặc một Feature được đính kèm cung cấp

Điểm thứ tư là liệu một Recipe có render được khi các kết nối và các Features được đính kèm của nó cung cấp những gì các template của nó đọc hay không.

Các template của một Recipe đọc những gì một kết nối phân phối dưới .context.inject và .context.uses, và những gì một Feature được đính kèm phân phối dưới .features. Bộ khung tổng hợp không nối kết nối nào và không đính kèm Feature nào, nên mọi lần đọc như vậy đều không tìm thấy gì: một lần đọc dưới .context.inject.env gặp một đường ống phân phối rỗng, và một range trên .context.uses không gặp kết nối nào. Validate render Recipe trước, và một lần render hoàn tất được báo cáo như bình thường. Khi lần render dừng lại và các template của Recipe — bao gồm cả các tệp và mục thư viện mà chúng import — đọc bất cứ thứ gì dưới ba vị trí đó, validate báo cáo lần render là chưa được thực hiện, nêu tên các giá trị mà Recipe đọc ở đó, in ra câu mà lần render dừng lại, và thoát với 0. Biến thể chart của ví dụ MariaDB + Adminer đọc thông tin xác thực cơ sở dữ liệu từ đường ống phân phối mà hai secret được đính kèm của nó lấp đầy:

$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yaml
Entity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml
Kind: Recipe
Schema: valid
Shape: valid
Attachments: required attachment slots not checked (root_password)
Validating a Recipe on its own places its Component in a build that attaches
no Feature, so nothing exists to fill a required slot. Whether each of these
slots is filled is checked when a Release that deploys the Component is built.
Resolution: valid
Render: not attempted (this Recipe reads values a build of one cannot supply)
Validating a Recipe on its own places its Component in a build that wires
no connection and attaches no Feature, so nothing supplies what its
templates read under .context.inject, .context.uses or .features. Its
render stopped, and whether on one of those values or on a fault of its
own is not judged here. To render it, build a Release that deploys a
component this Recipe implements.
Reads: .context.inject.env.MARIADB_PASSWORD, .context.inject.env.MARIADB_ROOT_PASSWORD
The render stopped: rendering: [CATALOG_ERROR] instance instance: rendering node "instance": [CATALOG_ERROR] catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml: recipe "mariadb-chart" valuesMapping: [CATALOG_ERROR] valuesMapping[mariadb-chart]: template "valuesMapping[mariadb-chart]" execute: template: valuesMapping[mariadb-chart]:7:30: executing "valuesMapping[mariadb-chart]" at <.context.inject.env.MARIADB_ROOT_PASSWORD>: nil pointer evaluating interface {}.MARIADB_ROOT_PASSWORD

Một lần đọc không tìm thấy gì và không làm dừng gì thì không bị gác lại: một range trên .context.uses không render ra gì, trong một lần render hoàn tất, được báo cáo đúng như lần render đó.

Điều quyết định là những gì Recipe đọc, không phải điều mà lần render dừng lại, và điều đó có một hệ quả đáng biết trước khi bạn gặp phải: một lỗi của chính Recipe trong một Recipe cũng đọc giá trị như vậy — ví dụ một khóa viết sai chính tả — được báo cáo là chưa được thực hiện cùng với phần còn lại, chứ không phải là một thất bại. Dòng The render stopped: mang câu của chính lần render để bạn thấy đó là trường hợp nào, và một bản build của một Release triển khai Component sẽ đánh giá đầy đủ lần render.

Hai lỗi vẫn làm lần chạy thất bại bất kể Recipe đọc gì, vì không kết nối hay Feature nào thay đổi được chúng: một template không phân tích cú pháp được, và một tham chiếu mà lần render từ chối — một gốc mà ngữ cảnh render không định nghĩa, hoặc một khóa gõ sai bên dưới một gốc có hình dạng cố định, chẳng hạn .context.instance_idd. Một assertion mà Recipe khai báo có gọi fail thì không bị gác lại cũng không phải là thất bại, bất kể Recipe đọc gì: nó được báo cáo là cảnh báo như một assertion thất bại luôn được báo cáo. Một Recipe có các template không đọc vị trí nào trong ba vị trí đó sẽ được đánh giá lần render đầy đủ, và một lần render dừng lại sẽ thất bại với câu nêu nguyên nhân.

Công cụ validate của aggrega mcp đưa ra cùng kết luận trên cùng Recipe: một lần render bị gác lại theo cách này được trả lời là hợp lệ, không có gì trong diagnostics của nó, và các dòng trên nằm trong văn bản nó trả về bên cạnh đó.

Việc tải catalog ở chế độ đơn thực thể có tính dung thứ: một thực thể bị hỏng không liên quan ở nơi khác trong catalog sẽ được bỏ qua thay vì hủy bỏ việc kiểm tra, nên nó không bao giờ cản trở việc xác thực đối tượng đích một cách độc lập.

Một tệp bị bỏ qua vẫn giải thích một Component bị mất vì nó. Khi đích implements của một Recipe không được tìm thấy và đúng một tệp bị bỏ qua khai báo Component đó, báo cáo mở đầu bằng lời từ chối của chính tệp đó — đường dẫn của nó, ràng buộc mà nó vi phạm và mã ngắn của điều kiện ở phần đầu — tiếp theo là một note: cho biết tệp đã bị bỏ qua khi tải, nên catalog không chứa gì dưới danh tính mà tệp khai báo, rồi đến lỗi implements target … not found in catalog như lý do tệp đó cần thiết. Khi không có tệp bị bỏ qua nào khai báo Component đó, hoặc có nhiều hơn một tệp khai báo, lỗi không tìm thấy đứng đầu và mọi tệp bị bỏ qua được liệt kê bên dưới nó dưới note: catalog files skipped at load. Đây là cách aggrega build giải thích về một tệp mà nó đã bỏ qua, và việc kiểm tra thực thể của trình soạn thảo qua aggrega serve cùng công cụ validate của aggrega mcp cũng đưa ra cách giải thích đó. Một catalog không có gì bị bỏ qua sẽ báo cáo đúng như bình thường.

Mối liên hệ giữa validate với lint và build

Ba lệnh này trả lời ba câu hỏi khác nhau:

  • aggrega validate — điều này có đúng không? Schema, các trụ cột, các tham chiếu, extends, khả năng theo loại đầu vào, và render cô lập. Lệnh này không đọc trạng thái runtime nào và không xuất artifact nào.
  • aggrega lint — điều này có tuân theo các quy ước xuất bản catalog không? Đặt tên, sự khớp giữa danh mục và thư mục, tiền tố annotation, mức tăng phiên bản, và phần còn lại của kỷ luật xuất bản tùy chọn. Lint phản chiếu ba phạm vi của validate nhưng không bao giờ kiểm tra tính đúng đắn.
  • aggrega build — biên dịch một bản triển khai hoàn chỉnh. Build cần một bao đóng đầy đủ gồm Aggregate + Manifest + Release và xuất các artifact gốc của provider. Lệnh này xác thực bao đóng phụ thuộc của chính nó như một phần của quá trình biên dịch, rồi mới render. aggrega validate --release chính là bước xác thực phụ thuộc đó đứng riêng, không có render; validate một thực thể đơn lẻ thì cô lập render của một Recipe duy nhất mà không cần một Aggregate đầy đủ.

Ví dụ

Kiểm tra toàn bộ catalog:

aggrega validate --catalog ./catalog

Kiểm tra chính xác những gì một Release phụ thuộc vào, trước khi build nó:

aggrega validate --release releases/production.yaml

Kiểm tra một thực thể, và — với một Recipe — xem đầu ra render riêng biệt của nó:

aggrega validate core/datastore/postgres/recipes/helm.yaml

Kiểm tra một thực thể theo các điều kiện của một Release mà cấu hình workspace cấp các thư mục catalog riêng:

aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml

Xem thêm

  • ./aggrega-lint.md — lệnh tương ứng về quy ước trên cùng ba phạm vi.
  • ./aggrega-build.md — biên dịch một Aggregate + Release hoàn chỉnh thành các artifact; kiểm tra bao đóng phụ thuộc của nó như một phần của quá trình biên dịch.
  • ./aggrega-inspect.md — truy vấn đồ thị IR sau khi phân giải mà không tiếp tục render.
  • ../errors/warnings.md — các phát hiện mang tính tư vấn mà validate hiển thị dưới dạng các dòng notice:.

Cú pháp

aggrega validate [entity-path] [flags]

Mô tả

Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillar
structure, cross-document library resolution, extends chains, and provider
input-kind capabilities, over every catalog entity. Where the workspace
configuration gives its Releases catalog directories of their own under
workspace.releases, it checks the catalog once for each Release, over the
directories that Release reads, and reports each pass under a line naming
its Releases and those directories; Releases reading the same directories
share one pass.
With --release, validate checks the entities a Release's dependency closure
reaches: closure-scoped pillars, extends, and pre-render authored-value
conformance — the same correctness a build applies, scoped to that Release.
It then evaluates the Recipe and FeatureRecipe assertions against the values
that Release resolves to, as a build does before it renders, and reports a
failing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it accepts
as a single-entity target are Component, Feature, Recipe, FeatureRecipe,
Workload and Plugin. A value the kind requires that the file leaves empty is
reported first, as a placeholder still owed: every one is named at once, with
what it takes, read from the kind's own schema. That reading is this scope's
alone; a whole-catalog run, a Release's closure and a build do not apply it.
Each kind then has its schema checked, then the checks its own kind carries:
pillar structure for a Component or Feature; shape for a Workload,
FeatureRecipe or Plugin; and for a Recipe, shape plus an end-to-end compile
against a minimal generated harness, so its resolution, its guards and a
render of its output are all exercised. Where that Recipe's source is one
that has to be fetched, the render is reported as not attempted instead:
validating one entity on its own reads no lockfile, reads and writes no cache
and makes no network request, so the chart or module it names is never
retrieved and there is nothing to render from. A render that stops while the
Recipe's templates read what only a connection or an attached Feature
supplies — anything under .context.inject, .context.uses or .features — is
reported as not attempted too: the generated harness wires no connection and
attaches no Feature, so that render cannot be judged there, and a fault of
the Recipe's own beside such a read is set aside with it. A template that
does not parse and a reference the render refuses still fail. An assertion
that calls fail, the Recipe's own or one its Component declares, is printed
as a warning closed by a sentence saying a Release must satisfy it before a
build can pass, and does not fail the check: the generated harness sets none
of a real Release's values, so it cannot tell an assertion waiting on one from
one that is broken, and a build still halts on it. Any other kind is refused here
today, and the refusal names the scope that checks it instead: a whole-catalog
run reaches an Aggregate and the library kinds when they sit in a catalog
directory, and --release reaches a Release, the Manifest it names and the
Aggregate it deploys.
With an entity path and --release together, the entity is checked in that
Release's terms: its references — the Component a Recipe implements, a
library a pillar refers to — resolve through the catalog directories the
workspace configuration gives that Release rather than the workspace's own,
so a workspace keeping one catalog variant per Release checks an entity
against the variant that Release builds with. The checks are the entity
path's; no closure is validated.
The command writes nothing to disk.

Cờ

CờMặc địnhMô tả
--catalog[]Thư mục catalog; có thể lặp lại. Mỗi —catalog <dir> được thêm vào đầu ngăn xếp tìm kiếm catalog (kết quả khớp đầu tiên được dùng): catalog_dirs của workspace, hoặc, với một Release mà cấu hình workspace cấp thư mục riêng trong workspace.releases, thì các thư mục của Release đó; ngăn xếp kết thúc bằng thư mục có tên catalog ở gốc workspace nếu có. Một danh sách catalog_dirs được viết rỗng sẽ không đọc catalog cục bộ nào cả.
--ir-graphfalseGhi thêm đồ thị IR mà lần chạy này tính được ra stdout, dưới dạng JSON, ngoài mọi thứ lệnh này vốn đã tạo ra. Các giá trị mà tác giả khai báo là nhạy cảm sẽ bị giữ lại khỏi đồ thị; truyền —unredacted để in chúng ra. Áp dụng cho phạm vi —release, phạm vi duy nhất phân giải một Release thành đồ thị. Cờ này chọn một TÀI LIỆU, còn —response-format đặt mức độ chi tiết của báo cáo riêng của lệnh này; cả hai đều không ảnh hưởng đến kết luận hay mã thoát
--no-unsupported-field-warningsfalseTắt lớp cảnh báo trường không được hỗ trợ: các thông báo mà một target đưa ra cho thứ bạn đã viết nhưng nó không thể đáp ứng — một trường Workload mà nó không thể biểu diễn (như một target có độ trung thực thấp hơn, chẳng hạn compose), hoặc một annotation aggrega.ai/ mà nó không xử lý đối với kiểu đầu vào của node. Các cảnh báo render khác vẫn hiển thị. Chỉ ảnh hưởng đến hiển thị; không thay đổi đầu ra được render. Áp dụng cho phạm vi thực thể, phạm vi duy nhất có render
--plugin—Đường dẫn đến một tệp .wasm thô để kiểm tra đối chiếu với bản tự báo cáo describe() của nó — bước kiểm tra khi viết trước khi phát hành. Khi dùng riêng, cờ này cần —type; khi có đối số là một thực thể Plugin, nó đối chiếu tệp nhị phân với kiểu đã khai báo, tuyên bố năng lực, bản phản chiếu lệnh và bản ghi hàm host của thực thể.
--release—Đường dẫn đến một tệp YAML của Release. Khi dùng riêng, kiểm tra trên bao đóng phụ thuộc đã phân giải của nó; khi có đối số thực thể, kiểm tra thực thể đó theo các điều kiện của Release, với các tham chiếu được phân giải qua các thư mục catalog mà cấu hình workspace cấp cho Release đó. Đường dẫn tương đối được phân giải theo thư mục mà bạn chạy lệnh, không theo gốc workspace. Khi thư mục đó không thuộc workspace nào và không có gốc nào được chỉ định, đường dẫn tuyệt đối sẽ tìm workspace từ chính thư mục của Release
--response-formatdetailedMức độ đầu ra cho phạm vi —release, tức bao đóng của một Release khi không có đối số thực thể: detailed (mặc định) báo cáo mọi chẩn đoán cùng các dòng tư vấn; concise chỉ báo cáo số lượng chẩn đoán và chẩn đoán đầu tiên. Kết luận và mã thoát giống hệt nhau ở cả hai chế độ.
--type—Kiểu Plugin cho phép kiểm tra —plugin chỉ với tệp nhị phân, được xác minh đối chiếu với kiểu mà tệp nhị phân tự báo cáo. Chỉ có ý nghĩa khi dùng với —plugin; khi một thực thể Plugin cung cấp kiểu, hãy bỏ cờ này (giá trị không khớp sẽ dừng quá trình).
--unredactedfalseIn ra các giá trị mà tác giả khai báo là nhạy cảm thay vì giữ lại chúng. Mọi nơi đầu ra đi tới — terminal, pipe, tệp, bản ghi màn hình — khi đó sẽ chứa các giá trị đó ở dạng rõ. Chỉ áp dụng cho đồ thị mà —ir-graph ghi ra và không gì khác, vì vậy cần có —ir-graph