aggrega validate
aggrega validate는 정확성을 검사합니다. 스키마, 필라 구조, 문서 간 참조 해석, extends 체인, provider 입력 종류 지원 여부, 그리고 (렌더링 엔터티의 경우) 실제로 렌더링되는지를 확인합니다. 인수로 선택되는 세 가지 모드가 있으며, 같은 정확성 검사를 세 가지 범위에 적용합니다. 카탈로그 전체(인수 없음), 단일 Release의 의존성 폐포(--release), 그리고 하나의 엔터티 파일(엔터티 경로)입니다. 각 범위는 카탈로그의 서로 다른 부분에 대해 같은 질문, 즉 “이 내용이 올바른가?”에 답합니다.
정확성은 관례와 구별됩니다. aggrega validate는 내용이 올바른 형식을 갖추고 컴파일되는지를 묻고, aggrega lint는 내용이 카탈로그의 게시 원칙(명명, 카테고리 디렉터리 정렬, 버전 증가 크기 등)을 따르는지를 묻습니다. 두 명령은 서로의 세 가지 범위를 그대로 따르므로, 필요한 세분성에 맞추어 어느 쪽 측면이든 검사할 수 있습니다.
aggrega validate는 디스크에 아무것도 쓰지 않으며 런타임 상태도 읽지 않습니다. 빌드가 수행하는 것과 같은 해석과 검증을 실행하되, 렌더링 전에 멈춥니다(단일 엔터티의 경우에는 렌더링을 격리합니다).
엔터티 경로는 위치 인수로 지정할 수 있습니다. 엔터티 경로와 함께 --release를 지정해도 Release 범위가 선택되지는 않습니다. 엔터티는 여전히 단독으로 검사되며, 다만 그 Release의 조건에 따라 검사됩니다. Release의 조건으로 엔터티 검사하기를 참조하십시오.
전체 카탈로그 정확성(인수 없음)
인수 없이 실행한 aggrega validate는 구성된 카탈로그 디렉터리 아래의 모든 카탈로그 엔터티를 불러와 처음부터 끝까지 검사합니다. 무엇이든 불러오기 전에 그 아래의 모든 YAML 파일을 읽으며, 그중 불러올 수 없는 Aggrega 문서가 있으면 아래에서 설명하는 대로 실행을 중단합니다. 그런 다음:
- 스키마 필러 구조 — 각 Component와 Feature의
spec.schema:블록을 확장하고 검증합니다(빌드가 적용하는 것과 같은 스키마 필러 검사). 축약형 확장도 포함됩니다. - 문서 간 참조 해석 — SchemaLibrary 항목을 가리키는
$ref및$import참조가 해석되는지 확인하며, 해석할 수 없거나 그 밖의 이유로 유효하지 않은 SchemaLibrary는 거부됩니다. extends체인 —extends를 선언하는 모든 엔터티는 부모를 기준으로 해석되고, 부모와 자식을 병합한 형태가 검사됩니다. 카탈로그 디렉터리에 없는 부모는 빌드가 읽는 곳에서 읽습니다. 즉, Release의 lockfile이 그 부모에 대해 기록한 고정을 따라 아티팩트 캐시에서 읽습니다. 이때 쓰이는 lockfile은 해당 패스가 실행되는 Releases의 lockfile이거나, 워크스페이스를 한 번의 패스로 검증하는 경우 워크스페이스가 가진 모든 Release의 lockfile입니다. 따라서 레지스트리에 게시된 베이스는aggrega pull이 이를 가져와 고정하면 검증을 통과하며, 둘 중 어디에도 없는 부모는aggrega pull --release <release>를 안내하며 실행을 중단시킵니다. 아무것도 가져오지 않습니다.- 선언된 선택자 — Component 또는 Feature 문서가
spec.usesSchema아래의 종속성 소켓이나spec.featuresSchema아래의 첨부 슬롯(Component에서는 소켓이 선언하는 슬롯 포함)에 선언하는 모든 레이블 선택자를, 소켓에 무언가가 배선되었는지나 슬롯이 채워졌는지와 관계없이 선택자 문법에 따라 읽습니다. 선언된 선택자를 참조하십시오. - OCI 위치 충돌 — 같은 레지스트리 위치에 게시될 서로 다른 두 카탈로그 식별자는 명시적으로 거부되므로, 빌드가 한 엔터티의 게시된 바이트를 다른 엔터티의 바이트로 조용히 덮어쓰는 일이 없습니다.
- Provider 입력 종류 기능 — 합성할 수 없는 프로바이더에 바인딩된
workload:블록을 선언하는 Recipe 또는 FeatureRecipe는 결코 빌드될 수 없으므로 오류로 표시됩니다.
이는 빌드의 Release별 검증에 대응하는 카탈로그 전체 단위의 검사로, 어떤 Release가 손상된 카탈로그 엔터티에 도달하기 전에 그 엔터티가 드러나도록 하기 위한 곳입니다. 불러올 수 없는 Aggrega 문서, 그리고 스키마 필러 위반, 해석할 수 없거나 유효하지 않은 라이브러리, extends 해석 실패, 문법이 거부하는 선언된 선택자, 위치 충돌, 입력 종류 기능 오류가 하나라도 있으면 명시적으로 중단합니다. 스키마 필러 중복 및 extend 시 좁히기(narrowing) 결과, 그리고 Component나 Feature가 스키마 콘텐츠에 인라인으로 작성한 각 x-aggrega-* 키워드는 종료 코드를 바꾸지 않는 권고성 notice: 줄입니다.
불러올 수 없는 Aggrega 문서는 실행을 중단시킵니다. 카탈로그 디렉터리 아래의 YAML 파일은 그 줄 중 하나가 들여쓰기 없이 apiVersion:으로 시작하고 값이 aggrega.ai/로 시작하면(따옴표 유무와 관계없이) Aggrega 문서입니다. 그런 파일을 읽을 수 없거나, YAML이 구문 분석되지 않거나, kind 또는 metadata가 엔터티 엔벨로프의 형태가 아니면(예: 목록으로 작성된 metadata), 디렉터리를 모두 읽은 뒤 E0175로 실행이 중단되며, 해당하는 모든 파일을 읽기 또는 파서가 제시한 이유와 함께 명시합니다. 아무것도 검사되지 않고 catalog validation passed 줄도 출력되지 않습니다. 불러올 수는 있지만 어떤 카탈로그에도 없는 kind를 선언하는 문서(예: 철자가 틀린 Componnent, 또는 kind가 아예 없는 경우)는 같은 실행을 E0371로 중단시키며, 선언한 종류와 함께 위 파일들 옆에 명시됩니다. Manifest, Release, 그리고 Recipe가 자신의 디렉터리에서 가져오는 Workload는 건너뜁니다. 그 밖의 YAML(렌더링되기 전에는 구문 분석되지 않는 Helm 차트의 템플릿, 차트 values, 워크플로 정의 등)은 건너뜁니다.
어떤 디렉터리를 읽는지는 워크스페이스의 형태에 따라 달라집니다.
-
구성에 자체 Release 카탈로그 디렉터리가 없는 워크스페이스는 검색 스택에 대해 한 번 검증됩니다. 검색 순서는
--catalog디렉터리, 그다음workspace.catalog_dirs, 그다음 워크스페이스 루트에catalog디렉터리가 있으면 그 디렉터리입니다. -
workspace.releases아래에 Releases를 지정한 워크스페이스는 한 카탈로그의 여러 변형을 나란히 두고 각각을 자신의 Release가 읽게 할 수 있으며, 이들을 한꺼번에 불러오면 모든 변형이 하나의 카탈로그에 들어가 한 변형의 엔터티가 다른 변형의 엔터티를 가리게 됩니다. 따라서 이런 워크스페이스는 보유한 각 Release마다 그 Release가 읽는 디렉터리에 대해 한 번씩 검증되며, 모든 패스에서--catalog디렉터리가 먼저 옵니다. 구성에서 지정하지 않은 Release는 워크스페이스의 목록을 읽습니다. 각 패스는 해당 Release와 읽은 디렉터리를 밝히는 줄 아래에 보고되고, 그 뒤에 해당 패스의 결과가 이어집니다.Release release-compose.yaml reads catalog-composecatalog validation passed (schema-pillar + library + extends + oci-location)Release release-helm-synth.yaml reads catalog-helm-synthcatalog validation passed (schema-pillar + library + extends + oci-location)정확히 같은 디렉터리를 읽는 Releases는 하나의 패스를 공유하며, 그 패스는 각 Release의 이름을 밝힙니다. 아무 디렉터리도 읽지 않는 Release(항목에
catalog_dirs: []가 적힌 경우)는 검사할 것이 없다고 보고되고, 다른 패스는 평소대로 실행됩니다. 한 변형의 손상된 엔터티는 다른 변형에 대해 아무것도 알려 주지 않으므로, 앞선 패스의 결과와 관계없이 모든 패스가 보고되며, 어느 패스라도 실패하면 명령은 디렉터리가 실패한 Releases의 이름을 밝히며 실패합니다. 워크스페이스가 보유한 Releases는 그 워크스페이스의 Release 문서, 즉 워크스페이스 루트 아래 숨김 디렉터리와node_modules,vendor,dist를 제외한 어디에든 있는,kind가Release인 YAML 파일입니다.
어느 패스에서도 읽을 것이 없는 실행은 깨끗한 카탈로그로 보고되지 않고 거부됩니다. 엔터티를 catalog/ 아래에 두거나, --catalog를 전달하거나, workspace.catalog_dirs를 설정하십시오. Releases를 지정한 워크스페이스라면 workspace.releases 아래 Release 자체의 catalog_dirs를 설정하십시오. 현재 작업 디렉터리를 암묵적으로 열거하지 않으므로 관련 없는 트리를 끌어오는 일이 없습니다.
aggrega mcp의 validate 도구에 전체 카탈로그를 요청하면 같은 패스들을 검증합니다. Releases를 지정한 워크스페이스에서는 그 응답이 전체에 대한 판정과 함께 각 패스를 passes 아래에 담습니다. 여기에는 해당 Releases, 읽은 디렉터리, 그 패스 자체의 판정이 포함됩니다.
아티팩트 캐시에만 있는 라이브러리
아티팩트 캐시에는 가져오기가 넣어 둔 것이 보관되며, 캐시된 SchemaLibrary는 Release의 lockfile에 있는 항목이 그 다이제스트를 보증하는 경우에만 카탈로그 콘텐츠로 간주됩니다. 캐시란 무엇이고 무엇이 아닌가를 참조하십시오. $ref:가 아무것에도 해석되지 않는데, 어떤 lockfile 항목도 고정하지 않고 검사가 읽는 어떤 카탈로그 디렉터리도 제공하지 않는 라이브러리를 캐시가 보유하고 있으면, 보고서 뒤에 remediation: 줄이 이어지며 그러한 각 라이브러리와 실패한 범위에 맞는 조치를 알려 줍니다:
- 인수가 없을 때, 그리고
--release지정 여부와 관계없이 엔티티 경로가 주어졌을 때, validate는 카탈로그 디렉터리에서만 라이브러리를 읽고 lockfile 항목을 통해서는 결코 읽지 않으므로, 기록된 항목이 있어도 판정은 바뀌지 않습니다. 이 줄은 그 사실을 알리고, 카탈로그 디렉터리 아래에 라이브러리를 작성하거나,aggrega pull --release <release>를 실행한 뒤aggrega validate --release <release>를 실행하도록 안내합니다. 후자는 lockfile이 고정한 라이브러리를 기준으로 Release를 검사합니다. --release만 주었을 때, validate는 Release의 lockfile을 읽으므로, 이 줄은 라이브러리를 해석하고 그 항목을 기록하는aggrega pull --release <release>, 또는 카탈로그 디렉터리 아래에 라이브러리를 작성하는 방법을 안내합니다.
이 줄은 판정도 종료 코드도 바꾸지 않습니다.
선언된 선택자
Component나 Feature는 레이블 선택자로 종속성 소켓에 무엇을 배선할 수 있는지, 첨부 슬롯을 무엇으로 채울 수 있는지를 제한합니다. 즉 각 spec.usesSchema 항목과 각 spec.featuresSchema 항목의 selector:, 그리고 Component에서는 소켓이 자체 featuresSchema 아래에 선언하는 각 슬롯의 selector:입니다. 빌드는 무언가가 선택자에 도달하는 곳, 즉 소켓을 통해 그려진 에지나 슬롯을 채우는 첨부가 있는 곳에서만 선택자를 읽습니다. 따라서 카탈로그 전체 범위와 단일 엔터티 범위는 소켓에 무언가가 배선되었는지나 슬롯이 채워졌는지와 관계없이 Component나 Feature 문서가 선언하는 모든 선택자를 읽으며, 문법이 거부하는 선택자(닫는 괄호가 빠진 값 목록, 중복된 쉼표, =이나 !를 포함한 키)가 있으면 검사가 실패합니다. 이 문법은 문자열 문법에서 설명하는 것입니다.
이 거부는 빌드가 같은 선택자에 도달했을 때 보고하는 것과 같으며, 코드와 문구도 같습니다. 소켓의 선택자에는 E0007, 슬롯의 선택자에는 E0008이 쓰이며, 선택자, 그것을 선언하는 소켓 또는 슬롯, 문법이 그것을 읽을 수 없었던 이유를 제시합니다. 이는 엔터티의 파일에 카탈로그 결함으로 기록됩니다:
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. (선택자 위반: 소켓에 선언된 선택자를 평가할 수 없습니다. 컴포넌트 유형의 usesSchema에서 소켓 선언의 선택자를 수정하십시오.)
각 문서는 작성자가 쓴 그대로 읽히므로, 기본 엔터티가 선언하는 선택자는 그것을 확장하는 엔터티마다 한 번씩이 아니라 기본 엔터티 자체의 파일에 대해 한 번 보고됩니다. Feature의 appliesTo와 appliesToAnyOf는 여기서 읽지 않습니다. 이들은 그 Feature의 첨부가 평가되는 곳에서 읽힙니다.
카탈로그 전체 범위는 거부된 각 선택자를 각각의 selector: 줄에 보고하고 그 개수와 함께 실패합니다. 단일 엔터티 범위는 이를 형태 단계의 실패로 보고하는데, 이는 엔터티 경로 옆에 --release가 있든 없든 마찬가지입니다. 그 형식은 Release의 조건으로 실행되는 단일 엔터티 범위이기 때문입니다(Release의 조건으로 엔터티 검사하기 참조). Release의 종속성 클로저를 검증하는 단독 --release와 빌드는 에지나 슬롯 채우기가 도달하는 곳에서만 선택자를 읽고 그곳에서 중단합니다.
Release 범위의 정확성(--release)
aggrega validate --release <release-path>는 카탈로그 전체나 엔터티 하나가 아니라, 단일 Release의 해석된 의존성이 도달하는 엔터티만 정확히 검증합니다. 이 명령은 빌드가 사용하는 것과 같은 메커니즘으로 클로저를 계산하므로, 검사하는 엔터티는 해당 Release를 빌드할 때 해석될 엔터티와 정확히 같습니다. 그리고 그 클로저에 대해 다음을 수행합니다.
- 클로저 범위의
extends체인을 해석하며, 해석 오류가 있으면 실패합니다. - 해석된 각 엔터티의 스키마 필러를 (클로저 범위에서) 검증하며, 스키마 필러 오류가 있으면 실패합니다.
- 빌드가 실행하는 것과 같은 렌더링 전 값 적합성 검사를 실행합니다. Release의 parameters를 작성된 값에 해석해 넣고(따라서
{{ .parameters.* }}값은 템플릿이 아니라 해석된 상태로 검사됩니다) 그 결과를 클로저의 합성된 스키마에 대해 검증하며,extends를 사용하는 엔터티의 경우 합성된 부모+자식 스키마에 대한 적합성도 검사합니다. 스키마를 위반하는 값은 0이 아닌 종료 코드로 실패합니다. - Release가 해석한 값에 대해 모든 Recipe 및 FeatureRecipe 어서션을, 빌드가 렌더링 전에 평가하는 것과 같이 평가합니다. 각 컴포넌트의 Recipe는 Manifest가 매핑하는 대로 바인딩되고, 그
locals와provides가 해석되며, 처음 실패하는 어서션 —fail을 호출하는 어서션, 또는 템플릿이 찾지 못한 키에서 멈추는 어서션 — 은 빌드가 중단될 때와 같은 조건과 문장으로 검증을 실패시킵니다. 평가할 수 없는locals또는provides템플릿도 빌드를 실패시키듯 검증을 실패시킵니다. 각 Recipe가 렌더링에 사용하는 프로바이더에게는, 빌드가 묻는 것과 같이, 그 컴포넌트의 리소스에 붙이는 이름을 묻습니다. Recipe의provides가 그 이름을 읽을 수 있기 때문입니다. 아무것도 렌더링되지 않습니다. 이 어서션들은 위의 어떤 것도 이미 실패하지 않은 경우에만 평가되므로, Release는 빌드가 중단될 가장 이른 결함을 보고합니다; - 스키마 필러 중첩 및 extend 시 좁히기 결과를 종료 코드를 바꾸지 않는 정보성
notice:줄로 표시합니다; - 읽어 들이는 엔터티가 스키마 콘텐츠에 인라인으로 작성한 각
x-aggrega-*키워드를 빌드가 표시하는 것과 같이 엔터티당 한 번warning:줄로 표시합니다. 이것 역시 종료 코드를 바꾸지 않습니다.
이로써 --release는 진정한 빌드 전 검사가 됩니다. 빌드가 거부할 것을 빌드 전에 잡아냅니다. 즉 렌더링을 뺀 빌드의 의존성 검증입니다. 렌더링을 실행하지 않으며 네트워크 풀도 일으키지 않습니다. 클로저는 로컬 카탈로그(그리고 있는 경우 Release의 lockfile 고정값)에서 해석되며, lockfile이 필요한 레지스트리 고정 의존성 집합은 가져오는 대신 있는 그대로 해석 불가능한 참조 오류를 표시합니다. 좁히기는 조언으로 표시될 뿐 강제되지 않습니다.
Release가 해석되는 결과와 더 이상 일치하지 않는 lockfile은 aggrega build가 출력하는 중단으로 검증을 거부합니다. Release 옆에 lockfile이 있으면, --release는 Release의 종속성이 해석되는 즉시, 위의 어떤 검사보다도 먼저, 빌드가 렌더링 전에 실행하는 드리프트 비교로 그 lockfile을 Release가 해석되는 결과와 대조합니다. 고정된 엔터티, 라이브러리, 플러그인 또는 Release 파일 자체가 lockfile에서 드리프트했다면 검증은 빌드의 E0130 거부(드리프트한 모든 항목과 이를 해소하는 aggrega pull --release <release>)와 0이 아닌 종료 코드로 중단되므로, 검증이 빌드가 드리프트로 거부하는 lockfile을 그냥 넘기는 일은 없습니다. 인수가 없을 때와 엔터티 경로를 지정했을 때 validate는 lockfile에 구속되지 않습니다. 전체 카탈로그 검사는 extends 부모를 찾기 위해서만 lockfile의 고정 항목을 읽고, 단일 엔터티 검사는 lockfile을 읽지 않습니다.
빌드가 실행하는 것과 같은 검사를 실행하므로, 연결된 게이트 플러그인도 똑같이 실행합니다. 따라서 빌드와 같은 신뢰된 플러그인 식별 기록을 따릅니다. 수락 또는 거부 판정을 반환하는 플러그인을 연결한 워크스페이스는 Release 옆에 플러그인 신뢰 기록을 두며, --release는 그 플러그인들이 실행되기 전에 구성을 이 기록과 비교합니다. 기록된 게이트를 구성이 더 이상 연결하지 않으면 검증이 중단되고, aggrega pull이 채우는 캐시에서 해석된 플러그인의 아티팩트가 기록된 것과 다르면 실행되지 않고 거부됩니다. 아무것도 기록하지 않은 워크스페이스에는 기록이 없으며, 이는 그 비교에 아무런 영향을 주지 않습니다. --release는 또한 Release가 의존하는 대상에 대해 기록된 모든 철회를 표준 오류에 deprecation: 줄로, aggrega build가 출력하는 것과 같은 문구로 알립니다. lockfile이 고정된 참조에 대해 기록한 표시와 신뢰 기록이 판정 역할로 연결된 플러그인에 대해 기록한 표시 모두 마찬가지입니다. 철회는 판정도 종료 코드도 바꾸지 않으며, 존재하지만 읽을 수 없는 신뢰 기록은 아무것도 기록하지 않은 기록처럼 통과되지 않고 검증을 중단시킵니다.
캐시에서 읽은 플러그인은 로드되는 시점에, 빌드에서와 마찬가지로 해당 항목이 기록한 서명도 따릅니다. 항목이 검증된 서명을 기록한 경우, 그 사실이 가리키는 캐시 내 서명 자료를 다시 검사하며, 자료가 없거나 다른 플러그인은 거부됩니다. 자료가 읽은 플러그인이 아닌 다른 플러그인을 위해 만들어진 경우도 서명 요구 사항과 관계없이 거부되는데, 이는 다른 항목에서 signature를 복사했을 때의 모습입니다. 워크스페이스의 신뢰 구성이 서명을 요구하는 경우, 캐시에서 읽은 플러그인 중 항목에 서명이 기록되지 않았거나 기록에 해당 항목이 없는 플러그인(기록이 삭제된 경우 포함)도 거부됩니다. 이는 aggrega pull이 서명되지 않은 플러그인을 거부하게 하는 것과 같은 설정에 따르므로, skip_signature_verification과 advisory 레지스트리는 실행을 허용합니다. 거부되면 검증이 실패하고 진단에 보고되며, 해당 플러그인과 aggrega pull --release <release>를 명시합니다. 이 명령은 레지스트리에서 서명을 검증하고 기록하며, 서명이 가리키는 번들을 캐시하고, 다이제스트와 더 이상 일치하지 않는 캐시 사본을 다시 씁니다. 카탈로그 디렉터리 중 하나에서 제공되거나 컴파일러 바이너리 내부 사본에서 제공되는 플러그인은 이 요구 사항을 따르지 않습니다. 나머지 두 범위는 이 중 어느 것도 따르지 않습니다. 이 범위들은 워크스페이스의 플러그인 연결을 읽지 않으므로 그런 플러그인이 실행되지 않습니다.
그래프를 판정하는 대신 변경하는 플러그인에도 마찬가지입니다. label-transform 또는 annotation-transform 연결은 렌더링될 출력의 형태를 결정하므로, lockfile은 그 식별 정보와 읽는 소스 파일을 모두 고정합니다. 그리고 --release는 빌드와 같은 방식으로 이 연결을 실행합니다. lockfile에서 재구성하고, 각각을 기록된 다이제스트에 맞추며, 디스크의 파일 대신 lockfile이 담고 있는 소스 내용을 읽습니다. 미리 알아 두면 좋은 두 가지 결과가 있습니다.
.aggrega-config.yaml에 변환 플러그인을 연결해도 풀하기 전까지는--release의 동작이 바뀌지 않습니다. 이는 빌드가 따르는 것과 같은 규칙이며 이유도 같습니다. 연결 집합은 바이트를 결정하는 입력이므로, 편집되는 순간이 아니라 풀 시점에 채택됩니다.- 바이트가 lockfile에 기록된 다이제스트와 더 이상 일치하지 않는 캐시된 플러그인은 거부됩니다. 빌드 중과 정확히 같습니다.
Release에 lockfile이 없어도 --release는 검증을 수행합니다. 거부하는 대신 플러그인의 식별 정보를 확인할 수 없었다고 경고하고 실행할 명령을 알려 줍니다. 경고를 참조하십시오.
컴파일된 그래프 돌려받기
--ir-graph는 이 검증이 해석한 그래프를 판정 줄보다 앞서 표준 출력에 JSON으로 씁니다. 이 플래그는 부가적입니다. 같은 검사가 실행되고, 같은 진단이 기록되며, 종료 코드도 플래그가 없을 때와 같습니다. 돌려받는 그래프는 검증이 수행된 바로 그 그래프이므로, 판정이 보고하는 것과 다른 해석을 나타낼 수 없습니다.
이 플래그는 이 범위에만 적용됩니다. 전체 카탈로그 범위와 단일 엔터티 범위는 Release가 아니라 합성된 하네스를 구동하며 그래프를 해석하지 않으므로, 다른 곳에서 요청하면 조용히 무시되지 않고 거부됩니다. 그래프가 해석되기 전에 실행이 멈추면 표준 출력에는 아무것도 기록되지 않으며, 명령 자체의 진단이 무엇 때문에 멈췄는지 알려 줍니다.
옆에 있는 플래그에 유의하십시오. --response-format은 이 명령 자체의 보고서를 얼마나 기록할지(detailed 또는 concise) 설정하고, --ir-graph는 그 보고서 옆에 두 번째 문서를 요청합니다. 하나는 분량이고 다른 하나는 대상이며, 어느 쪽도 판정을 바꾸지 않습니다.
작성자가 민감하다고 선언한 값은 aggrega inspect에서 설명하는 구조화된 형식으로 그래프에서 제외됩니다. 소비하는 컴포넌트의 소켓이 리프를 민감하다고 선언한 경우에는 연결의 values와 infra도 제외 대상입니다. --ir-graph와 함께 --unredacted를 주면 aggrega inspect --unredacted가 명시하는 조건에 따라 그 값을 대신 출력합니다. 이 플래그는 그래프에만 적용되고 이 명령이 기록하는 다른 어떤 것에도 적용되지 않으며, 출력이 전달되는 곳에는 그 값이 평문으로 담깁니다. --ir-graph 없이 전달하면 드러낼 것이 없으므로 거부됩니다.
단일 엔터티 정확성(엔터티 경로)
aggrega validate <entity-path>는 카탈로그 엔터티 파일 하나를 검사합니다. 단계별 검사 집합을 적용하며, 처음으로 차단 실패가 발생하면 중단하므로 스키마 오류는 카탈로그 작업 전에 분명하게 드러납니다.
- 자리 표시자(모든 종류) — 종류가 요구하는 값인데 파일이 빈 문자열로 남겨 둔 값입니다. 다른 검사보다 먼저 모두 한꺼번에 보고되며, 각각 무엇을 받는지 함께 표시됩니다. 아직 채워야 할 자리 표시자를 참조하십시오.
- 스키마 엔벨로프(모든 종류) — 카탈로그 로더가 각 파싱 경계에서 실행하는 것과 정확히 같은 엔터티별 JSON Schema 검사입니다.
- 형태(모든 종류) — 종류별 구조 검증입니다. Component나 Feature의 경우 파일이 종속성 소켓이나 첨부 슬롯에 선언하는 모든 레이블 선택자를 선택자 문법에 따라 읽는 것이 포함됩니다. 선언된 선택자를 참조하십시오.
- 필러 구조(Component 및 Feature) —
spec.schema:필러 검사로, 문서 간$ref확장에 카탈로그의 SchemaLibraries를 사용합니다.
Component 또는 Feature는 여기서 끝납니다. 스키마 엔벨로프, 형태, 필러 구조입니다. 단독 Component에는 격리하여 렌더링할 작성된 values나 infra가 없으므로 렌더링할 것이 없으며, 그 정확성은 스키마 및 필러 단계로 완전히 다루어집니다. 스키마 콘텐츠에 인라인으로 작성된 각 x-aggrega-* 키워드는 표준 오류의 권고성 메모 가운데 warning: 줄로 보고되며, 키워드, 그 위치, 대신 작성할 선언적 테이블을 알려 줍니다. 판정이나 종료 코드는 바꾸지 않습니다.
Recipe는 추가로 격리 상태에서 렌더링됩니다. 이는 단일 엔터티 정확성의 한 측면일 뿐 핵심은 아닙니다. 스키마 및 형태 단계를 통과한 후 validate는 카탈로그에서 Recipe의 implements Component를 확인하고, 검사 대상 Recipe에 바인딩된 해당 Component의 단일 인스턴스를 중심으로 최소한의 Aggregate, Manifest, Release를 합성한 뒤, 그 위에서 실제 컴파일 파이프라인을 구동합니다. 먼저 확인 및 가드(렌더링 생략)를 수행하고, 이어서 격리된 출력을 실제로 렌더링합니다. 기본값이 없는 각 필수 값과 각 필수 infra 필드는 선언된 형식의 자리 표시자로 채워지며(값은 합성된 Aggregate에, infra는 합성된 Release에), 그 밖의 모든 값과 infra 필드는 리졸버를 통해 스키마 기본값을 받습니다. Release는 인스턴스를 합성된 기본 경계로 라우팅하며, values:를 선언하지 않고 Aggregate가 선언하지 않은 컴퓨팅도 선언하지 않습니다. 자리 표시자는 필드 자체에 선언된 제약 조건이 받아들이는 값입니다. 상수 또는 enum이 나열하는 첫 번째 값, 범위 내의 숫자, 길이와 format에 맞는 문자열, pattern이 요구하는 경우의 시맨틱 버전, 요구되는 만큼의 목록 항목, 그리고 객체가 요구하는 모든 속성입니다. 그 밖의 pattern, validate: 또는 when: 조건, 스키마 조합, 목록이 어떤 항목을 담는지에 대한 제약은 참조되지 않으므로, 이에 의존하는 필드는 여전히 자리 표시자를 거부할 수 있습니다. 이 경우 validate는 그 거부를 스키마 자체의 표현으로 보고합니다. 렌더링된 아티팩트가 출력되므로, 작성자는 엔터티를 전체 Aggregate에 연결하기 전에 격리된 출력을 볼 수 있습니다. 단일 엔터티 하네스는 그 필수 필드만 채우고 연결을 구성하지 않으며 Feature를 연결하지 않으므로, 연결이나 연결된 Feature만 전달하는 값을 템플릿이 읽는 Recipe는 격리 상태에서 렌더링할 수 없습니다. validate는 이러한 렌더링을 실패가 아니라 시도되지 않음으로 보고합니다. fail을 호출하는 어서션은 검사를 실패시키지 않고 경고로 보고됩니다. 실패한 어서션은 경고입니다를 참조하십시오. 그 밖의 이유로 중단된 렌더링은 완료되지 않은 것이며, validate는 중단 원인을 밝히는 문장까지 포함한 기본 렌더링 진단과 함께 이를 보고합니다.
source:를 가져와야 하는 Recipe는 전혀 렌더링되지 않으며, 연결이나 연결된 Feature만 제공하는 값을 읽다가 렌더링이 중단된 Recipe는 그 렌더링이 보류됩니다. 아래의 단일 엔터티 정확성이 검사하지 않는 것을 참조하십시오.
FeatureRecipe는 스키마와 형태가 검사되며 렌더링은 생략됩니다. FeatureRecipe는 호스트 컴포넌트에 연결되었을 때만 렌더링되며, 임의의 Feature에 대해 가드를 통과하는 호스트를 합성하는 것은 시도하지 않기 때문입니다.
Release 기준으로 엔터티 검사하기
워크스페이스는 각 Release에 고유한 카탈로그 디렉터리를 지정할 수 있으며(Release에 고유한 카탈로그 디렉터리 지정하기 참조), 이를 통해 Release마다 카탈로그 변형 하나씩을 나란히 유지할 수 있습니다. 엔터티 경로만 단독으로 지정하면 워크스페이스 자체의 카탈로그 디렉터리를 대상으로 검사되며, 이때 그러한 변형 중 하나를 가리키는 참조(Recipe가 구현하는 Component, 필러가 참조하는 SchemaLibrary)는 찾을 수 없습니다. 엔터티 경로와 함께 --release를 지정하면 같은 검사가 해당 Release 기준으로 실행됩니다. 엔터티의 참조는 워크스페이스 구성이 해당 Release에 지정한 카탈로그 디렉터리(지정된 --catalog가 앞에 추가됨)를 통해 확인되며, 이는 해당 Release의 빌드가 읽는 디렉터리입니다.
MariaDB + Adminer 예제는 이러한 변형 네 개를 유지합니다. synth 변형의 Component는 synth 및 chart 변형만 가진 SchemaLibrary에서 스토리지 설정을 가져오므로, 그것으로 빌드하는 Release 기준으로 검증됩니다.
$ aggrega validate catalog-helm-synth/component/mariadb.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/component/mariadb.yamlKind: ComponentSchema: validPillars: valid그리고 디렉터리에 해당 라이브러리가 없는 Release 기준(--release release-compose.yaml, 또는 고유한 카탈로그 디렉터리를 나열하지 않는 워크스페이스에서 --release를 아예 지정하지 않은 경우)에서는 확인할 수 없는 라이브러리를 명시하며 실패합니다.
Recipe도 같은 방식으로 검사됩니다. synth 변형의 Recipe는 core/datastore/mariadb를 구현하는데, 워크스페이스 자체의 카탈로그 디렉터리에는 이것이 없으므로 단독으로 지정하면 render: implements target "core/datastore/mariadb" not found in catalog로 실패합니다. 그것으로 빌드하는 Release를 지정하면 해당 Release의 Component를 확인하고 격리 상태에서 렌더링합니다.
$ aggrega validate catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yaml --release release-helm-synth.yamlEntity: catalog-helm-synth/recipe/helm/mariadb-synth/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: 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: validRender: 3 artifact(s)이어서 렌더링된 아티팩트 세 개가 출력됩니다. 이 예제의 모든 변형은 core/datastore/mariadb를 선언하므로, Recipe는 네 개의 Releases 각각을 기준으로 검증됩니다. 카탈로그 디렉터리에 그러한 Component가 없는 Release 기준에서는 --release를 지정하지 않았을 때와 마찬가지로 대상을 명시하며 실패합니다. Attachments: 줄은 필수 연결 슬롯 또는 존재 의무에서 설명합니다.
이것은 여전히 단일 엔터티 범위입니다. 검사, 보고서, 종료 코드는 이 섹션에서 설명하는 것이며(문법이 거부하는 소켓 또는 슬롯 선택자를 가진 Component나 Feature는 --release 없이 실행할 때와 똑같이 여기서 실패합니다. 선언된 선택자 참조), 클로저는 검증되지 않습니다. --release는 엔터티의 참조를 읽어 들일 카탈로그 디렉터리를 가진 Release를 지정할 뿐 검사할 클로저를 지정하지 않으며, 이 때문에 엔터티 경로와 함께 --ir-graph를 지정하면 거부됩니다. 존재하지 않는 파일이나 디렉터리를 지정하는 --release는 검사 전에 거부됩니다.
워크스페이스 구성이 나열하는 디렉터리가 디렉터리가 아닌 경우(예를 들어 그 위치에 아무것도 존재하지 않는 경우), 해당 Release에 대해서든 --release가 지정되지 않았을 때 워크스페이스에 대해서든, 아무것도 검사하기 전에 거부되며, 이는 그 카탈로그를 읽는 모든 명령이 거부하는 것과 같습니다(로컬 엔터티를 읽는 위치). 거부 메시지는 항목, 그것을 나열하는 구성 파일과 줄, 그리고 해당 설정을 명시하며, 판정은 내려지지 않습니다. aggrega serve를 통한 편집기의 엔터티 검사는 같은 거부를 엔터티 파일의 유일한 항목으로 오류 수준에서 표시하며, aggrega mcp의 validate 도구는 이를 이유로 호출을 거부합니다.
아직 채워야 할 플레이스홀더
종류가 요구하는 값을 파일이 빈 문자열로 남겨 둔 것이 플레이스홀더이며, validate는 이를 다른 무엇보다 먼저 보고합니다. aggrega scaffold로 초안을 작성한 문서에는 해당 종류가 사용자만 제공할 수 있는 값을 필요로 하는 곳마다 플레이스홀더가 들어 있으므로, 어떤 값이 남아 있는지 여기서 알 수 있습니다. 다음은 버전만 채운 FeatureRecipe 초안입니다:
Entity: my-feature-recipe.yamlKind: FeatureRecipe2 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).파일의 모든 플레이스홀더가 문서 순서대로 한꺼번에, 줄과 열, 그리고 받는 값과 함께 표시됩니다. 받는 값은 종류 자체의 스키마에서 읽습니다. 스키마가 값을 나열하는 경우 허용되는 값, 스키마가 시맨틱 버전을 요구하는 경우 1.0.0 같은 시맨틱 버전, 그 밖의 경우에는 스키마가 해당 필드를 설명하는 첫 문장입니다.
어떤 값이 해당되는지도 스키마에서 읽습니다. 종류가 문서 최상위에서 요구하거나 종류가 역시 요구하는 객체 안에서 요구하는 값을 파일이 빈 문자열로 설정하면 해당됩니다. 파일이 아예 생략한 키는 스키마 검사가 누락된 속성으로 보고합니다. 비어 있는 선택 필드는 플레이스홀더가 아니며, 직접 작성하기로 한 목록이나 맵 안에서만 요구되는 필드도 마찬가지입니다. 스키마 자체가 필드가 허용하는 값 중에 빈 문자열을 나열하는 경우, 빈 값은 플레이스홀더가 아니라 값입니다.
스키마가 빈 값을 받아들이는 경우에도 값은 채워야 합니다. 스키마는 Recipe나 FeatureRecipe의 capability와 implements에 빈 문자열을 허용하지만, 빈 값은 어떤 provider도, 어떤 타입도 지정하지 않으므로 validate는 두 값 모두 다른 것과 마찬가지로 플레이스홀더로 보고합니다. 스키마 검사도 같은 파일을 거부하는 경우(빈 버전, 값이 없는 타입 레이블)에는 aggrega scaffold의 예시처럼 보고에 해당 검사의 코드 E0215가 포함됩니다. 위의 경우처럼 스키마 검사가 받아들이면 보고에는 코드가 없습니다. 같은 파일에서 빈 값에 관한 것이 아닌 발견 사항은 여전히 스키마 검사 자체의 문구로 목록 앞에 보고됩니다.
이 해석은 엔터티 경로 옆에 --release가 있든 없든 단일 엔터티 검증에만 적용됩니다. 같은 문서를 만나는 전체 카탈로그 실행은 스키마 검사가 보고하는 내용을 보고하므로, 카탈로그 디렉터리 안에 implements가 비어 있는 FeatureRecipe가 있어도 통과합니다. Release 범위와 aggrega build도 이 해석을 적용하지 않습니다.
이 범위가 받지 않는 종류
단일 엔터티 검증은 Component, Feature, Recipe, FeatureRecipe, Workload, Plugin을 받습니다. 그 밖의 종류의 파일은 거부되며, 거부 메시지는 받는 종류와, 엔터티 종류인 경우 해당 종류의 문서를 실제로 검사하는 범위를 알려 줍니다:
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전체 카탈로그 범위는 인수 없는 실행이고, Release 범위는 엔터티 경로 없는 --release입니다:
| 종류 | 검사 주체 |
|---|---|
| Aggregate | 카탈로그 디렉터리에 있을 때 전체 카탈로그 실행, 이를 배포하는 Release에 대한 --release |
| Manifest | 이를 지정하는 Release에 대한 --release |
| Release | --release <release-path> |
| SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary | 카탈로그 디렉터리에 있을 때 전체 카탈로그 실행 |
전체 카탈로그 실행은 구성된 카탈로그 디렉터리 안에 있는 것만 읽으므로, 워크스페이스 루트에 Release와 나란히 둔 Aggregate는 해당 Release에 대한 --release로 검사합니다.
실패한 어서션은 경고입니다
fail을 호출하는 어서션은 Recipe가 선언한 것이든 그 implements Component가 선언한 것이든 경고로 보고되며, 검사는 이로 인해 실패하지 않습니다. 합성된 Release에는 실제 Release가 설정하는 값 대신 플레이스홀더와 스키마 기본값이 들어 있으므로, 이미지나 선행 조건의 존재 같은 그런 값에 대한 어서션은 Recipe가 올바른지와 관계없이 여기서 실패하며, validate는 Release를 기다리는 어서션과 잘못된 어서션을 구별할 수 없습니다. 어서션에 대한 판정은 항상 Release가 있는 빌드에 맡깁니다.
경고는 모든 권고 메시지 뒤에 warning:으로 시작하여 표준 오류에 기록됩니다. 경고에는 어서션의 전체 메시지(엔터티, 인스턴스, 어서션 이름, 작성자가 쓴 문장)가 담기며, 마지막에 한 문장이 더 붙습니다:
A Release must satisfy this assertion before a build of it can pass.표준 출력의 보고는 실행이 어디서 멈췄는지 알려 주며, 명령은 0으로 종료합니다. Recipe 자체의 어서션은 렌더링을 멈추므로 보고는 Resolution: valid 뒤에 Render: stopped on a failed assertion, reported as a warning으로 표시됩니다. Component의 어서션은 렌더링 전에 평가되므로 보고는 Resolution: stopped on a failed assertion, reported as a warning, 그 뒤에 Render: not attempted (the run stopped on that assertion)로 표시됩니다. 어느 경우든 아무것도 렌더링되지 않으므로 아티팩트는 출력되지 않습니다.
fail을 호출하는 어서션만 경고입니다. 읽으려는 키를 찾지 못해 멈추거나 파싱되지 않는 어서션은 실패한 어서션이 아니라 어서션 자체 텍스트의 결함이며, 다른 중단과 똑같이 판정됩니다. 그 밖의 모든 결함은 그대로 검사의 판정이 됩니다.
어서션을 충족하지 않는 Release의 aggrega build는 항상 그렇듯 어서션 이름과 작성자의 문장을 담은 오류와 함께 중단되며, 그 Release에 대한 aggrega validate --release도 같은 오류로 실패합니다. aggrega serve를 통한 에디터의 엔터티 검사도 같은 경고를 표시하며, Recipe가 어서션을 선언한 경우 어서션 자체의 키에 표시합니다. aggrega mcp의 validate 도구는 notices에 경고를 포함하여 valid: true로 응답합니다.
단일 엔터티 정확성이 검사하지 않는 것
실제 빌드의 검사 중 네 가지는 하나만의 빌드로는 할 수 없으며, validate는 확신할 수 없는 발견 사항을 보고하는 대신 각각을 검사하지 않습니다.
가져와야 하는 소스
하나의 엔터티를 검증할 때는 lockfile을 읽지 않고, 캐시를 읽거나 쓰지 않으며, 네트워크 요청도 하지 않습니다. 따라서 source:가 전송 수단(OCI 또는 HTTPS 차트 저장소, Git 저장소)을 통해 가져오는 대상을 지정하는 Recipe에는 렌더링할 인프라 코드가 없습니다. 차트나 모듈은 실행이 접근할 수 있는 어디에도 없으며, 검사 중인 파일에는 잘못이 없습니다. validate는 이를 알리고, 렌더링과 구별되는 결과로 출력한 뒤 0으로 종료합니다:
Entity: catalog/recipe/helm/openbao/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validResolution: validRender: 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.그 줄 위의 모든 항목은 검사되었고 유효한 것으로 보고됩니다. 따라서 이러한 Recipe에서 종료 코드가 의미하는 바는 렌더링된 Recipe보다 좁습니다. 스키마, 형태, 해석은 유효하지만 렌더링은 증명되지 않았으며, 보고는 둘 중 어느 것을 보고 있는지 알려 줍니다.
워크스페이스에 이미 있는 소스는 제외되지 않습니다. 상대 경로 source: ./module은 가져올 필요가 없으므로 다른 것과 마찬가지로 렌더링이 시도되며, 그 실패는 0이 아닌 종료 코드와 함께 Render: not completed in isolation으로 보고되는 실제 발견 사항입니다. 위의 줄은 가져와야 하는 소스에만 표시됩니다.
가져오는 소스를 사용하는 Recipe를 실제로 렌더링하려면 해당 Recipe가 구현하는 component를 배포하는 Release에 대해 aggrega build를 실행합니다. 빌드는 Release의 lockfile과 로컬 캐시를 통해 소스를 해석하며, 이것이 validate로는 얻을 방법이 없는 바이트를 제공합니다.
필수 uses 소켓
두 번째는 implements Component의 required: true uses 소켓이 채워져 있는지 여부입니다.
필수 소켓은 다른 컴포넌트로 향하는 에지를 연결하여 채워집니다. 이 에지는 Aggregate 자체의 uses 블록에서 오거나, Component가 선언한 소켓을 연결하는 Release에서 옵니다. 합성된 하니스는 인스턴스를 하나만 가지므로 그러한 에지가 대상으로 삼을 두 번째 컴포넌트가 없으며, 합성된 문서를 어떻게 작성하더라도 그것을 만들어 낼 수 없습니다. 피어를 만들어 낸다는 것은 하니스가 선언한 적 없는 컴퓨트를 만들어 낸다는 뜻이기 때문입니다. 따라서 validate는 검사하지 않은 소켓의 이름을 밝히고 해석과 렌더를 계속 진행합니다:
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.이 줄은 Component가 필수 소켓을 하나 이상 선언한 경우에만 나타나며, 필수 소켓만 나열합니다. 선택적 소켓은 나열되지 않습니다. 연결하지 않은 채로 두는 것은 어떤 범위에서도 문제로 보고되지 않기 때문입니다. Component가 필수 소켓을 선언하지 않은 Recipe에서는 이러한 줄이 나오지 않으며, 보고서도 달라지지 않습니다.
규칙 자체는 완화되지도 중복되지도 않습니다. 답할 수 있는 범위에서 검사될 뿐입니다. aggrega build는 Aggregate와 Release의 에지 표면 전체에 이 규칙을 온전히 적용하며, 아무것도 연결되지 않은 필수 소켓이 있으면 중단합니다. 따라서 단일 엔터티 검증을 통과한 Recipe도 그 Component가 배포될 때 필수 소켓 규칙을 만족해야 하며, 보고서는 validate가 검사한 것과 빌드가 검사할 것 사이의 차이를 말없이 남겨 두지 않고 이를 명시합니다.
필수 연결 슬롯 또는 존재 의무
세 번째는 implements Component의 required: true 연결 슬롯, 즉 그 featuresSchema가 선언하는 이름 있는 바인딩 지점이 채워져 있는지, 그리고 존재 의무가 요구하는 각 Feature 타입의 연결이 존재하는지 여부입니다.
필수 슬롯은 해당 이름으로 Feature를 연결하여 채워집니다. 이는 Aggregate 또는 Release에서, 컴포넌트에 또는 그보다 상위 범위에서 이루어지며, Recipe가 아니라 Component가 배포되는 곳에서 이루어집니다. 합성된 하니스는 Feature를 연결하지 않으므로, 하니스가 빌드하는 어떤 것도 그러한 슬롯을 채울 수 없습니다. 따라서 validate는 필수 소켓의 경우와 똑같이, 검사하지 않은 슬롯의 이름을 밝히고 해석과 렌더를 계속 진행합니다:
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.이 줄은 Component가 필수 슬롯을 하나 이상 선언한 경우에만 나타나며, 필수 슬롯만 나열합니다. Component가 필수 슬롯을 하나도 선언하지 않은 Recipe에서는 이러한 줄이 나오지 않습니다. 보류되는 것은 요구 사항뿐입니다. 슬롯의 레이블 제약과 허용된 전달 메커니즘은 선언된 대로 유지됩니다. 구문 분석되지 않는 템플릿은 여전히 실행을 실패시키며, provider가 합성할 수 없는 Workload와 같은 Recipe 자체의 결함도 마찬가지입니다. 다만 다음 절에서 설명하듯이 Recipe가 연결 또는 연결된 Feature만 제공하는 값도 읽는 경우는 예외입니다.
존재 의무, 즉 어떤 연결이 자신이 지정한 Feature 타입을 지닐 것을 요구하는 Component의 features.aggrega.ai/requiredType.<label> 어노테이션도 같은 이유로 보류됩니다. 하니스는 아무것도 연결하지 않으므로, 하니스가 빌드하는 어떤 것도 그 타입을 지닐 수 없습니다. validate는 검사하지 않은 각 의무를 레이블과 요구하는 타입으로 밝히고, 해석과 렌더를 계속 진행합니다. 표준 라이브러리의 example/compute/service가 이러한 의무를 하나 선언하므로, 그 Recipe는 렌더된 두 아티팩트에 앞서 다음을 보고합니다:
$ aggrega validate aggrega-catalog/recipe/helm/service/1.0.0/recipe.yaml --catalog aggrega-catalogEntity: aggrega-catalog/recipe/helm/service/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: 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: validRender: 2 artifact(s)선언을 평가할 수 없는 의무, 즉 뒤에 레이블이 없는 어노테이션 접두사나 Feature 타입이 아닌 값은 보류되지 않습니다. 이는 어떤 연결로도 고칠 수 없는 Component 자체의 결함이며, validate는 빌드와 마찬가지로 이를 이유로 실행을 실패시킵니다.
각 규칙은 답할 수 있는 곳에서 검사됩니다. aggrega pull, aggrega build, aggrega validate --release는 Release의 실제 연결에 대해 두 규칙을 모두 평가하며, 각각 아무것도 채우지 않은 필수 슬롯과 어떤 연결도 지니지 않은 의무 타입이 있으면 중단합니다.
연결 또는 연결된 Feature만 제공하는 값
네 번째는 연결과 연결된 Features가 템플릿이 읽는 값을 제공했을 때 Recipe가 렌더되는지 여부입니다.
Recipe의 템플릿은 연결이 .context.inject와 .context.uses 아래에 전달하는 것과, 연결된 Feature가 .features 아래에 전달하는 것을 읽습니다. 합성된 하니스는 연결을 구성하지 않고 Feature도 연결하지 않으므로, 이러한 읽기는 모두 아무것도 찾지 못합니다. .context.inject.env 아래의 읽기는 빈 전달 파이프를 만나고, .context.uses에 대한 range는 연결을 하나도 만나지 않습니다. validate는 먼저 Recipe를 렌더하며, 완료된 렌더는 평소대로 보고됩니다. 렌더가 중단되었고 Recipe의 템플릿(템플릿이 가져오는 파일과 라이브러리 항목 포함)이 이 세 가지 아래의 무언가를 읽는 경우, validate는 렌더를 시도되지 않음으로 보고하고, Recipe가 그곳에서 읽는 값의 이름을 밝히고, 렌더가 중단된 문장을 출력한 뒤 0으로 종료합니다. MariaDB + Adminer 예제의 차트 변형은 연결된 두 시크릿이 채우는 전달 파이프에서 데이터베이스 자격 증명을 읽습니다:
$ aggrega validate catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yaml --release release-helm-chart.yamlEntity: catalog-helm-chart/recipe/helm-chart/mariadb-chart/1.0.0/recipe.yamlKind: RecipeSchema: validShape: validAttachments: 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: validRender: 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아무것도 찾지 못하지만 아무것도 중단시키지 않는 읽기는 보류되지 않습니다. 완료된 렌더에서 아무것도 렌더하지 않는 .context.uses에 대한 range는 그 렌더 그대로 보고됩니다.
판단 기준은 렌더가 무엇에서 중단되었는지가 아니라 Recipe가 무엇을 읽는지이며, 여기에는 마주치기 전에 알아 둘 만한 결과가 따릅니다. 이러한 값도 읽는 Recipe에서 Recipe 자체의 결함(예를 들어 철자가 틀린 키)은 실패가 아니라 나머지와 함께 시도되지 않음으로 보고됩니다. The render stopped: 줄에는 렌더 자체의 문장이 담기므로 어느 쪽이었는지 확인할 수 있으며, Component를 배포하는 Release의 빌드가 렌더를 온전히 판정합니다.
어떤 연결이나 Feature로도 바뀌지 않으므로, Recipe가 무엇을 읽든 두 가지 결함은 여전히 실행을 실패시킵니다. 구문 분석되지 않는 템플릿, 그리고 렌더가 거부하는 참조(렌더 컨텍스트가 정의하지 않은 루트, 또는 .context.instance_idd처럼 형태가 고정된 루트 아래의 잘못 입력된 키)입니다. Recipe가 선언하고 fail을 호출하는 어서션은 Recipe가 무엇을 읽든 보류되지도 실패로 처리되지도 않습니다. 실패한 어서션이 항상 그렇듯 경고로 보고됩니다. 템플릿이 세 가지 중 어느 것도 읽지 않는 Recipe는 렌더가 완전히 판정되며, 중단된 렌더는 원인을 밝히는 문장과 함께 실패합니다.
validate 도구(aggrega mcp)는 같은 Recipe에 대해 같은 판정을 내립니다. 이렇게 제외된 렌더는 진단 항목 없이 유효한 것으로 응답하며, 위의 줄들은 진단과 함께 반환되는 텍스트에 들어 있습니다.
단일 엔터티 모드의 카탈로그 로드는 관대합니다. 카탈로그의 다른 곳에 있는 관련 없는 손상된 엔터티는 검사를 중단시키지 않고 건너뛰므로, 대상을 단독으로 검증하는 것을 결코 막지 않습니다.
건너뛴 파일은 그 때문에 사라진 Component에 대해서도 설명합니다. Recipe의 implements 대상을 찾을 수 없고 그 Component를 선언하는 건너뛴 파일이 정확히 하나일 때, 보고는 그 파일 자체의 거부, 즉 그 경로, 위반한 제약, 머리말에 있는 조건의 짧은 코드로 시작합니다. 그다음에는 그 파일이 로드 시 건너뛰어졌으므로 카탈로그가 그 파일이 선언하는 식별자 아래에 아무것도 가지고 있지 않다는 note:가 이어지고, 이어서 그 파일이 필요했던 이유로 implements target … not found in catalog 실패가 나옵니다. 그 Component를 선언하는 건너뛴 파일이 없거나 둘 이상이면, not-found 실패가 앞에 오고 건너뛴 모든 파일이 그 아래 note: catalog files skipped at load 아래에 나열됩니다. 이는 aggrega build가 건너뛴 파일에 대해 제공하는 설명이며, aggrega serve를 통한 편집기의 엔터티 검사와 aggrega mcp의 validate 도구도 같은 설명을 제공합니다. 아무것도 건너뛰지 않은 카탈로그는 평소와 똑같이 보고합니다.
validate와 lint, build의 관계
세 명령은 서로 다른 세 가지 질문을 다룹니다.
aggrega validate— 이것이 올바른가? 스키마, 필러, 참조,extends, 입력 종류 기능, 격리된 렌더를 다룹니다. 런타임 상태를 읽지 않으며 아티팩트를 내보내지 않습니다.aggrega lint— 이것이 카탈로그 게시 관례를 따르는가? 명명, 카테고리 디렉터리 정렬, 어노테이션 접두사, 버전 증가 크기, 그 밖의 선택적 게시 규율을 다룹니다. Lint는 validate의 세 가지 범위를 그대로 따르지만 정확성은 결코 검사하지 않습니다.aggrega build— 완전한 배포를 컴파일합니다. Build에는 완전한 Aggregate + Manifest + Release 클로저가 필요하며, 프로바이더 네이티브 아티팩트를 내보냅니다. 컴파일 과정의 일부로 자체 의존성 클로저를 검증한 다음 렌더링합니다.aggrega validate --release는 렌더 없이 그 의존성 검증만 수행하는 것이고, 단일 엔터티 validate는 완전한 Aggregate 없이 단일 Recipe의 렌더를 격리합니다.
예시
카탈로그 전체를 검증합니다:
aggrega validate --catalog ./catalog빌드하기 전에 하나의 Release가 의존하는 대상만 정확히 검증합니다:
aggrega validate --release releases/production.yaml하나의 엔터티를 검증하고, Recipe의 경우 격리된 렌더링 출력을 확인합니다:
aggrega validate core/datastore/postgres/recipes/helm.yaml워크스페이스 구성이 자체 카탈로그 디렉터리를 지정한 Release의 관점에서 하나의 엔터티를 검증합니다:
aggrega validate core/datastore/postgres/recipes/helm.yaml --release releases/production.yaml참고 항목
- ./aggrega-lint.md — 동일한 세 가지 범위에 걸쳐 관례를 다루는 대응 명령입니다.
- ./aggrega-build.md — 완전한 Aggregate + Release를 아티팩트로 컴파일하며, 컴파일 과정의 일부로 그 의존성 클로저를 검증합니다.
- ./aggrega-inspect.md — 렌더링으로 진행하지 않고 해석 후의 IR 그래프를 조회합니다.
- ../errors/warnings.md — validate가
notice:줄로 표시하는 권고 사항입니다.
개요
aggrega validate [entity-path] [flags]설명
Check CORRECTNESS across three symmetric scopes.
With no argument, validate checks the WHOLE catalog: schema-pillarstructure, cross-document library resolution, extends chains, and providerinput-kind capabilities, over every catalog entity. Where the workspaceconfiguration gives its Releases catalog directories of their own underworkspace.releases, it checks the catalog 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, validate checks the entities a Release's dependency closurereaches: closure-scoped pillars, extends, and pre-render authored-valueconformance — the same correctness a build applies, scoped to that Release.It then evaluates the Recipe and FeatureRecipe assertions against the valuesthat Release resolves to, as a build does before it renders, and reports afailing assertion as a build reports it. Nothing is rendered.
With an entity path, validate checks one entity file. The kinds it acceptsas a single-entity target are Component, Feature, Recipe, FeatureRecipe,Workload and Plugin. A value the kind requires that the file leaves empty isreported first, as a placeholder still owed: every one is named at once, withwhat it takes, read from the kind's own schema. That reading is this scope'salone; 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 compileagainst a minimal generated harness, so its resolution, its guards and arender of its output are all exercised. Where that Recipe's source is onethat 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 cacheand makes no network request, so the chart or module it names is neverretrieved and there is nothing to render from. A render that stops while theRecipe's templates read what only a connection or an attached Featuresupplies — anything under .context.inject, .context.uses or .features — isreported as not attempted too: the generated harness wires no connection andattaches no Feature, so that render cannot be judged there, and a fault ofthe Recipe's own beside such a read is set aside with it. A template thatdoes not parse and a reference the render refuses still fail. An assertionthat calls fail, the Recipe's own or one its Component declares, is printedas a warning closed by a sentence saying a Release must satisfy it before abuild can pass, and does not fail the check: the generated harness sets noneof a real Release's values, so it cannot tell an assertion waiting on one fromone that is broken, and a build still halts on it. Any other kind is refused heretoday, and the refusal names the scope that checks it instead: a whole-catalogrun reaches an Aggregate and the library kinds when they sit in a catalogdirectory, and --release reaches a Release, the Manifest it names and theAggregate it deploys.
With an entity path and --release together, the entity is checked in thatRelease's terms: its references — the Component a Recipe implements, alibrary a pillar refers to — resolve through the catalog directories theworkspace configuration gives that Release rather than the workspace's own,so a workspace keeping one catalog variant per Release checks an entityagainst the variant that Release builds with. The checks are the entitypath's; no closure is validated.
The command writes nothing to disk.플래그
| 플래그 | 기본값 | 설명 |
|---|---|---|
--catalog | [] | 카탈로그 디렉터리이며 반복할 수 있습니다. 각 —catalog <dir>는 카탈로그 검색 스택의 앞에 추가됩니다(처음 일치하는 항목이 우선). 스택은 워크스페이스 catalog_dirs이거나, 워크스페이스 구성이 workspace.releases 아래에서 자체 디렉터리를 지정한 Release의 경우 해당 Release의 디렉터리이며, 워크스페이스 루트에 catalog라는 이름의 디렉터리가 있으면 그것으로 끝납니다. 비어 있게 작성된 catalog_dirs 목록은 로컬 카탈로그를 전혀 읽지 않습니다. |
--ir-graph | false | 이 명령이 이미 생성하는 모든 것에 더해, 이번 실행에서 계산한 IR 그래프를 JSON으로 stdout에도 기록합니다. 작성자가 민감하다고 선언한 값은 여기에서 제외됩니다. 대신 출력하려면 —unredacted를 전달합니다. Release를 그래프로 해석하는 유일한 범위인 —release 범위에 적용됩니다. 이 플래그는 DOCUMENT를 선택하며, —response-format은 이 명령 자체의 보고서를 얼마나 기록할지 설정합니다. 둘 다 판정이나 종료 코드에는 영향을 주지 않습니다 |
--no-unsupported-field-warnings | false | unsupported-field 경고 클래스를 표시하지 않습니다. 이는 작성한 내용 중 대상이 따를 수 없는 것에 대해 대상이 발생시키는 알림으로, 대상이 표현할 수 없는 Workload 필드(compose와 같은 충실도가 낮은 대상의 경우)나 노드의 입력 종류에 대해 대상이 처리하지 않는 aggrega.ai/ 어노테이션이 해당됩니다. 다른 렌더링 경고는 계속 표시됩니다. 표시 전용이며 렌더링된 출력은 변경하지 않습니다. 렌더링하는 유일한 범위인 엔터티 범위에 적용됩니다 |
--plugin | — | describe() 자체 보고에 대해 검증할 원시 .wasm 경로로, 게시 전 작성 검사입니다. 단독으로 사용하면 —type이 필요하며, Plugin 엔터티 인수와 함께 사용하면 바이너리를 엔터티에 선언된 유형, 기능 주장, 명령 미러, 호스트 함수 기록과 교차 검사합니다. |
--release | — | Release YAML의 경로입니다. 단독으로 사용하면 해석된 의존성 클로저 전체를 검증하고, 엔터티 인수와 함께 사용하면 해당 엔터티를 Release의 관점에서 검사하며, 그 참조는 워크스페이스 구성이 해당 Release에 지정한 카탈로그 디렉터리를 통해 해석됩니다. 상대 경로는 워크스페이스 루트가 아니라 명령을 실행하는 디렉터리를 기준으로 해석됩니다. 해당 디렉터리가 어떤 워크스페이스에도 속하지 않고 루트도 지정되지 않은 경우, 절대 경로는 Release 자체의 폴더에서 워크스페이스를 찾습니다 |
--response-format | detailed | 엔터티 인수 없이 Release의 클로저를 다루는 —release 범위의 출력량입니다. detailed(기본값)는 모든 진단과 권고 줄을 보고하고, concise는 진단 개수와 첫 번째 진단만 보고합니다. 판정과 종료 코드는 두 경우 모두 동일합니다. |
--type | — | 바이너리 전용 —plugin 검사를 위한 플러그인 유형으로, 바이너리가 자체 보고한 유형과 대조하여 확인됩니다. —plugin과 함께 사용할 때만 의미가 있으며, Plugin 엔터티가 유형을 제공하는 경우에는 생략합니다(일치하지 않는 값은 중단을 일으킵니다). |
--unredacted | false | 작성자가 민감하다고 선언한 값을 제외하지 않고 출력합니다. 그러면 출력이 도달하는 모든 곳(터미널, 파이프, 파일, 화면 녹화)에 해당 값이 평문으로 남습니다. —ir-graph가 기록하는 그래프에만 적용되므로 —ir-graph가 필요합니다 |