aggrega lint
aggrega lint는 게시 관례, 즉 명명, 카테고리-디렉터리 정렬, 어노테이션 접두사, 스키마 작성 규율, 버전 증가 폭을 검사합니다. 인수로 선택하는 세 가지 모드가 있으며, 같은 관례 규율을 세 가지 범위에 적용합니다. 전체 카탈로그(인수 없음), 단일 Release의 의존성 폐포(--release), 그리고 하나의 엔터티 파일(엔터티 경로, 선택적 --pre-publish 게시 게이트 포함)입니다. 각 범위는 카탈로그의 서로 다른 부분에 대해 같은 질문, 즉 “이 콘텐츠가 카탈로그의 게시 규율을 따르는가?”에 답합니다.
관례는 정확성과 구별됩니다. aggrega lint는 콘텐츠가 올바른 형식인지, 컴파일되는지를 검사하지 않습니다. 그것은 aggrega validate의 역할이며, 이 명령은 스키마, 필러, 참조 해석, extends, 입력 종류 기능, 렌더링에 대해 같은 세 가지 범위를 그대로 제공합니다. 선택자 문법으로 읽을 수 없는 소켓 또는 슬롯 선택자는 정확성 결함이므로 lint는 이에 대해 아무것도 보고하지 않습니다. 카탈로그 전체에 대해서든 하나의 Component나 Feature에 대해서든 validate가 이를 거부합니다. 선언된 선택자를 참조하십시오. 두 명령은 상호 보완적입니다. validate는 콘텐츠가 올바른지를 알려 주고, lint는 카탈로그의 관례에 따라 게시할 수 있는지를 알려 줍니다.
aggrega lint는 선택 사항입니다. 컴파일러 자체는 카탈로그 규율에 대해 주관이 없는 상태를 유지하며, 이 규칙들은 실행 여부를 직접 선택하는 별도의 플러그인에 있습니다. aggrega lint를 한 번도 실행하지 않는 워크스페이스도 빌드와 게시가 가능합니다.
엔터티 경로는 위치 인수로 지정하거나 --entity <path>로 지정할 수 있습니다. --release는 엔터티 인수와 함께 사용할 수 없습니다. 둘은 서로 다른 범위를 선택하므로, 둘 다 전달하면 실행이 중단됩니다.
카탈로그 전체의 관례 (인수 없음)
인수 없이 실행한 aggrega lint는 구성된 카탈로그 디렉터리 아래에서 찾은 모든 카탈로그 엔터티에 대해 구조적인 게시 규율 규칙을 실행합니다. 결과는 권고 사항입니다. warn 심각도로 보고되며, 관례에 관한 결과만으로는 중단하지 않습니다. 이름 지정, 카테고리 디렉터리, 어노테이션 접두사가 어긋난 곳을 카탈로그 전체에서 찾아낼 때 사용합니다. 카탈로그 디렉터리에 있는 Aggregate, Manifest, Release 또는 Workload는 검사하지 않고 건너뜁니다. 이 패스는 요약 다음의 not checked: 줄에 그러한 종류별 개수를 표시하고, 모든 종류의 문서를 검사하는 엔터티 모드를 안내합니다.
카탈로그 디렉터리 아래의 YAML 파일은 그 줄 중 하나가 들여쓰기 없이 apiVersion:으로 시작하고 그 값이 따옴표 유무와 관계없이 aggrega.ai/로 시작하면 Aggrega 문서입니다. 읽을 수 없거나, YAML이 파싱되지 않거나, kind, metadata 또는 spec이 엔터티 엔벌로프의 형태가 아닌 Aggrega 문서(예를 들어 목록으로 작성된 metadata)는 디렉터리를 모두 읽은 후 E0175로 실행을 중단시키며, 그런 파일을 모두 읽기 또는 파서가 제시한 이유와 함께 알려 줍니다. 아무것도 린트되지 않고 conventions checked 줄도 출력되지 않습니다. 불러올 수는 있지만 어떤 카탈로그에도 없는 kind를 선언하는 문서(예를 들어 철자가 틀린 Componnent, 또는 kind가 아예 없는 경우)는 같은 실행을 E0371로 중단시키며, 선언한 종류와 함께 위 파일들 옆에 나열됩니다. Manifest, Release, 그리고 Recipe가 자신의 디렉터리에서 가져오는 Workload는 건너뜁니다. 그 밖의 YAML(렌더링되기 전에는 파싱되지 않는 Helm 차트의 템플릿, 차트 values, 워크플로 정의)은 건너뜁니다. --release도 카탈로그 디렉터리 아래의 그런 문서에서 같은 방식으로 중단됩니다.
어떤 디렉터리를 읽는지는 워크스페이스의 형태에 따라 달라집니다.
-
구성에 자체 Release 카탈로그 디렉터리가 없는 워크스페이스는 검색 스택에 대해 한 번 검사됩니다. 검색 스택은
--catalog디렉터리, 그다음workspace.catalog_dirs, 그다음 워크스페이스 루트에catalog디렉터리가 있으면 그 디렉터리입니다. -
workspace.releases아래에 Releases를 지정하는 워크스페이스는 하나의 카탈로그를 여러 변형으로 나란히 두고 각 변형을 해당 Release가 읽게 할 수 있으며, 이 모두를 한 번에 검사하면 모든 변형을 동시에 읽게 되어 한 변형의 엔터티가 다른 변형의 엔터티를 가리게 됩니다. 따라서 워크스페이스에 있는 각 Release마다 그 Release가 읽는 디렉터리에 대해 한 번씩 검사하며, 모든 패스에서--catalog디렉터리를 먼저 읽습니다. 구성에서 지정하지 않은 Release는 워크스페이스의 목록을 읽습니다. 각 패스는 해당 Release와 읽은 디렉터리를 나타내는 줄 아래에 보고되며, 그 뒤에 해당 패스의 결과와 자체 요약이 이어집니다.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)정확히 같은 디렉터리를 읽는 Releases는 하나의 패스를 공유하며, 그 패스는 각 Release의 이름을 나타내므로 그 안의 결과는 한 번만 보고됩니다. 디렉터리를 하나도 읽지 않는 Release, 즉 항목에
catalog_dirs: []가 적힌 Release는 검사할 것이 없다고 보고되고, 다른 패스는 평소대로 실행됩니다.-o json을 사용하면 문서에passes도 포함됩니다. 여기에는 각 패스의releases,catalogDirs,findings,summary가 들어 있으며, 최상위findings와summary는 모든 패스를 합친 내용을 다룹니다. 워크스페이스에 있는 Releases는 해당 워크스페이스의 Release 문서입니다. 즉, 숨김 디렉터리와node_modules,vendor,dist를 제외한 워크스페이스 루트 아래 어디에든 있는,kind가Release인 YAML 파일입니다.
어느 패스에서도 읽을 것이 없는 실행은 깨끗한 카탈로그로 보고되지 않고 거부됩니다. 엔터티를 catalog/ 아래에 두거나, --catalog를 전달하거나, workspace.catalog_dirs를 설정하십시오. Releases를 지정하는 워크스페이스에서는 workspace.releases 아래에 Release 자체의 catalog_dirs를 설정할 수도 있습니다. 현재 작업 디렉터리를 암묵적으로 열거하는 일은 없습니다.
카탈로그 디렉터리 아래에 있으면서 워크스페이스 밖으로, 또는 워크스페이스 밖에서 지정한 디렉터리의 밖으로 이어지는 링크는 읽지 않으며, 읽지 못한 문서가 있는 카탈로그를 깨끗하다고 보고하는 대신 해당 링크를 지목하며 실행이 그 자리에서 중단됩니다. 같은 디렉터리에 대한 빌드도 같은 링크에서 중단됩니다. 워크스페이스 경계에서 이 규칙과 해결 방법을 설명합니다.
Release 전반의 관례 (--release)
aggrega lint --release <release-path>는 전체 카탈로그나 단일 엔터티가 아니라, 하나의 Release가 해석한 클로저가 도달하는 카탈로그 엔터티 파일에 대해 동일한 구조 규칙을 실행합니다. 빌드가 사용하는 것과 같은 메커니즘으로 클로저를 계산한 다음, 각 엔터티의 작성자 소유 카탈로그 파일을 린트합니다. 캐시 슬롯에 있는 레지스트리 고정 엔터티는 린트할 로컬 파일이 없으므로 건너뜁니다. 게시 규칙은 로컬에서 작성된 파일에 적용됩니다. 전체 카탈로그 모드와 마찬가지로 결과는 권고 사항이며, 관례 결과만으로는 중단되지 않습니다.
이 범위는 또한 Release 전체를 손에 쥐는 유일한 범위이므로, 하나의 실행을 읽는 규칙, 즉 The discipline rules에서 설명하는 연결 자격 증명 규칙이 실행되는 곳입니다. 이러한 규칙은 엔터티별 규칙 다음에 검사당 한 번, 세 가지 문서에 대해 실행됩니다. Release가 배포하는 Aggregate(작성자가 작성한 그대로), extends 체인이 합쳐진 Release(따라서 자식 Release는 상속받은 내용을 가짐), 그리고 Aggregate가 선언하는 각 component에 대해 그 component가 인스턴스인 Component(카탈로그가 해석한 그대로)입니다. 모든 범위에서와 마찬가지로 매개변수 값은 그중에 포함되지 않습니다. Release는 기본 Release에서 상속받은 값을 포함하여 parameters 블록 없이 전달되고, Aggregate는 기본값이나 가져오는 각 모듈에 전달하는 값 없이 전달됩니다. What a linter plugin is handed를 참조하십시오. 그 결과는 Release 파일 아래에 보고됩니다.
이는 같은 클로저의 정확성을 검사하는 aggrega validate --release에 대응하는 관례 쪽 명령입니다.
이 범위가 실행하는 린터는 빌드와 마찬가지로 Release 옆에 있는 신뢰된 플러그인 ID 기록을 따릅니다. 린터가 실행되기 전에 --release는 구성된 plugins.linter 연결을 플러그인 신뢰 기록과 비교합니다. 기록되었지만 구성이 더 이상 연결하지 않는 플러그인(린터 또는 게이트)이 있으면 해당 패스가 중단되고, 캐시에서 읽은 린터의 아티팩트가 기록된 것이 아니면 실행되지 않고 거부됩니다. 캐시에서 읽은 린터는 로드될 때 기록된 서명도 따릅니다. 해당 항목이 검증된 서명을 기록하고 있으면 그 사실이 가리키는 캐시 안의 서명 자료를 다시 검사하며, 자료가 없거나 다르면 E0144로, 읽은 린터와 다른 플러그인을 위해 만들어진 경우(다른 항목에서 복사한 signature)에는 서명 요구 사항과 관계없이 E0332로 패스가 중단됩니다. 워크스페이스의 신뢰 구성이 서명을 요구하는 경우, 서명을 기록하지 않은 항목이나 린터에 대한 항목이 없는 경우(삭제된 기록 포함)에는 aggrega pull이 서명되지 않은 것으로 거부하게 되는 것과 같은 설정에서 E0331로 패스가 중단됩니다. 세 가지 모두 해결 방법으로 aggrega pull --release <release>를 제시합니다. 이 명령은 레지스트리에서 린터의 서명을 검증하여 기록하고, 그것이 가리키는 번들을 캐시하며, 다이제스트와 더 이상 일치하지 않는 캐시된 사본을 다시 씁니다. 컴파일러 바이너리 내부의 사본에서 제공되는 린터는 이 요구 사항을 따르지 않습니다. 이들은 관례 결과가 아니라 패스의 실패이므로, 결과라면 중단되지 않을 상황에서도 중단됩니다. 전체 카탈로그 범위와 단일 엔터티 범위는 Release를 지정하지 않고 기록도 읽지 않으므로, 이 범위에서 캐시로부터 읽은 린터는 캐시된 매니페스트만을 기준으로 검사됩니다. 이 모든 것에 앞서 --release는 Release가 의존하는 대상에 기록된 모든 철회를 aggrega build가 출력하는 문구 그대로 deprecation: 줄로 밝힙니다. 잠금 파일이 고정된 참조에 대해 기록한 마커와 신뢰 기록이 린터나 게이트에 대해 기록한 마커 모두 마찬가지입니다. 따라서 위의 거부로 패스가 중단되는 경우에도 패스는 이를 알립니다. 철회는 어떤 결과나 종료 코드도 바꾸지 않으며, 존재하지만 읽을 수 없는 신뢰 기록은 아무것도 기록하지 않은 기록으로 통과되는 대신 패스를 중단시킵니다.
엔터티 규율: 로컬 및 게시 게이트
엔터티 경로 모드는 두 가지 심각도 중 하나로 실행됩니다.
- 기본값(로컬). 로컬 엔터티 내용에 대해 규율 규칙을
warn심각도로 실행합니다. 레지스트리에 접근하지 않으며, 버전 상향 검사는 건너뜁니다. 작성 중에 사용합니다. --pre-publish(게시 게이트). 레지스트리에서 엔터티의 최신 게시된 비프리릴리스 버전을 가져와 같은 규칙을halt심각도로 실행하고, 추가로 변경을PATCH/MINOR/MAJOR로 분류하여 제안된metadata.version상향이 변경에 필요한 것보다 작으면 중단합니다. 게시 흐름에서aggrega push전에 사용합니다.--pre-publish는 단일 엔터티 형태에만 적용됩니다.
필요 이상으로 버전을 올리는 것은 항상 허용되며, 필요보다 적게 올리면 중단됩니다. 엔터티의 첫 게시(레지스트리에 이전 버전이 없는 경우)에서는 상향 검사를 건너뛰고, 검증이 수행되지 않았음을 알리는 경고를 표시합니다.
엔터티 모드가 검사하는 종류
엔터티 모드는 지정한 문서를 종류와 관계없이 lint하고, 하나의 엔터티를 읽는 모든 규칙에 전달합니다. 각 규칙은 자신이 어떤 종류를 다루는지 스스로 정하며, 다루지 않는 종류를 전달받은 규칙은 아무것도 보고하지 않습니다. 따라서 Aggregate, Manifest, Release 또는 Workload(카탈로그 전체 패스가 건너뛰고 not checked: 줄에 나열하는 종류)를 지정해도 규칙이 실행되며, 그 종류를 다루는 규칙만 보고할 수 있습니다:
| 규칙 | 엔터티 모드에서 보고하는 종류 |
|---|---|
| 어노테이션 접두사 | 모든 종류: 문서의 종류와 관계없이 metadata.annotations를 읽습니다. |
x-aggrega-* 확장의 직접 사용 | 모든 종류: 문서의 종류와 관계없이 spec.schema를 읽습니다. |
| 이름 형식 | Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary. |
| 카테고리와 디렉터리 일치 | Component. |
| 시크릿 슬롯의 sensitive 선언 | Component와 Feature. |
| 메트릭 자격 증명 어노테이션과 provides 일치 | Component. |
| Component가 선언하는 Provides | Recipe. |
| 동적 참조, Id 재정의 | SchemaLibrary. |
| Plugin 기본 제한 | Plugin. |
버전 상향 비교(--pre-publish) | Component, Feature, Recipe, FeatureRecipe, SchemaLibrary, MappingLibrary, Aggregate, Plugin(컴파일러에 내장된 플러그인은 비교하지 않습니다). 그 밖의 종류에 대한 변경은 MAJOR로 분류됩니다. |
| 연결 자격 증명과 대상 키 일치 | 없음: Release 전체를 읽으므로 --release에서만 실행됩니다. |
Aggregate, Manifest, Release, Workload는 스키마에서 metadata.annotations도 spec.schema도 선언하지 않으므로, 이들 중 자신의 종류의 스키마에 맞는 문서는 모든 종류를 읽는 두 규칙에서 아무런 결과도 받지 않습니다. 이 두 규칙은 문서가 그럼에도 해당 키 중 하나를 가지고 있을 때만 보고하며, 그 키는 종류의 스키마가 예상하지 않은 속성으로 거부합니다. Aggregate를 지정하면 추가되는 것은 --pre-publish에서의 버전 상향 비교로, 아래 기준에서 설명하듯 게시된 버전과 비교합니다.
버전 증가 기준
--pre-publish 모드에서는 변경 사항을 이전에 게시된 버전과 비교하여 다음과 같이 분류합니다.
PATCH— 문서 또는 주석만 바뀐 변경.MINOR— 엄격하게 추가만 하는 변경(새로운 선택적 필드, 새 항목).MAJOR— 제거, 타입 축소, 또는 이전에 선택적이던 필드가 필수가 되는 경우.
비교는 엔터티 종류별로 이루어집니다. Component, Feature, SchemaLibrary는 스키마를 담는 필드를 고려하여 비교하고, MappingLibrary는 항목 키 수준에서 비교하며(항목 본문은 불투명하므로 본문이 바뀌면 보수적으로 MAJOR로 취급합니다), Recipe와 FeatureRecipe는 핵심 필드를 기준으로 비교합니다. Aggregate는 매개변수 선언, 구성 요소, 하위 시스템을 기준으로 비교합니다. 매개변수의 기본값은 다른 매개변수 값과 마찬가지로 비교 대상에 포함되지 않으므로(린터 플러그인에 전달되는 것 참조), 기본값을 추가하거나 변경하거나 제거하는 등 기본값에 국한된 변경은 비교에 포함되지 않으며, 매개변수 슬롯 어휘에 속하지 않는 키의 변경도 마찬가지입니다. 버전 증가가 부족하면 필요한 증가 수준을 명시하는 진단과 함께 중단됩니다.
규율 규칙
대부분의 규칙에는 .aggrega-config.yaml의 lint.publishing_discipline 아래에 워크스페이스별 설정이 있고 이에 대응하는 CLI 재정의가 있으며, 각 재정의에는 --no- 대응 플래그가 있습니다. 우선순위는 전체 카탈로그, Release, 단일 엔터티의 모든 범위에서 --no-<flag>가 --<flag>보다, 그리고 그것이 워크스페이스 구성 값보다 우선합니다. 모든 규칙은 기본적으로 켜져 있으며, 각 기본값은 플랫폼 메커니즘이나 문서화된 카탈로그 관례에 근거합니다. 설정은 규칙 하나를 완화할 이유가 있는 워크스페이스를 위한 선택적 해제 수단입니다.
설정이 없는 규칙은 아래 항목에서 그렇다고 밝히며, 그 이유는 모두 같습니다. 이러한 규칙은 엔티티에 관한 사실을 보고하고 결정을 작성자에게 맡기므로 완화할 판단이 없습니다. 위에서 설명한 버전 올림 기준표에도 설정이 없습니다. 이 기준표는 제안된 내용을 게시된 버전과 비교하여 변경이 요구하는 바를 보고하며, 이는 워크스페이스 선호가 아니라 변경 자체의 속성입니다.
- 어노테이션 접두사 — 예약된 네임스페이스(
aggrega.ai/, 그리고 Feature 밖에서의feature.aggrega.ai/)는 플랫폼 소유이며 다른 키에서는 거부됩니다. 기본값은 켜짐이며,allow_aggrega_ai_prefix로 옵트아웃합니다. - 이름 형태 — 각 엔티티 종류에는 이름 형태 관례가 있습니다(클라우드 네이티브 종류는 세그먼트 수, 라이브러리 종류는 PascalCase). 기본값은 켜짐이며,
allow_nonstandard_names로 옵트아웃합니다. - 동적 참조 — SchemaLibrary 항목은
$dynamicAnchor/$dynamicRef를 사용할 수 없습니다(플랫폼의 컴파일 시점$ref확장이 이를 해석할 수 없습니다). 기본값은 켜짐이며,allow_dynamic_refs로 옵트아웃합니다. - Id 재정의 — SchemaLibrary 항목은 자체
$id를 선언할 수 없습니다(플랫폼이 정규$id를 도출합니다). 기본값은 켜짐이며,allow_id_overrides로 옵트아웃합니다. - 카테고리와 디렉터리 일치 — Component의
component.aggrega.ai/category레이블은core/아래 첫 번째 디렉터리 세그먼트와 일치해야 하며, 닫힌 카테고리 집합(ai-agent,ai-model,ai-tool,ai-pipeline,datastore,gateway,mesh,network,messaging,storage,compute,observability,security,bigdata,devtool)에서 선택됩니다.core/경로 아래 엔티티에 대해 기본값은 켜짐이며,allow_category_mismatches로 옵트아웃합니다. - 직접 작성한
x-aggrega-*확장 — Component 또는 Feature 스키마에x-aggrega-*키를 직접 작성하는 것은 권장되지 않으며, 일급 작성 경로를 사용하는 것이 좋습니다. 기본값은 켜짐이며,allow_direct_x_aggrega_extensions로 옵트아웃합니다. - Component가 선언한 provides — Recipe의
spec.provides는 항목마다 키 하나를 게시하며, Recipe가 구현하는 Component는 자신의spec.schema의provides기둥에서 해당 타입이 노출하는 키를 선언합니다.injectfrom:참조는 바로 이 선언을 기준으로 검사되므로, Component가 선언하지 않았는데 Recipe가 게시하는 키는 생성된 뒤 소비자가 연결하는 곳에서 거부됩니다. 선언된 계약을 넘어선 게시는 빌드 시점에 허용되며, 이 때문에 이 결과는 거부가 아니라 권고입니다. Recipes에 대해 기본값은 켜짐이며,allow_undeclared_recipe_provides로 옵트아웃합니다. - Plugin 기본 제한 — Plugin의
spec.runtime에는 호스트가 플러그인을 로드하고 실행할 때 적용하는 두 가지 상한인maxMemoryPages와timeoutMs가 있습니다. 둘 다 고정하지 않은 Plugin은 플랫폼 기본값으로 실행되며, 이는 안전한 결과이지 오류가 아니므로 이 규칙은 기본값이 적용 중이며 명시적 상한을 고정할 수 있다고 보고합니다. Plugin 엔티티에 대해 기본값은 켜짐이며, 설정은 없습니다. - 비밀 슬롯의 sensitive 선언 — 첨부 슬롯은 레이블 셀렉터를 통해 자신을 채우는 Feature의 종류를
secret으로 고정할 수 있으며, 별도로sensitive: true를 선언하여 무엇이 채우든 비밀 자료를 다룬다는 것을 기록할 수 있습니다. 셀렉터는 어떤 채움이 허용되는지를, 마커는 취급 방식을 나타냅니다. 종류를 고정하고 마커를 선언하지 않은 슬롯은 그 취급 방식을 직접 읽는 대신 셀렉터에서 다시 도출하도록 남겨 둡니다. 이 규칙은 엔티티가 선언하는 모든 슬롯을 읽습니다. 즉spec.featuresSchema아래 자체 첨부 블록의 슬롯과, Component의 경우 이를 통해 연결된 연결에 대해 각 의존성 소켓이spec.usesSchema.<socket>.featuresSchema아래에 선언하는 슬롯입니다. 소켓 슬롯에 관한 결과는 슬롯과 함께 소켓의 이름도 명시합니다. Components와 Features에 대해 기본값은 켜짐이며, 설정은 없습니다. - Connection credential matches target key (
connection-credential-matches-target-key) — 키를 검사하는 서버는 자신이 검증하는 키를 자기 Component의 슬롯에 보관하고, 호출자는 서버에 도달하는 데 사용하는 연결에서 키를 제시합니다. 어느 쪽도 상대편의 첨부를 보지 못하므로, 두 쪽이 하나의 키를 갖는 것은 작성자가 양쪽 끝에 그 키를 작성하기 때문일 뿐이며(대개 두 첨부가 하나의 파라미터를 읽게 함으로써), 빌드는 이 둘을 비교하지 않습니다. 이 규칙은 이를 비교하며, Release 전체를 읽는 유일한 규칙이므로--release에서만 실행되고 다른 범위에서는 실행되지 않습니다. 이 규칙은 표준 카탈로그가 부여하는 이름으로 양쪽 끝을 찾습니다. 대상의 키는 그 Component가spec.featuresSchema에 선언하는 슬롯api_key이고, 호출자의 키는 연결의 슬롯credential로, Aggregate에서uses.<socket>.<alias>.features.credential에 작성되거나 Release가 연결하는 연결에 작성됩니다. 대상이api_key를 선언하고 managed로 레이블되지 않은 각 연결에 대해, 키 슬롯이 채워지지 않은 대상으로 자격 증명을 전달하는 연결, 채워진 키 슬롯이 있으나 연결에 자격 증명이 없는 경우, 그리고 양쪽 끝이 시크릿을 서로 다르게 지칭하는 경우를 보고합니다. 비교하는 것은 각 끝의 로케이터, 즉 첨부가 작성하는origin(Aggregate의values또는 Release의infra에 있음)을 작성자가 작성한 그대로입니다. 따라서 하나의 파라미터를 읽는 두 끝은 같다고 비교되고 두 리터럴은 텍스트로 비교됩니다. 아무것도 해석되지 않으며, 결과는 컴포넌트, 연결, 대상, 두 슬롯을 명시하지만 어느 로케이터도 인용하지 않습니다. 그곳에 작성된 텍스트가 시크릿 자체일 수 있기 때문입니다.api_key슬롯을 선언하지 않은 대상은 아무 결과도 내지 않으며, 모델 서버의 레지스트리 pull 토큰처럼 호출자 키가 아닌 슬롯은 절대 읽지 않습니다. 또한 Component가component.aggrega.ai/hosting: managed로 레이블된 대상은 그api_key슬롯에 무엇이 있든 판정하지 않습니다. 그러한 Component는 벤더가 운영하는 서비스를 나타내므로 Release가 실행하는 어떤 것도 그 위에서 키를 검사하지 않으며, 그것이api_key를 선언하는 경우(예를 들어 벤더의 제품이 부여하는 이름으로 호스팅 모델 API의 키를 선언하는 경우) 그 슬롯은 Release가 해당 벤더에 제시하는 키를 보관할 뿐, 호출자가 제시하는 키를 보관하지 않습니다.self-hosted,external또는mixed로 레이블되거나 호스팅 레이블이 없는 대상은 판정합니다. 소켓scrape_target(표준 카탈로그가 메트릭 스크레이퍼가 대상에 도달하는 소켓에 부여하는 이름)의 연결은 스크레이프이며, 스크레이프의 자격 증명이 대상의 호출자 키여야 하는지는 대상의 제품에 따라 다릅니다. 어떤 제품은 자격 증명 없이 메트릭을 제공하고, 어떤 제품은 모든 호출자가 제시하는 키 뒤에 두며, 어떤 제품은 자체 토큰을 받습니다. 따라서 스크레이프의 경우 이 규칙은 대상의 Component가 어노테이션observability.aggrega.ai/metrics-credential에 명시한 내용을 읽습니다.none이면 스크레이프를 전혀 판정하지 않고,separate-token이면 그 자격 증명을 대상의api_key와 절대 비교하지 않으므로 세 가지 결과 중 어느 것도 보고되지 않으며,target-key이면 다른 연결과 마찬가지로 판정합니다. 이 규칙은 이 세 값만 읽으므로, 어노테이션이 없거나 다른 값을 가진 대상으로의 스크레이프는 다른 연결과 마찬가지로 판정되며, 모델, 도구, 데이터스토어 연결을 포함하여 다른 소켓의 모든 연결은 대상의 어노테이션이 무엇이든 동일하게 판정됩니다. 이 규칙은 대상과 연결에 작성된 첨부를 읽습니다. 서브시스템이나 경계로부터 대상에 도달하는api_key첨부는 대신 그 연결을 판정하지 않은 상태로 두고, 어노테이션이 추가하는 첨부는 읽는 대상에 포함되지 않으므로 그런 방식으로만 채워진 키 슬롯은 채워지지 않은 것으로 읽히며, 첨부가 로케이터를 작성하지 않은 끝은 채워졌는지 여부로만 비교되고, 가져온 모듈이 기여하는 컴포넌트는 읽지 않습니다. 슬롯 이름, 호스팅 레이블, 스크레이프 소켓의 이름, 메트릭 어노테이션은 어떤 스키마 키워드도 표시하지 않는 카탈로그 관례이므로, 슬롯 이름을 다르게 지정한 카탈로그는 아무 결과도 내지 않고, 다른 이름의 스크레이프 소켓은 다른 소켓과 마찬가지로 판정되며, managed 레이블 없이api_key라는 이름의 슬롯에 벤더의 키를 보관하는 Component는 그 키를 검사하는 대상으로 읽힙니다. 슬롯의 이름, 레이블, 어노테이션이 이 규칙이 대상의 Component에서 읽는 전부이기 때문입니다. 기본값은 켜짐이며,allow_connection_credential_mismatches로 해제할 수 있습니다. - Metrics credential annotation matches provides (
metrics-credential-annotation-matches-provides) — Component는 자신의 메트릭에 대해 두 가지 사실을 명시할 수 있습니다. 어노테이션observability.aggrega.ai/metrics-credential은 제품의 메트릭이 어떻게 인증하는지를 명시합니다.none은 자격 증명 없이 제공됨을,target-key는 Component가 모든 호출자에게 요구하는 키, 즉api_key슬롯이 보관하는 키를 받음을,separate-token은 자체 토큰을 받음을 뜻합니다.spec.schema의provides기둥에 선언되는 provides 키metrics_credential_required는 각 Recipes가 한 인스턴스의 메트릭에 자격 증명이 필요한지를 알리기 위해 게시하는 것입니다. 이는 인스턴스의 구성 방식에 따라 달라질 수 있습니다. 호출자 키 뒤에 있는 메트릭은 키가 첨부된 동안에만 자격 증명이 필요하므로, 어노테이션이 이를 대신할 수 없습니다. 두 가지는 제품에 대한 하나의 사실을 명시하므로, 이 규칙은 둘이 일치하도록 합니다.none으로 어노테이션되었으나 키를 선언한 Component와,target-key또는separate-token으로 어노테이션되었으나 키를 선언하지 않은 Component는 각각 보고되며, 결과는 Component, 어노테이션의 값, 그리고 남거나 빠진 키를 명시합니다. 어노테이션이 없거나 다른 값을 가진 Component는 아무 결과도 내지 않습니다. 이 규칙은 Component를 작성된 그대로 읽으므로, 다른 Component를 확장하는(스키마가 기반의 것인) Component는 아무 결과도 내지 않고 그 기반은 선언된 곳에서 읽히며, 참조, 합성 또는 텍스트로 작성된 이스케이프된 본문으로 작성된provides기둥은 열거할 수 없으므로 그 Component 역시 아무 결과도 내지 않습니다. Components에 대해 기본값은 켜짐이며, 설정은 없습니다.
아티팩트 불변성은 이 규칙들 중 하나가 아니며, 설정이 없습니다. 게시된 name:version은 최종입니다. aggrega push는 해당 태그에 이미 게시된 다이제스트와 푸시하려는 내용이 생성할 다이제스트를 비교하고, 다른 내용으로 덮어쓰기를 거부합니다. 바이트 단위로 동일한 내용을 다시 푸시하면 아무것도 업로드하지 않고 해당 게시에 아직 없는 것, 즉 게시 날짜와 푸시가 서명하는 경우 서명만 첨부합니다. 레지스트리가 운영자가 선택할 수 있는 덮어쓰기 경로를 제공하지 않으므로, 어떤 플래그나 워크스페이스 구성 설정도 이를 완화하지 않습니다. 변경된 내용은 새 버전으로 게시되며, --pre-publish가 이전 릴리스와 비교하여 그 버전 증가를 검증합니다.
규칙별 재정의 플래그는 호출 단위의 게이트이며 의도적으로 환경 변수가 없습니다. 이미 .aggrega-config.yaml의 lint.publishing_discipline 아래에서 구성으로 뒷받침되기 때문입니다. 일반적인 AGGREGA_* 우선순위 모델은 environment-variables.md에 설명되어 있습니다.
빌드 시점과 게시 시점
x-aggrega-* 사용 억제 규칙은 aggrega build 중에도 실행되며, 이때는 경고로 표시됩니다. aggrega lint --pre-publish는 같은 결과를 오류로 격상합니다. 로컬 빌드에서는 권고로 전달되고, 게시 관문에서는 이를 강제합니다.
에디터에서 작성하는 동안
에디터는 카탈로그 엔터티에 대해 서로 다른 두 가지 질문을 하며, 이는 이 페이지의 첫머리에서 다룬 두 가지입니다. 엔터티가 올바른가 — 파싱되는가, 기둥(pillar)이 해석되는가, 렌더링되는가? 이는 aggrega validate의 영역이며, 에디터 세션은 항상 이 질문에 답합니다. 엔터티가 게시 가능한가 — 이름이 관례를 따르는가, 파일이 해당 카테고리가 기대하는 디렉터리에 있는가, 어노테이션 접두사가 올바른가? 이는 이 규칙들의 영역이며, 에디터 세션은 요청할 때만 이 질문에 답합니다.
켜기 전에는 꺼져 있습니다. 조언을 받고 싶은 엔터티가 속한 워크스페이스의 .aggrega-config.yaml에서 serve.lint_on_validate로 켭니다:
serve: lint_on_validate: true이를 위한 명령줄 플래그는 없으며, 이는 의도된 것입니다. 이 질문은 특정 워크스페이스 자체의 내용에 관한 것이고, 사용자는 언어 서버를 실행하는 쪽이 아니라 그 워크스페이스를 작성하는 쪽이기 때문입니다. 언어 서버는 에디터가 실행합니다.
이 설정을 켜면 검증하는 모든 엔터티에 정확성 관련 결과와 함께 이 결과들도 표시되며, 각 결과에는 이를 만든 규칙의 이름이 붙습니다. 이에 따라 세 가지가 성립하며, 이것이 입력하는 동안 이 기능을 쓸 수 있게 해 줍니다:
- 결과는 권고로 남습니다. 관례를 어긴 엔터티도 여전히 검증을 통과하며, 그 Release도 여전히 해석되고 렌더링됩니다. 이 설정을 켜면 조언 계층이 추가될 뿐이며, 에디터가 작동을 거부하게 만들지는 않습니다.
- 둘을 구별할 수 있습니다. 게시되는 모든 문제에는 이를 제기한 계층의 이름이 붙으므로, 같은 파일에 대한 명명 문제와 해석 실패는 한 문제가 두 번 보고된 것이 아니라 서로 다른 두 가지로 읽힙니다.
- 입력한 내용이 그대로 검사됩니다. 규칙은 디스크의 파일이 아니라 버퍼를 읽으므로, 수정한 이름은 저장하기 전에 보고되지 않게 됩니다.
이 계층에서는 로컬 콘텐츠 모드만 실행됩니다. 레지스트리를 조회하지 않고, 아무것도 가져오지 않으며, 아무것도 쓰지 않습니다. --pre-publish 비교는 요청해야만 실행됩니다 — 터미널에서 --pre-publish를 입력하는 것과 같은 방식으로 에디터가 이를 위한 요청을 보내며, 위 설정을 편집해서는 절대 실행되지 않습니다. 문서를 건드릴 때마다 실행되는 검사야말로 레지스트리에 접근해서는 안 되는 곳이므로, 그 모드는 함께 따라 실행되는 것이 아니라 직접 호출하는 것으로 남습니다.
검사를 명시적으로 요청하면 설정과 관계없이 위의 세 가지 범위 모두에서 작동합니다. 따라서 편집 시 계층을 한 번도 켜지 않은 워크스페이스도 에디터에 카탈로그 전체, Release의 클로저 또는 엔터티 하나를 검사하도록 요청할 수 있으며, 이 명령이 출력하는 것과 같은 결과를 받습니다. 설정은 이름을 지정해 요청하지 않은 곳에서도 검사를 실행할지만 결정합니다.
프로토콜 세부 사항은 두 페이지에 나뉘어 있습니다. 요청의 의미와 보낼 시점은 aggrega serve 레퍼런스에, 매개변수와 응답의 형태는 필드별로 와이어 형태 레퍼런스에 있습니다.
린터 선택
규칙은 표준 게시 린터 Wasm 플러그인으로 제공됩니다. 규칙이 컴파일러가 아니라 플러그인에 있으므로, 기업은 컴파일러를 변경하지 않고도 aggrega lint가 다른 플러그인을 사용하도록 지정하여 자체 카탈로그 규율을 적용할 수 있습니다.
워크스페이스는 plugins.linter 아래에 둘 이상의 린터를 연결할 수 있으며, 모든 연결이 실행됩니다. 연결이 작성된 순서대로 각각 자체 진입 함수에서 실행되고, 모든 결과가 함께 보고됩니다. 이 덕분에 카탈로그는 둘 중 하나를 선택하는 대신 표준 규칙을 유지하면서 자체 규칙을 함께 추가할 수 있습니다. --plugin은 예외입니다. 이 플래그는 구성된 연결 대신 파일 시스템 경로의 아티팩트 하나만 정확히 실행하며, 이 점이 규칙을 개발하는 동안 유용한 이유입니다.
연결은 uri:로 플러그인을 지정하고, function:은 그 플러그인의 진입 함수를 지정합니다. function:은 지정하고 uri:는 지정하지 않은 항목은 어떤 플러그인에도 속하지 않는 함수를 지정하는 것이므로, 구성은 읽히는 시점에 E0224로 거부되며, 파일과 목록 안에서 항목의 위치가 지목됩니다. 그 함수를 내보내는 플러그인의 uri를 추가하십시오. 둘 다 지정하지 않은 항목은 아무것도 연결하지 않으며 건너뜁니다. 그것이 유일한 항목이면, plugins.linter가 아예 없을 때와 마찬가지로 표준 린터가 자체 기본 진입 함수로 실행됩니다.
린터 플러그인이 전달받는 것
어떤 범위에서도 파라미터 값은 린터 플러그인에 전달되지 않습니다. 파라미터 값은 그 자체가 자격 증명일 수 있습니다. 시크릿 첨부의 origin은 Release가 채우는 파라미터를 읽는 템플릿일 수 있으며, 이 경우 시크릿은 그 파라미터의 값이 됩니다. 또한 워크스페이스가 첨부하는 플러그인은 워크스페이스가 직접 작성하지 않은 것일 수 있으므로, 모든 문서는 파라미터 값이 제외된 상태로 전달됩니다.
- Aggregate는 각 파라미터 선언을 유지하되, 선언을 작성하는 키, 즉 파라미터 슬롯 어휘인 타입, 설명, 제약 조건만 유지하며,
properties,items,valuesType아래에 중첩된 모든 선언에도 동일하게 적용됩니다. 선언의default는 모든 수준에서 제외되며, 키를 비우는 대신 키 자체를 제거하므로 플러그인은 선언이 기본값을 제공하는지 알 수 없습니다. 이 어휘에 속하지 않는 키는 모든 수준에서 그 내용과 함께 제외됩니다. 빌드는 그러한 키에 아무 의미도 부여하지 않으며, 키 이름을 잘못 쓴 초안은 그 아래에 시크릿을 담고 있을 수 있기 때문입니다.parameters아래의 항목 중 선언이 아닌 것은 통째로 제외됩니다. - Aggregate의
aggregates아래에 나열된 각 모듈은 해당 모듈에 전달되는 값을 담은parameters블록을 잃습니다. - Release는 값을 인라인으로 작성하든
$import로 가져오든parameters블록을 잃습니다. spec아래에parameters블록을 가진 그 밖의 모든 문서는 이를 통째로 잃습니다. 다른 어떤 종류도 이 블록을 선언하지 않습니다.
이는 명령줄에 지정된 엔터티, --pre-publish가 비교 대상으로 삼는 게시된 버전, 전체 카탈로그 패스와 --release 패스가 순회하는 모든 엔터티, 그리고 Release 전체를 읽는 규칙이 받는 문서에 적용됩니다. 파라미터를 읽는 템플릿은 값이 아니므로 그 텍스트가 유지되며, 따라서 규칙은 작성된 값이 어떤 파라미터를 읽는지 여전히 확인할 수 있습니다.
예시
카탈로그 전체에서 관례에서 벗어난 부분을 점검합니다:
aggrega lint --catalog ./catalog작성 중에 엔터티를 로컬에서 린트합니다:
aggrega lint core/datastore/postgres/component.yaml새 버전을 게시하기 전에 게시 게이트를 실행합니다:
aggrega lint core/datastore/postgres/component.yaml --pre-publish한 번의 실행에 대해 규칙 하나를 완화합니다:
aggrega lint core/datastore/postgres/component.yaml --pre-publish --allow-nonstandard-names참고 항목
- ./aggrega-validate.md — 같은 세 가지 범위에 걸쳐 정확성을 검사하는 대응 명령입니다.
- ./aggrega-build.md — 컴파일 과정의 일부로 검증하며,
x-aggrega-*권고를warn심각도로 표시합니다. - ./aggrega-push.md — 엔터티를 레지스트리에 게시합니다.
aggrega lint --pre-publish는 그에 앞서는 게이트입니다. - ./aggrega-pull.md — 종속성을 해석하고 고정합니다.
- ./aggrega-serve.md — 이러한 검사 결과를 편집기에 보고하는 언어 서버와, 편집할 때마다 실행되는 계층을 켜는 설정입니다.
- ../errors/warnings.md — 로컬 모드 린트 결과를 포함한 치명적이지 않은 경고입니다.
개요
aggrega lint [entity-path] [flags]설명
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.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--allow-aggrega-ai-prefix | false | allow_aggrega_ai_prefix=true를 강제합니다 |
--allow-category-mismatches | false | allow_category_mismatches=true를 강제합니다 |
--allow-connection-credential-mismatches | false | allow_connection_credential_mismatches=true를 강제합니다 |
--allow-direct-x-aggrega-extensions | false | allow_direct_x_aggrega_extensions=true를 강제합니다 |
--allow-dynamic-refs | false | 이번 실행에 한해 allow_dynamic_refs=true를 강제합니다 |
--allow-id-overrides | false | 이번 실행에 한해 allow_id_overrides=true를 강제합니다 |
--allow-nonstandard-names | false | allow_nonstandard_names=true를 강제합니다 |
--allow-undeclared-recipe-provides | false | allow_undeclared_recipe_provides=true를 강제합니다 |
--baseline | — | 게시 전 진화 검사를, 게시하려는 버전보다 낮은 버전 중 자동으로 선택된 최고 버전 대신 이미 게시된 이 특정 버전과 비교합니다. 레지스트리에 있는 엄격한 SemVer 태그여야 합니다(—pre-publish 필요) |
--catalog | [] | 카탈로그 디렉터리이며 반복해서 지정할 수 있습니다. 각 —catalog <dir>는 카탈로그 검색 스택의 앞에 추가됩니다(먼저 일치하는 항목이 우선). 스택은 워크스페이스의 catalog_dirs이며, 워크스페이스 구성이 workspace.releases 아래에 자체 디렉터리를 지정한 Release의 경우에는 그 Release의 디렉터리입니다. 워크스페이스 루트에 catalog라는 이름의 디렉터리가 있으면 스택은 그 디렉터리로 끝납니다. 비어 있게 작성된 catalog_dirs 목록은 로컬 카탈로그를 전혀 읽지 않습니다. 전체 카탈로그 검사와 —release 관례 검사에서 사용됩니다. |
--entity | — | 린트할 엔터티 YAML의 경로입니다(위치 인수로 전달할 수도 있음) |
--no-allow-aggrega-ai-prefix | false | allow_aggrega_ai_prefix=false를 강제합니다 |
--no-allow-category-mismatches | false | allow_category_mismatches=false를 강제합니다 |
--no-allow-connection-credential-mismatches | false | allow_connection_credential_mismatches=false를 강제합니다 |
--no-allow-direct-x-aggrega-extensions | false | allow_direct_x_aggrega_extensions=false를 강제합니다 |
--no-allow-dynamic-refs | false | 이번 실행에 한해 allow_dynamic_refs=false를 강제합니다 |
--no-allow-id-overrides | false | 이번 실행에 한해 allow_id_overrides=false를 강제합니다 |
--no-allow-nonstandard-names | false | allow_nonstandard_names=false를 강제합니다 |
--no-allow-undeclared-recipe-provides | false | allow_undeclared_recipe_provides=false를 강제합니다 |
--output, -o | text | 출력 형식: text|json. |
--plugin | — | 게시용 린터 .wasm 아티팩트의 파일 시스템 경로입니다(워크스페이스의 plugins.linter 연결 대신 이 아티팩트를 실행함) |
--pre-publish | false | 레지스트리의 이전 버전을 가져와 제안된 버전 올림을 스키마 진화 분류에 비추어 검증합니다 |
--release | — | 해석된 종속성 클로저 전체에 걸쳐 관례를 검사할 Release YAML의 경로입니다(엔터티 인수와 함께 사용할 수 없음). 상대 경로는 워크스페이스 루트가 아니라 명령을 실행하는 디렉터리를 기준으로 해석됩니다. 그 디렉터리가 어떤 워크스페이스에도 속하지 않고 루트도 지정되지 않은 경우, 절대 경로는 Release 자체의 폴더에서 워크스페이스를 찾습니다 |