aggrega lint
aggrega lint kiểm tra các quy ước xuất bản — cách đặt tên, sự khớp giữa danh mục và thư mục, tiền tố annotation, kỷ luật khi viết schema và mức tăng phiên bản. Lệnh có ba chế độ, được chọn theo đối số, áp dụng cùng một kỷ luật quy ước ở 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 thực thể (một đường dẫn thực thể, kèm cổng xuất bản --pre-publish tùy chọn). Mỗi phạm vi trả lời cùng một câu hỏi — “nội dung này có tuân theo kỷ luật xuất bản của catalog không?” — trên một phần khác nhau của catalog.
Quy ước khác với tính đúng đắn. aggrega lint không bao giờ kiểm tra nội dung có đúng cấu trúc hay có biên dịch được không — đó là việc của aggrega validate, lệnh phản chiếu cùng ba phạm vi đó cho schema, pillar, phân giải tham chiếu, extends, khả năng theo loại đầu vào và render. Một selector của socket hoặc slot mà ngữ pháp selector không đọc được là một lỗi về tính đúng đắn, nên lint không báo cáo gì về nó: validate từ chối nó, trên toàn bộ catalog hoặc trên một Component hay Feature — xem các selector được khai báo. Hai lệnh bổ sung cho nhau: validate cho bạn biết nội dung có đúng không; lint cho bạn biết nội dung có xuất bản được theo các quy ước của catalog không.
aggrega lint là tùy chọn. Bản thân trình biên dịch vẫn không có quan điểm riêng về kỷ luật catalog; các quy tắc này nằm trong một plugin riêng mà bạn chọn chạy. Một workspace không bao giờ chạy aggrega lint vẫn build và xuất bản được.
Đường dẫn thực thể có thể được truyền theo vị trí hoặc bằng --entity <path>. --release loại trừ lẫn nhau với đối số thực thể — chúng chọn các phạm vi khác nhau; truyền cả hai sẽ dừng lệnh.
Quy ước trên toàn catalog (không có đối số)
aggrega lint khi không có đối số sẽ chạy các quy tắc cấu trúc về kỷ luật xuất bản trên mọi thực thể catalog tìm thấy trong các thư mục catalog đã cấu hình. Các phát hiện chỉ mang tính khuyến nghị — được báo cáo ở mức nghiêm trọng warn, chúng không bao giờ dừng lệnh chỉ vì một phát hiện về quy ước. Hãy dùng chế độ này để rà soát một catalog nhằm tìm những sai lệch về đặt tên, thư mục danh mục và tiền tố annotation. Một Aggregate, một Manifest, một Release hay một Workload nằm trong một thư mục catalog sẽ bị bỏ qua thay vì được kiểm tra: lượt chạy đếm từng loại như vậy trên một dòng not checked: sau phần tóm tắt và hướng bạn tới chế độ thực thể, chế độ kiểm tra tài liệu thuộc bất kỳ loại nào.
Một tệp YAML dưới một thư mục catalog là một 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ó hoặc không có dấu nháy. Một tài liệu Aggrega không đọc được, có YAML không phân tích được, hoặc có kind, metadata hay spec không mang hình dạng của phong bì thực thể — chẳng hạn một metadata được 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 từng tệp như vậy cùng lý do mà việc đọc hoặc trình phân tích đưa ra; không có gì được lint và không có dòng conventions checked nào được in. 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 tới khi được render, values của chart, định nghĩa workflow — đều bị bỏ qua. --release cũng dừng theo cách tương tự với một tài liệu như vậy dưới các thư mục catalog của nó.
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 riêng nào cho Release được kiểm tra một lần, trên ngăn xếp tìm kiếm của nó: các thư mục
--catalog, sau đó làworkspace.catalog_dirs, rồi đến thư mụccatalogở gốc workspace nếu có. -
Một workspace nêu tên các Releases dưới
workspace.releasescó thể giữ một catalog ở nhiều biến thể song song, mỗi biến thể được đọc bởi Release riêng của nó, và một lượt duy nhất trên tất cả chúng sẽ đọc mọi biến thể cùng lúc — thực thể của biến thể này che khuất thực thể của biến thể khác. Vì vậy workspace được kiểm tra một lần cho mỗi Release mà nó 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 nêu 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 lượt đó và các thư mục nó đã đọc, theo sau là các phát hiện và bản tóm tắt riêng của lượt đó:Release release-compose.yaml reads catalog-composeconventions checked: 7 entities, 0 advisory finding(s)Release release-helm-synth.yaml reads catalog-helm-synthconventions checked: 8 entities, 0 advisory finding(s)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, nên một phát hiện ở đó chỉ được báo cáo một lần. 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. Với-o json, tài liệu còn mangpasses:releases,catalogDirs,findingsvàsummarycủa từng lượt, trong khifindingsvàsummaryở cấp cao nhất bao gồm tất cả các lượt. 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ókindlàRelease, ở bất kỳ đâu dưới gốc workspace, ngoài các thư mục ẩn vànode_modules,vendorvà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 thực thể dưới catalog/, truyền --catalog, hoặc đặt workspace.catalog_dirs — hoặc, trong một workspace nêu tên các Releases, đặt catalog_dirs riêng của một Release dưới workspace.releases. Lệnh không bao giờ ngầm liệt kê thư mục làm việc hiện tại.
Một liên kết bên dưới một thư mục catalog dẫn ra ngoài workspace — hoặc ra ngoài một thư mục bạn đã nêu tên nằm ngoài workspace — sẽ không được đọc, và lần chạy dừng tại đó, nêu tên liên kết, thay vì báo cáo một catalog sạch trong khi có một tài liệu nó không đọc được; một bản build trên cùng các thư mục cũng dừng ở cùng liên kết đó. Ranh giới workspace trình bày quy tắc và các cách khắc phục.
Các quy ước trên một Release (--release)
aggrega lint --release <release-path> chạy cùng các quy tắc cấu trúc trên các tệp thực thể catalog mà bao đóng đã 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 bằng chính cơ chế mà một lần build sử dụng, rồi lint tệp catalog do tác giả sở hữu của từng thực thể. Một thực thể được ghim theo registry nằm trong một ô cache không có tệp cục bộ nào để lint và được bỏ qua — các quy tắc xuất bản áp dụng cho các tệp được viết cục bộ. Cũng như chế độ toàn catalog, các phát hiện chỉ mang tính khuyến nghị và không bao giờ dừng chỉ vì một phát hiện về quy ước.
Đây cũng là phạm vi duy nhất có trong tay toàn bộ một Release, nên đây là nơi các quy tắc đọc một lần chạy được thực thi — quy tắc về thông tin xác thực kết nối được mô tả trong Các quy tắc kỷ luật. Một quy tắc như vậy chạy một lần cho mỗi lần kiểm tra, sau các quy tắc theo từng thực thể, trên ba tài liệu: Aggregate mà Release triển khai, đúng như tác giả của nó đã viết; Release, với chuỗi extends được gộp vào, để một Release con mang những gì nó kế thừa; và, với mỗi component mà Aggregate khai báo, Component mà component đó là một thể hiện, theo cách catalog phân giải nó. Không có giá trị tham số nào nằm trong số đó, như ở mọi phạm vi: Release đến mà không có khối parameters của nó, bao gồm cả các giá trị nó kế thừa từ một base, và Aggregate đến mà không có các giá trị mặc định hay các giá trị nó truyền cho mỗi module nó import — xem Những gì một plugin linter được trao. Các phát hiện của nó được báo cáo dưới tệp Release.
Đây là phần đối ứng về quy ước của aggrega validate --release, lệnh kiểm tra cùng bao đóng đó về tính đúng đắn.
Các linter mà phạm vi này chạy được đối chiếu với bản ghi danh tính plugin tin cậy nằm cạnh Release, như một lần build đối chiếu chúng. Trước khi bất kỳ linter nào chạy, --release so sánh các gắn kết plugins.linter đã cấu hình với bản ghi tin cậy plugin: một plugin đã ghi nhận mà cấu hình không còn gắn kết — một linter hay một gate — sẽ dừng lượt chạy, và một linter đọc từ cache có artifact không phải là artifact đã ghi nhận sẽ bị từ chối thay vì được chạy. Một linter đọc từ cache cũng được đối chiếu với chữ ký đã ghi nhận của nó khi được nạp: nơi mục của nó ghi nhận một chữ ký đã xác minh, tài liệu chữ ký mà dữ kiện đó chỉ tới trong cache được kiểm tra lại, và lượt chạy dừng với E0144 khi tài liệu đó bị thiếu hoặc khác, và với E0332 khi nó được tạo cho một plugin khác với linter đã đọc — 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ì; nơi cấu hình tin cậy của workspace yêu cầu chữ ký, một mục không ghi nhận chữ ký nào — hoặc không có mục nào cho linter, kể cả một bản ghi đã bị xóa — sẽ dừng lượt chạy với E0331, theo cùng các thiết lập khiến aggrega pull từ chối nó khi chưa ký. Mỗi lỗi trong ba lỗi này nêu cách khắc phục của nó, aggrega pull --release <release>, lệnh xác minh chữ ký của linter tại registry của nó, ghi nhận chữ ký và cache bundle mà chữ ký chỉ tới, ghi đè một bản sao trong cache không còn khớp với digest của nó. Một linter được phục vụ từ bản sao bên trong tệp nhị phân của trình biên dịch không bao giờ bị đối chiếu với yêu cầu này. Đây là các lỗi của lượt chạy, không phải phát hiện về quy ước, nên chúng dừng ở chỗ một phát hiện thì không. Các phạm vi toàn catalog và một thực thể không nêu Release nào và không đọc bản ghi nào, nên một linter mà chúng đọc từ cache chỉ được kiểm tra dựa trên manifest đã cache của nó. Trước tất cả những điều đó, --release 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, 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 linter hay một gate — nên lượt chạy vẫn cho biết điều đó ngay cả khi một trong các lời từ chối ở trên dừng nó lại. Một lần rút lại không thay đổi phát hiện nào và mã thoát nào, và một bản ghi tin cậy có tồn tại nhưng không đọc được sẽ dừng lượt chạy thay vì được coi như một bản ghi không ghi nhận gì.
Kỷ luật thực thể: cục bộ và cổng xuất bản
Chế độ đường dẫn thực thể chạy ở một trong hai mức độ nghiêm trọng:
- Mặc định (cục bộ). Chạy các quy tắc kỷ luật trên nội dung thực thể cục bộ ở mức độ nghiêm trọng
warn. Không truy cập registry; bước kiểm tra tăng phiên bản bị bỏ qua. Hãy dùng chế độ này trong khi soạn thảo. --pre-publish(cổng xuất bản). Lấy phiên bản đã xuất bản mới nhất không phải bản tiền phát hành của thực thể từ registry, chạy cùng các quy tắc ở mức độ nghiêm trọnghalt, và ngoài ra còn phân loại thay đổi làPATCH/MINOR/MAJORvà dừng lại nếu mức tăngmetadata.versionđược đề xuất nhỏ hơn mức mà thay đổi đòi hỏi. Hãy dùng chế độ này trong quy trình xuất bản, trướcaggrega push.--pre-publishchỉ áp dụng cho dạng một thực thể.
Tăng phiên bản vượt mức luôn được cho phép; tăng thiếu mức sẽ dừng lại. Lần xuất bản đầu tiên của một thực thể (chưa có phiên bản nào trước đó trong registry) bỏ qua bước kiểm tra tăng phiên bản và đưa ra một cảnh báo cho biết không có xác minh nào được thực hiện.
Những loại mà chế độ thực thể kiểm tra
Chế độ thực thể lint tài liệu bạn nêu tên, bất kể loại của nó, và chuyển nó cho mọi quy tắc đọc một thực thể. Mỗi quy tắc tự quyết định nó mô tả những loại nào, và một quy tắc được chuyển một loại mà nó không mô tả thì không báo cáo gì. Vì vậy, việc nêu tên một Aggregate, một Manifest, một Release hay một Workload — những loại mà lượt chạy toàn catalog bỏ qua và liệt kê trên dòng not checked: của nó — cũng chạy các quy tắc trên tài liệu đó, và chỉ những quy tắc mô tả loại đó mới có thể báo cáo:
| Quy tắc | Các loại mà nó báo cáo trong chế độ thực thể |
|---|---|
| Tiền tố annotation | Mọi loại: nó đọc metadata.annotations bất kể loại của tài liệu. |
Phần mở rộng x-aggrega-* trực tiếp | Mọi loại: nó đọc spec.schema bất kể loại của tài liệu. |
| Dạng tên | Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary và ArtifactLibrary. |
| Danh mục khớp với thư mục | Component. |
| Slot bí mật khai báo sensitive | Component và Feature. |
| Annotation thông tin xác thực của metrics khớp với provides | Component. |
| Provides được Component khai báo | Recipe. |
| Ref động, ghi đè Id | SchemaLibrary. |
| Giới hạn mặc định của Plugin | Plugin. |
Phép so sánh mức tăng phiên bản (--pre-publish) | Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate và Plugin (plugin được tích hợp sẵn trong trình biên dịch không được so sánh); thay đổi ở bất kỳ loại nào khác được phân loại là MAJOR. |
| Thông tin xác thực của kết nối khớp với khóa của đích | Không loại nào: nó đọc toàn bộ một Release, nên chỉ chạy với --release. |
Một Aggregate, một Manifest, một Release và một Workload không khai báo metadata.annotations lẫn spec.schema trong schema của chúng, nên một tài liệu thuộc một trong các loại đó mà khớp với schema của loại mình sẽ không nhận phát hiện nào từ hai quy tắc đọc mọi loại; hai quy tắc đó chỉ báo cáo về nó khi nó vẫn mang một trong các khóa ấy, điều mà schema của loại nó từ chối như một thuộc tính không mong đợi. Điều mà việc nêu tên một Aggregate bổ sung là phép so sánh mức tăng phiên bản với --pre-publish, phép này so sánh nó với phiên bản đã xuất bản như bộ tiêu chí bên dưới mô tả.
Thang đánh giá mức tăng phiên bản
Ở chế độ --pre-publish, thay đổi được so sánh với phiên bản đã phát hành trước đó và được phân loại:
PATCH— các thay đổi chỉ liên quan đến tài liệu hoặc chú thích.MINOR— các thay đổi thuần túy bổ sung (một trường tùy chọn mới, một mục mới).MAJOR— các thao tác loại bỏ, thu hẹp kiểu, hoặc một trường trước đây là tùy chọn trở thành bắt buộc.
Việc so sánh được thực hiện theo từng loại thực thể: Component, Feature và SchemaLibrary được so sánh có xét đến các trường mang schema của chúng; MappingLibrary được so sánh ở cấp khóa mục (nội dung của mục là không trong suốt, nên một nội dung bị thay đổi được xử lý một cách thận trọng là MAJOR); Recipe và FeatureRecipe được so sánh trên các trường chịu tải của chúng. Một Aggregate được so sánh trên các khai báo tham số, các component và các hệ thống con của nó; giá trị mặc định của một tham số không đi vào phép so sánh, cũng như bất kỳ giá trị tham số nào khác (xem Những gì một plugin linter được trao), nên một thay đổi chỉ giới hạn ở giá trị mặc định — thêm, thay đổi hoặc xóa một giá trị mặc định — không thuộc phép so sánh, và một thay đổi đối với khóa nằm ngoài bộ từ vựng của slot tham số cũng vậy. Việc tăng phiên bản không đủ sẽ dừng lại với một chẩn đoán nêu rõ mức tăng cần thiết.
Các quy tắc kỷ luật
Hầu hết các quy tắc có một thiết lập theo từng workspace dưới lint.publishing_discipline trong .aggrega-config.yaml và một tùy chọn ghi đè CLI tương ứng, mỗi tùy chọn ghi đè đều có một bản đối ứng --no-. Thứ tự ưu tiên là --no-<flag> trên --<flag> trên giá trị trong cấu hình workspace, ở mọi phạm vi: toàn bộ catalog, một Release và một thực thể. Mọi quy tắc đều bật theo mặc định, và mỗi giá trị mặc định dựa trên cơ chế của nền tảng hoặc trên một quy ước catalog đã được ghi lại; các thiết lập là lựa chọn từ chối dành cho workspace có lý do để nới lỏng một quy tắc.
Các quy tắc không có thiết lập sẽ nêu rõ điều đó trong mục của chúng bên dưới, và lý do ở mỗi trường hợp là như nhau: chúng báo cáo một sự thật về thực thể và để quyết định cho tác giả, nên không có phán đoán nào cần nới lỏng. Thang đánh giá nâng phiên bản mô tả ở trên cũng không có thiết lập nào — nó so sánh nội dung đề xuất với phiên bản đã phát hành và báo cáo những gì thay đổi đòi hỏi, đó là thuộc tính của thay đổi chứ không phải tùy chọn của workspace.
- Tiền tố annotation — các namespace dành riêng (
aggrega.ai/, vàfeature.aggrega.ai/bên ngoài một Feature) thuộc sở hữu của nền tảng và bị từ chối trên các khóa khác. Mặc định bật; từ chối bằngallow_aggrega_ai_prefix. - Dạng tên — mỗi loại thực thể có một quy ước về dạng tên (số phân đoạn cho các loại cloud-native; PascalCase cho các loại thư viện). Mặc định bật; từ chối bằng
allow_nonstandard_names. - Tham chiếu động — các mục của SchemaLibrary không được dùng
$dynamicAnchor/$dynamicRef(việc mở rộng$reftại thời điểm biên dịch của nền tảng không thể phân giải chúng). Mặc định bật; từ chối bằngallow_dynamic_refs. - Ghi đè id — các mục của SchemaLibrary không được tự khai báo
$id(nền tảng suy ra$idchuẩn). Mặc định bật; từ chối bằngallow_id_overrides. - Danh mục khớp với thư mục — nhãn
component.aggrega.ai/categorycủa một Component phải khớp với phân đoạn thư mục đầu tiên dướicore/, lấy từ tập danh mục đóng (ai-agent,ai-model,ai-tool,ai-pipeline,datastore,gateway,mesh,network,messaging,storage,compute,observability,security,bigdata,devtool). Mặc định bật cho các thực thể dưới đường dẫncore/; từ chối bằngallow_category_mismatches. - Phần mở rộng
x-aggrega-*trực tiếp — việc viết trực tiếp các khóax-aggrega-*trong schema của một Component hoặc Feature không được khuyến khích, thay vào đó nên dùng cách viết chính thức. Mặc định bật; từ chối bằngallow_direct_x_aggrega_extensions. - Provides được Component khai báo —
spec.providescủa một Recipe công bố một khóa cho mỗi mục, và Component mà Recipe đó hiện thực khai báo, trong trụprovidescủaspec.schemacủa nó, những khóa mà kiểu đó cung cấp. Chính khai báo đó là thứ mà một tham chiếuinjectfrom:được kiểm tra đối chiếu, nên một khóa mà Recipe công bố mà Component không khai báo sẽ được tạo ra rồi bị từ chối tại nơi một bên tiêu thụ nối nó. Việc công bố vượt ngoài hợp đồng đã khai báo được chấp nhận tại thời điểm build, đó là lý do phát hiện này chỉ mang tính khuyến nghị thay vì từ chối. Mặc định bật cho các Recipes; từ chối bằngallow_undeclared_recipe_provides. - Giới hạn mặc định của Plugin —
spec.runtimecủa một Plugin mangmaxMemoryPagesvàtimeoutMs, hai giới hạn mà host áp dụng khi nạp và chạy plugin. Một Plugin không cố định giới hạn nào sẽ chạy theo các giá trị mặc định của nền tảng, đây là kết quả an toàn chứ không phải lỗi, nên quy tắc báo cáo rằng các giá trị mặc định đang có hiệu lực và có thể cố định các giới hạn tường minh. Mặc định bật cho các thực thể Plugin; quy tắc này không có thiết lập. - Slot bí mật khai báo sensitive — một slot đính kèm có thể, thông qua bộ chọn nhãn của nó, cố định loại Feature lấp đầy nó là
secret, và có thể khai báo riêngsensitive: trueđể ghi nhận rằng bất cứ thứ gì lấp đầy nó đều xử lý dữ liệu bí mật. Bộ chọn nêu những gì được phép lấp đầy; dấu đánh dấu nêu cách xử lý. Một slot cố định loại mà không khai báo dấu đánh dấu sẽ để cách xử lý đó phải được suy ra lại từ bộ chọn thay vì đọc trực tiếp. Quy tắc đọc mọi slot mà một thực thể khai báo: các slot trong khối đính kèm của chính nó dướispec.featuresSchema, và, trên một Component, các slot mà mỗi socket phụ thuộc khai báo dướispec.usesSchema.<socket>.featuresSchemacho các kết nối được nối qua nó — một phát hiện về slot của một socket nêu tên cả socket lẫn slot. Mặc định bật cho các Components và Features; quy tắc này không có thiết lập. - Thông tin xác thực của kết nối khớp với khóa của đích (
connection-credential-matches-target-key) — một máy chủ kiểm tra khóa sẽ giữ khóa mà nó xác minh trong một slot của chính Component của nó, còn bên gọi trình khóa trên kết nối mà qua đó nó đến được máy chủ. Không đầu nào thấy các attachment của đầu kia, nên hai đầu chỉ giữ cùng một khóa vì tác giả của chúng viết khóa ấy ở cả hai đầu — thường bằng cách cho cả hai attachment đọc cùng một tham số — và một lần build không bao giờ so sánh chúng. Quy tắc này thì có, và đây là quy tắc duy nhất đọc toàn bộ một Release, nên nó chạy dưới--releasevà không ở phạm vi nào khác. Nó tìm cả hai đầu theo những tên mà catalog chuẩn đặt cho chúng: khóa của đích là slotapi_keymà Component của nó khai báo trongspec.featuresSchema, và của bên gọi là slotcredentialtrên kết nối, được viết tạiuses.<socket>.<alias>.features.credentialtrong Aggregate hoặc trên một kết nối mà Release nối. Với mỗi kết nối có đích khai báoapi_keyvà không được gắn nhãn managed, quy tắc báo cáo một kết nối mang thông tin xác thực tới một đích có slot khóa chưa được điền, một slot khóa đã điền nhưng kết nối không có thông tin xác thực, và hai đầu đặt tên bí mật của chúng khác nhau. Thứ nó so sánh là locator của mỗi đầu —originmà một attachment viết, trongvaluesở Aggregate hoặcinfraở Release — đúng như tác giả đã viết, nên hai đầu đọc cùng một tham số được coi là bằng nhau và hai giá trị literal được so sánh theo văn bản của chúng; không có gì được phân giải, và một phát hiện nêu tên component, kết nối, đích và hai slot nhưng không bao giờ trích dẫn locator nào, vì văn bản viết ở đó có thể chính là bí mật. Một đích không khai báo slotapi_keykhông nhận phát hiện nào, và một slot không phải khóa của bên gọi, chẳng hạn token kéo registry của một máy chủ mô hình, không bao giờ được đọc. Một đích có Component được gắn nhãncomponent.aggrega.ai/hosting: managedcũng không bị đánh giá, bất kể slotapi_keycủa nó chứa gì: một Component như vậy đại diện cho một dịch vụ do nhà cung cấp vận hành, nên không thứ gì Release chạy kiểm tra khóa trên nó, và khi nó khai báoapi_key— chẳng hạn khóa tới một API mô hình được lưu trữ, dưới tên mà sản phẩm của nhà cung cấp đặt cho nó — slot giữ khóa mà Release trình cho nhà cung cấp đó, không bao giờ là khóa mà các bên gọi của nó trình. Một đích được gắn nhãnself-hosted,externalhoặcmixed, hoặc không mang nhãn hosting nào, thì bị đánh giá. Một kết nối trên socketscrape_target— tên mà catalog chuẩn đặt cho socket qua đó một trình thu thập metrics đến các đích của nó — là một lần scrape, và việc thông tin xác thực của một lần scrape có nên là khóa của bên gọi của đích hay không phụ thuộc vào sản phẩm của đích: một số phục vụ metrics không cần thông tin xác thực, một số đặt chúng sau khóa mà mọi bên gọi trình, và một số dùng token riêng. Vì vậy với một lần scrape, quy tắc đọc điều mà Component của đích nêu trong annotationobservability.aggrega.ai/metrics-credential: vớinone, lần scrape hoàn toàn không bị đánh giá; vớiseparate-token, thông tin xác thực của nó không bao giờ được so sánh vớiapi_keycủa đích, nên không phát hiện nào trong ba phát hiện được báo cáo cho nó; vớitarget-key, nó bị đánh giá như mọi kết nối khác. Quy tắc chỉ đọc ba giá trị đó, nên một lần scrape tới đích không có annotation, hoặc có giá trị khác, bị đánh giá như mọi kết nối khác — và mọi kết nối trên socket khác, kể cả kết nối tới mô hình, công cụ hay kho dữ liệu, đều bị đánh giá như nhau bất kể annotation của đích nói gì. Nó đọc các attachment được viết trên đích và trên kết nối: một attachmentapi_keyđến đích từ một subsystem hoặc một boundary thay vào đó sẽ khiến kết nối đó không được đánh giá, attachment do một annotation thêm vào không nằm trong số đó, nên một slot khóa chỉ được điền theo cách ấy được coi là chưa điền, một đầu có attachment không viết locator chỉ được so sánh xem đã điền hay chưa, và một component do một module được import đóng góp thì không được đọc. Vì tên slot, nhãn hosting, tên socket scrape và annotation metrics là các quy ước catalog mà không từ khóa schema nào đánh dấu, một catalog đặt tên slot khác sẽ không nhận phát hiện nào, một socket thu thập được đặt tên khác bị đánh giá như mọi socket khác, và một Component giữ khóa của nhà cung cấp trong slot tênapi_keymà không có nhãn managed sẽ được hiểu là một đích kiểm tra khóa đó, vì tên slot, nhãn và annotation là tất cả những gì quy tắc đọc từ Component của một đích. Mặc định bật; tắt bằngallow_connection_credential_mismatches. - Chú thích thông tin xác thực metrics khớp với provides (
metrics-credential-annotation-matches-provides) — một Component có thể nêu hai sự kiện về metrics của nó. Chú thíchobservability.aggrega.ai/metrics-credentialcủa nó nêu cách metrics của sản phẩm xác thực:none, chúng được phục vụ mà không cần thông tin xác thực;target-key, chúng nhận khóa mà Component yêu cầu ở mọi bên gọi, chính là khóa mà slotapi_keycủa nó giữ;separate-token, chúng nhận một token riêng. Khóa providesmetrics_credential_required, được khai báo trong trụ cộtprovidescủaspec.schemacủa nó, là thứ mà mỗi Recipes của nó công bố để cho biết metrics của một instance có cần thông tin xác thực hay không — điều này có thể phụ thuộc vào cách instance được cấu hình, vì metrics nằm sau khóa của bên gọi chỉ cần một khóa khi có khóa được gắn vào, nên chú thích không thể thay thế cho nó. Cả hai nêu cùng một sự kiện về sản phẩm, nên quy tắc này buộc chúng phải thống nhất: một Component được chú thíchnonemà khai báo khóa, và một Component được chú thíchtarget-keyhoặcseparate-tokenmà không khai báo, đều bị báo cáo, và phát hiện nêu tên Component, giá trị của chú thích và khóa bị thừa hoặc bị thiếu. Một Component không có chú thích, hoặc có bất kỳ giá trị nào khác, không bị báo cáo gì. Quy tắc đọc Component như được viết, nên một Component mở rộng một Component khác — có schema là schema của Component cơ sở — không bị báo cáo gì và Component cơ sở của nó được đọc tại nơi nó được khai báo, và một trụ cộtprovidesđược viết dưới dạng tham chiếu, dạng tổ hợp hoặc một phần thân được thoát viết dưới dạng văn bản thì không phải là thứ quy tắc có thể liệt kê, nên Component đó cũng không bị báo cáo gì. Mặc định bật cho Components; quy tắc này không có thiết lập nào.
Tính bất biến của artifact không phải là một trong các quy tắc này, và nó không có thiết lập. Một name:version đã công bố là cuối cùng: aggrega push so sánh digest đã được công bố tại tag đó với digest mà nội dung sắp được push sẽ tạo ra, và từ chối ghi đè bằng nội dung khác. Push lại nội dung giống hệt từng byte không tải lên gì và chỉ gắn thêm những gì lần công bố đó còn thiếu — ngày công bố, và chữ ký nếu lần push có ký. Không flag và không thiết lập workspace-config nào nới lỏng điều này, vì registry không cung cấp đường ghi đè nào để người vận hành chọn bật. Nội dung đã thay đổi được công bố dưới một phiên bản mới; --pre-publish là thứ xác minh việc tăng phiên bản đó so với bản phát hành trước.
Các flag ghi đè theo từng quy tắc là các cổng theo từng lần gọi và cố ý không có biến môi trường — chúng đã được hỗ trợ bằng cấu hình trong .aggrega-config.yaml dưới lint.publishing_discipline. Mô hình thứ tự ưu tiên chung của AGGREGA_* được mô tả trong environment-variables.md.
Thời điểm build và thời điểm phát hành
Quy tắc không khuyến khích x-aggrega-* cũng chạy trong aggrega build, nơi nó xuất hiện dưới dạng cảnh báo; aggrega lint --pre-publish nâng cùng phát hiện đó lên thành lỗi. Các bản build cục bộ mang theo lời khuyên; cổng phát hành thì bắt buộc áp dụng nó.
Trong lúc bạn soạn thảo, ngay trong trình soạn thảo
Trình soạn thảo của bạn đặt ra hai câu hỏi khác nhau về một thực thể trong catalog, và đó chính là hai câu hỏi mở đầu trang này. Thực thể có đúng không — nó có phân tích cú pháp được không, các trụ cột có được phân giải không, nó có render được không? Đó là aggrega validate, và một phiên làm việc của trình soạn thảo luôn trả lời câu hỏi này. Thực thể có công bố được không — tên có tuân theo quy ước không, tệp có nằm trong thư mục mà danh mục của nó mong đợi không, các tiền tố annotation có đúng không? Đó là các quy tắc này, và một phiên làm việc của trình soạn thảo chỉ trả lời câu hỏi này khi bạn yêu cầu.
Tính năng này tắt trừ khi bạn bật nó. Hãy bật bằng serve.lint_on_validate trong tệp .aggrega-config.yaml của workspace có các thực thể mà bạn muốn nhận lời khuyên:
serve: lint_on_validate: trueKhông có cờ dòng lệnh nào cho tính năng này, và đó là chủ ý: câu hỏi liên quan đến nội dung riêng của một workspace cụ thể, và bạn là người soạn thảo workspace đó chứ không phải người khởi chạy language server — trình soạn thảo của bạn làm việc đó.
Khi bật, mỗi thực thể bạn validate cũng mang theo các phát hiện này, mỗi phát hiện nêu tên quy tắc đã tạo ra nó, bên cạnh các phát hiện về tính đúng đắn. Từ đó có ba điều, và chúng là những gì khiến tính năng này dùng được trong lúc gõ:
- Các phát hiện chỉ mang tính tư vấn. Một thực thể vi phạm một quy ước vẫn validate thành công, và Release của nó vẫn được phân giải và render. Bật thiết lập này chỉ thêm một lớp lời khuyên; nó không bao giờ khiến trình soạn thảo của bạn từ chối hoạt động.
- Bạn có thể phân biệt hai loại. Mỗi vấn đề được công bố đều nêu tên lớp đã phát hiện ra nó, nên một vấn đề về đặt tên và một lỗi phân giải trên cùng một tệp được hiểu là hai điều khác nhau, chứ không phải một vấn đề bị báo cáo hai lần.
- Những gì bạn đã gõ là những gì được kiểm tra. Các quy tắc đọc bộ đệm chứ không phải tệp trên đĩa, nên một tên bạn sửa sẽ thôi bị báo cáo ngay trước khi bạn lưu.
Chỉ chế độ nội dung cục bộ chạy trên lớp đó: không tra cứu registry nào, không tải gì về, không ghi gì cả. Phép so sánh --pre-publish chỉ được thực hiện khi bạn yêu cầu — trình soạn thảo của bạn gửi một yêu cầu cho nó, giống như cách bạn gõ --pre-publish trong terminal — và không bao giờ bằng cách sửa thiết lập ở trên. Một phép kiểm tra chạy mỗi khi bạn chạm vào tài liệu chính là nơi không được phép truy cập registry, nên chế độ đó vẫn là thứ bạn chủ động gọi chứ không phải thứ tự động chạy kèm.
Yêu cầu kiểm tra trực tiếp luôn hoạt động bất kể thiết lập là gì, ở cả ba phạm vi nêu trên. Vì vậy, một workspace chưa bao giờ bật lớp kiểm tra theo từng lần sửa vẫn có thể yêu cầu trình soạn thảo quét toàn bộ catalog, bao đóng của một Release, hoặc một thực thể — và nhận được đúng các phát hiện mà lệnh này in ra. Thiết lập chỉ quyết định liệu phép kiểm tra có chạy thêm ở những nơi bạn không yêu cầu đích danh hay không.
Chi tiết giao thức nằm trên hai trang: yêu cầu đó có ý nghĩa gì và khi nào gửi nó có trong tài liệu tham khảo về aggrega serve , còn các tham số của nó và hình dạng câu trả lời, từng trường một, có trong tài liệu tham khảo về hình dạng wire.
Chọn linter
Các quy tắc được phát hành dưới dạng một Plugin Wasm linter xuất bản tiêu chuẩn. Vì các quy tắc nằm trong một plugin chứ không nằm trong trình biên dịch, một doanh nghiệp có thể trỏ aggrega lint tới một plugin khác để áp dụng kỷ luật danh mục của riêng mình mà không cần thay đổi trình biên dịch.
Một workspace có thể gắn nhiều linter dưới plugins.linter, và mọi phần gắn đều chạy: theo thứ tự các phần gắn được viết, mỗi phần tại hàm điểm vào riêng của nó, với tất cả các kết quả của chúng được báo cáo cùng nhau. Chính điều đó cho phép một danh mục giữ các quy tắc tiêu chuẩn và thêm quy tắc riêng bên cạnh, thay vì phải chọn giữa hai bên. --plugin là ngoại lệ — nó chạy đúng một artifact từ một đường dẫn trên hệ thống tệp thay cho các phần gắn đã cấu hình, và đó là điều khiến nó hữu ích khi đang phát triển một quy tắc.
Một mục gắn nêu plugin của nó bằng uri:, và function: nêu một hàm điểm vào trên plugin đó. Một mục nêu function: mà không có uri: là nêu một hàm không thuộc plugin nào, nên cấu hình bị từ chối ngay khi được đọc, dưới mã E0224, kèm tên tệp và vị trí của mục trong danh sách của nó — hãy thêm uri của plugin xuất ra hàm đó. Một mục không nêu cái nào trong hai thì không gắn gì và bị bỏ qua; khi đó là mục duy nhất, linter chuẩn chạy với hàm điểm vào mặc định của chính nó, như khi hoàn toàn không có plugins.linter.
Những gì một plugin linter được trao
Không giá trị tham số nào đến được một plugin linter, ở bất kỳ phạm vi nào. Bản thân giá trị của một tham số có thể là một thông tin xác thực — origin của một secret attachment có thể là một template đọc một tham số mà Release đáp ứng, và khi đó secret chính là giá trị của tham số đó — và plugin mà một workspace gắn vào có thể không phải do workspace đó viết, nên mọi tài liệu đều được trao đi với các giá trị tham số bị giữ lại:
- Một Aggregate giữ lại từng khai báo tham số, chỉ chứa các khóa mà một khai báo được viết bằng — bộ từ vựng slot tham số: kiểu, mô tả và các ràng buộc của nó — và mọi khai báo lồng dưới
properties,itemsvàvaluesTypecủa nó cũng tuân theo điều tương tự.defaultcủa khai báo bị giữ lại ở mọi cấp, bằng cách xóa khóa chứ không làm rỗng nó, nên plugin không thể biết một khai báo có đưa ra giá trị mặc định hay không. Một khóa nằm ngoài bộ từ vựng đó bị giữ lại cùng với mọi thứ nó chứa, ở mọi cấp: bản build không gán ý nghĩa nào cho khóa như vậy, và một bản nháp viết sai chính tả một khóa có thể mang một secret bên dưới nó. Một mục dướiparameterskhông phải là khai báo sẽ bị giữ lại toàn bộ. - Mỗi module được liệt kê dưới
aggregatescủa một Aggregate mất khốiparameterscủa nó, khối chứa các giá trị được truyền cho module đó. - Một Release mất khối
parameterscủa nó, dù nó viết các giá trị trực tiếp hay nhập chúng bằng$import. - Mọi tài liệu khác có khối
parametersdướispecsẽ mất toàn bộ khối đó; không loại nào khác khai báo khối này.
Điều này áp dụng cho entity được nêu trên dòng lệnh, cho phiên bản đã xuất bản mà --pre-publish so sánh với nó, cho mọi entity mà các lượt kiểm tra toàn catalog và --release duyệt qua, và cho các tài liệu mà một quy tắc đọc toàn bộ một Release nhận được. Một template đọc một tham số không phải là một giá trị và giữ nguyên văn bản của nó, nên một quy tắc vẫn thấy được một giá trị do tác giả viết đọc tham số nào.
Ví dụ
Quét toàn bộ catalog để phát hiện sai lệch so với quy ước:
aggrega lint --catalog ./catalogLint một entity cục bộ trong khi soạn thảo:
aggrega lint core/datastore/postgres/component.yamlChạy cổng kiểm tra xuất bản trước khi xuất bản một phiên bản mới:
aggrega lint core/datastore/postgres/component.yaml --pre-publishNới lỏng một quy tắc cho một lần chạy duy nhất:
aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-namesXem thêm
- ./aggrega-validate.md — lệnh tương ứng về tính đúng đắn, trên cùng ba phạm vi.
- ./aggrega-build.md — kiểm tra hợp lệ như một phần của quá trình biên dịch; hiển thị cảnh báo khuyến nghị
x-aggrega-*ở mức độwarn. - ./aggrega-push.md — xuất bản một thực thể lên registry;
aggrega lint --pre-publishlà cổng kiểm tra chạy trước nó. - ./aggrega-pull.md — phân giải và ghim các phụ thuộc.
- ./aggrega-serve.md — language server báo cáo các phát hiện này trong trình soạn thảo của bạn, và thiết lập bật lớp kiểm tra theo từng lần chỉnh sửa.
- ../errors/warnings.md — các cảnh báo không gây dừng, bao gồm các phát hiện lint ở chế độ cục bộ.
Cú pháp
aggrega lint [entity-path] [flags]Mô tả
aggrega lint checks publishing CONVENTIONS — naming, category-directoryalignment, annotation prefixes, and the rest of the publishing-linterdiscipline. It does not check correctness (schema, pillars, resolution,render): that is aggrega validate.
Three invocation shapes, mirroring validate:
aggrega lint conventions across every catalog entity aggrega lint --release <path> conventions across a Release's dependency closure aggrega lint <entity> publishing discipline for one entity
Without an entity argument, lint runs the structural conventions rulesover every catalog entity found under the catalog directories. Where theworkspace configuration gives its Releases catalog directories of their ownunder workspace.releases, it runs them once for each Release, over thedirectories that Release reads, and reports each pass under a line namingits Releases and those directories; Releases reading the same directoriesshare one pass. With --release it runs them over the entities thatRelease's closure reaches, and also runs the rules that read a wholeRelease: once, over the Aggregate it deploys, the Release and theComponents the Aggregate's components are instances of, with everyparameter value removed. In both, findings are advisory (warn severity)and never halt.
With an entity path, lint runs the publishing-linter rule set againstthat one entity. In default mode the rules run at warn severity overlocal content without consulting any registry. With --pre-publish theprevious registry version is fetched and the schema-evolutionclassification is compared against the proposed version bump; mismatcheshalt. --pre-publish applies to the single-entity shape only. Per-workspacepolicy flags from .aggrega-config.yaml's lint.publishing_discipline blockcan be overridden per invocation via the --allow-*/--no-allow-* flag pairs,in all three shapes.
All three shapes accept -o json, which replaces the human report on standardoutput with one structured document: every finding with its severity, the rulethat produced it, its short code (the code printed at the head of its row inthe human report, which aggrega explain expands), its message, and the entityfile it concerns, plus counts by severity. A finding from a rule Aggrega doesnot declare, one a linter of your own adds, carries no short code, as its rowprints none. A finding carries a line and column only when the rule thatproduced it located the issue that precisely; otherwise the file alone locatesit. The message is the rule's own text, carried through unchanged, so thestructured and human renderings never word a finding differently. The exitstatus is the same under either format.Cờ
| Cờ | Mặc định | Mô tả |
|---|---|---|
--allow-aggrega-ai-prefix | false | Buộc allow_aggrega_ai_prefix=true |
--allow-category-mismatches | false | Buộc allow_category_mismatches=true |
--allow-connection-credential-mismatches | false | Buộc allow_connection_credential_mismatches=true |
--allow-direct-x-aggrega-extensions | false | Buộc allow_direct_x_aggrega_extensions=true |
--allow-dynamic-refs | false | Buộc allow_dynamic_refs=true cho lần gọi này |
--allow-id-overrides | false | Buộc allow_id_overrides=true cho lần gọi này |
--allow-nonstandard-names | false | Buộc allow_nonstandard_names=true |
--allow-undeclared-recipe-provides | false | Buộc allow_undeclared_recipe_provides=true |
--baseline | — | So sánh kiểm tra tiến hóa trước khi xuất bản với phiên bản đã xuất bản cụ thể này thay vì phiên bản cao nhất được tự động chọn thấp hơn phiên bản đang xuất bản; phải là một tag strict-SemVer có trong registry (yêu cầu —pre-publish) |
--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 cung cấp các thư mục riêng dưới workspace.releases, 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 dùng bởi các lượt kiểm tra quy ước trên toàn catalog và —release. |
--entity | — | Đường dẫn tới YAML của thực thể cần lint (hoặc truyền dưới dạng đối số vị trí) |
--no-allow-aggrega-ai-prefix | false | Buộc allow_aggrega_ai_prefix=false |
--no-allow-category-mismatches | false | Buộc allow_category_mismatches=false |
--no-allow-connection-credential-mismatches | false | Buộc allow_connection_credential_mismatches=false |
--no-allow-direct-x-aggrega-extensions | false | Buộc allow_direct_x_aggrega_extensions=false |
--no-allow-dynamic-refs | false | Buộc allow_dynamic_refs=false cho lần gọi này |
--no-allow-id-overrides | false | Buộc allow_id_overrides=false cho lần gọi này |
--no-allow-nonstandard-names | false | Buộc allow_nonstandard_names=false |
--no-allow-undeclared-recipe-provides | false | Buộc allow_undeclared_recipe_provides=false |
--output, -o | text | Định dạng đầu ra: text|json. |
--plugin | — | Đường dẫn hệ thống tệp tới artifact .wasm của publishing-linter (chạy artifact này thay cho các plugin được gắn qua plugins.linter của workspace) |
--pre-publish | false | Lấy phiên bản trước đó trên registry và xác minh mức tăng phiên bản đề xuất theo phân loại tiến hóa schema |
--release | — | Đường dẫn tới YAML của một Release để kiểm tra quy ước trên bao đóng phụ thuộc đã phân giải của nó (loại trừ lẫn nhau với đối số thực thể). Đường dẫn tương đối được phân giải theo thư mục 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, một đường dẫn tuyệt đối sẽ tìm workspace từ chính thư mục của Release |