콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

aggrega serve

aggrega serve는 IDE 통합을 위해 Aggrega를 장기 실행되는 서비스형 컴파일러 데몬으로 실행합니다. stdin/stdout을 통해 JSON-RPC 2.0으로 통신하고 카탈로그 리졸버, 파싱 캐시, 진단 상태를 요청 간에 유지하므로, 편집기 작업은 키 입력마다 전체 카탈로그 로드 비용을 치르는 대신 1초 미만의 피드백을 받습니다.

이 데몬은 보통 직접 실행하지 않고 편집기 확장이 하위 프로세스로 생성합니다. VS Code 확장이 참조 클라이언트이며, 다른 편집기도 같은 프로토콜로 통신하여 통합할 수 있습니다.

프로토콜

와이어 프로토콜은 Content-Length 프레이밍을 사용하는 JSON-RPC 2.0이며, aggrega/ 메서드 네임스페이스 아래에 있습니다. 이는 의도적으로 Language Server Protocol이 아닙니다. Aggrega에는 LSP에 대응하는 것이 없는 도메인 작업(IR 그래프 쿼리, 캐시 무효화 신호)이 있기 때문입니다. 에디터 확장은 에디터의 LSP 요청과 이 aggrega/* 메서드 사이를 변환하며, LSP 형태의 position, range, location 값은 맞는 곳에서 재사용됩니다.

두 메서드는 aggrega/ 네임스페이스로 이름을 바꾸지 않고 프로토콜 표준 $/ 이름을 유지합니다. 둘 다 Aggrega의 의미를 담지 않는 전송 계층의 관심사이며, 이미 해당 프로토콜을 사용하는 클라이언트는 아무것도 추가하지 않고 처리할 수 있기 때문입니다. 클라이언트가 더 이상 응답을 원하지 않는 요청을 중지하는 $/cancelRequest와, 데몬이 긴 작업을 실행하는 동안 그 진행 상황을 보고하는 $/progress입니다. 둘 다 아래에서 설명합니다.

🔴 아래의 모든 요청은 작업 대상 워크스페이스의 절대 경로인 workspaceRoot를 포함하며, 이는 메서드마다 반복해서 설명하지 않습니다. 세 가지는 대상이 워크스페이스가 아니므로 포함하지 않습니다: aggrega/initialize, aggrega/getSchema, aggrega/scaffoldEntity. 다만 실행 가능한 예제를 쓰거나 나열하는 aggrega/scaffoldEntity는 워크스페이스를 지정합니다. 워크스페이스를 지정하지 않은 요청이 받는 결과는 모든 요청은 대상 워크스페이스를 지정합니다를, 푸시되는 진단이 전달되는 곳은 진단을 푸시받을 워크스페이스 선언하기를 참조하십시오.

필드별 형태는 스키마로 게시되며, 와이어 형태 레퍼런스에서 확인할 수 있습니다. 해당 페이지는 모든 메서드의 매개변수 객체, 모든 결과, 모든 알림 페이로드를 각 필드의 타입, 필수 여부, 담는 내용과 함께 설명하며, 메서드별이 아니라 전체 인터페이스에 걸쳐 성립하는 세 가지 속성도 함께 설명합니다. 모든 요청이 자체 메서드가 선언한 필드 외에 허용하는 두 필드, 즉 위의 workspaceRoot와 긴 작업 지켜보기의 workDoneToken, 메서드가 허용하지 않는 키를 포함한 params 객체는 거부되며 거부 시 허용되는 키 집합이 명시된다는 점, 그리고 없는 컬렉션이 빈 컬렉션이 아닌 null로 와이어에 전달되는 경우입니다. 이 페이지는 해당 스키마에서 생성되므로 계약이 바뀌면 함께 바뀝니다.

이 페이지는 프로토콜을, 저 페이지는 형태를 다루며, 둘은 함께 읽도록 되어 있습니다. 이 페이지에서는 프레이밍, 각 메서드의 용도, 적용 범위, 기록하는 내용, 발생시키는 거부와 그 이유, 오류 코드와 각각에 대한 대처 방법을 다룹니다. 저 페이지에서는 와이어에 무엇을 넣어야 하는지를 키별로 다룹니다. 따라서 아래 목록은 각 메서드의 이름과 그것을 요청하는 것이 무엇을 의미하는지를 설명하며, 작성 중인 요청의 필드 목록은 옆의 레퍼런스에 있습니다.

요청:

  • aggrega/initialize — 핸드셰이크. 위치 인코딩을 협상하고(서버는 UTF-8, UTF-16, UTF-32 순으로 선호하며 기본값은 UTF-16), 푸시 진단용으로 선언한 워크스페이스를 받으며, 해당 워크스페이스의 루트, 설정이 결정된 구성 계층, 그리고 이를 결정한 마커를 보고합니다. 응답에는 응답하는 바이너리의 버전인 version도 포함되며, 이는 해당 바이너리에 대해 aggrega version이 보고하는 값과 같습니다. 이 값은 실행 중인 프로세스를 설명하므로, 데몬을 시작한 파일이 교체된 후에는(예: 같은 경로로 다시 빌드한 경우) version은 여전히 실행 중인 데몬을 가리키는 반면 파일에 직접 물으면 교체된 파일을 가리킵니다. 대화 중인 버전이 무엇인지 알고 싶다면 여기에서 확인하십시오. workspaceRoot는 선택 사항이며, 워크스페이스에 대해 작업하는 것이 아니라 워크스페이스를 선언합니다. 진단을 푸시받을 워크스페이스 선언하기를 참조하십시오. 클라이언트가 진행 알림을 처리할 수 있음을 알리려면 capabilities.window.workDoneProgress: true를 보내십시오. 응답의 capabilities.workDoneProgress가 이를 그대로 반환하며, 아무것도 선언하지 않은 클라이언트에는 이 필드가 없습니다. 긴 작업 지켜보기를 참조하십시오.
  • aggrega/validate — 파일 내용을 검증하고 진단을 반환합니다. release는 검증 기준이 될 Release를 지정하는 워크스페이스 루트 기준 상대 경로로, aggrega/irGraph가 받는 값과 같고, 루트에서 실행할 때 aggrega build --release가 받는 값과 같습니다. 이는 선택 사항이며 응답의 적용 범위를 결정합니다. Release를 지정하면 Release가 필요한 검사가 그에 대해 실행되어, 카탈로그 엔터티는 해당 Release의 관점에서 단일 엔터티로 검사되고 그 밖의 문서는 해당 Release의 의존성 클로저에 대해 검사됩니다. 생략하면 응답은 문서 자체만으로 검사할 수 있는 범위를 다루며, 이를 나타내기 위해 checked를 포함합니다. 값이 있지만 형식이 잘못된 경우에는 어느 쪽이든 거부됩니다. 절대 경로나 워크스페이스 루트 밖으로 해석되는 경로는 해석되지 않고 거부됩니다. 라이브 검증을 참조하십시오.
  • aggrega/diagnostics — 파일에 대해 보유한 검사 결과를 반환합니다. 요청이 도착했을 때 같은 파일의 검증이 실행 중이면, 응답은 그 검증을 기다렸다가 발견한 내용을 보고합니다. 따라서 데몬이 문제를 찾고 있는 도중인 파일에 대해 문제가 없다는 응답을 보내는 일은 없습니다. 검증 실행 중에 진단 요청하기를 참조하십시오.
  • aggrega/hover — 특정 위치의 엔터티에 대한 호버 내용입니다. release는 선택 사항이며 해당 Release의 관점에서 응답합니다. 하나의 Release 관점에서 응답하기를 참조하십시오.
  • aggrega/completion — 특정 위치의 완성 후보입니다. 커서가 종류로 엔터티를 지정하는 곳(component의 type, Feature 연결의 type, extends: 값, Recipe 또는 FeatureRecipe의 implements:)에서는 워크스페이스 자체 문서가 선언한 해당 종류의 이름이 후보가 되며, Component나 Feature의 경우 구성된 catalog_dirs가 선언한 이름도 포함됩니다. 각 이름은 한 번씩 이름 순으로 제공됩니다. 따라서 Components와 Features를 카탈로그에서 가져오는 워크스페이스에는 직접 작성한 것뿐 아니라 그것들도 제공됩니다. Manifest 매핑의 값에서 제공되는 Recipes와 FeatureRecipes는 워크스페이스 자체 문서에서 가져옵니다. 아티팩트 캐시나 레지스트리에만 있는 엔터티는 제공되지 않습니다. 완성 응답은 절대 가져오기를 수행하지 않습니다. release는 선택 사항이며 해당 Release의 관점에서 응답합니다. 하나의 Release 관점에서 응답하기를 참조하십시오.
  • aggrega/resolve — 특정 위치에서 참조된 엔터티를 해석합니다(정의로 이동). release는 선택 사항이며 해당 Release의 관점에서 응답합니다. 하나의 Release 관점에서 응답하기를 참조하십시오.
  • aggrega/findReferences / aggrega/findImplementations. 각각 선택적인 release를 받으며 해당 Release의 관점에서 응답합니다. 하나의 Release 관점에서 응답하기를 참조하십시오.
  • aggrega/irGraph — 편집기 내부 검사를 위한, Release의 컴파일된 IR 그래프입니다. release는 워크스페이스 루트를 기준으로 한 상대 경로로, 그 안의 Release를 지정합니다. 루트에서 실행할 때 aggrega build --release가 받는 값과 같습니다. 그 밖의 형식은 대신 무엇을 보내야 하는지 알려 주는 표준 invalid-params 오류로 거부됩니다. 절대 경로, 워크스페이스 루트 밖으로 해석되는 경로(작성된 그대로 밖으로 올라가든, 파일이나 경로상의 디렉터리로 향하는 링크를 통해 밖으로 나가든), 빈 값은 모두 해석되지 않고 거부되므로, 요청이 워크스페이스에 없는 파일에 대해 보고하는 일은 없습니다. 워크스페이스 구성이 build.authoring_release로 또는 workspace.releases의 키로 지정하는 Release는 그 파일이 어디에 있든 워크스페이스가 보유한 것이므로, 그것으로 향하는 워크스페이스 내부의 링크는 aggrega/releaseCandidates가 나열하는 대로 허용됩니다. Release가 읽는 카탈로그 디렉터리를 순회할 수 없는 경우(예: 존재하지만 읽을 수 없는 경우)에는 다른 어떤 것도 읽기 전에 aggrega inspect가 거부하는 방식대로 거부됩니다. 오류는 1004 entity-not-resolvable이고, 메시지는 명령줄이 그 디렉터리에 대해 출력하는 보고를 한 줄로 나타낸 것이며([CATALOG_ERROR] <directory>: catalog load: …), 남은 디렉터리들로 그래프를 그리지 않습니다. 워크스페이스 구성이 나열했지만 디렉터리가 아닌 항목(예: 그 자리에 아무것도 존재하지 않는 경우)도 같은 방식으로 같은 시점에 거부됩니다. 오류는 1004 entity-not-resolvable이고, 메시지는 모든 명령이 그것에 대해 내는 거부로서, 해당 항목, 그것을 나열한 구성 파일과 줄, 그리고 해당 설정을 지정합니다(로컬 엔터티를 읽는 위치). 읽기가 머물러야 하는 디렉터리 밖으로 나가는 링크를 보유한 카탈로그 디렉터리(워크스페이스 내부의 카탈로그 디렉터리 아래에 있든, 구성이 워크스페이스 밖에 지정한 카탈로그 디렉터리 아래에 있든, 다른 곳에서 링크된 문서나 디렉터리)도 같은 방식으로 같은 시점에 거부되며, 1004와 함께 그 링크와 링크가 향하는 곳을 지정하는 해당 조건 고유의 문장이 주어집니다. 그러한 링크를 통해서는 아무것도 읽지 않으며, 링크 없이 그린 그래프는 그 자리에 같은 이름의 다른 엔터티를 해석할 수 있기 때문입니다. Release가 자신의 Aggregate나 Manifest를 식별자로 지정하는 경우, Release 옆의 문서들 사이에서 밖으로 나가는 링크도 마찬가지입니다. Release, 그 Manifest 또는 그것이 확장하는 Release가 경로로 지정하는 파일(aggregate:, manifest:, extends: 또는 parameters의 $import:)이 작성된 그대로든 링크를 통해서든 워크스페이스 밖으로 나가면 해당 조건 고유의 문장으로 거부되며(fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (다른 파일에 대한 참조가 머물러야 하는 디렉터리 밖으로 나갑니다)”), 오류의 data는 그 파일로 이어진 Release의 키에 위치를 두고, 그 파일에서는 아무것도 읽지 않습니다. 구성이 워크스페이스 밖에 지정한 Release는 그것을 보유한 디렉터리에 같은 방식으로 묶이므로, 그 Release 또는 그 체인이 이어지는 Release가 작성한, 그 디렉터리를 벗어나는 경로도 거부됩니다. aggrega/releaseCandidates는 절대 경로로 응답하므로, 한 쪽 표면의 값을 다른 쪽에 넣는 클라이언트는 둘 사이를 변환해야 합니다. 이 매개변수가 문서별 file 및 uri 매개변수가 허용하는 표기를 거부하는 것은 의도된 것이며, 무엇이 그것을 결정하는지는 보내는 매개변수가 허용하는 표기에서 설명합니다. 그래프는 명령줄에서 --ir-graph가 보류하는 것과 정확히 같이 작성자가 민감하다고 선언한 모든 값을 보류합니다. 각 값은 aggrega-inspect “Machine-readable output”이 설명하는 마커로 대체되며, 그 밖의 모든 것은 컴파일러가 기록한 그대로 전달됩니다. unredacted: true는 그 값들을 평문으로 요청합니다. 이는 명령줄 --unredacted의 프로토콜 표기이자 유일한 요청 방법이며, 없거나 false이면 응답은 값을 보류합니다. 그러면 응답이 도달하는 모든 곳이 값을 평문으로 지니게 되므로, 클라이언트는 그것을 사용하는 사람이 요청한 경우에만 값을 요청해야 합니다.
  • aggrega/build — Release를 컴파일하고 그 아티팩트를 워크스페이스의 출력 디렉터리에 씁니다. 이 디렉터리는 워크스페이스 루트에서 실행할 때 aggrega build가 쓰는 디렉터리와 같습니다. release는 위와 같은 계약을 따릅니다. 모든 게이트를 켠 채로 렌더링하므로, 명령줄 빌드가 중단될 불일치는 여기서도 중단됩니다. Release가 읽는 카탈로그 디렉터리를 순회할 수 없는 경우(예: 존재하지만 읽을 수 없는 경우)에는 아무것도 쓰기 전에 aggrega build가 거부하는 방식대로 거부됩니다. 아티팩트도 쓰지 않고, autoPull이 설정된 경우 lockfile도 쓰지 않습니다. 워크스페이스 구성이 나열했지만 디렉터리가 아닌 디렉터리도 마찬가지로, aggrega build가 거부할 때와 같은 문구로 거부됩니다(로컬 엔터티를 읽는 위치). 거부는 같은 디렉터리에 대해 aggrega/irGraph가 내는 것과 같으며, 명령줄의 보고를 한 줄로 담은 1004 entity-not-resolvable입니다. 카탈로그 디렉터리의 읽기 범위 밖으로, 또는 Release 옆의 문서들 밖으로 나가는 링크는 aggrega/irGraph가 거부하는 방식대로 거부되며 아무것도 쓰지 않습니다. 응답은 쓴 대상인 outputDirectory와 쓴 files(각각 그 디렉터리를 기준으로 한 상대 경로이며 정렬됨)를 실행 중 발생한 notices와 함께 지정합니다. 문서 위치를 지닌 결과는 대신 aggrega/publishDiagnostics로 전달됩니다. 렌더링 중 거부하는 Release에는 모든 원인을 포함하여 컴파일러의 표현 그대로 그 거부로 응답하며, 거부는 그것이 가리키는 곳에 게시됩니다. 렌더링 중 발생한 거부를 참조하십시오. autoPull이 설정된 경우 응답에는 dependencyResolution도 포함됩니다. 이는 aggrega/resolveDependencies가 응답하는 것과 같은 보고이므로, 빌드의 일부로 의존성을 채운 클라이언트는 다시 묻지 않고도 무엇이 고정되었는지, 그리고 이 빌드의 해석이 각 참조를 어디에서 가져왔는지(lockfile이 기록하지 않는 해당 실행에 대한 사실)를 읽을 수 있습니다. 각 알림은 그것을 발생시킨 표면의 class를 지닙니다. deprecation, catalog, catalog-lint, extends, release-composition, 또는 아래의 의존성 해석이 발생시킨 줄의 경우 dependency-resolution이며, 데몬이 그 표면의 이름을 갖고 있지 않은 경우 빈 class를 지닙니다. 이 경우 클라이언트는 가장 가까운 항목을 추측하지 않고 text만 그대로 표시합니다. 쓰기 과정에서 출력 디렉터리, 또는 그 아래에서 파일을 썼거나 거쳐 간 디렉터리에서 발견한, 이 빌드가 쓰지 않은 파일은 그대로 남겨 두며, 실행 자체의 알림 뒤에 오는 하나의 알림에서 빈 class 아래에, aggrega build가 경고를 출력할 때 쓰는 문장으로 지목됩니다. 빌드가 쓰지 않은 파일을 참조하십시오. files는 그 파일들을 지목하지 않습니다. outputParent는 워크스페이스 안에서 아티팩트가 들어갈 위치를 말하며, 그 이름이 의미하는 바가 전부입니다. 이는 출력 디렉터리가 그 안에 생성되는 디렉터리이므로, docs를 보내면 아티팩트를 docs 자체가 아니라 docs/dist에 씁니다. 터미널에서 docs에서 실행한 빌드가 생성하는 것과 정확히 같습니다. 생략하면 빌드는 워크스페이스 루트에서 실행한 빌드가 쓰는 곳에 씁니다. 이는 여기의 다른 쓰기 요청이 받는 outputDir과 다르게 읽히며, 의도적으로 그렇습니다. 그것들은 그 안에 쓰는 디렉터리를 지정하고, 이것은 그 디렉터리의 부모를 지정하며, 둘은 서로 다른 것이므로 서로 다른 이름을 지닙니다. 이것도 워크스페이스 내부의 대상이므로, 절대 값, 루트 밖으로 올라가는 값, 링크를 통해 루트 밖으로 나가는 값(루트 밖의 링크된 디렉터리, 또는 그 아래 아직 만들어지지 않은 디렉터리)은 해석되지 않고 거부됩니다. 그 안에 생성되는 출력 디렉터리와 빌드가 거기에 쓰는 모든 파일도 워크스페이스에 묶입니다. 그중 하나가 링크를 통해 워크스페이스 밖으로 나가면, 빌드는 1004와 함께 그 링크와 링크가 향하는 곳을 지정하는 해당 조건 고유의 문장으로 거부되며, 아무것도 지우거나 쓰지 않습니다. autoPull은 렌더링 전에 Release의 의존성을 해석하며(aggrega/resolveDependencies가 수행하는 것과 같은 해석), 명령줄 자체의 기본값에 맞추어 요청이 요구하지 않는 한 꺼져 있습니다. 이것이 없으면 lockfile이 없는 Release는 무엇을 실행해야 하는지 알려 주는 lockfile-absent 오류로 거부됩니다. autoPull이 설정되면 이 요청은 레지스트리에 접근하고 lockfile을 씁니다. 레지스트리 접근과 쓰기를 참조하십시오. 먼저 해석하는 요청도 Release를 한 번만 렌더링합니다. Release가 어떤 원격 참조를 소비하는지 알아내는 것 자체가 렌더링이므로, 해석 단계에서 이미 빌드 대상을 렌더링했으며, 빌드는 이를 반복하지 않고 그 렌더링 결과로 응답됩니다. policyInput은 워크스페이스 안의 디렉터리를 루트 기준 상대 경로로 지정하며, 빌드가 끝나든 중단되든 빌드는 각 거버넌스 역할이 그곳에 연결된 플러그인에 전달하는 페이로드도 이 디렉터리에 씁니다. 이는 aggrega build --policy-input이 같은 이름으로 쓰는 파일들입니다. 그런 다음 응답의 notices가 몇 개를 썼는지 알리고, 파일을 하나도 쓰지 않은 각 역할을 빈 class 아래에 명시합니다. 실패한 요청에서는 쓴 파일이 디스크에 남아 있지만 그 내역은 응답에 포함되지 않습니다. 오류 엔벨로프에는 거부만 담깁니다. 이것은 대상 위치이므로, 절대 값이나 워크스페이스 밖으로 올라가는 값은 무엇이든 실행되기 전에 거부됩니다.
  • aggrega/buildPreview — Release의 빌드가 무엇을 쓸지 보고하며, 아무것도 쓰지 않습니다. release는 위와 같은 계약을 따릅니다. aggrega/build가 실행하는 것과 같은 계산을 같은 게이트 아래에서 실행하므로, Release는 둘 다에서 거부되거나 둘 다에서 보고됩니다. 그래서 둘 사이의 선택은 엄격성이 아니라 출력에 관한 선택이 됩니다. Release가 읽는 카탈로그 디렉터리를 순회할 수 없거나, 그 디렉터리가 읽기가 머물러야 하는 디렉터리 밖으로 나가는 링크를 보유한 경우, 아무것도 렌더링하기 전에 같은 방식으로 거부됩니다. aggrega/build에서처럼, 워크스페이스 구성이 나열했지만 디렉터리가 아닌 디렉터리도 마찬가지로 거부됩니다. 응답에는 빌드가 내보낼 출력 기준 상대 이름인 files가 정렬되어 notices와 함께 포함됩니다. 어디에도 쓴 것이 없어 지정할 대상이 없으므로 outputDirectory는 없습니다. 렌더링 중 거부하는 Release는 aggrega/build가 응답하고 게시하는 것과 정확히 같이 응답되고 게시됩니다. 이 요청은 대신 무엇을 보내야 하는지 알려 주는 invalid-params 오류로 autoPull을 거부합니다. 의존성을 채우면 lockfile을 쓰게 되는데, 이 요청은 lockfile을 쓰지 않기 때문입니다. 어떤 레지스트리에도 접근하지 않습니다. policyInput은 이 요청이 하는 유일한 쓰기이며, 보낸 경우에만 수행됩니다. aggrega/build와 정확히 같이 거버넌스 페이로드를 그 디렉터리에 쓰고(aggrega build --dry-run --policy-input이 쓰는 파일), 출력 디렉터리와 lockfile은 건드리지 않으며, notices에 같은 내역을 담고 같은 제약을 따릅니다. 실패한 요청에서는 쓴 파일이 디스크에 남아 있지만 그 내역은 응답에 포함되지 않습니다.
  • aggrega/resolveDependencies — Release의 카탈로그 및 소스 의존성을 캐시로 해석하고, 그 렌더링이 소비하는 외부 입력을 콘텐츠 주소 지정 저장소에 고정한 뒤, lockfile을 기록합니다. release는 워크스페이스 루트 기준 상대 경로로, aggrega/irGraph가 받는 것과 같은 값이며 같은 형태에서 거부됩니다. upgrade는 기록된 고정을 버리고 다시 해석하여 각 의존성을 사용 가능한 가장 높은 버전으로 올립니다. targets는 이를 지정한 엔터티 참조로 좁히고 다른 모든 고정은 유지합니다. verify는 기록된 해석을 이 옵션이 없을 때 이 요청이 수행할 해석과 비교하며, 기록된 고정을 같은 방식으로 존중하고, lockfile, 플러그인 신뢰 기록, entity.lock 중 어느 것도 기록하지 않습니다. 캐시는 이 옵션이 없을 때와 같이 읽히고 채워지며, 응답은 verified: true와 lockfile에 기록된 toolchain입니다. verify는 upgrade와 함께, targets와 함께, 그리고 어떤 값이든 pinSources와 함께 보내면, 무엇이 해석되거나 진행 상황이 보고되기 전에 잘못된 매개변수(invalid params)로 거부됩니다. upgrade는 verify가 존중하기 위해 존재하는 고정을 버리고, 지정된 대상은 upgrade에 의해서만 다시 해석되며, pinSources는 해석이 entity.lock에 누락된 고정을 기록할지 아니면 그 때문에 거부할지를 결정하는데, entity.lock을 기록하지 않는 비교는 둘 중 어느 것도 하지 않기 때문입니다. 명령줄과 어시스턴트 도구도 같은 조합을 거부합니다. 응답은 기록했거나 비교 대상으로 삼은 lockfile과 고정한 모든 참조를 entities, libraries, plugins에 담아 알려 주며, 각 항목은 해석된 version과 그 source를 담습니다. 이는 이번 실행이 참조를 어디서 가져왔는지를 같은 해석에 대해 aggrega pull --detail이 출력하는 단어 fetched-fresh, cache-reuse, local, in-binary, external 중 하나로 나타냅니다. 이와 함께 sourceArtifacts, trustedPlugins, externalInputs(실행이 끝난 뒤 lockfile이 고정하는 외부 입력의 수로, 이어받은 것과 이번 실행이 발견한 것을 모두 셉니다), 그리고 해석이 발생시킨 notices가 담깁니다. 🔴 성공 응답 자체가 외부 입력 고정이 완료되었음을 뜻하지는 않습니다. 실행이 모든 의존성을 고정했지만 Release가 어떤 외부 입력을 소비하는지 끝까지 파악하지 못한 경우, 발견을 멈추게 한 원인을 담은 incompleteExternalInputs로 응답하며 여전히 성공으로 응답합니다. 의존성 고정은 완료되어 디스크에 있으므로, 요청 전체를 실패로 보고하면 이미 올바른 작업을 다시 하라고 알리는 셈이 되기 때문입니다. lockfile을 완전히 고정된 것으로 취급하기 전에 이 필드를 읽으십시오. 발견되지 않은 것이 없으면 이 필드는 없으므로, 필드가 있다는 것 자체가 신호입니다. 카탈로그 디렉터리 매개변수는 없습니다. 검색 스택은 워크스페이스가 구성한 것입니다. 이 요청은 세션에서 Release를 고정하는 유일한 요청이며, 외부 입력도 여기서 고정됩니다. 렌더링이 어떤 URL을 소비하는지는 무엇을 렌더링하는지에서 결정되므로, 이 요청은 이를 알아내기 위해 Release를 렌더링하고, 이후 빌드 요청은 이 요청이 기록한 내용으로 처리됩니다. Release가 빌드하는 Recipe 또는 FeatureRecipe의 entity.lock에 그 엔터티가 읽는 입력의 고정이 기록되어 있지 않으면, aggrega pin과 기록되지 않은 각 입력을 명시하며 요청이 거부됩니다. pinSources: true는 대신 해당 엔터티들에 그 고정 단계를 실행하여 각 엔터티 옆에 entity.lock을 기록합니다. 이는 aggrega/pin이 실행하는 것과 같은 단계이며 같은 바이트를 기록합니다. pinSources가 없으면 워크스페이스의 pin_sources_at_pull을 따르고, 보내면 양방향으로 그 설정을 재정의하므로, false는 고정하도록 구성된 워크스페이스에서도 거부합니다. 이 요청은 레지스트리에 접근하고 기록합니다. 레지스트리 접근과 기록을 참고하십시오.
  • aggrega/pin — Recipe 또는 FeatureRecipe 옆의 entity.lock에, 엔티티가 자신의 문서 바깥에서 읽는 모든 입력의 콘텐츠 핀을 기록합니다. 대상은 좌표가 완전히 기재된 원격 소스, artifacts 항목이 가져오는 파일, 그리고 로컬 소스가 엔티티의 게시물에 담기는 내용에 기여하는 각 파일입니다. 이는 터미널에서 aggrega pin이 실행하는 것과 같은 단계이며, 같은 바이트를 씁니다. entity는 필수이며 엔티티 문서를 가리키는 워크스페이스 루트 기준 상대 경로로, release와 같은 세 가지 형태에서 거부됩니다. Release는 지정하지 않습니다. 좌표에 템플릿이 없는 원격 소스는 그 엔티티를 사용하는 모든 Release에 대해 하나의 아티팩트를 가리키므로 핀을 고정하는 데 Release가 제공하는 것이 필요하지 않고, 좌표가 템플릿에서 오는 원격 소스는 aggrega/resolveDependencies가 Release별로 핀을 고정합니다. 템플릿으로 작성된 로컬 소스는 엔티티 디렉터리의 모든 파일을 기여하며, 그 각각은 여기서 핀이 고정됩니다. dryRun은 입력을 해석하고 이 단계가 쓸 잠금을 content로 응답하며, 엔티티 옆에는 아무것도 쓰지 않습니다. 콘텐츠 캐시는 여전히 채워집니다. 응답에는 entity, kind, name, pinnable이 담깁니다. 잠금이 기록하는 것을 아무것도 읽지 않는 종류라면 이 값은 false이고, 이 경우 엔티티 옆의 어떤 것도 건드리지 않았으며 다른 모든 필드는 없습니다. 그렇지 않으면 응답에는 쓴 lock, changed(잠금이 이미 모든 핀을 기록하고 있어 바이트 단위로 동일하게 남았다면 false), 엔티티가 이제 잠금이 기록하는 것을 아무것도 읽지 않아 잠금이 삭제된 경우의 removed, 그리고 핀 클래스마다 하나씩 잠금이 보유한 개수를 담은 항목인 pins가 담깁니다. 엔티티 파일 자체는 절대 쓰이지 않습니다. 이 요청은 워크스페이스 안의 엔티티 옆에 쓰며, 엔티티의 소스가 지정하는 호스트에 접근합니다 — Reaching a registry, and writing을 참조하십시오.
  • aggrega/cacheStatus — 디스크 캐시가 보유한 내용입니다. 캐시된 요소마다 크기와, 있는 경우 콘텐츠 다이제스트를 담은 항목 하나를 클래스별로 묶어 보여 줍니다. 워크스페이스 외에는 아무것도 받지 않습니다. 각 클래스는 reach를 담습니다. 이 워크스페이스 자체 캐시 디렉터리 아래의 아티팩트 캐시는 workspace, 머신의 모든 프로젝트가 공유하는 컴파일된 모듈, plugin-describe, 문서 번들 저장소는 machine이며, scope는 머신 전체 클래스를 직접 지정합니다. 아무것도 작성하지 않습니다. 아무것도 바꾸지 않는 응답에 reach가 있는 이유는 레지스트리 접근과 쓰기를 참조하십시오.
  • aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear — 캐시된 콘텐츠를 회수합니다. prune은 어떤 워크스페이스 lockfile도 참조하지 않는 것을 제거하고, eviction은 컴파일된 모듈 저장소를 maxSize로 줄이며(명령줄과 같은 방식으로 쓰는 바이트 수량: 5GiB, 512MiB 또는 바이트 수), clear는 이 세션이 다루는 모든 캐시를 비웁니다. 각 응답은 제거한 것을 나열하며, 각 제거 항목은 그것이 속했던 클래스의 reach를 담고, 각 응답은 scope를 담습니다. 각 응답은 또한 다른 프로세스가 열고 있어서 남겨 둔 것도 나열합니다. Windows는 열린 파일의 제거를 거부하며, 작업은 실패하지 않고 나머지를 계속 처리합니다. prune이나 eviction은 해당 항목을 heldOpen에 나열하고, clear는 비운 각 캐시에 대해 남겨 둔 파일 수를 heldOpenFiles에, 그 크기를 heldOpenBytes에 셉니다. 그 밖의 플랫폼에서는 목록이 비어 있고 개수는 0이며, 남겨진 것은 이후 실행에서 회수할 수 있습니다. 이 요청들은 워크스페이스 너머에 영향을 미칩니다. 레지스트리 접근과 쓰기를 참조하십시오.
  • aggrega/registryList — 이 워크스페이스가 접근하도록 구성된 레지스트리입니다. 각 항목의 호스트, 선택적 별칭, 기본값 여부, 개별 필드로 나타낸 신뢰 정책, 그리고 해당 호스트의 자격 증명이 있는지 여부를 보여 줍니다. 워크스페이스 외에는 아무것도 받지 않습니다. 어떤 레지스트리에도 연결하지 않습니다. 자격 증명 상태는 존재 여부만 보고합니다. 자격 증명 자체, 그 형태, 레지스트리가 이를 수락할지 여부는 절대 보고하지 않으며, 마지막 것은 목록 조회가 하지 않는 네트워크 왕복이 필요하기 때문입니다. 이 상태는 머신 전체 자격 증명 저장소에서 읽으며, credentialStateIsMachineWide가 이를 명시합니다.
  • aggrega/search — 구성된 레지스트리의 로컬 인덱스를 검색합니다. 모든 필드는 범위를 좁히며 모두 선택 사항이므로, 빈 params 객체는 인덱스에 있는 모든 것을 요청합니다. 네트워크에 접속하지 않습니다. 인덱스는 이 워크스페이스 자체의 캐시 디렉터리 아래에 기록된 오프라인 스냅샷입니다. 보고되는 버전은 해석(resolution)이 선택할 버전입니다. 이 워크스페이스가 신뢰하는 서명이 붙은 철회가 있는 버전은 제외되고 retracted에 명시됩니다. 응답은 자체 출처 정보를 담습니다. indexes는 검색한 각 레지스트리의 스냅샷 경과 시간을 제공하고, stale은 갱신할 가치가 있는 스냅샷을 표시하며, missingIndexHosts는 로컬 인덱스가 없는 구성된 레지스트리를 명시합니다. 따라서 그 레지스트리의 내용은 응답에 포함되지 않습니다.
  • aggrega/registryAdd — 레지스트리와 그 서명 신뢰 정책을 등록합니다. host는 필수이며, 나머지는 모두 정책이나 쓰기 대상을 결정합니다. keyPath와 trustedRoot는 파일을 지정합니다. 절대 값(예를 들어 대화 상자에서 선택한 파일)은 지정된 위치에서 읽습니다. 상대 값은 워크스페이스 안의 파일을 지정하며, 데몬이 실행되는 디렉터리가 아니라 워크스페이스 루트를 기준으로 해석됩니다. 루트 밖으로 올라가거나 링크를 통해 루트 밖으로 이어지는 값은 무엇이든 읽거나 쓰기 전에 invalid-params 오류로 거부됩니다. 상대 trustedRoot는 워크스페이스 안에서 지정하는 파일로 기록되므로, 이후 검증이 어느 디렉터리에서 실행되든 항목은 그 파일을 지정합니다. fetchTrust는 키가 없으면 명령줄과 동일하게 true가 기본값이며, 첫 접촉 시 레지스트리가 자체적으로 공지하는 정책을 가져옵니다. 응답의 trust는 무슨 일이 있었는지 알려 줍니다. 정책이 고정되었는지, 레지스트리가 아무 정책도 공지하지 않았는지(그리고 그 옆에 unreachable이 있으면 아예 접속할 수 없었는지), 공식 허브의 내장 기준선이 대신 고정되었는지, 또는 가져오기를 시도하지 않았는지입니다. 이 등록은 aggrega registry add가 수행하는 것과 같습니다. 같은 네트워크 정책 아래에서 같은 가져오기를 수행하고 바이트 단위로 같은 항목을 기록합니다. 오프라인 워크스페이스에서는 어떤 연결도 시도하기 전에 가져오기가 거부되므로 레지스트리에 요청하지 않으며, 요청이 identities나 keyPath를 제공하지 않는 한 공식 허브가 아닌 레지스트리는 거부됩니다. 이 두 필드는 보낸 내용을 그대로 등록하고 가져오기를 하지 않습니다. 오류 메시지는 명령줄이 출력하는 문장이며 그 앞에 조건의 짧은 코드 E0310이 붙습니다. 이 요청의 거부 중 조건을 명시하는 모든 메시지가 짧은 코드로 시작하기 때문입니다. 그리고 아무것도 기록되지 않습니다. 공식 허브는 여전히 내장 기준선으로 기록되며, 응답에는 trust.baseline이 true이고, trust.reason은 워크스페이스가 오프라인이므로 허브에 신뢰 정책을 요청하지 않았다고 알리며(명령줄의 알림이 시작하는 이유와 같습니다), 허브에 요청한 적이 없으므로 notAdvertised는 없습니다. 이 요청은 기본적으로 전역 구성에 기록합니다 — 레지스트리 접속과 쓰기를 참조하십시오.
  • aggrega/registryRemove — 호스트나 별칭으로 지정한 레지스트리 항목을 삭제합니다. 아무것과도 일치하지 않는 토큰은 변경되지 않은 구성에 대해 성공으로 응답하지 않고 거부됩니다. 이 요청은 기본적으로 전역 구성에 기록합니다 — 레지스트리 접속과 쓰기를 참조하십시오.
  • aggrega/logout — 레지스트리에 대해 저장된 자격 증명을 제거합니다. 터미널에서 aggrega logout이 수행하는 것과 같은 제거입니다. registry는 필수이며 인증했던 그대로의 레지스트리 호스트를 지정합니다. 여기서는 해석할 별칭이 없습니다. 자격 증명 저장소는 구성이 지정하는 이름이 아니라 클라이언트가 인증하는 주소를 키로 사용하므로, 어떤 워크스페이스도 구성하지 않은 호스트에도 제거할 수 있는 자격 증명이 있을 수 있기 때문입니다. 저장소에 자격 증명이 없는 호스트는 성공적으로 제거되며 아무것도 다시 기록되지 않습니다. 호스트에 자격 증명이 없기를 요청한 호출자는 요청한 결과를 얻은 것이므로 이는 오류가 아니라 응답이며, 터미널 명령도 같게 동작합니다. 응답에는 registry와 scope가 담깁니다. 자격 증명의 어떤 부분도 어떤 형태로도 담지 않으며, 자격 증명이 있었는지 여부도 보고하지 않습니다. 이를 확인하려면 아무도 요청하지 않은 저장소 읽기를 한 번 더 해야 하므로, 존재 여부가 궁금하다면 aggrega/registryList에 요청하십시오. 레지스트리에 접속하지 않습니다. 저장된 자격 증명을 제거하는 것은 로컬 작업이며, 해당 레지스트리가 그 자격 증명을 수락했을지는 묻지 않습니다. 이 요청은 머신의 모든 프로젝트가 공유하는 자격 증명 저장소를 변경합니다 — 레지스트리 접속과 쓰기를 참조하십시오.
  • aggrega/registryUpdate — aggrega/search가 읽는 로컬 검색 인덱스를 갱신합니다. registry가 없으면 구성된 모든 레지스트리를 갱신하고, 하나를 지정하면 그 레지스트리만 갱신합니다. upgrade는 이미 기록된 인덱스와 아무것도 비교하지 않고 모든 저장소를 처음부터 다시 읽습니다. 이것이 없는 갱신도 변경된 것은 이미 다시 읽습니다. 응답에는 각 호스트의 레코드 수, 읽을 수 없었던 저장소(각각 reason을 지니며, 있는 경우 읽기의 마지막 실패 종류로 시작함), readsRetried(레지스트리가 도중에 거부하거나 끊어서 다시 요청한 읽기의 수로, 각 읽기를 한 번씩 세며 0도 포함), 발견한 지원 중단 마커, 실패한 호스트의 error(해당 레지스트리에 접속할 수 없었던 경우 그 옆에 unreachable), 그리고 인덱스가 기록된 이 워크스페이스 자체 캐시 아래의 디렉터리인 indexRoot가 담깁니다. 이 요청은 갱신하는 모든 레지스트리에 접속합니다 — 레지스트리 접속과 쓰기를 참조하십시오.
  • aggrega/publishEntity — 카탈로그 엔티티를 번들로 묶어 레지스트리에 게시합니다. entity는 게시할 문서를 가리키는 워크스페이스 루트 기준 상대 경로이며, release와 같은 세 가지 형태, 즉 없음, 절대 경로, 루트 밖으로 해석되는 경우에 거부됩니다. Plugin 엔티티에는 같은 종류의 경로인 plugin도 필요하며, 이는 엔티티 자체의 매니페스트 안에 게시되는 실행 파일을 가리킵니다. registry는 대상이며 기본값은 워크스페이스에 구성된 레지스트리입니다. dryRun은 번들과 그 게시가 남길 다이제스트를 계산하며 어떤 레지스트리에도 접속하지 않습니다. sign을 생략하면 대상 레지스트리 자체의 정책을 따르며, 이는 명령줄에서 해당 플래그가 없을 때의 동작과 같습니다. 이를 보내는 것은 호출자의 선택이지만, 어느 쪽도 거부를 완화하지 않습니다. 서명을 요구하는 레지스트리 또는 워크스페이스 정책은 이 필드의 값과 관계없이 서명되지 않은 게시를 거부하기 때문입니다. pinSources: true는 엔티티를 번들로 묶기 전에 엔티티 작성자의 고정(pin) 단계를 실행하므로, 이 단계가 엔티티 옆에 기록하는 entity.lock도 게시 대상에 포함됩니다. 이는 aggrega/pin이 실행하는 것과 같은 단계입니다. 이 단계는 서명 정책이나 불변성 보호처럼 엔티티의 내용을 판단하는 모든 거부보다 먼저 실행되므로, 그 단계에서 거부된 게시라도 잠금 파일은 기록된 채로 남습니다. 오프라인 워크스페이스나 대상 없음처럼 요청 자체에 대한 거부는 먼저 일어나며 아무것도 고정하지 않습니다. 다른 엔티티와 디렉터리를 공유하는 엔티티에 대한 거부도 마찬가지인데, 이 단계는 그런 디렉터리에 잠금 파일을 기록해서는 안 되기 때문입니다. 필드가 없으면 워크스페이스의 pin_sources_at_push를 따르고, 보내면 양방향 모두에서 그 설정을 재정의합니다. dryRun에서는 이 단계가 기록할 잠금 내용을 보고하고 아무것도 기록하지 않습니다. 이 단계를 실행하지 않는 게시는, entity.lock이 읽는 입력에 대한 고정을 기록하지 않았거나 입력이 더 이상 일치하지 않는 Recipe 또는 FeatureRecipe를 번들로 묶기 전에 거부하며(dryRun에서도 마찬가지), aggrega pin, pinSources, pin_sources_at_push를 언급합니다. 이는 aggrega/resolveDependencies가 같은 잠금 파일에 대해 발생시키는 거부와 같습니다. 응답에는 reference, tag, kind, mediaType, size 쌍, 게시된 digest(dryRun에서는 그 게시가 남길 다이제스트로, aggrega push --dry-run이 출력하는 값입니다), signed, alreadyPublished, dryRun, reach가 포함됩니다. 단계가 실행된 경우에는 pin(aggrega/pin이 주는 것과 같은 응답)이, 엔티티의 로컬 소스가 템플릿으로 작성된 경우에는 그 소스를 작성된 그대로 가리키는 wholeDirectorySource가 포함됩니다. 그런 소스는 Release가 템플릿을 채워야 비로소 디렉터리가 정해지므로, 게시는 엔티티가 지정한 파일만이 아니라 엔티티 디렉터리의 모든 파일을 담으며, 호출자는 이 필드를 통해 그렇게 되었음을 알 수 있습니다. 드라이 런에서도 마찬가지입니다. 또한 게시가 담는 아카이브에 Windows가 작성된 그대로 담을 수 없는 항목, 즉 CON, AUX, NUL처럼 장치 이름을 딴 부분이 있는 경로(대소문자나 뒤따르는 확장자와 관계없음) 또는 마침표나 공백으로 끝나는 부분이 있는 경로가 있으면 windowsUnusableEntries가 포함되며, 엔티티 문서 자체의 파일 이름을 먼저, 그다음 담긴 파일들을 각각 나열합니다. 그런 항목이 없으면 이 필드는 없으며, 문서만으로 게시된 엔티티도 여기에 해당합니다. Windows에서 실행되는 aggrega는 그런 항목의 압축 해제를 거부하므로 Windows 워크스페이스는 해당 버전을 사용할 수 없습니다. 이 항목들은 aggrega push가 경고하는 항목과 같으며, 보고를 요청한 요청은 게시 진행 상황 중에 같은 경고 줄을 받습니다. 어느 쪽도 아무것도 거부하지 않으므로, 게시는 이 항목들이 없을 때와 똑같이 진행되거나 거부되며 dryRun에서도 마찬가지입니다. 이 요청은 레지스트리에 기록하고 이 머신 밖으로 접속하며, 고정 단계가 있으면 엔티티 옆에도 기록합니다. 레지스트리 접속과 기록을 참조하십시오.
  • aggrega/publishArtifact — 문서 번들과 같은 독립 데이터 아티팩트를 게시합니다. file은 워크스페이스 루트 기준 상대 경로로 같은 계약을 따르며, 그 바이트는 그대로 게시됩니다. 엔티티 봉투를 파싱하지 않으며 kind에 따라 분기하지도 않습니다. name과 tag는 게시될 이름을 지정하며 둘 다 필수입니다. mediaType의 기본값은 문서 번들 유형입니다. 응답에는 reference, tag, mediaType, size 쌍, 게시된 digest, alreadyPublished, dryRun, reach가 포함됩니다. 이 요청은 아무것도 서명하지 않습니다. 게시된 아티팩트는 이후 aggrega/signArtifacts로 참조를 통해 서명하며, 이때 필요한 것은 이 응답이 보고하는 참조뿐입니다. 이 요청은 레지스트리에 기록하고 이 머신 밖으로 접속합니다. 레지스트리 접속과 기록을 참조하십시오.
  • aggrega/signArtifacts — 이미 게시된 아티팩트에 서명하고 각 서명을 첨부합니다. references는 경로가 아닌 하나 이상의 레지스트리 주소를 담으므로 워크스페이스 상대 경로 계약을 따르지 않습니다. 빈 목록이나 목록 안의 빈 항목은 거부됩니다. 하나의 ID가 일괄 작업 전체에 사용되며 어떤 참조에 서명하기 전에 해석되므로, 사용 가능한 자격 증명이 전혀 없는 일괄 작업은 도중이 아니라 시작 시점에 거부됩니다. 참조들이 서로 다른 자격 증명을 필요로 하는 일괄 작업도 마찬가지입니다. 요청은 키를 지정하지 않으므로, 이는 워크스페이스 구성이 한 참조의 레지스트리에는 보유한 키를 지정하고 다른 참조의 레지스트리에는 키를 지정하지 않거나 다른 키를 지정한 경우입니다. 이때 아무것도 서명되지 않으며, 거부 메시지는 References signed together need different signing credentials (함께 서명되는 참조에 서로 다른 서명 자격 증명이 필요함)에서 설명하듯 양쪽의 레지스트리를 명시합니다. 아무것도 게시되지 않은 참조에 서명하는 것은 아무것에도 첨부하지 않는 대신 거부되며, 해당 레지스트리의 신뢰 정책으로 검증되는 서명을 이미 가진 참조는 aggrega sign에서 설명하듯 그대로 두고 서명된 것으로 집계됩니다. jobs는 선택 사항이며 한 번에 서명하는 참조의 수입니다. 없으면 참조를 하나씩 차례로 서명하고, 1보다 작은 값은 어떤 참조도 읽기 전에 invalid-params 오류로 거부됩니다. 각 참조는 aggrega sign에서 설명하듯 여전히 단독으로 서명할 때와 정확히 같이 서명되며, 요청이 보고하는 진행 상황과 응답 모두 참조가 주어진 순서를 유지합니다. 응답에는 signed가 포함되며, 각 항목은 reference와 그 서명이 확정하는 게시된 digest를 명시하고, reach가 함께 포함됩니다. 하나라도 실패한 참조가 있는 일괄 작업은 짧은 목록을 담은 결과가 아니라 실패한 각 참조를 명시하는 실패로 응답됩니다. 이 요청은 레지스트리에 기록하고 이 머신 밖으로 접속합니다. 레지스트리 접속과 기록을 참조하십시오.
  • aggrega/deprecateArtifact — 이미 게시된 아티팩트에 서명된 지원 중단 마커를 첨부합니다. severity 및 reason과 함께 단일 reference를 보내거나, 워크스페이스 루트 기준 상대 경로의 일괄 파일을 가리키는 from을 보냅니다. 둘 다 보내면 거부됩니다. 내용 필드는 입력을 요청받는 대신 필수입니다. 이 스트림을 지켜보는 사람이 없으므로, 필드가 하나라도 빠진 요청은 보내야 할 항목을 명시하며 거부됩니다. 이 필드는 단일 reference에만 속합니다. 일괄 파일은 각 마커의 내용을 자체 항목에 담으므로, from과 함께 보낸 severity, reason, replacement 또는 message는 무시되지 않고, 보낸 각 필드를 명시하며 잘못된 매개변수로 거부됩니다. 마커는 자체 다이제스트로 서명되므로 두 서명 요청이 받는 것과 같은 키 없는 입력이 여기에도 적용되며, 일괄 파일의 항목은 서명 일괄 작업의 참조와 똑같이 하나의 자격 증명으로 제한됩니다. 응답에는 marked가 포함되며, 각 항목은 철회된 reference, 그 severity, issuedOn 타임스탬프, 마커 자체의 매니페스트 digest를 명시합니다. 마커는 철회하는 아티팩트의 태그 없는 참조자로 첨부되므로 다른 어떤 것도 이를 가리키지 않습니다. reach도 함께 포함됩니다. 이 요청은 레지스트리에 기록하고 이 머신 밖으로 접속합니다. 레지스트리 접속과 기록을 참조하십시오.
  • aggrega/catalogIndex — 엔터티 인덱스입니다. 요청이 지정한 워크스페이스에 있는 모든 엔터티의 kind, name, apiVersion, description, labels, 소스 파일, origin을 제공합니다. 워크스페이스와, 선택적으로 release를 받습니다. 이 집합은 해당 워크스페이스 루트와 그것이 구성하는 카탈로그 디렉터리의 속성이며, release를 지정하면 구성이 그 Release에 부여하는 디렉터리의 속성입니다. 한 Release의 관점에서 답하기를 참조하십시오. 인덱스는 엔터티가 오는 두 곳, 즉 워크스페이스 루트 아래의 Aggrega 문서와 구성된 카탈로그 디렉터리가 담고 있는 Features를 모두 포괄합니다. 이것은 클라이언트가 엔터티의 설명 필드가 필요할 때 조인하는 인터페이스이며, 둘 중 하나만 아는 인덱스는 모든 후보 목록의 일부를 확인할 수 없는 상태로 남기기 때문입니다. 워크스페이스 문서는 kind:와 metadata.name을 모두 선언하고 다른 프로젝트의 그룹에 속하는 apiVersion을 선언하지 않을 때 엔터티로 간주되므로, 트리에 우연히 있는 YAML(차트의 values 파일, CI 구성, 렌더링된 Kubernetes 매니페스트)은 목록에 오르지 않고 건너뜁니다. apiVersion을 전혀 선언하지 않은 문서는 보고됩니다. 이는 필드가 누락된 Aggrega 문서이며, 목록에 나타나는 것을 보고 고쳐야 할 문서가 있다는 것을 알 수 있습니다. origin과 빈 file의 의미는 엔터티를 지정하는 방법을 참조하십시오. 워크스페이스 루트 밖으로 이어지는 링크 뒤의 문서는 읽지 않습니다. 루트 밖의 디렉터리는 검색하지 않고, 루트 밖의 파일은 무엇을 선언하든 읽지 않으므로, 편집기가 그러한 링크 아래에 표시하는 엔터티는 워크스페이스 자체의 엔터티로 나열되지 않습니다. 같은 문서를 읽는 aggrega/attachCandidates나 aggrega/connectionCandidates도 편집기에서 그 문서가 열려 있는 동안에조차 이를 제시하지 않습니다. 이는 문서가 무엇을 선언하든 마찬가지입니다. 유일한 예외는 워크스페이스 구성이 build.authoring_release로, 또는 workspace.releases의 키로 지정하는 Release입니다. 이는 링크가 가리키는 파일을 기준으로 판단하므로 링크를 지정하든 그 파일을 지정하든 동일하게 간주되며, 이 Release는 링크가 가리키는 파일에서 읽혀 링크 자체의 위치에 aggrega/releaseCandidates가 나열하는 방식대로 나열되고, 이름이 보고되지 않습니다. 이 설정 중 하나가 지정한 파일이 Release 이외의 것을 선언하면 나열되지 않고 그 링크가 보고됩니다. 구성된 카탈로그 디렉터리는 워크스페이스가 다른 곳에 보관된 엔터티를 읽는 방법이므로, 구성이 워크스페이스 또는 Release에 대해 catalog_dirs 아래에 나열한 디렉터리로의 링크는 워크스페이스 자체 문서처럼 검색되지 않고 보고되지도 않습니다. 구성이 이미 그곳에 도달했으며, 그 Features는 구성된 모든 카탈로그 디렉터리의 경우와 같이 카탈로그에서 나열됩니다. 카탈로그 디렉터리에서 나열되는 Features에는 카탈로그 디렉터리의 읽기가 머물러야 하는 디렉터리(워크스페이스 안의 카탈로그 디렉터리라면 워크스페이스, 구성이 워크스페이스 밖에서 지정한 디렉터리라면 그 디렉터리 자체) 밖으로 이어지는 링크 뒤의 것이 결코 포함되지 않습니다. 따라서 응답이 읽지 않은 링크 뒤에 있다고 지정한 엔터티가 그 이름과 함께 나열되는 일은 없습니다. 응답은 그러한 각 링크를, 디렉터리로의 링크는 unreadLinkedDirs에, 자체 이름이 .yaml 또는 .yml로 끝나고 파일로 이어지는 링크는 unreadLinkedFiles에, 루트 기준 링크가 위치한 경로로, 워크스페이스를 검색하는 순서대로 보고하므로 클라이언트는 그 이유를 설명할 수 있습니다. 이름, 위치 또는 .gitignore로 인해 검색에서 제외된 링크는 보고되지 않으며, Release 관점의 응답에서는 다른 Releases만 읽는 카탈로그 디렉터리 아래의 링크도 보고되지 않습니다. 워크스페이스 밖 카탈로그 디렉터리 아래의 링크는 루트 기준으로 보고할 위치가 없으므로 보고되지 않습니다. 두 필드는 항상 존재하며, 해당 링크가 없으면 비어 있습니다. 워크스페이스 자체의 구성 파일 또는 그 옆의 CI 소유 오버레이가 그 자체로 워크스페이스 밖으로 이어지는 링크인 경우, 검색이 그것을 어떻게 처리하든 그 파일은 unreadLinkedFiles에 보고되고, 인덱스는 아무것도 구성되지 않은 상태로 읽은 워크스페이스 자체의 것이 됩니다. 이 경우 카탈로그 디렉터리는 전혀 읽지 않으며, Release 관점의 인덱스는 거부됩니다. 워크스페이스 루트와 활성 Release를 참조하십시오.
  • aggrega/entityDefinition — 지정한 엔터티가 무엇으로 확인되는지를 제공합니다. 그 kind, 자체 name과 version, 있는 경우 description과 publishScope, 선언된 file, 그 뒤에 있는 작성된 텍스트의 authoredLength, 그리고 상속이 이미 적용된 YAML 문서로서의 definition입니다. file은 모든 종류에 대해 열 수 있는 경로로 보고됩니다. 보고된 경로의 표기 방법에 따라 워크스페이스 안의 문서는 워크스페이스 루트 기준 상대 경로로, 밖의 문서는 절대 경로로 표기됩니다. 비어 있는 경우는 하나뿐입니다. 레지스트리에서 확인된 엔터티는 이 머신에 지정할 작성된 문서가 없습니다. authoredLength는 다른 질문, 즉 확인 과정에서 작성된 텍스트를 얼마나 보존했는지에 답하며, Aggregate만 그 값을 가지고 제공되므로 두 값을 한 쌍으로 보지 말고 따로 읽으십시오. name은 엔터티의 식별자로, 한 엔터티가 다른 엔터티를 참조하는 방식으로 작성되며 버전 접미사를 가질 수 있습니다. 이 요청은 커서가 아닌 이름에서 시작하는 유일한 요청이므로, 어떤 엔터티를 의미하는지 이미 알고 있을 때 사용합니다. release는 선택 사항이며 이름을 그 Release의 관점에서 확인합니다. 한 Release의 관점에서 답하기를 참조하십시오. 아무것으로도 확인되지 않는 이름은 빈 문서로 응답되지 않고 거부됩니다. 이름 기반의 두 거부 구별하기를 참조하십시오. name은 대신 레지스트리 참조(oci://<host>/<repository>:<tag>, 또는 :<tag> 대신 @<digest>)일 수도 있으며, 이 경우 응답은 레지스트리에서 읽은, 그 좌표에 게시된 엔터티이고 published가 읽은 대상을 나타냅니다. 좌표에 대해 질의하기를 참조하십시오.
  • aggrega/releaseClosure — Release의 의존성 클로저입니다. 어떤 엔터티에 어떤 확인된 버전으로 도달하는지를 entities, libraries, plugins에 담고, 두 포인터가 확인된 aggregate 및 manifest 식별자, 확인 과정에서 발생한 mappingDiagnostics, 그리고 도달한 대상에 대해 lockfile과 그 옆의 플러그인 신뢰 기록에 기록된 deprecations를 함께 제공합니다. 따라서 판정 역할로 연결된 철회된 플러그인도 철회된 고정 참조와 마찬가지로 명시됩니다. release는 워크스페이스 루트 기준 상대 경로로 그 안의 Release를 지정하며, aggrega/irGraph가 받는 것과 같은 값이고 같은 형태에서 거부되며, 같은 이유로 lockfile이 필요합니다. 아무것도 렌더링되지 않습니다. 항목에는 source가 없습니다. 항목은 한 번의 실행이 한 일이 아니라 Release가 무엇에 의존하는지를 나타내며, 실행이 한 일은 aggrega/resolveDependencies가 보고합니다. 이미 그래프를 받고 있는 클라이언트도 이 정보는 가지고 있지 않으므로 클로저는 그래프가 아닙니다를 참조하십시오.
  • aggrega/attachCandidates — 노드에 어떤 Features를 연결할 수 있는지, 즉 선언된 적용 조건을 노드의 레이블이 충족하는 것들입니다. 좌표는 정확히 하나만 보냅니다. node는 metadata.name으로 워크스페이스 문서를 지정합니다. graphNode는 release의 컴파일된 그래프에 있는 노드를 그 그래프가 키로 사용하는 id로 지정합니다. labels는 레이블 집합을 직접 전달하며 아무것도 지정하지 않으므로, 이미 레이블 집합을 가지고 있는 클라이언트를 위한 것입니다. 응답은 응답 대상이 된 좌표를 되풀이하며(되풀이할 좌표가 없으면 비어 있음), 일치 여부를 평가한 레이블 쌍인 nodeLabels, 그 레이블 집합이 어떤 종류인지 알려 주는 labelSource, 그리고 각 후보를 가리키는 kind, name, 소스 파일, origin을 담습니다. 레이블을 함께 돌려주기 때문에 응답 자체만으로 검증할 수 있습니다. 클라이언트는 노드의 레이블을 스스로 추측하지 않고도 어떤 Feature가 제시된 이유를 설명할 수 있으며, 그런 추측이야말로 클라이언트의 답과 컴파일러의 답이 어긋나는 원인입니다. 그래프 노드의 경우 제시되는 Features는 그 노드의 Release가 도달하는 것들입니다. graphNode와 함께 connection은 그 노드의 component가 그리는 연결 하나를 그 socket과 alias로 지정하며, 이때 응답은 slots도 담습니다. 이는 그 연결의 socket이 선언하는 각 슬롯과 그 슬롯을 채울 수 있는 Features이며, 채울 수 있는 슬롯이 없으면 대신 noSlotReason을 담습니다. attach-candidate 응답이 알려 주는 것을 참조하십시오.
  • aggrega/connectionCandidates — 지정한 엔터티가 무엇에 연결될 수 있는지입니다. node는 엔터티의 metadata.name으로, aggrega/attachCandidates가 같은 이름으로 받는 좌표와 동일합니다. 응답의 두 부분은 완전성이 같지 않으며 응답이 어느 쪽이 어느 쪽인지 알려 주므로, 아래의 connection-candidate 응답이 알려 주는 것을 참조하십시오.
  • aggrega/insertionPoint — 작성된 문서에서 지정한 컨테이너 아래의 새 항목이 들어갈 위치로, 클라이언트가 문서를 직접 파싱하지 않고 적용할 수 있는 형태로 표현됩니다. file은 워크스페이스가 포함하는 문서를 워크스페이스 루트 기준 상대 경로, 절대 경로 또는 file:// 주소로 지정합니다. 루트 밖의 문서는, 쓰인 그대로든 루트 밖으로 나가는 링크(파일로 가는 링크든 경로상의 디렉터리로 가는 링크든)를 통해서든, 어떤 표기로 지정하든 그리고 그 사본을 가지고 있든 없든 거부됩니다. container는 문서 루트에서 항목이 들어갈 컨테이너까지의 구조적 경로이며, 각 요소는 매핑 키이거나 십진수로 쓴 시퀀스 위치입니다. 그 경로는 직접 제공해야 합니다 — 데몬은 문서 자체의 구조를 읽을 뿐, 무엇이 어디에 속하는지를 그 이름으로부터 추론하지 않습니다. 위치만으로는 편집을 적용하기에 충분하지 않으므로 insertion-point 응답이 알려 주는 것을 참조하십시오.
  • aggrega/attachmentContainer — 노드에 대한 Feature 연결이 어느 문서에, 그리고 그 안의 어느 컨테이너에 속하는지를 알려 줍니다. graphNode는 release의 컴파일된 그래프에 있는 노드를 그 그래프가 해당 노드를 키로 삼는 id로 지정하며, 둘 다 필수입니다. 노드 id는 하나의 Release 그래프의 키이므로 그 Release 없이는 의미가 없습니다. 응답에는 node, file, container가 담기며, 이는 aggrega/insertionPoint가 받는 것과 정확히 같은 형태의 세그먼트 목록이므로 두 요청은 중간에 따로 계산할 것 없이 그대로 이어서 사용할 수 있습니다. 노드의 component가 그리는 하나의 connection에 대한 연결이라면 socket, alias, document(aggregate 또는 release)를 갖춘 connection을 추가하면, 응답은 그 문서 안에 있는 해당 connection 자체의 features 컨테이너를 지정합니다. file은 이미 알고 있는 값이 아니라 응답의 일부이므로 attachment-container 응답이 알려 주는 것을 참조하십시오.
  • aggrega/connectionAtPosition — Aggregate 또는 Release 안의 위치가 어느 연결의 항목 안에 있는지를, 위의 두 요청이 연결을 받는 형식으로 답합니다. file은 aggrega/insertionPoint와 같은 방식으로 문서를 지정하며, 세션이 그 문서에 대해 보유한 내용을 먼저 읽습니다. position은 그 안의 위치로, 세션의 인코딩으로 0부터 센 line과 character입니다. release는 컴파일된 그래프에 연결이 기록된 Release를 지정하며, 그래프 노드와 연결은 컴파일된 그래프에만 존재하므로 Aggregate 안의 위치에 대해서도 필수입니다. 응답은 aggrega/attachCandidates와 aggrega/attachmentContainer에 그대로 넘길 graphNode와 connection(그 socket, alias, 위치를 읽은 document)을 담거나, 그곳에 쓰인 연결이 없으면 noConnectionReason을 담습니다. connection-at-position 응답이 알려 주는 것을 참조하십시오.
  • aggrega/editDocument — 작성된 문서에 범위가 제한된 구조적 편집 하나를 적용하며, 건드리지 않는 모든 바이트를 보존합니다. 위의 두 위치 탐색 메서드와 짝을 이룹니다. 그 메서드들은 항목이 들어갈 위치를 알려 주고 구성과 적용은 맡기지만, 이 메서드는 직접 구성하고 적용합니다. edit은 add-component, attach-feature, wire-edge, set-value 네 가지 중 하나를 지정하며, 그 밖의 값은 해석하지 않고 거부합니다. node는 문서 루트로부터의 구조적 경로로, aggrega/insertionPoint가 받는 것과 정확히 같은 형태의 세그먼트 목록입니다. name은 항목이 쓰일 키이고 value는 그 항목이 담는 내용이며, 그 의미는 edit에 따라 정해집니다. socket은 wire-edge일 때 읽고 그 밖에는 무시합니다. dryRun은 쓰기를 제외하고 일반 요청이 하는 모든 일을 수행하며, 결과를 먼저 작성자에게 보여 주는 클라이언트를 위해 편집된 문서를 content로 반환합니다. 이 경우 아무것도 생성되지 않으며 written은 비어 있습니다. file은 문서를 워크스페이스 루트 기준 상대 경로 또는 절대 경로로 지정하며, 루트 밖의 문서는 쓰인 그대로든 루트 밖으로 나가는 링크(파일로 가는 링크든 경로상의 디렉터리로 가는 링크든)를 통해서든 아무것도 읽거나 쓰지 않은 채 거부됩니다. 이 메서드는 워크스페이스 안에서 지정한 문서에 씁니다 — 어느 전달 방식에서도 의존성을 해석하지 않고, 레지스트리에 접근하지 않으며, 네트워크를 사용하지 않습니다. 또한 쓰기는 구성된 문서가 자기 kind의 스키마에 대해 검증을 통과해야만 이루어집니다. 기본 동작은 쓰기이며 거부되면 파일이 바이트 단위까지 그대로 남으므로 document-edit 응답이 알려 주는 것을 참조하십시오.
  • aggrega/releaseCandidates — 요청이 지정한 워크스페이스의 Release 문서를 절대 경로로 반환합니다. 워크스페이스 외에는 아무것도 받지 않습니다. 이 집합은 해당 워크스페이스 루트의 속성이기 때문입니다. 포함 여부는 파일 이름이 아니라 문서 종류, 즉 파일의 kind:가 Release인지로 결정되므로, 관례적인 접두사 없이 이름 붙인 Release도 제공되며, 이름만 Release처럼 붙은 파일은 제공되지 않습니다. 편집기의 “어떤 Release?” 선택기가 나열해야 하는 것이 바로 이 집합입니다. 아래의 활성 Release 단계적 결정이 고르는 대상과 같은 집합이기 때문입니다. 응답에는 lockfiles도 포함됩니다. 이 필드는 나열된 각 Release를 releases가 나열한 문자열 그대로를 키로 하여 해당 lockfile의 절대 경로에 매핑하며, 항상 존재하고 워크스페이스에 Release가 없으면 빈 객체입니다. unreadLinkedDirs도 포함됩니다. 이 필드는 목록 작성이 디렉터리를 읽을 위치에 있으면서 워크스페이스 루트 밖의 디렉터리로 이어지는 각 링크를, 링크가 놓인 위치 기준으로 루트에 대한 상대 경로로 지정합니다. 루트 밖의 디렉터리는 검색하지 않으므로, 편집기가 그런 디렉터리 안에 보여 주는 Release는 나열되지 않으며, 이 필드가 있어야 선택기가 그 이유를 설명할 수 있습니다. 워크스페이스 구성이 catalog_dirs에 나열한 디렉터리로 이어지는 링크는 지정되지 않습니다. 구성이 그 디렉터리에 Releases를 보관하는 장소로서가 아니라 카탈로그 디렉터리로서 이미 도달했기 때문입니다. 이 필드는 항상 존재하며, 그런 링크가 없으면 비어 있습니다. 그 옆의 unreadLinkedFiles는 같은 방식으로, 자체 이름이 .yaml 또는 .yml로 끝나고 워크스페이스 루트 밖의 파일로 이어지는 각 링크를 지정합니다. 그런 파일은 내용과 상관없이 읽지 않으므로, 이런 링크로만 도달하는 Release는 나열되지 않고, 아래 단계적 결정의 단일 Release 단계에서도 세지 않습니다. 예외는 워크스페이스 구성이 Release로 지정한 파일입니다. 즉 build.authoring_release로, 또는 workspace.releases의 키로 지정한 파일이며, 링크가 이어지는 파일을 기준으로 판단하므로 링크를 지정하든 그 파일을 지정하든 똑같이 인정됩니다. 이런 파일은 Release를 선언하는 경우 링크 자체의 위치에서 읽혀 나열되고 지정되지 않습니다. 다른 것을 선언하는 파일은 나열되지 않으며 그 링크가 지정됩니다. 이 필드는 항상 존재하며, 그런 링크가 없으면 비어 있습니다. 워크스페이스 자체의 구성 파일이나 그 옆의 CI 소유 오버레이가 그 자체로 워크스페이스 밖으로 이어지는 링크인 경우, 검색이 그 파일을 어떻게 다루든 해당 파일은 여기에 지정되며, 목록은 아무것도 구성되지 않은 상태로 읽히므로 구성이 링크를 통해 지정했을 Release는 나열되지 않습니다. 워크스페이스 루트와 활성 Release를 참조하십시오. Release의 lockfile 위치를 참조하십시오.
  • aggrega/activeRelease — 요청이 지정한 워크스페이스가 가리키는 Release를 release 필드에 절대 경로로 반환하며, 기본으로 무엇을 선택할지 결정하는 클라이언트를 위한 것입니다. 워크스페이스 외에는 아무것도 받지 않습니다. 이 필드는 항상 존재하며, 빈 값은 워크스페이스가 아무것도 가리키지 않음을 뜻합니다. 이는 오류가 아니라 성공한 응답이므로, 데몬이 재시작할 때마다 이를 새로 고치는 클라이언트가 평범한 워크스페이스를 실패로 처리하게 되지 않습니다. 값이 비어 있으면 응답에는 단계적 결정이 무엇을 찾았는지에 대한 한 줄 요약인 reason과 단계별 기록인 trace도 포함되며, Release가 결정되면 둘 다 생략됩니다. Release가 결정되면 응답에는 대신 해당 Release의 lockfile 절대 경로인 lockfile이 포함되며, 결정되지 않으면 생략됩니다. 이 응답이 지정하는 Release는 aggrega/releaseCandidates가 나열하는 것일 필요가 없습니다. 마커는 vendor/처럼 그 목록이 제외하는 디렉터리의 Release나 YAML 확장자 없이 이름 붙은 Release를 지정할 수 있으므로, 클라이언트는 기본 Release의 lockfile을 이 응답에서 읽습니다. Release의 lockfile 위치를 참조하십시오. 단계적 결정의 입력 중 하나에서 답을 직접 도출하지 말고 이 요청으로 물어보십시오. 단계적 결정이 최종적으로 사용하지 않은 입력은 선택된 것과 다른 Release를 지정합니다. 응답은 요청 시점에 계산되므로, 마커를 쓰거나 구성을 편집하거나 Release 파일을 추가한 뒤 다시 물으면 데몬 시작 시점의 워크스페이스가 아니라 새로운 답이 보고됩니다.
  • aggrega/setActiveRelease — 요청이 지정한 워크스페이스의 .aggrega/active-release 마커를 작성하여 Release를 해당 워크스페이스의 기본값으로 기록하고, 마커가 작성된 뒤 aggrega/activeRelease가 응답하는 것과 정확히 같게 응답합니다. 워크스페이스와 release를 받습니다. 이는 워크스페이스 안의 Release를 지정하는 워크스페이스 루트 기준 상대 경로이며, aggrega/irGraph의 release와 같은 계약을 따릅니다. 절대 경로, 워크스페이스 밖으로 올라가는 경로, 빈 값은 거부되며, 워크스페이스 구성이 그 Release를 지정하지 않는 한 링크를 통해 밖으로 이어지는 경로도 거부됩니다. 마커는 루트 기준으로 Release를 지정하는 한 줄로, 아래 단계적 결정이 읽는 형식입니다. 마커는 워크스페이스 안에만 작성됩니다. .aggrega나 마커 자체가 워크스페이스 밖으로 이어지는 링크이면, 이어지는 대상이 이미 존재하는지와 관계없이 요청은 invalid-params 오류로 거부됩니다. 그 메시지는 해당 조건의 문장 앞에 짧은 코드를 붙인 E0320: …(fatal-halts.md §“A path the operation writes leads through a link out of the directory it must stay inside(작업이 쓰는 경로가 링크를 통해 머물러야 할 디렉터리 밖으로 이어짐)”)이며, 링크와 그 대상을 지정하고, 아무것도 작성되지 않습니다. 워크스페이스 안에 머무는 링크는 그대로 따라가 작성됩니다. 응답은 보낸 값을 되돌려 주는 것이 아니라 단계적 결정이 최종적으로 정한 것을 지정하며, build.authoring_release가 Release를 지정하는 경우 둘은 다릅니다. 구성이 마커보다 우선하기 때문입니다. 파일을 직접 작성하지 말고 이 방법으로 기본값을 기록하십시오. 그래야 마커가 놓이는 위치가 제품이 워크스페이스에 작성하는 모든 파일에 적용되는 규칙에 따라 판단됩니다. 워크스페이스 경계를 참조하십시오.
  • aggrega/effectiveConfiguration — 요청이 지정한 워크스페이스에 적용되는 구성과 각 설정이 비롯된 계층을 반환합니다. 워크스페이스 외에는 아무것도 받지 않습니다. 응답은 해당 워크스페이스의 속성이기 때문입니다. layers는 기여한 구성 파일과 환경 재정의를 우선순위가 낮은 것부터 나열합니다. settings는 출처가 확인된 각 설정을 점으로 구분된 이름, 유효 값, 그리고 이를 결정한 source로 담습니다. source는 layers의 해당 항목과 정확히 같은 철자로 적히므로 둘을 바로 연결할 수 있습니다. source가 어느 계층을 지정하는지와 각 행이 뜻하는 바의 한계는 유효 구성 응답이 다루는 범위를 참조하십시오.
  • aggrega/configInit — 레지스트리와 그 서명 신뢰 정책을 등록하여 작동하는 구성을 초기화하므로, 새 머신에서 YAML을 직접 편집하지 않고도 서명된 아티팩트를 가져와 검증할 수 있습니다. registry는 선택 사항이며, 값이 없으면 aggrega config init과 같은 기본값인 공식 허브로 초기화합니다. 응답의 host는 실제로 사용된 쪽을 나타냅니다. global과 workspace는 쓰기 대상 재정의이며 둘을 함께 보내면 거부됩니다. 이 요청은 기존 구성 파일을 덮어쓰지 않고 거부하며, 해당 파일을 명시합니다. 그래도 진행하려면 force를 보내십시오. 이 경우 레지스트리 항목이 기존 내용에 병합되고 다른 설정은 보존됩니다. dryRun은 쓰기를 제외하고 일반 요청이 하는 모든 작업을 수행하며, 초기화된 구성을 content로 응답합니다. 이는 문서를 저장하기 전에 작성자에게 보여 주는 클라이언트를 위한 것으로, 이때는 아무것도 생성되지 않고 written은 false입니다. 기존 파일 거부는 dryRun에서도 적용되므로, 덮어쓰는 쓰기가 만들어 낼 병합 결과를 응답으로 받으려면 force를 함께 보내십시오. 오프라인 워크스페이스에서는 공식 허브만 초기화할 수 있습니다. 이 요청은 신원이나 키를 받지 않으므로, 다른 레지스트리는 aggrega/registryAdd가 거부하는 것과 똑같이 짧은 코드와 문장까지 포함하여 거부되며, 대신 해당 요청을 통해 직접 제공한 정책과 함께 추가해야 합니다. 응답에는 host, scope, trust, written이 담기고, 구성 파일이 이미 있었던 경우 true가 되는 existed도 담깁니다. 이 경우 새 파일을 만드는 대신 레지스트리 항목이 기존 파일에 병합되며, 파일이 새로 생성되는 경우에는 이 필드가 없습니다. 이 요청은 기본적으로 전역 구성에 씁니다 — 레지스트리 접근과 쓰기를 참조하십시오.
  • aggrega/configCapture — 유효한 빌드 핵심 구성을 이 워크스페이스 자체의 구성 파일에 고정하여, 머신의 전역 구성이 없어도 워크스페이스가 동일하게 빌드되도록 합니다. 쓰기 대상을 받지 않습니다. 고정은 하나의 워크스페이스를 자급적으로 만들기 위한 것이므로 항상 해당 워크스페이스의 파일에 씁니다. allPlugins는 고정 대상을 렌더링 출력을 결정하는 소켓(프로바이더 바인딩과 label-transform 거버넌스 연결)에서 모든 플러그인 소켓으로 넓히며, verdict 거버넌스와 린터 게이트, 임포트 소켓을 추가합니다. 응답에는 configFile, workspaceRoot, captured, sockets, catalogDirs가 포함됩니다. 응답은 이제 존재하는 문서를 가리키며 클라이언트의 다음 동작은 그 문서를 여는 것이므로, 구성 쓰기가 남기는 것을 참조하십시오.
  • aggrega/skillsInstall — 이 바이너리에 내장된 Aggrega 스킬을 요청이 지정하는 각 어시스턴트의 스킬 폴더에 씁니다. 이는 aggrega skills install이 터미널에서 수행하는 것과 같은 설치입니다. agents는 어시스턴트를 식별자로 나열합니다. 식별자는 aggrega/skillsList가 보고하는 것입니다. 두 번 주어진 식별자는 한 번만 설치되며, 지정된 어시스턴트 중 여럿이 하나의 공유 폴더를 읽는 경우 스킬은 그곳에 한 번만 쓰입니다. 프로젝트 설치에는 이 필드가 필수입니다. 어시스턴트를 하나도 지정하지 않은 global 요청은 --agent 없이 실행한 aggrega skills install --global과 마찬가지로 이 머신에서 찾은 어시스턴트, 즉 구성 폴더가 홈 디렉터리에 있거나 명령이 데몬 환경의 PATH에 있는 각 어시스턴트를 위해 설치하며, 하나도 찾지 못하면 아무것도 쓰지 않고 거부됩니다. 입력을 요청하는 일은 없으며, installed가 스킬을 쓴 어시스턴트를 알려 줍니다. global이 없으면 스킬은 각 어시스턴트의 프로젝트 폴더 중 요청이 지정하는 워크스페이스 안의 폴더에 들어가며, 데몬이 시작된 디렉터리에는 절대 들어가지 않습니다. global: true이면 데몬 환경이 지정하는 홈 디렉터리(HOME, Windows에서는 USERPROFILE) 아래의 각 어시스턴트 사용자별 폴더에 들어갑니다. 무엇이든 쓰기 전에 모든 대상을 확인하므로, 거부되면 모든 폴더가 그대로 남습니다. 알려진 스킬 폴더가 없는 식별자는 그 식별자와 사용 가능한 식별자들을 명시하여 거부되며, 대상에 있는 파일이 스킬을 쓴 모든 사본에 있는 주석 줄을 지니지 않으면 그 경로를 명시하여 거부됩니다. 그 줄을 지닌 사본(이전 설치가 쓴 것이거나 게시된 스킬 저장소에서 가져온 것)은 교체되며, 이것이 더 새로운 aggrega가 스킬을 자신의 버전으로 올리는 방식입니다. 워크스페이스 밖으로 이어지는 링크를 통해 도달하는 프로젝트 폴더는 데몬이 워크스페이스에서 하는 모든 쓰기와 마찬가지로 아무것도 쓰지 않고 거부됩니다. 워크스페이스 경계를 참조하십시오. 응답에는 skill, installed(쓴 폴더당 하나의 항목이며, 어시스턴트가 지정된 순서대로 나열되고, 각각 그 폴더를 읽는 agents, 절대 경로 folder, replaced를 지님), scope가 포함됩니다. global을 사용하면 머신의 모든 프로젝트가 읽는 폴더에 씁니다. 레지스트리 접근과 쓰기를 참조하십시오.
  • aggrega/skillsList — 이 바이너리가 제공하는 스킬과, aggrega/skillsInstall이 그 스킬을 써 줄 수 있는 모든 어시스턴트로, aggrega skills list가 출력하는 목록입니다. 워크스페이스만 받으며 그 워크스페이스에서 아무것도 읽지 않습니다. skills는 각 스킬의 name과 description을 담고, agents는 각 어시스턴트의 id, name, projectFolder(프로젝트 루트 기준 상대 경로이며, 이 인터페이스에서 프로젝트 루트는 요청이 지정하는 워크스페이스), userFolder(홈 디렉터리 기준 상대 경로)를 담습니다. 두 경로 모두 슬래시로 구분되며, 식별자 순으로 정렬됩니다. 아무것도 쓰지 않고 어디에도 접근하지 않습니다.
  • aggrega/pluginAdd — 구성된 레지스트리에서 지정한 유형의 플러그인을 검색하여 구성에 추가합니다. type과 query는 모두 필수입니다. type은 provider, governance, linter, importer, cli 중 하나이며, query는 해당 유형의 플러그인 이름과 대조되어 정확히 하나로 결정되어야 합니다. 따라서 여러 개와 일치하는 쿼리는 임의로 결정되지 않고 후보 목록과 함께 거부됩니다. capability는 provider 바인딩이 제공하는 기능을 지정하며 해당 유형에서 필수입니다. role은 governance 연결의 역할(label-transform, ir-verdict 또는 render-verdict)을 지정하며 해당 유형에서 필수입니다. 각 필드는 해당 유형에서만 읽히고 다른 유형에서는 거부됩니다. 아무 일도 하지 않는 필드가 조용히 무시되면 마치 작동한 것처럼 보이기 때문입니다. acceptCapabilities는 cli에 필수이며 해당 플러그인이 선언한 기능을 승인합니다. 터미널 명령은 이 결정을 사용자에게 물어서 얻지만 이 인터페이스에는 물어볼 사람이 없으므로, 호출자가 결정을 얻어 보내야 합니다. global과 workspace는 쓰기 대상 재정의이며, 둘을 함께 보내면 거부됩니다. dryRun은 쓰기를 제외하고 일반 요청과 동일한 작업을 모두 수행하며, 결과 구성을 content로 응답합니다. 아무것도 생성되거나 수정되지 않으며 written은 false입니다. 이때도 레지스트리를 검색하고 버전을 결정합니다. 해당 내용의 식별자는 쓰기가 고정했을 식별자이기 때문입니다. dryRun은 cli 유형에서 무시되지 않고 거부됩니다. 명령 확장 추가가 기록하는 것은 검증한 바이트의 콘텐츠 다이제스트로, 누군가 편집하는 내용이 아니라 컴파일러가 유지하는 기록이며, 추가 과정에서 해당 바이트를 캐시하므로 응답으로 돌려주지 않고 기록합니다. 버전은 자동으로 고정됩니다. 쿼리는 하나의 플러그인으로 결정되고, 쿼리가 <name>:<version>으로 지정한 버전이, 지정하지 않았다면 그 플러그인의 게시된 최상위 버전이 항목에 기록됩니다. 지정된 버전은 이 워크스페이스가 신뢰하는 철회 선언이 철회했더라도 그대로 고정되며, 응답에 withdrawn: true가 포함됩니다. 이 요청은 레지스트리에 접근하며, 범위를 지정하지 않은 cli 유형 추가는 전역 구성에 씁니다 — 레지스트리 접근과 쓰기를 참조하십시오. 플러그인 변경이 알려 주는 것을 참조하십시오.
  • aggrega/pluginRemove — 구성된 플러그인의 항목을 제거하여 더 이상 참여하지 않게 합니다. type은 추가와 동일한 집합을 받으며, query는 항목을 식별합니다. 플러그인의 짧은 이름, 고정된 참조, 또는 provider의 경우 바인딩이 제공하는 기능입니다. 둘 다 필수입니다. global과 workspace는 동일한 쓰기 대상 재정의이며, 같은 방식으로 함께 보내면 거부됩니다. 어떤 항목과도 일치하지 않는 쿼리는 변경되지 않은 구성에 대한 성공으로 응답되지 않고 거부됩니다. 따라서 플러그인이 참여를 멈추지 않았는데 멈췄다고 호출자에게 알리는 일이 없으며, 오타로 다른 플러그인이 제거되는 일도 없습니다. 레지스트리에 접근하지 않습니다. 제거는 구성 텍스트에만 작용합니다. 범위를 지정하지 않은 cli 유형 제거는 전역 구성에 씁니다 — 레지스트리 접근과 쓰기를 참조하십시오. 플러그인 변경이 알려 주는 것을 참조하십시오.
  • aggrega/pluginSync — Plugin 엔터티의 머신 소유 기록을 해당 모듈에 맞춥니다. 즉, 모듈 자체의 임포트에서 도출한 호스트 함수 집합과 모듈의 자기 보고에서 읽은 명령 미러입니다. 두 기록 모두 실제 근거가 모듈에 있으므로 직접 작성하지 않습니다. 두 필드는 모두 필수이며 어느 쪽도 기본값이 없습니다. 기록은 모듈에서 도출되므로, 아무것도 지정하지 않은 정렬에는 맞출 대상이 없기 때문입니다. 두 필드 모두 워크스페이스 루트 기준의 상대 경로이며, 절대 경로이거나 작성된 그대로 또는 링크를 통해 루트 밖으로 해석되면 거부됩니다. 이 두 블록만 변경됩니다. 나머지 모든 바이트는 주석, 빈 줄, 인용 스타일까지 포함하여 그대로 유지되며, 이미 모듈이 의미하는 내용을 기록하고 있는 파일은 바이트 단위로 동일하게 남고 변경 없음으로 보고됩니다. 이 요청은 워크스페이스 안에서 지정한 엔터티 파일에 쓰며, 레지스트리에는 접근하지 않습니다. 플러그인 변경이 알려 주는 것을 참조하십시오.
  • aggrega/pluginGenCatalog — 선택한 게스트마다 Plugin 엔터티를 하나씩 생성하며, 게스트의 자체 보고에서 도출한 계약 필드를 작성된 플러그인별 오버레이와 병합합니다. fromEmbedded와 plugin은 두 가지 선택 모드이며 정확히 하나만 적용됩니다. 이 바이너리가 포함하는 모든 게스트이거나, 지정한 경로에 있는 모듈 하나입니다. 둘 다 지정하거나 둘 다 지정하지 않으면 임의로 해석하지 않고 거부됩니다. overlay는 필수이며, fromEmbedded에서는 오버레이 디렉터리이고 plugin에서는 단일 오버레이 파일입니다. 게스트가 여럿이면 오버레이는 ID로 게스트와 대응되고, 하나뿐이면 대응할 것이 없습니다. outputDir는 두 전달 방식 모두에서 필수이며 dryRun도 이를 면제하지 않습니다. 드라이 런은 내용이 어디로 가는지를 바꿀 뿐 어느 파일을 위한 내용인지를 바꾸지 않으므로, 반환되는 각 문서는 여전히 자신이 대상으로 하는 경로를 명시하고 그 경로는 이 디렉터리로부터 구성됩니다. 여기서 세 경로는 같은 방식으로 판단되지 않으며, 그 구분은 생성 과정이 각 경로로 무엇을 하는지에 따릅니다. plugin과 overlay는 읽히며 둘 다 직접 선택한 파일입니다. 모듈은 툴체인이 빌드하는 디렉터리 아래에 놓이고 그 오버레이는 모듈 옆에 작성되므로, 각각 절대 경로일 수 있으며 실제 위치에서 읽힙니다. outputDir는 쓰기 대상이므로 워크스페이스 루트 기준 상대 경로이며, 절대 경로이거나 작성된 그대로 또는 링크를 통해 루트 밖으로 해석되면 거부됩니다. 밖으로 이어지는 링크된 디렉터리 아래에 아직 만들어지지 않은 디렉터리는 그 링크된 디렉터리와 마찬가지로 거부됩니다. 변경되지 않은 입력으로 다시 실행하면 바이트 단위로 동일한 엔터티가 생성됩니다. 이 요청은 dryRun이 내용으로 요청하지 않는 한 생성된 엔터티를 워크스페이스 안의 outputDir 아래에 씁니다. 플러그인 변경이 알려 주는 것을 참조하십시오.
  • aggrega/getSchema — 엔터티 또는 계약 종류의 JSON Schema로, 실행 중인 바이너리에 컴파일된 사본에서 읽습니다. kind는 소문자 하이픈 형식의 스키마 토큰(component, aggregate, release, recipe, ir, wasm-provider 등)이며, 두 질문 중 어느 것을 묻는지를 선택하므로 선택 사항입니다. 종류를 지정하면 응답에 kind와 schema가 담기며, 스키마는 그것을 담은 문자열이 아니라 JSON 문서로 제공됩니다. 지정하지 않으면 응답에 대신 kinds와 entityKinds가 담깁니다. 이는 지정할 수 있는 종류를 두 가지 범위로 알려 줍니다. kinds는 이 바이너리에 요청할 수 있는 모든 토큰이며, aggrega get-schema --list가 출력하는 것과 같은 순서입니다. entityKinds는 작성자가 문서를 작성하는 더 좁은 집합으로, 각 항목에는 다시 보낼 kind 토큰, 문서 자체의 kind: 필드에 들어가는 documentKind 값, 그리고 단일 엔터티 검증, 게시, 이름별 검사가 해당 종류의 문서를 받아들이는지를 나타내는 acceptedBy가 담깁니다. 둘 중 어느 것으로든 선택기를 만들기 전에 작성자에게 제시할 수 있는 종류를 참조하십시오. 스키마 응답과 열거는 결코 함께 제공되지 않으므로, 어느 질문에 답했는지를 응답에서 알 수 있습니다. 어떤 스키마에도 해당하지 않는 토큰은 유효한 전체 집합을 메시지에 담아 거부되므로, 두 번째 호출 없이 오타를 바로잡을 수 있습니다. 워크스페이스에서 아무것도 가져오지 않고, 레지스트리에 접속하지 않으며, 아무것도 쓰지 않으므로 아무것도 없는 워크스페이스에서도 응답합니다. 덕분에 다른 곳에 설치된 스키마 사본이 아니라 편집기가 실제로 구동하는 바이너리를 기준으로 편집기의 스키마 연결을 구성하는 데 사용할 수 있습니다.
  • aggrega/scaffoldEntity — 엔터티 종류의 시작 문서로, 해당 종류의 스키마가 요구하는 필드만 정확히 담고, 고정된 apiVersion과 kind를 채우며, 값이 필요한 모든 곳에 자리 표시자를 넣습니다. kind는 필수이며 소문자 하이픈 형식의 스키마 토큰(component, aggregate, release, recipe, manifest, feature 등)입니다. kind 없이 aggrega/getSchema를 호출하면 보낼 수 있는 토큰을 알려 주며, 어떤 스키마에도 해당하지 않는 토큰은 그 집합을 메시지에 담아 거부되므로 두 번째 호출 없이 오타를 바로잡을 수 있습니다. 작성자에게 종류 선택을 제시하는 클라이언트는 해당 메서드의 entityKinds를 읽으며, 이는 문서를 작성할 수 있는 종류의 집합입니다. name은 선택 사항이며, 스키마가 요구하는 종류에 대해 metadata.name을 채웁니다. 응답에는 kind와 skeleton이 담깁니다. 응답은 작성된 문서가 아니라 작성할 문서이므로 스캐폴드 응답이 제공하는 것을 참조하십시오. 스켈레톤은 aggrega/getSchema가 보고하는 것과 같은 스키마에서 도출되므로, 두 메서드는 하나의 출처에서 응답합니다. kind 대신 example을 보내면 문서의 실행 가능한 예제 중 하나를 워크스페이스의 새 디렉터리에 씁니다. 이는 aggrega scaffold --example이 터미널에서 하는 것과 같습니다. list: true만 보내면 존재하는 모든 예제로 응답하며 아무것도 쓰지 않습니다. 두 형식 모두 워크스페이스가 필요하므로, 어느 쪽 요청이든 workspaceRoot에 워크스페이스를 지정하며, 지정하지 않은 요청은 거부됩니다. dir은 새 디렉터리를 워크스페이스 루트 기준 상대 경로로 지정하며, 기본값은 예제의 이름입니다. 절대 경로 값이나 루트 밖으로 해석되는 값(쓰인 그대로든 링크를 통해서든)은 무엇이든 읽기 전에 거부되며, 무엇이든 들어 있는 디렉터리는 거부되고 그대로 남습니다. 목록에 대한 응답에는 examples가 담기며 각 항목에는 name, level, summary가 있습니다. 쓰기에 대한 응답에는 example, dir, files(쓴 각 파일로, dir 기준 상대 경로), next(예제 페이지가 제시하는 빌드 명령으로, 제시하지 않으면 없음), version(예제를 읽어 온 문서 버전)이 담깁니다. 두 형식의 필드를 함께 보내면(kind와 example, list와 example 또는 kind, name과 example 또는 list, 또는 example 없는 dir) 무엇이든 읽기 전에 어시스턴트 도구가 거부할 때와 같은 문구로 거부됩니다. 쓰기는 워크스페이스 자체의 서명 검사가 허용하는 사본이 머신에 없으면 문서 번들을 가져오며, 워크스페이스 안에 씁니다 — 레지스트리 접근과 쓰기를 참조하십시오.
  • aggrega/import — 외부 소스 기술을 Aggrega 작성 파일 초안으로 변환하며, 터미널에서 aggrega import가 수행하는 것과 같은 변환입니다. source는 필수이며 변환할 파일 또는 디렉터리를 절대 경로나 워크스페이스 루트 기준 상대 경로로 지정합니다. 다른 도구가 내보낸 기술은 저장한 위치에 있으므로, 이 경로는 워크스페이스 안에서만이 아니라 실제 위치에서 읽힙니다. 디렉터리는 aggrega import가 읽는 방식대로 읽힙니다. 즉 임포터가 선언한 파일 패턴이 선택하는 파일을 읽되 워크스페이스의 빌드 출력 폴더인 dist/는 제외하고, 어디에 있든 그 디렉터리 자체에 한정되므로 내부의 어떤 링크도 디렉터리 밖으로 따라가지 않습니다. outputDir는 선택 사항으로 초안이 들어갈 디렉터리를 지정하며, 이 계약을 따르지 않습니다. 쓰기 대상이므로 워크스페이스 안의 경로여야 하며, 절대 경로이거나 작성된 그대로 또는 링크를 통해(링크 아래에 아직 만들어지지 않은 디렉터리 포함) 루트 밖으로 해석되는 값은 거부됩니다. 생략하면 초안은 aggrega import가 대상을 지정하지 않을 때 쓰는 위치인 워크스페이스 루트 아래로 가며, dryRun에서도 마찬가지입니다. format은 소스 형식을 명시적으로 지정합니다. 생략하면 임포터가 선언한 시그니처(워크스페이스 카탈로그의 임포터와 컴파일러의 코어 임포터 모두)로 형식을 인식하며, 어느 것도 인식하지 못하거나 둘 이상의 형식의 임포터가 인식하는 소스는 추측하지 않고 format을 요청하며 거부됩니다. target은 compose나 helm 같은 프로바이더 기능(Recipe의 spec.capability가 바인딩하는 단어)을 지정하며, aggrega import --target과 똑같이 임포터의 초안과 함께 초안 Release가 해당 프로바이더에 대해 빌드할 Manifest의 초안을 만듭니다. 이는 manifest.yaml로, 초안이 필요로 하는 각 컴포넌트 유형과 피처 유형(초안 Aggregate가 구성하는 카탈로그 Aggregate의 유형 포함)을 워크스페이스 카탈로그가 그 유형에 제공하는 해당 기능의 Recipe 또는 피처 레시피에 버전 없이 기능 한정 이름으로 매핑합니다. 하나만 있으면 그것을, 여럿 있으면 그 유형의 이름을 딴 것을 사용합니다. Release의 spec.manifest는 이 파일로 설정됩니다. 해당하는 것이 없거나, 여럿 있지만 그렇게 이름 붙은 것이 없는 유형은 매핑되지 않은 채 남고 이를 명시하는 warn 발견 사항이 보고되며, 임포터가 직접 초안으로 만든 매핑은 카탈로그가 그 유형과 기능에 대해 제공하는 경우 유지되고 그렇지 않으면 warn 발견 사항과 함께 삭제됩니다. 카탈로그의 어떤 Recipe도 바인딩하지 않는 target은 임포터가 실행되기 전에 거부되며, 해당 값과 카탈로그의 Recipes가 바인딩하는 기능을 명시하고 아무것도 쓰지 않습니다. 생략하면 Manifest 초안은 만들어지지 않습니다. 다만 sync에서는 이전 임포트 기록이 지정하는 대상에 대해 초안을 만듭니다. 머신에 아직 없는 코어 임포터는 그것이 필요한 첫 임포트에서 가져옵니다. 임포트 응답이 알려 주는 것을 참조하십시오. dryRun은 쓰기를 제외하고 일반 요청이 하는 모든 것을 수행하며, 초안을 먼저 작성자에게 보여 주는 클라이언트를 위해 초안을 내용으로 응답합니다. 이 경우 아무것도 생성되지 않으며 written은 비어 있습니다. sync는 aggrega import --sync와 같이 이전 임포트가 outputDir에 만든 초안을 소스에 맞게 갱신하며, 임포트가 쓴 것만 변경합니다. 이것이 없으면 초안이 이미 있는 Aggregate를 덮어쓰게 되는 요청은 거부됩니다. 응답에는 format, outputDir, written, files, drift, diagnostics, decisions, halted가 담깁니다. 임포터가 완전히 변환하지 못한 소스도 오류가 아니라 성공 응답이므로 임포트 응답이 알려 주는 것을 참조하십시오.
  • aggrega/explainError — 코드가 가리키는 조건에 대해 컴파일러가 선언하는 내용과, 작성 시 수정 방법을 알려 주는 게시된 항목을 반환합니다. code는 필수이며 조건의 두 식별자 중 하나를 받습니다. 진단이 shortCode에 담는 짧은 코드이거나 code에 담는 설명형 코드입니다. 이 요청은 이 통신에서 진단이 이미 담고 있는 코드를 풀어 설명하는 것이며, aggrega explain이 터미널에 출력하는 것과 같은 답입니다. 답에는 항상 조건, 즉 shortCode, code, message가 담깁니다. 이 정도는 바이너리 안에 선언되어 있어 네트워크가 필요 없기 때문입니다. entries에는 게시된 해설이 담기며, 해설이 없는 경우에는 note가 그 이유를 알려 줍니다. 워크스페이스 자체의 서명 검사가 받아들이는 사본을 머신이 갖고 있지 않으면, 이 요청은 문서 번들을 가져옵니다. 레지스트리 접근과 쓰기를 참조하십시오. 진단이 담은 코드 풀어 보기를 참조하십시오.
  • aggrega/invalidate — 편집기의 파일 감시기가 보내는 캐시 무효화 신호입니다.

알림:

  • $/cancelRequest — 클라이언트에서 서버로: 해당 id로 보낸 진행 중인 요청을 중지합니다. 데몬은 그 요청의 작업을 취소합니다. 작업은 취소를 즉시가 아니라 다음 단계 경계에서 인지하므로, 이미 진행 중인 작업은 잠시 더 실행됩니다. 실행 중인 것이 없는 id를 취소하는 것은 아무 영향이 없는 안전한 동작입니다.
  • $/progress — 서버에서 클라이언트로: 오래 걸리는 작업이 진행되는 동안 무엇을 하고 있는지를, 요청이 보고받겠다고 지정한 토큰으로 알립니다. 토큰을 담은 요청에 대해서만 전송됩니다. 오래 걸리는 작업 지켜보기를 참조하십시오.
  • aggrega/shutdown — 협조적 종료 절차를 시작합니다. 진행 중인 요청은 완료되고, 새 요청은 거부되며, 그다음 데몬이 종료됩니다.
  • aggrega/publishDiagnostics — 서버가 푸시하는 진단 집합입니다(lockfile 드리프트 경고와 시작 시점 상태에 사용됩니다). 각 항목에는 데몬의 진단 계층 중 어느 것이 그 항목을 제기했는지 나타내는 source가 담깁니다. 작성된 문서에 대한 발견 사항은 aggrega, 빌드가 제기한 권고는 aggrega-build(빌드가 제기한 모든 권고이며, aggrega build가 출력하는 것과 같은 집합입니다), 게시 관례에 대한 발견 사항은 aggrega-lint(aggrega lint가 출력하는 것과 같은 발견 사항)입니다. 이 필드는 모든 항목에 항상 존재하므로, 클라이언트는 구분 없는 하나의 목록을 보여 주는 대신 항목을 묶을 수 있으며, source가 없는 경우를 계층 중 하나와 구별할 필요가 전혀 없습니다. 프레임은 파일의 집합이 이 클라이언트가 마지막으로 받은 집합과 다를 때에만 그 파일에 대해 전송되므로, 같은 발견 사항을 다시 계산하는 요청은 아무것도 보내지 않습니다. 파일의 첫 프레임과 파일의 집합을 비우는 프레임은 모두 차이에 해당하므로 항상 전송됩니다.

프로세스 자체에 중지를 요청해도 데몬에는 같은 조건으로 전달됩니다. 터미널의 인터럽트나 감독 프로세스 또는 컨테이너 런타임의 종료 요청은 aggrega/shutdown이 시작하는 것과 같은 종료 절차를 시작합니다. 진행 중인 요청은 완료되고, 새 요청은 거부되며, 그다음 데몬이 종료됩니다. 두 번째 요청은 프로세스를 즉시 끝냅니다. 데몬을 띄우는 클라이언트는 어느 방식으로든 데몬을 중지할 수 있으며, 통신으로 중지하는 클라이언트와 시그널을 보내는 클라이언트는 같은 종료 절차를 거칩니다.

실시간 검증

aggrega/validate 요청마다 데몬은 편집기 버퍼를 문서의 스키마에 대해 검증하고, 문제가 있는 키를 가리키는 진단을 반환합니다. 이는 저장되지 않은 내용에 대해 빌드가 내릴 것과 같은 판정입니다. content를 보내지 않은 요청은 디스크에 있는 그대로의 파일에 대해 묻는 것이고, 빈 값으로 보낸 content는 빈 버퍼이지 파일에 대한 요청이 아닙니다. 내용 없이 보낸 파일은 워크스페이스가 포함하고 있으며 읽을 수 있는 파일이어야 합니다. 워크스페이스 밖의 파일, 워크스페이스 밖으로 이어지는 링크를 통해 도달한 파일, 존재하지 않는 파일은 invalid-params 코드로 거부됩니다. 카탈로그 엔터티, Aggregates, Manifests, Releases는 apiVersion과 kind로 인식됩니다. 그러한 헤더가 없는 두 문서, 즉 .aggrega-config.yaml 워크스페이스 구성과 요청이 지정한 Release의 lockfile은 대신 파일 이름으로 인식되므로, 둘 중 어느 쪽에 있는 잘못되거나 형태가 어긋난 키도 실시간으로 밑줄이 표시됩니다. Aggrega 문서가 아닌 파일, 즉 Helm 차트 템플릿, Compose 파일, Kubernetes 매니페스트, Cargo.lock이나 flake.lock 같은 다른 생태계의 .lock 파일은 진단을 받지 않습니다. 데몬은 외부 파일에 대해서는 절대 보고하지 않습니다.

아직 채워야 하는 플레이스홀더는 해당 키에서, 필요한 값과 함께 지정됩니다. aggrega validate가 단일 엔터티로 검사하는 종류의 카탈로그 엔터티는 빈 문자열로 남겨 둔 필수 값에 대해서도 해당 명령이 적용하는 방식으로 읽히므로, 데몬은 같은 바이트에 대해 명령이 지정하는 모든 플레이스홀더를 지정합니다. 각 플레이스홀더는 하나의 항목입니다. 그 message는 해당 키가 아직 채워야 하는 플레이스홀더임을 말하고, suggest는 그 값에 무엇이 들어가는지 말하며, keyPath는 키의 점으로 구분된 경로를 담습니다. 이 항목은 그 빈 값에 대한 스키마 자체의 결과를 대신하며, 문서의 다른 모든 결과는 스키마 검사가 보고하는 그대로 보고됩니다. 스키마가 빈 값을 허용하는 플레이스홀더도 스키마 검사가 이에 대해 아무것도 보고하지 않지만 지정됩니다. 초안 상태인 Recipe나 FeatureRecipe의 capability와 implements가 흔히 접하게 되는 예입니다. 스키마 검사도 문서를 거부하는 경우 각 항목은 그 검사의 코드 E0215를 담고, 스키마 검사가 문서를 허용하는 경우 항목에는 코드가 없습니다. 이는 같은 바이트에 대해 명령의 보고서가 담는 것과 같은 식별자입니다. 항목은 빈 값을 담은 키에, 명령이 그것을 지정하는 줄에 그려집니다. 이름 자체에 점이 포함된 키, 예를 들어 component.aggrega.ai/type 레이블이라도 마찬가지이며, 이 경우 스키마 검사가 그 키에 대해 보고하는 결과는 그 키를 감싸는 키에 그려집니다. 그리고 keyPath는 키 전체를 지정합니다. 이는 요청이 Release를 지정하든 하지 않든 적용됩니다. 문서가 스스로 답하는 질문이며, 아직 값을 채워야 하는 문서는 아직 게시 관례를 물을 대상이 아니기 때문입니다. 스키마가 형태를 거부하는 문서와 마찬가지로, 그 계층은 해당 문서에 대해 비워집니다.

각 요청은 대상이 되는 Release를 지정하며, 데몬은 자체적으로 어떤 Release도 유지하지 않습니다. 의미 검사는 그 Release의 의존성 클로저를 해석하고 고정 버전을 위해 그 Release의 lockfile을 읽습니다. 또는 카탈로그 엔터티의 경우, 다음 단락에서 설명하듯 그 Release가 빌드에 사용하는 카탈로그 디렉터리를 읽습니다. 따라서 두 Releases를 지정한 두 요청은 각각 지정한 Release에 대해 답변됩니다. 둘 사이에 이어지는 것은 없습니다. 변경할 선택된 Release가 없으며, 검증 대상 Release를 바꾸는 것은 다음 요청의 다른 값일 뿐 데몬에게 잊으라고 알려야 하는 무언가가 아닙니다.

Release와 함께 지정된 카탈로그 엔터티는 단일 엔터티로, 그 Release의 관점에서 검사됩니다. Component, Feature, Recipe, FeatureRecipe 또는 Plugin을 담은 file을 release와 함께 보내면, 편집기의 저장되지 않은 버퍼에 대해 aggrega validate <path> --release <release>가 실행하는 검사를 받습니다. 그 참조, 즉 Recipe가 구현하는 Component나 필러가 참조하는 라이브러리는 워크스페이스 구성이 그 Release에 부여하는 카탈로그 디렉터리를 통해 해석됩니다. 따라서 하나의 파일이 그것으로 빌드하는 Release의 관점에서는 문제가 없고, 디렉터리에 그 파일이 참조하는 것이 없는 Release의 관점에서는 실패할 수 있습니다. 이는 같은 Release 옆의 같은 엔터티에 대해 명령줄과 aggrega mcp의 validate 도구가 내리는 판정과 같으며, 그것들처럼 클로저를 탐색하지 않고 lockfile도 읽지 않습니다. 차단 결과는 검사 자체의 문구로 된, 그 코드를 담은 하나의 오류 항목으로, 진단 항목이 담는 내용에서 설명하듯 엔터티에서 그것이 지정하는 키에, 지정하는 키가 없으면 엔터티의 kind: 키에 그려집니다. 단, 빌드가 이미 그 파일에서 해당 결함을 보고하고 있다면 빌드의 항목이 유일한 보고가 됩니다. 검사가 카탈로그를 읽는 동안 제기하는 권고는 그 앞에 오는 경고 항목이며, 모두 존재하는 디렉터리에 대한 깨끗한 검사는 항목을 반환하지 않습니다. 실패한 단언, 즉 Recipe 또는 그것이 구현하는 Component에서 fail을 호출하는 단언은 여기서 차단 결과가 아니라 경고 항목입니다. 검사의 문구로 되어 그 코드를 담고, A Release must satisfy this assertion before a build of it can pass.라는 문장으로 끝나며, 차단 결과가 그려질 위치에 그려집니다. Recipe의 단언은 assertions 아래 그 단언 자체의 키에, Component의 단언은 Recipe의 kind: 키에 그려집니다. 차단 결과와 마찬가지로, 파일에서 같은 결함을 보고하는 빌드의 항목에 자리를 내줍니다. 검사는 Release가 설정하는 값이 아니라 플레이스홀더와 스키마 기본값으로 엔터티를 구성하므로, Release를 기다리는 단언과 깨진 단언을 구별할 수 없으며, 판정은 같은 단언을 오류로 보고하는 빌드에 맡깁니다(실패한 단언은 경고입니다). 워크스페이스 구성이 Release에 대해 나열하지만 디렉터리가 아닌 디렉터리(예를 들어 그곳에 아무것도 존재하지 않는 경우)에서는 검사가 그 이상 진행되지 않습니다. 파일에는 검사의 판정 대신 하나의 오류 항목이 표시되며, 이는 모든 명령이 그 디렉터리에 대해 내리는 거부로서 해당 항목, 그것을 나열하는 구성 파일과 줄, 그리고 설정을 지정합니다(로컬 엔터티를 읽는 위치). 파일이 없는 것을 지정하거나 디렉터리를 지정하는 release는 워크스페이스의 관점에서 검사되는 대신, 명령줄이 그것을 거부할 때 쓰는 문장으로 파일에 대해 답변됩니다. 하나의 빌드로 대신할 수 없는 것은 명령줄이 판단하는 대로 판단되며, 명령줄이 제외하거나 검사하지 않는 것은 여기서 항목을 반환하지 않습니다. 단일 엔터티 정확성이 검사하지 않는 것을 참조하고, 템플릿이 토폴로지 엣지나 연결된 자격 증명만 전달하는 값을 읽는 Recipe에 대해서는 단일 엔터티 정확성을 참조하십시오. Release 자체의 Aggregate, Manifest, Release, 라이브러리는 단일 엔터티 검사가 그런 종류를 받지 않으므로 하나씩 검사되지 않으며, 위에 설명한 클로저 검사를 그대로 유지합니다. Workload 내용을 담은 버퍼는 Aggrega 문서가 아닌 YAML로 읽힙니다. 그 내용은 Recipe나 FeatureRecipe의 workload: 필드 안에 작성되며 그것이 놓인 그곳에서 검사되기 때문입니다. 명령줄과 validate 도구는 경로로 Workload 파일을 받으면 그 형태를 독자적으로 검사합니다.

Release 지정은 선택 사항이며, 응답은 두 가지 중 어느 쪽을 요청했는지 알려 줍니다. Release를 지정하면 위의 모든 검사를 받습니다. 지정하지 않으면 문서가 스스로 답할 수 있는 검사만 받습니다. 즉 파싱되는지, 자체 형태가 허용되는지, 그리고 단일 엔터티로 검증되는 종류의 카탈로그 엔터티라면 아직 채워야 할 플레이스홀더가 무엇인지를 검사하며, Release를 해석하지 않고 클로저를 순회하지 않으며 lockfile을 읽지 않습니다. 이때 응답에는 checked: "document"가 포함됩니다. Release를 지정하면 이 키는 없습니다. 그 응답은 메서드의 완전한 판정이며 단서를 달 것이 없기 때문입니다.

진단으로부터 추론하지 말고 이 키를 읽으십시오. 두 응답이 똑같아 보일 수 있기 때문입니다. Release 없이 검증된 올바른 형식의 문서는 빈 진단 목록으로 응답하는데, 이는 문제없는 완전한 판정이 응답하는 것과 정확히 같습니다. 따라서 “잘못된 것이 없음”과 “Release가 필요한 것은 살펴보지 않음”을 구분하는 것은 checked뿐입니다. 같은 규칙에서 한 가지 결과가 따릅니다. lockfile은 요청이 지정한 Release와의 대응 관계로 인식되므로, Release를 지정하지 않은 요청은 어떤 lockfile도 인식하지 않으며 lockfile에 대해 아무것도 보고하지 않습니다.

Release가 없는 워크스페이스에는 거부 대신 응답하며, 이것이 그곳에서 데몬의 나머지 기능을 쓸 수 있게 해 줍니다. 검증은 다른 모든 파일 작업이 읽는 파싱 캐시를 채우는 작업이므로, 카탈로그만 있는 저장소, 단일 Aggregate 스캐폴드, 임시 디렉터리에서도 호버, 자동 완성, 정의로 이동, 참조, 구현, 캐시된 진단을 계속 사용할 수 있습니다. 대신 거부한다면 클라이언트가 지정할 Release가 없는 바로 그 워크스페이스에서 이 모든 기능이 함께 사라집니다.

진단 항목에 담기는 내용

각 항목은 line과 column으로 위치를 나타내며, 둘 다 핸드셰이크에서 협상된 위치 인코딩 기준으로 1부터 시작합니다. 항목이 토큰 전체에 걸치면 end_line과 end_column이 추가됩니다. message는 클라이언트가 사용자에게 보여 주는 텍스트이고, severity는 이를 분류하며, source는 위에서 설명한 대로 데몬의 어느 계층이 이를 발생시켰는지 나타냅니다.

계층들은 한 파일에 대해 서로 다른 질문에 답하므로, 각 계층의 항목이 같은 줄에 있어도 어느 쪽도 다른 쪽의 중복이 아닙니다. 하나는 배포가 올바르지 않다고 말하고, 다른 하나는 엔터티를 게시할 수 없다고 말합니다. 이를 하나의 목록으로 보여 주는 클라이언트는 한 문제를 두 번 보고하게 되며, 이를 구분하는 것은 source를 읽는 것입니다.

항목의 위치는 어느 계층이 발생시켰는지가 아니라 무엇에 관한 것인지에 따라 정해집니다. 작성자가 쓴 내용에 관한 결과는 작성자가 그것을 쓴 키에 위치하므로, 편집기는 수정이 필요한 곳에 이를 표시합니다. 배포된 토폴로지의 형태에 관한 결과는 줄이 아니라 component와 전달 키를 지정합니다. 이는 문서가 아니라 배포된 토폴로지의 좌표이므로, 이 결과는 문서의 kind: 키에 표시되고 대신 메시지에 좌표를 밝힙니다. 빌드는 두 종류 모두를 발생시키므로 둘 다 aggrega-build 계층에 도달합니다. 빌드가 렌더링 중에 발생시킨 거부도 이 계층에 도달하며, 거부 자체가 가리키는 문서에 놓입니다. 검사를 충족하지 않는 Workload는 해당 Recipe의 workload 키에, Recipe의 실패한 어서션은 그 어서션 자체의 키에, 그래프 구성이 거부한 항목은 Release나 Aggregate가 그 항목을 쓴 키에, 여러 결과를 묶는 거부의 각 결과는 그 결과 자체의 문서와 키에 놓이며, 어떤 문서도 가리키지 않으면 Aggregate의 kind: 키에 놓입니다. 렌더링 중 발생한 거부에서 이를 설명합니다. 따라서 클라이언트는 모든 항목을 그 자체의 line과 column으로 배치하며, 계층으로부터 위치를 추론하지 않습니다.

문서에 있는 어떤 키도 지정하지 않는 결과는 문서를 지정하는 키에 표시됩니다. 문서 자체의 검사가 문서 내용에 대해 발생시킨 결과, 단일 엔터티 검사의 결과, 빌드가 발생시킨 권고나 거부는 각각 지정한 키에 표시됩니다. 아무 키도 지정하지 않거나 문서에 없는 키를 지정하면 문서의 kind: 키에, kind:를 선언하지 않은 경우 metadata.name에 표시되며, 문서가 둘 다 선언하지 않았거나 파싱되지 않을 때에만 파일 맨 앞에 표시됩니다. 문서는 흔히 주석으로 시작하며(모든 카탈로그 파일에는 라이선스 헤더가 있습니다), 첫 줄에 표시된 항목은 그 주석 위에 놓여 주석의 결함처럼 읽히는 반면, 문서 자체의 식별 정보는 작성자가 쓴 줄이기 때문입니다. 문서 내용이 아닌 다른 것에 관한 항목은 파일 맨 앞에 놓입니다. Release의 종속성에 관한 Dependencies: 항목, 문서의 어떤 것도 지정하지 않고 멈춘 단계, 어긋난 lockfile, 렌더링이 거절해야 했던 참조, 로드되지 않은 Release가 그렇고, 규칙이 줄을 계산하지 않은 aggrega-lint 항목도 마찬가지입니다. 위치를 표시하는 대신 명시하는 경우에도 키를 지정하지 않는 결과에는 여전히 위치가 없습니다. 키를 지정하지 않는 거부의 오류 응답은 data에 문서만 담습니다.

항목이 어느 문서에 게시되는지도 같은 규칙에서 따릅니다. Release를 지정한 검증은 그 Release의 Aggregate, Release 자체, Aggregate가 가져오는 각 모듈의 문서, 그리고 Release가 지정하는 Manifest에 응답합니다. Release에 위치한 결과, 즉 Release가 컴포넌트의 연결 중 하나에 쓴 항목, 그 연결에 부여한 크기 지정, 그곳에서 채우거나 크기를 지정한 첨부, Release가 배선한 연결, Release만 컴포넌트나 경계에 부착하는 Feature, 또는 첨부에 부여한 infra에 대한 거부는 Release 문서가 검증될 때 그것을 쓴 Release의 키에 게시되며, Aggregate에는 전혀 게시되지 않습니다. 모듈 자체 문서에 위치한 결과, 즉 모듈의 컴포넌트 중 하나가 선언하는 내용, 그 첨부가 배선하는 소켓, 그 값 또는 자체 연결의 값에 대한 거부는 그 모듈의 문서가 검증될 때 그곳에서 그것을 쓴 키에 게시되며, Aggregate에는 전혀 게시되지 않습니다. Manifest의 매핑 테이블에 관한 결과, 즉 어떤 유형을 그 유형을 구현하지 않는 Recipe나 FeatureRecipe에 매핑하는 항목, 버전 고정을 구문 분석할 수 없는 항목, 또는 extends 체인을 따라갈 수 없는 매핑된 유형에 관한 결과는 그 Manifest가 검증될 때 해당 매핑 항목의 키에 게시되며, Aggregate에는 전혀 게시되지 않습니다. Manifest의 열린 텍스트에 그 항목이 쓰여 있지 않으면(자체 extends를 통해 상속하는 항목이나 저장되지 않은 편집으로 제거된 항목 등) 결과는 Manifest의 첫 줄에 게시됩니다. 그 Release의 검증이 발생시킨 다른 모든 결과는 Aggregate에 게시되며, 여기에는 워크스페이스의 어떤 문서도 가리키지 않는 종속성 수준의 결과, 즉 철회된 참조나 플러그인, extends 체인이 해석되지 않거나 스키마가 유효하지 않은 카탈로그 Component나 Feature, 신뢰 기록과 일치하지 않는 게이트 플러그인, 어떤 매핑으로도 해석되지 않는 컴포넌트 인스턴스, 선언한 입력 종류를 프로바이더가 렌더링할 수 없는 Recipe나 FeatureRecipe, 그리고 스키마 필러 중복 및 extend 시 좁히기 권고가 포함됩니다. 따라서 빌드의 어느 단계가 발생시켰든, 운영자가 쓴 내용에 관한 결과는 Release가 열려 있는 동안, 모듈이 선언하는 내용에 관한 결과는 그 모듈이 열려 있는 동안, 매핑에 관한 결과는 Manifest가 열려 있는 동안 나타나며, 열린 모든 문서를 해당 Release에 대해 검증하는 편집기는 각 결과를 그곳에 표시합니다. 종속성을 전혀 해석할 수 없는 Release는 이러한 결과를 발생시키지 않으며, 해석 실패는 하나의 항목으로 Release 자체 문서의 맨 앞과, 그 Release에 대해 검증되고 데몬이 인식하지만(실시간 검증에서 설명한 대로) 단일 엔터티로 검사하지 않는 다른 모든 문서(그 Aggregate, Manifest, 라이브러리, 다른 Release, 워크스페이스 구성)의 맨 앞에 놓입니다. 이 항목은 Dependencies: 접두사가 붙고 무엇이 해석을 멈추게 했는지에 대한 해석 자체의 설명을 담습니다. Release 자체 문서에서는 항목이 그 설명뿐입니다. 다른 모든 문서에서는 먼저 문서가 그 Release에 대해 검사되었다고 밝히고 요청이 지정하는 방식으로 Release 이름을 지정하며(Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: 뒤에 설명이 이어집니다), 이는 그 문서의 어떤 내용도 어느 Release에 대해 검사되었는지 말해 주지 않기 때문입니다. 선택된 하나의 Release에 대해 열린 모든 문서를 검사하는 편집기는 그 Release와 무관한 문서에도 항목을 표시하게 되며, 선택이 원인임을 알려 주는 것이 바로 그 이름입니다. 데몬이 인식하지 않는 파일에는 함께 지정된 Release와 관계없이 이러한 항목이 없습니다.

검증이 어디까지 진행되었든 응답은 파일에 있는 모든 계층을 담습니다. aggrega/validate 응답은 파일의 현재 상태 전체입니다. 즉 이번 검증이 찾은 것, 빌드·미리 보기·그래프 요청이 파일에 게시한 aggrega-build 항목, 게시 관례 결과를 각각 고유한 source 아래에 담습니다. 버퍼 단계에서 멈춘 검증, 즉 파싱되지 않거나 스키마가 엔벌로프를 거부한 문서의 검증도 같은 방식으로 응답합니다. 자신의 결과를 보고하고 파일의 모든 빌드 항목은 그대로 둡니다. 빌드에 대해 알아낸 것이 없기 때문입니다. 따라서 클라이언트는 어떤 응답으로든 파일에 대해 보유한 내용을 계층별로 교체할 수 있습니다.

하나의 결함은 한 번만 보고됩니다. 문서 자체의 검증과 빌드는 그 문서에서 같은 결함을 찾을 수 있습니다. 단일 엔터티 검사는 빌드도 렌더링하는 Recipe를 렌더링하고, 검증은 빌드가 구성하는 그래프를 구성하며, 의존성이 해석되지 않는 Release는 양쪽 모두에서 실패합니다. 빌드가 어떤 문서에서 그러한 결함을 보고하는 동안에는 그 문서의 검증이 그것을 다시 보고하지 않습니다. 같은 문서에서 빌드의 거부와 같은 조건, 즉 같은 code를 지정하고 같은 범위에 놓이거나 자체 키 없이 놓인(키를 지정하지 않는 항목이 그려지는 위치 또는 파일 머리에 그려진) aggrega 항목은 그 문서에 대한 모든 응답과 모든 게시에서 제외되며, 빌드의 보고만 남습니다. 빌드의 보고란 aggrega-build 계층에 있는 거부 항목이며, 의존성이 해석되지 않아 1004로 거부된 aggrega/build, aggrega/buildPreview 또는 aggrega/irGraph의 경우에는 그 응답 자체입니다. 이 응답은 아무것도 게시하지 않으며, 그 data.file이 지정하는 문서, 없으면 data.lockfile, 그것도 없으면 요청이 지정한 Release에 해당하고, 한 Release에 대해서는 그러한 응답 중 가장 최근 것이 기준이 됩니다. 검증은 찾은 내용을 유지합니다. 더 이상 어떤 빌드도 그 결함을 보고하지 않게 되면, 즉 다음 실행이 그 결함 없이 계층을 게시하거나, 그 Release에 대한 다음 빌드, 미리 보기 또는 그래프 응답이 다른 결과이거나, 그러한 1004를 응답받지 않은 클라이언트가 연결되면, 문서 자체의 항목이 다시 보고됩니다. 빌드가 실행된 적이 없으면 아무것도 제외되지 않습니다. 빌드 거부가 놓이지 않은 키에 놓인 aggrega 항목은 같은 조건을 지정하더라도 남습니다. 빌드가 아직 보고하지 않은 같은 종류의 두 번째 결함일 수 있기 때문입니다.

code는 항목이 보고하는 내용에 대한 안정적이고 기계가 대조할 수 있는 코드이므로, 클라이언트는 메시지 텍스트를 대조하지 않고도 이를 기준으로 분기할 수 있습니다. 누가 지정했든 하나의 키가 코드를 담으며, 계층마다 서로 다른 어휘로 대상을 명명하므로 source가 지금 어떤 종류의 코드를 가지고 있는지 알려 줍니다.

  • 작성된 문서에 대한 발견 사항인 aggrega 항목에서 코드는 조건이 등록된 문자열이며, 선언한 패키지 다음에 kebab-case로 쓴 규칙이 오는 형태입니다. 이는 Go 소비자가 CodeOf로 읽는 값과 같으며, 그 형식과 대조 가능한 표면은 오류 센티널 참조에서 설명합니다.
  • 빌드가 발생시킨 권고인 aggrega-build 항목에서 코드는 발생시킨 곳이 지정한 값이며, 빌드는 서로 다른 두 종류의 대상에 대해 권고를 발생시키므로 이 계층은 서로 다른 두 어휘의 권고를 담습니다. 배포된 토폴로지의 형태에 대한 권고는 unsupported-field와 같은 클래스 코드를 담으며, 이는 렌더링 플러그인이든 렌더 자체든 그것이 발생한 곳에서 지정됩니다. 클래스 코드는 등록된 조건이 아니라 권고의 클래스를 지정하므로 센티널 참조에 행이 없으며, 경고 참조에서 unsupported-field 클래스와 이를 억제하는 플래그를 설명합니다. 작성된 문서에 대한 권고, 예를 들어 선언된 이름과 한 글자 차이인 이름이나 아무것도 읽지 않는 매개변수는 그 조건이 등록된 문자열을 aggrega 항목과 같은 형식으로 담으며 센티널 참조에 행이 있습니다. 어느 경우든 코드는 누가 찾았는지가 아니라 발견 사항이 무엇인지를 지정하므로, 하나의 클래스는 얼마나 많은 곳에서 발생하든 하나의 코드로 전달되며, 계층이 아니라 코드를 읽어야 둘 중 어느 쪽을 가지고 있는지 알 수 있습니다. 렌더링 중에 빌드가 멈춘 원인인 거부는 이 계층에서 권고가 아닌 유일한 항목이며, 마찬가지로 그 조건이 등록된 문자열을 담습니다.
  • 게시 관례 발견 사항인 aggrega-lint 항목에서 코드는 발견 사항의 식별자입니다. 즉 그것을 생성한 규칙의 식별자이거나, 규칙을 지정하지 않는 발견 사항(직접 만든 린터가 자체 코드로 보고할 수 있음)의 경우 그 코드입니다. 이는 aggrega lint가 발견 사항의 행에서 짧은 코드가 있으면 그 뒤에 출력하는 식별자이며, aggrega lint --output json이 같은 발견 사항에 대해 ruleId로, 규칙을 지정하지 않는 발견 사항이면 code로 담는 값입니다. 하나의 발견 사항은 모든 표면에서 하나의 식별자를 유지하므로, 편집기에서 규칙을 그룹화하거나 억제하는 클라이언트는 터미널에서도 같은 규칙을 그룹화하고 억제합니다. Aggrega가 선언하는 게시 린터 규칙 집합의 각 규칙은 그 식별자로 조건으로 등록되므로, 모든 조건의 표에 aggrega lint가 같은 발견 사항의 행 머리에 출력하고 aggrega lint --output json이 shortCode로 담는 짧은 코드로 나열됩니다. Aggrega가 선언하지 않는 직접 만든 린터의 규칙은 등록된 조건을 지정하지 않으며, 규칙을 지정하지 않는 발견 사항도 자체 코드가 Aggrega가 선언하는 규칙의 식별자와 철자가 같더라도 마찬가지이므로, 둘 다 그 표에 나열되지 않습니다. 규칙은 aggrega lint 참조에서 설명합니다.

계층이 무엇이든 이 키는 하나의 질문, 즉 기계가 대조할 수 있는 용어로 이것이 무엇인지에 답합니다. 따라서 한 클래스의 발견 사항을 강조, 그룹화 또는 억제하는 편집기 확장은 코드를 기준으로 삼으며, 메시지 문구가 바뀌어도 계속 동작합니다.

어떤 객체가 어떤 것을 담는지 유의하십시오. 이것은 진단 항목의 문자열이며, 아래 오류 코드에서 설명하는 JSON-RPC 오류 봉투의 숫자 code와는 다릅니다. 응답은 둘 중 하나를 담으며, 한 곳에 둘 다 담지는 않습니다.

항목을 생성한 어떤 것도 코드를 지정하지 않았으면 이 키는 생략되며, 모든 종류에 그런 경우가 있습니다. 어떤 YAML 파서도 읽지 못하는 버퍼는 파서 자체의 텍스트만 보고하고 코드는 보고하지 않습니다. 그 뒤에 Aggrega 자체의 조건이 없기 때문입니다. 조건을 지정하지 않고 실패를 보고하는 단계도 마찬가지로 보고할 코드가 없으며, 발생시킨 쪽이 코드를 지정하지 않은 권고는 코드 없이 도착합니다. 따라서 code는 end_line 및 end_column과 마찬가지로 선택 사항으로 취급하고, 있을 때만 이를 기준으로 분기하십시오. 코드는 진단이 보고하는 것이지 진단을 선택하는 것이 아닙니다. 코드를 받는 요청은 없으며, 코드를 자신의 코드에 다시 써 넣으면 대조 수단이 아니라 문자열을 얻게 될 뿐입니다.

프로그램이 매칭하는 식별자와 사람이 인용하는 식별자

조건에는 두 개의 식별자가 있으며, 이 둘은 서로 다른 독자를 위한 것입니다. code는 앞에서 설명한 식별자로, 한정되고 하이픈으로 연결되어 있어 이를 기준으로 분기하는 프로그램이 그 의미대로 읽힙니다. shortCode는 문자 E와 네 자리 숫자(E0164)로 이루어지며, 사람이 소리 내어 읽거나 검색창에 입력하거나 이슈에 붙여 넣을 수 있는 식별자입니다. 둘 다 같은 조건을 가리키며, 어느 쪽도 다른 쪽의 약칭이 아닙니다.

어느 쪽을 사용할지는 누가 읽는지에 따라 정해집니다. 확장에서는 code로 매칭하고, 작성자에게는 shortCode를 보여 주십시오. code만 보여 주는 확장은 독자에게 프로그램용 식별자를 쥐여 주게 되고, shortCode로 매칭하는 확장은 조건에 대해 아무것도 말해 주지 않는 번호로 매칭하는 셈입니다. 이러한 구분 때문에 하나가 아니라 둘 다 전달됩니다.

codeDescription은 조건이 게시된 위치이며, { "href": … } 형태로 전달됩니다. 이는 진단에 대해 더 알아보기 위해 열 참조를 나타내는 프로토콜 자체의 구조입니다. 프로토콜을 인식하는 에디터는 Aggrega에 대해 따로 배우지 않고도 이를 “자세히 알아보기” 기능으로 바꾸며, 어떤 클라이언트도 설명의 사본을 가질 필요가 없습니다. 이 주소는 모든 조건의 게시된 목록으로 연결되며, 그 목록에서 shortCode의 항목은 조건을 명시하고 작성 측 수정 방법의 안내로 이어집니다.

설명문 자체는 항목에 포함되지 않으며, 이는 의도된 것입니다. 진단은 편집할 때마다 생성되므로, 각 진단에 설명을 실으면 대개 이미 그 설명을 읽은 독자에게 키를 누를 때마다 같은 문단을 다시 게시하게 됩니다. 텍스트가 필요한 클라이언트는 아래의 aggrega/explainError로 한 번 요청하면 되고, 링크를 따라갈 수 있는 클라이언트는 둘 다 필요하지 않습니다.

두 키는 항목이 등록된 조건을 가리킬 때 정확히 함께 존재하며, 그 밖의 경우에는 함께 없습니다. 이를 결정하는 것은 어느 레이어가 항목을 게시했는지가 아니라 항목 뒤에 무엇이 있는지이므로, 레이어가 아니라 키를 읽으십시오.

  • 등록된 조건을 가리키는 항목은 세 가지를 모두 갖습니다. shortCode는 해석되며, 참조는 그것이 해석되는 목록으로 연결됩니다.
  • 코드가 클래스를 가리키는 항목은 code만 갖습니다. 렌더 권고의 클래스와, 직접 만든 린터가 낸 관례 검사 결과의 식별자(Aggrega가 선언하지 않은 규칙, 또는 규칙을 명시하지 않는 검사 결과가 갖는 코드)는 그룹화하거나 억제하는 데 쓸 수 있는 실제 식별자이지만, 어느 쪽도 등록된 조건이 아니므로 인용할 번호도 없고 그 주소에 이를 설명하는 내용도 없습니다. 그럼에도 참조를 보낸다면 독자의 문제와 무관한 페이지를 여는 링크가 될 것이므로 보내지 않습니다. 이는 aggrega-build 레이어의 일반적인 형태이지만, 등록된 조건을 가리키는 빌드 권고는 다른 항목과 마찬가지로 세 가지를 모두 갖습니다. aggrega-lint 레이어에서는 전체 세트가 일반적인 형태입니다. Aggrega가 선언하는 게시 린터 규칙 세트의 규칙은 등록된 조건이므로, 그 검사 결과는 aggrega lint가 해당 결과 행의 맨 앞에 출력하는 것과 같은 shortCode와 그 옆의 참조를 갖습니다.
  • 아무것도 가리키지 않는 항목은 식별자를 전혀 갖지 않습니다.

따라서 세 경우는 키만으로 구별할 수 있습니다. code가 없으면 가리킬 것이 없다는 뜻이고, 옆에 shortCode가 없는 code는 더 이상 해석되지 않는 식별자를 뜻하며, 전체 세트는 읽을 곳이 있는 식별자를 뜻합니다. 새로운 두 키는 code와 마찬가지로 선택적인 것으로 취급하고, codeDescription이 도착한 경우에만 독자에게 열어 볼 것을 제공하십시오.

진단이 전달한 코드 확장하기

aggrega/explainError는 조건의 두 식별자 중 어느 것이든 받아, 컴파일러가 그 조건에 대해 선언하는 내용과 작성 측 수정 방법을 알려 주는 게시된 항목으로 바꿔 줍니다. 이는 aggrega explain이 터미널에서, explain-error 도구가 어시스턴트를 위해 수행하는 것과 같은 확장이며, 세 가지 모두 한곳에서 답하므로 여기서 확장한 코드와 저기서 확장한 같은 코드는 우연히 일치하는 세 답이 아니라 하나의 답입니다.

code는 필수이며 어느 식별자든 받습니다. 진단이 전달한 shortCode든 그 옆의 code든 됩니다. 둘 중 하나를 가진 클라이언트는 요청하지 않고는 다른 하나를 얻을 방법이 없기 때문입니다. 빈 값은 무엇을 보내야 하는지 알려 주며 거부됩니다.

응답에는 항상 shortCode, code, message가 포함됩니다. 조건의 두 식별자와, 그 조건을 가리키는 모든 진단이 시작하는 문장입니다. 이들은 바이너리 안에 선언되어 있으므로 네트워크나 캐시 없이 도착하며, 이 덕분에 문서를 전혀 갖지 않은 워크스페이스에도 답할 수 있습니다. reference는 진단의 codeDescription이 전달하는 것과 같은 주소로, 설명문을 렌더링하기보다 독자를 문서로 안내하려는 클라이언트를 위한 것입니다.

entries는 게시된 안내를 전달하며, 각 항목은 그 항목을 여는 heading과 그 아래의 body로 이루어지고, 문서 자체가 조건과 짝지은 순서를 따릅니다. 안내를 추가할 수 없는 경우에는 생략되며, 이때 note가 그 이유를 알려 줍니다. 게시된 페이지가 아직 이 조건에 대한 항목을 문서화하지 않았거나, 이 워크스페이스가 문서를 읽을 수 없는 경우(머신에 사본이 없거나, 워크스페이스의 서명 검사가 거부하는 사본만 있는 경우)입니다. 어느 경우든 그 위의 조건은 유효합니다. 응답은 실패가 아니며, 클라이언트는 도착한 내용과 그 옆의 노트를 보여 줍니다. entries와 note가 함께 도착하는 일은 없습니다.

아무것도 해석되지 않는 코드는 모든 필드가 빈 조건으로 응답되는 대신 거부되며, 각 거부는 어떤 경우인지 알려 줍니다. 어떤 조건도 등록되지 않은 코드, 한때 조건을 가리켰지만 다시는 다른 조건을 가리키지 않는 번호, 또는 게시된 목록을 전혀 읽을 수 없는 상황에서 이 바이너리가 선언하지 않은 코드입니다. 마지막 경우에는 두 가지 해결 방법이 모두 열려 있습니다. 다른 버전용으로 게시된 목록이 이 바이너리가 선언하지 않은 조건을 가리킬 수 있기 때문입니다.

문서는 요청이 지정한 워크스페이스에 캐시된 번들에서 읽으며, 번들이 없으면 처음 사용할 때 가져옵니다. 이것이 이 요청이 레지스트리에 접근하는 유일한 경우입니다. 레지스트리 접근과 쓰기를 참조하십시오. 워크스페이스에는 아무것도 쓰지 않습니다. 어떤 검증도 이를 유발하지 않습니다. 확장은 요청이 요구했기 때문에 일어나므로, 문서를 검증하거나 검사하는 동안에는 레지스트리에 절대 접근하지 않습니다.

요청 시 및 모든 편집 시의 게시 관례

데몬은 카탈로그 엔터티에 대해 서로 다른 두 질문에 답하며, 이는 터미널에서 aggrega validate와 aggrega lint가 답하는 질문과 같습니다. 배포가 올바른지, 그리고 엔터티가 카탈로그의 관례에 따라 게시 가능한지입니다. 검증은 항상 첫 번째 질문에 답합니다. 두 번째 질문에는 요청할 때만 답합니다.

aggrega/lint는 이를 직접 요청합니다. 카탈로그 엔터티 하나에는 entity를, 해당 Release의 의존성 클로저가 도달하는 모든 엔터티에는 release를 보내고, 구성된 카탈로그 디렉터리 아래의 모든 엔터티를 검사하려면 둘 다 보내지 않습니다. 이것이 명령이 가진 세 가지 범위입니다. entity와 release를 모두 보내면 서로 다른 두 대상을 지정하는 것이므로 거부됩니다. 응답에는 실행이 다룬 엔터티 문서의 수인 checked와, 각 결과가 관련된 문서별로 묶이고 경로순으로 정렬된 결과인 files가 담기며, 각 파일의 항목은 위에서 설명한 진단 형태를 따릅니다. halted는 실행 자체의 판정이 게시를 거부하는지를 나타냅니다.

둘 다 보내지 않으면 aggrega lint를 인수 없이 실행할 때처럼 카탈로그 전체를 검사합니다. 구성에 자체 Release 카탈로그 디렉터리가 없는 워크스페이스는 자체 디렉터리에 대해 한 번 검사되며, 응답은 위에서 설명한 것과 같습니다. workspace.releases 아래에 Releases를 지정한 워크스페이스는 그 안의 각 Release마다 해당 Release가 읽는 디렉터리에 대해 한 번씩 검사되며, 모든 디렉터리를 한꺼번에 검사하는 일은 없습니다. 따라서 Release마다 하나씩 나란히 둔 카탈로그 변형은 각각 그것을 읽는 Release의 조건으로 검사됩니다. 이때 응답에는 패스마다 하나의 항목인 passes도 담깁니다. 각 항목은 해당 패스가 실행된 Releases인 releases(각각 워크스페이스 루트 기준 상대 경로이며, 같은 디렉터리를 읽는 Releases는 한 항목을 공유합니다), 해당 패스가 읽은 디렉터리인 catalogDirs(files가 경로를 표기하는 방식으로 표기되며, 아무것도 읽지 않는 Release에는 비어 있고, 이는 다른 패스를 실패시키지 않고 보고됩니다), 그리고 해당 패스 자체의 개수와 files(어떤 결과가 어느 Release에 대해 발견되었는지를 알려 줍니다)로 이루어집니다. 그 바깥의 checked, 개수, files는 모든 패스를 합쳐 다루므로, passes를 읽지 않는 클라이언트도 전체 실행을 읽을 수 있습니다. 읽을 디렉터리가 있는 패스가 하나도 없는 실행은 깨끗한 카탈로그로 응답되지 않고 거부됩니다.

entity와 함께 prePublish를 설정하면 해당 엔터티를 이전에 게시된 버전과 비교하고, 제안된 버전 증가를 그에 대해 분류합니다. 이는 여기서 레지스트리에 접근하는 유일한 모드이며, 요청이 이를 지정했기 때문에 실행됩니다. 외부에 접근하는 작업을 허용하는 것은 호출자가 그것을 요청했다는 사실입니다. 이 모드는 entity와 함께일 때만 의미가 있으므로, 엔터티 없는 prePublish는 거부됩니다.

aggrega/lint는 세션에 아무것도 게시하지 않습니다. 주어진 대상에 대해서만 답하며, 그 결과를 편집기의 문제 목록에 기록하면 요청이 다루지 않은 파일에 대해 검증이 게시한 내용을 대체하게 됩니다. 어떤 모드에서도 디스크에는 아무것도 기록되지 않습니다.

serve.lint_on_validate는 모든 검증 시 같은 규칙을 실행하며, 켜지 않는 한 꺼져 있습니다. 조언을 받고자 하는 엔터티가 있는 워크스페이스의 .aggrega-config.yaml에서 켭니다.

serve:
lint_on_validate: true

이를 위한 플래그는 없습니다. 이것이 답하는 질문은 워크스페이스 자체의 내용에 관한 것이며, 그 질문을 가진 사람은 데몬을 실행한 사람이 아니라 워크스페이스를 작성하는 사람이기 때문입니다. 이를 켜면 카탈로그 엔터티의 검증이 aggrega-lint 소스로 관례 결과도 게시합니다. 끄면(기본값) 검증은 정확성 계층만 보고하며 관례 결과는 전달되지 않습니다. 편집기 세션은 해당 계층을 요청하기 전까지 엔터티가 게시 가능한지에 대해 아무것도 알려 주지 않습니다.

키 값과 관계없이 해당 계층에는 세 가지가 적용됩니다. 로컬 내용을 읽는 모드만 실행되므로 레지스트리를 조회하지 않고, 아무것도 가져오지 않으며, 아무것도 기록하지 않습니다. 게시 전 비교는 검증이 아니라 prePublish와 함께 aggrega/lint를 보내야만 수행됩니다. 모든 편집 시 실행되는 검사야말로 레지스트리에 접근해서는 안 되는 곳이기 때문입니다. 규칙은 디스크의 파일이 아니라 요청이 전달한 버퍼를 대상으로 평가되므로, 이름을 고치면 저장하기 전에 보고가 멈춥니다. 그리고 결과는 권고입니다. 결과가 나온 문서도 여전히 검증을 통과하고, 그 Release도 여전히 해석되고 렌더링되므로, 이는 계층을 더할 뿐 거부를 더하지 않습니다.

이 키는 해당 계층만 제어하며 다른 것은 제어하지 않습니다. aggrega/lint는 어느 값에서든 요청받은 것에 답합니다. 이를 보내는 호출자는 이름으로 검사를 요청한 것이기 때문입니다.

관례가 다루는 대상이 카탈로그에 게시되는 종류이므로, 그런 종류만 검사됩니다. 카탈로그 내용이 아닌 문서(Aggregate와 Release 포함)는 건너뛰며, Aggrega 문서가 아닌 YAML도 마찬가지입니다. 덕분에 작성자가 대부분의 시간을 보내는 문서에 대해 세션이 조용하게 유지됩니다.

보고되는 경로의 표기 방식

데몬이 대신 찾아 준 문서를 응답이 가리킬 때, 그 경로의 표기 방식은 하나의 규칙으로 정해집니다. 문서가 워크스페이스 루트 안에 있으면 루트에 대한 상대 경로로, 그렇지 않으면 절대 경로로 표기합니다. 이 규칙은 엔터티 식별 정보의 file, 엔터티 정의의 file, 그리고 lint 응답에서 각 그룹의 키가 되는 file에 적용됩니다. 두 표기 모두 열 수 있는 경로이며(첫 번째는 지정한 루트를 기준으로, 두 번째는 그대로), 문서가 있는 위치 때문에 어느 쪽도 빈 값으로 남지 않습니다.

규칙의 후반부는 구성된 카탈로그 디렉터리를 위한 것입니다. 워크스페이스는 머신의 어느 곳에 있는 카탈로그 디렉터리든 가리킬 수 있으며, 그 안의 문서는 루트 아래의 문서와 똑같이 실재합니다. 그 문서를 가리키는 것은 절대 경로이며, 이는 터미널에서 aggrega lint와 중단 진단이 해당 파일에 대해 출력하는 표기와 같습니다. 따라서 어느 인터페이스에 요청하든 하나의 파일은 하나의 이름을 가집니다. 루트 위로 올라가는 경로는 제공되지 않습니다. 그런 경로는 어디에서 읽느냐에 따라 서로 다른 파일을 가리키게 되기 때문입니다.

어떤 표기를 받았는지는 값에서 알 수 있습니다. 플랫폼이 절대 경로로 읽는 값은 두 번째 형식이고, 그 밖의 값은 워크스페이스 루트에 대한 상대 경로입니다. 파일을 열기 위해 이를 검사할 필요는 없습니다. 상대 경로는 루트에 이어 붙여 열고 절대 경로는 그대로 열면 모두 동작합니다. 다만 워크스페이스 문서별로 그룹화하는 클라이언트는 따로 묻지 않고도 두 형식을 구별할 수 있습니다.

이 규칙이 적용되지 않는 범위. 직접 보내는 경로는 위에서 각 요청과 함께 설명한 해당 요청 자체의 계약을 따르며, 대개 더 엄격합니다. 대상 경로는 워크스페이스 루트에 대한 상대 경로이고 링크를 포함하여 루트 안으로 해석되지 않으면 거부됩니다. aggrega/publishDiagnostics 알림은 루트 안팎을 가리지 않고 모든 경우에 file을 절대 경로로 전달합니다. 그 값은 워크스페이스 안의 좌표가 아니라 직접 연 문서와 대조하는 식별자이기 때문이며, 편집기는 이를 파일 시스템 경로로 해석합니다. aggrega/releaseCandidates와 aggrega/activeRelease는 위의 각 항목에서 설명한 대로 모든 Release와 lockfile을 절대 경로로 가리킵니다. 그리고 aggrega/irGraph는 컴파일된 그래프를 컴파일러가 기록한 그대로 전달하며(작성자가 민감하다고 선언한 값만 제외), 따라서 그 안에 기록된 경로는 이 프로토콜이 구성한 경로가 아니라 컴파일러가 기록한 경로이며, 그래프 자체의 계약이 정한 형식을 따릅니다.

보내는 매개변수가 받아들이는 표기

매개변수가 받아들이는 표기는 어느 메서드가 그 경로를 전달하느냐가 아니라 경로가 무엇을 가리키느냐로 정해집니다. 각 요청이 받는 매개변수의 계약은 위의 해당 항목에 설명되어 있습니다. 아래에서는 그 차이를 대비하고, 그것이 메서드마다 외워야 하는 불일치가 아니라 의도된 대비인 이유를 설명합니다.

이미 보유한 문서를 가리키는 매개변수는 세 가지 방식으로 표기할 수 있습니다. 워크스페이스 루트에 대한 상대 경로, 절대 경로, 또는 language server 클라이언트가 열린 문서에 대해 보내는 file:// 주소입니다. 이는 aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint, aggrega/connectionAtPosition의 file 또는 uri에 해당합니다. 세 가지 모두 하나의 문서를 가리키고 똑같이 응답됩니다. 각 표기는 무엇이든 읽기 전에 요청 경계에서 하나의 정규 표기로 변환되기 때문입니다. 따라서 경로로 검증한 문서는 주소로도 찾을 수 있고 그 반대도 마찬가지이며, 어떤 표기를 보내든 응답은 달라지지 않습니다. 주소는 authority가 비어 있거나 localhost이면 퍼센트 이스케이프를 디코딩한 뒤 그것이 가리키는 경로로 읽힙니다. 다른 머신을 가리키는 주소는 그런 방식으로 문서를 여는 시스템에서는 해당 머신의 네트워크 공유로 읽히며, 그 밖의 시스템에서는 데몬이 열 수 있는 어떤 것도 가리키지 않습니다. 쿼리, 프래그먼트, 자격 증명 또는 포트를 함께 담은 주소도 데몬이 열 수 있는 어떤 것도 가리키지 않습니다. 대소문자와 관계없이 file://로 시작하지 않는 값은 결코 주소로 읽히지 않으며, 파일 미검증 거부는 어떤 표기였든 보낸 값을 그대로 명시합니다. 이 중 aggrega/insertionPoint와 aggrega/connectionAtPosition은 사본을 보유하지 않은 경우 디스크에서 문서를 읽는 두 요청이며, 워크스페이스 안의 문서에 대해서만 응답합니다. 루트 밖의 문서는(직접 쓴 경로든, 파일로 또는 도중의 디렉터리로 루트 밖을 향하는 링크를 통해서든) 세 가지 표기 중 무엇으로 가리키든 거부되며, 루트 안의 문서는 세 가지 모두로 응답됩니다. 나머지 여덟 요청은 가리키는 경로에서 디스크의 어떤 것도 읽지 않습니다. aggrega/validate는 문서의 바이트를 content에서 가져오고 나머지는 검증된 내용으로 응답하므로, 워크스페이스 안이든 밖이든 문서를 어디에 두었든 응답하며, 파일을 읽기 위해 가리키는 링크를 따라가지 않습니다. 워크스페이스 밖에서 선택한 문서를 가리키는 매개변수도 같은 이유로 같은 경우입니다. aggrega/import의 source는 해당 항목에서 설명한 대로 실제 위치에서 읽힙니다. 둘 다 클래스 단위로 워크스페이스 경계의 예외이며(클라이언트가 열어 둔 문서, 그리고 사람이 고른 파일), 각각이 예외인 이유는 워크스페이스 경계에서 설명합니다.

데몬이 워크스페이스 안의 문서를 찾아야 하는 매개변수는 워크스페이스 상대 경로만 받습니다. 알아 둘 것은 release입니다. aggrega/irGraph에서, 그리고 그 밖에 등장하는 모든 곳에서 같은 계약을 따르며, 절대 경로 값은 invalid-params 오류로 거부됩니다. 이 오류는 계약을 설명한 뒤 구체적인 잘못을 명시합니다. 워크스페이스 안에 쓰는 요청은 각 항목에서 설명한 대로 대상 경로에 같은 계약을 적용합니다. 그런 모든 경로는 이어서 그것이 향하는 곳으로 판단되며, 요청이 읽든 쓰든 하나의 규칙을 따릅니다. 이는 워크스페이스 경계가 정의하는 “안”의 기준입니다. 밖을 향하는 경로는 보낸 값을 그대로 인용하여 해당 요청 자체의 오류로 거부되며, 아무것도 읽거나 쓰지 않습니다. 밖의 파일로 향하는 링크와 도중의 디렉터리로 향하는 링크가 모두 그러하며, 밖을 향하는 링크된 디렉터리 아래에 아직 만들어지지 않은 경로도 그곳에 쓰거나 밖에서 찾아 누락으로 보고하는 대신 링크 때문에 거부됩니다. 이는 요청이 데몬에게 읽도록 지정하는 모든 경로(어디에 등장하든 release, aggrega/lint의 entity, 게시 요청의 entity, plugin, file, from)에 적용되므로, 요청은 워크스페이스 자체의 목록에서 제외된 파일을 링크를 통해 읽을 수 없습니다. 또한 모든 대상 경로에도 적용됩니다. 생성, 가져오기, 빌드가 쓰는 디렉터리, aggrega/pin이 옆에 잠금을 쓰는 엔터티, aggrega/pluginSync가 읽고 다시 쓰는 엔터티 파일과 모듈, 그리고 aggrega/editDocument가 편집하는 문서입니다. 워크스페이스 구성이 지정한 Release를 가리키는 release는 aggrega/irGraph의 항목에서 설명한 대로 유일한 예외입니다.

둘이 다른 것은 발생할 수 있는 잘못이 다르기 때문입니다. 이미 보유한 문서를 가리키는 매개변수에는 어느 문서인가라는 질문 하나만 남으므로, 표기를 정규 표기로 변환해도 잃는 것이 없고 각 표기를 받아들여도 비용이 들지 않습니다. 워크스페이스 안에서 문서를 선택하는 매개변수는 그런 처지가 아닙니다. 클라이언트가 사용할 가능성이 높은 경로 라이브러리에서는 절대 경로 값을 루트에 이어 붙이면 오류가 아니라 그 절대 경로 값이 그대로 나옵니다. 따라서 값을 조용히 고쳐 주면 데몬은 워크스페이스가 보유한 적 없는 경로를 읽고 그에 대한 결과를 보고하게 되며, 존재하지 않는 파일에 대해 안내받게 됩니다. 고쳐 주는 대신 거부하는 것이 답입니다. 그런 값을 고쳐 주는 데몬은 그런 값을 보내는 모든 클라이언트가 계약이 선택 사항이라고 믿게 만들기 때문입니다.

엔터티를 지정하는 방식

응답이 명명하는 모든 엔터티는 kind, name, file이라는 같은 방식으로 지정됩니다. 표시하려는 정보가 있으면 이 세 키로 aggrega/catalogIndex와 조인합니다. 이것이 엔터티의 전체 설명 집합인 apiVersion, description, labels를 담는 표면이므로, 엔터티를 명명하기만 하면 되는 응답은 세 지정 키만 보고하고 설명은 한곳에 맡깁니다. aggrega/entityDefinition 같은 이름 기반 조회는 자체 응답이 다루는 몇몇 설명 필드를 반복하지만, 전체 집합이 필요할 때 조인할 표면은 여전히 인덱스입니다.

응답이 둘 이상의 위치에서 엔터티를 명명할 수 있는 경우, 각 식별 정보는 이 세 키 옆에 origin을 함께 담습니다. aggrega/catalogIndex와 aggrega/attachCandidates가 모두 그러한데, 이들의 엔터티는 워크스페이스 문서와 구성된 카탈로그 디렉터리 양쪽에서 오기 때문입니다. 한 위치만 참조하는 응답은 세 키만 보고하고 origin은 보고하지 않습니다. 가능한 값이 하나뿐인 키는 아무 정보도 주지 않기 때문입니다. 그러한 응답이 명명하는 엔터티는 모두 워크스페이스 문서이며, 그 file은 열 수 있는 워크스페이스 상대 경로입니다. 따라서 origin을 모든 곳에서 요구하지 말고 있을 때 읽으십시오. 어느 경우든 조인 기준은 세 키입니다.

origin은 엔터티를 나열하는 응답, 즉 모집단을 구별하는 것이 읽는 쪽의 문제인 응답에 속합니다. aggrega/entityDefinition 같은 이름 기반 응답에는 이것이 없습니다. 이름이 확인된 단 하나의 엔터티를 명명하므로 구별할 모집단이 없기 때문입니다. 그 file이 비어 있는 경우는 위의 해당 항목에 설명되어 있습니다. 그 비어 있음을 목록을 설명하는 아래의 origin 값을 통해 해석하지 마십시오.

origin은 데몬이 엔터티를 어디서 읽었는지 알려 주며, file을 해석할 수 있게 해 주는 것이 바로 이 값입니다.

  • workspace — 워크스페이스 루트 아래의 Aggrega 문서입니다. file은 그 루트에 대한 상대 경로이며, 클라이언트가 열 수 있는 경로입니다.
  • catalog — 구성된 카탈로그 디렉터리에서 확인된 엔터티입니다. 이 목록에서 file은 비어 있으며, name이 주소 전체입니다. 비어 있는 이유는 목록이 카탈로그 조회가 열거한 것, 즉 문서가 아닌 식별 정보를 보고하므로 항목에 보고할 경로가 없기 때문입니다. 위치 때문에 숨겨진 경로가 아닙니다. 문서가 필요하면 같은 이름으로 aggrega/entityDefinition을 요청하십시오. 이 요청은 엔터티를 확인하고 그 file을 위의 규칙에 따라 보고하므로, 워크스페이스 루트 밖의 카탈로그 디렉터리는 그곳에서 절대 경로로 명명됩니다. 어차피 name은 Aggregate, Recipe, 카탈로그 조회가 모두 사용하는 좌표입니다.

file만 검사하지 말고 둘을 함께 읽으십시오. 빈 file만으로는 엔터티에 워크스페이스 경로가 없는 것인지, 단지 보고되지 않은 것인지 알 수 없습니다. origin이 이를 직접 알려 줍니다.

Feature에 두 경로로 모두 도달할 수 있는 경우, 즉 워크스페이스 루트 자체가 구성된 카탈로그 디렉터리 중 하나인 흔한 레이아웃에서는, 워크스페이스 문서로 한 번만 보고됩니다. 그것이 파일을 열 수 있는 사본이기 때문입니다.

attach-candidate 응답이 알려 주는 것

aggrega/attachCandidates는 하나의 질문, 즉 이 레이블 집합이 어떤 Features를 허용하는지에 답하며, 어떤 레이블 집합을 뜻하는지 지정하는 세 가지 방법을 제공합니다. 좌표는 정확히 하나만 보내십시오. 두 개를 보내거나 하나도 보내지 않으면 순위를 매기는 대신 거부됩니다.

{node}는 워크스페이스 문서를 metadata.name으로 지정하며 다른 것은 필요하지 않습니다. 일치 여부는 해당 문서가 metadata.labels에 선언한 레이블을 기준으로 평가되며, 응답은 labelSource: "declared"를 보고합니다.

{graphNode, release}는 컴파일된 그래프의 노드를 지정합니다. graphNode는 그래프가 노드를 키로 삼는 id로, aggrega/irGraph에서 읽는 것과 같은 id이며 하위 aggregate가 기여한 노드가 갖는 한정된 형태도 포함합니다. release는 워크스페이스 루트에 대한 상대 경로로, 그래프를 빌드할 Release를 지정하며 aggrega/irGraph가 받는 것과 같은 값입니다. 일치 여부는 노드의 최종 레이블을 기준으로 평가되며, 응답은 labelSource: "resolved"를 보고합니다.

{labels}는 레이블 집합 자체를 담으며 아무것도 지정하지 않습니다. 이는 다른 두 좌표의 바탕이 되는 형태입니다. 일치는 레이블 집합과 제공되는 Features의 함수이므로, 이미 레이블 집합을 가진 클라이언트는 지정할 것도 기다릴 것도 없습니다. 레이블 쌍으로 된 JSON 객체를 보내십시오. 응답은 labelSource: "supplied"와 빈 node를 보고하는데, 이 요청은 아무것도 지정하지 않았기 때문입니다. 빈 객체는 좌표입니다. 레이블이 없는 노드에 대해 묻는 것입니다. 반면 키를 완전히 생략하거나 null을 보내면 아무것도 지정하지 않으므로 거부됩니다.

두 이름 좌표는 식별자 공간이 겹치기 때문에 분리되어 있습니다. 그래프 노드 id와 문서의 metadata.name은 서로 다른 것을 지칭하면서도 같은 문자열일 수 있으므로, 둘을 모두 담는 하나의 매개변수는 모호해지고, 어느 공간을 뜻하는지 추측하는 데몬은 때때로 잘못된 대상에 대해 확신에 차서 답하게 됩니다. 어떤 질문을 하는지 밝히는 것이 모호함을 없애는 방법입니다.

labelSource는 답이 어디까지 미치는지를 알려 주며, 세 값은 서로 바꿔 쓸 수 없습니다. declared는 한 문서가 자기 자신에 대해 말하는 내용에 대한 일치로, 소스를 읽어서 볼 수 있는 범위입니다. resolved는 노드가 실제로 최종적으로 갖게 되는 레이블에 대한 일치로, 빌드가 적용 가능성을 평가하는 기준입니다. 따라서 resolved 답은 빌드가 무엇을 결정할지에 대한 진술이지만 declared 답은 그렇지 않습니다. supplied는 데몬이 레이블을 전혀 읽지 않고 보낸 것을 일치시켰다는 뜻이며, 그 답의 신뢰도는 전적으로 레이블 집합의 출처에 달려 있습니다.

그래서 그래프를 가진 클라이언트는 이름 대신 {labels}를 보내야 합니다. 노드의 최종 레이블은 노드가 해석되는 component type의 레이블이지, 우연히 같은 id를 가진 문서의 레이블이 아닙니다. 또한 label-transform 어태치먼트가 그 레이블을 추가, 변경 또는 제거할 수 있으므로, 노드의 적용 가능성을 결정하는 레이블이 어느 한 문서가 선언한 레이블과 같을 필요는 없습니다. 그래프를 그리는 클라이언트는 이미 aggrega/irGraph에서 그 집합을 가지고 있으며, 이를 다시 전달하면 그래프를 다시 빌드하지 않고도 {graphNode, release} 좌표가 주는 것과 같은 답을 얻습니다. 데몬이 직접 보고한 집합, 즉 aggrega/irGraph의 노드 레이블이나 aggrega/catalogIndex의 엔터티 레이블을 다시 전달하면, 그 집합이 데몬 자신의 답을 벗어난 적이 없으므로 노드 레이블에 대한 이해가 데몬의 것과 어긋날 수 없습니다. 직접 집합을 조립하면 가정에 대해 묻는 것이 되며, 이는 정직하게 답해지지만 워크스페이스가 가진 어떤 노드에 대한 진술도 아닙니다.

후보는 워크스페이스와 카탈로그에서 나옵니다. Features를 자체 트리가 아닌 카탈로그에 두는 워크스페이스에는 로컬 Feature가 전혀 없으며, 그 후보는 모두 origin: "catalog"입니다. 그래프 노드의 경우 둘 다 해당 노드의 Release 기준으로 읽힙니다. 카탈로그 Features는 워크스페이스 구성이 그 Release에 부여한 카탈로그 디렉터리가 선언하는 것들이며, 워크스페이스 자체 문서는 다른 Releases만 읽는 카탈로그 디렉터리 아래의 문서를 제외하고 제공됩니다. 따라서 Release마다 Feature의 변형을 두는 워크스페이스는 각 Release의 그래프에 그 자신의 변형만 제공하고 다른 것의 변형은 결코 제공하지 않으며, 카탈로그 옆에, 어떤 카탈로그 디렉터리에도 속하지 않게 작성된 Feature는 모든 Release에 제공됩니다. {node}와 {labels}는 Release를 지정하지 않으므로 모든 워크스페이스 문서와 워크스페이스 자체의 catalog_dirs를 사용합니다. 적용 가능성을 전혀 선언하지 않은 Feature는 모든 노드의 후보입니다. 선언이 없으면 요구 사항도 없기 때문입니다. 반면 선언을 읽을 수 없는 Feature는 어떤 노드의 후보도 아닌데, 읽을 수 없는 셀렉터를 충족된 것으로 취급하면 오타 하나로 제공 범위가 넓어질 수 있기 때문입니다.

해석되지 않는 이름은 빈 목록이 아니라 오류입니다. 두 답은 의미가 다릅니다. 빈 candidates 배열은 이 노드에 어태치할 수 있는 것이 없다는 뜻이며, 잘못 입력한 이름을 그렇게 보고하면 오타를 확정된 답처럼 보여 주게 됩니다. 거부 응답은 검색한 공간을 명시하므로 워크스페이스 문서를 찾아야 할지 그래프 노드를 찾아야 할지 알 수 있습니다. {labels}에는 그런 위험이 없습니다. 잘못 입력할 이름이 없기 때문입니다. 따라서 아무것도 허용하지 않는 레이블 집합은 빈 배열을 담은 성공 응답으로 돌아오며, 데몬이 읽을 수 없는 요청은 여전히 일치 작업이 실행되기 전에 거부됩니다.

그래프 노드 좌표에는 lockfile이 필요하며, 다른 두 좌표에는 필요하지 않습니다. 그래프를 빌드한다는 것은 Release가 도달하는 것을 해석한다는 뜻이므로, lockfile이 생성되지 않았으면 이 경로는 실행할 명령을 알려 주는 lockfile 부재 오류로 거부됩니다. 이는 aggrega/irGraph가 같은 이유로 갖는 것과 같은 전제 조건입니다. 워크스페이스 문서를 지정하는 것은 그래프를 빌드하지 않고, 레이블 집합을 제공하는 것은 아무것도 빌드하지 않으므로, 둘 다 아직 아무도 준비하지 않은 워크스페이스에서도 답합니다.

보고만 하며 생성하지 않습니다. 이 메서드는 아무것도 변경하지 않고, 아무것도 쓰지 않으며, 어태치먼트를 생성하지 않습니다. 편집을 구성하고 적용하는 것은 버퍼와 실행 취소 기록이 있는 에디터의 몫입니다.

무엇을 해석하는지는 좌표에 따라 다르며, 세 좌표는 같지 않습니다. {node}는 아무것도 해석하지 않고 레지스트리나 네트워크에 접근하지 않습니다. 후보는 워크스페이스와 카탈로그 디렉터리에서 나오며, 둘 다 이미 디스크에 있습니다. {labels}는 그보다도 적게 해석합니다. 조회할 것이 없으므로 아무것도 조회하지 않습니다. {graphNode, release}는 Release의 그래프를 빌드하므로 aggrega/irGraph와 같은 방식으로 그 Release의 의존성 클로저를 해석합니다. 먼저 로컬 카탈로그 디렉터리와 아티팩트 캐시에서, 그리고 둘 중 어느 곳에도 없는 엔터티는 구성된 레지스트리에서 해석합니다. 엔터티가 모두 로컬에 있는 워크스페이스라면 세 좌표 모두 오프라인으로 답하며, 더 멀리 찾으러 갈 수 있는 것은 그래프 노드 좌표뿐입니다.

연결에 대해 묻기

컴포넌트가 그리는 연결은 자체 어태치먼트를 가질 수 있으며, 이는 소비하는 Component에서 해당 소켓이 선언하는 슬롯을 채웁니다. 예를 들어 컴포넌트가 연결이 닿는 대상에 제시하는 자격 증명이 그렇습니다. 그곳에 무엇이 들어갈 수 있는지 물으려면 {graphNode, release}와 함께 connection을 보냅니다. socket은 연결이 배선된 의존성 소켓이고 alias는 그 소켓 안에서 연결이 갖는 이름이며, 둘 다 작성자가 쓴 그대로입니다. 연결은 컴파일된 그래프에만 존재하므로 node 또는 labels와 함께 보낸 connection은 거부되며, 소켓이나 별칭을 지정하지 않은 연결, 또는 노드가 그리지 않는 연결도 거부됩니다.

답변은 그래프 노드 답변에 연결의 슬롯을 더한 것입니다. candidates는 의미가 그대로 유지되어 노드 자체에 attach될 수 있는 Features를 나타내며, slots가 추가되어 소켓이 선언하는 슬롯마다 하나의 항목을 Component가 선언하는 순서대로 담습니다:

  • slot — 이 슬롯을 채우는 어태치먼트가 연결의 features에서 작성되는 이름입니다.
  • selector, required, inject, sensitive, description — Component가 소켓에 선언한 그대로의 슬롯이며, 아무것도 선언하지 않은 곳은 비어 있거나 false입니다. selector는 후보를 좁히는 데 사용된 제약이므로, 응답만으로 후보나 후보가 없는 이유를 설명할 수 있습니다.
  • candidates — 이 연결에서 이 슬롯을 채울 수 있는 Features입니다. 빌드는 이러한 어태치먼트에 두 가지 규칙을 적용하며, 두 규칙 모두 적용됩니다. 하나는 노드의 최종 레이블에 대한 Feature의 선언된 적용 가능성으로, 노드가 갖는 모든 어태치먼트에 적용됩니다. 다른 하나는 Feature 자체의 레이블에 대한 슬롯의 selector입니다. 따라서 슬롯의 후보는 항상 노드의 후보 중 셀렉터로 좁혀진 것입니다. 셀렉터를 평가할 수 없는 레이블을 가진 Feature는 제공되지 않습니다. 빌드가 이를 허용하지 않고 거부하기 때문입니다.

채울 수 있는 슬롯이 없으면 slots는 빈 목록이며 noSlotReason이 그 이유를 알려 줍니다. 빈 목록을 “일치하는 Feature 없음”으로 받아들이지 말고 이유를 읽으십시오. 그것은 다른 응답이며, 둘을 구별해 주는 것이 바로 이유입니다.

  • feature-created-connection — Feature가 자체 의존성 블록에서 연결을 그렸습니다. 어태치먼트는 컴포넌트나 Release가 그리는 연결에만 작성되므로, 소켓이 무엇을 선언하든 여기에는 아무것도 들어가지 않습니다.
  • ad-hoc-socket — 소켓이 Component가 선언하지 않은 것입니다. 작성자가 이름을 지정했으며 이는 허용되지만, 선언되지 않은 소켓은 슬롯을 선언하지 않습니다.
  • no-slot-declared — Component가 슬롯 없이 소켓을 선언합니다.

슬롯이 존재하는 곳에서는 noSlotReason이 없으며, 연결을 지정하지 않은 요청에 대한 응답에는 slots와 noSlotReason이 모두 없습니다. 따라서 연결을 지정하지 않은 요청은 두 필드가 모두 없는 응답을 받습니다.

document는 허용되지만 여기서는 아무것도 바꾸지 않습니다. 슬롯은 소켓의 것이고 후보는 Features의 것이므로, 어태치먼트가 어느 문서에 작성되든 같습니다. 어디에 들어가는지는 aggrega/attachmentContainer가 답합니다. aggregate나 release가 아닌 값은 여전히 거부됩니다. 허용되었지만 무시된 값은 보낸 쪽에게 반영된 값처럼 읽히기 때문입니다.

connection-candidate 응답이 알려 주는 것

aggrega/connectionCandidates는 두 가지 질문에 한꺼번에 답하며, 그중 하나만 완전한 답을 가집니다. 응답을 하나의 필터링된 목록으로 읽으면 나머지 하나를 잘못 이해하게 됩니다.

보고되는 각 소켓은 targets를 가집니다. 이는 해당 소켓이 자신을 충족할 수 있는 대상에 대해 선언한 레이블 제약을 선언된 레이블이 충족하는 워크스페이스 로컬 Components입니다. 여기에 더해 그 대상들을 계산하는 데 쓰인 selector, 소켓이 선언한 required 플래그, 그리고 declaration을 가집니다. targets는 항상 배열이며 없는 대신 비어 있으므로, 아무것도 충족하지 않는 소켓도 엔터티가 선언한 소켓으로 여전히 보고됩니다.

대상 쪽은 완전합니다. 이 집합은 소켓의 선언된 제약을 후보의 선언된 레이블에 대해 평가하여 결정되며, 이는 빌드가 수행하는 것과 같은 평가입니다. 따라서 제시하는 것은 같은 제약이 빌드 중에 허용하는 것과 같습니다. 제약을 선언하지 않은 소켓은 대상을 제약하지 않으며 모든 Component를 보고합니다. 이는 빈 셀렉터에 대한 제약 언어의 의미이지 오류가 아닙니다.

소켓 쪽은 열려 있으며, declaration과 adHocSocketsAccepted로 이를 구별합니다. Aggregate의 작성자는 그 토폴로지를 소유하며 컴포넌트의 카탈로그 엔터티가 선언한 적 없는 소켓을 연결할 수 있습니다. 따라서 엔터티가 선언하는 소켓은 유용한 시작 집합일 뿐 합법적인 소켓 이름의 집합이 아닙니다. 이를 유일한 선택지가 아니라 제안으로 제시하십시오. 선언된 소켓만 제시하는 선택기는 작성자에게 실제보다 자유가 좁다고 알리는 셈이 됩니다.

  • declaration은 지정된 엔터티가 소켓을 자신의 usesSchema에 나열하면 declared이고, 나열하지 않으면 ad-hoc입니다. 이는 IR 그래프에서 엣지가 가지는 것과 같은 두 값이므로, 하나의 어휘로 “이 소켓은 어디에서 왔는가”라는 질문에 어디서든 답할 수 있습니다.
  • adHocSocketsAccepted는 지정된 엔터티의 표면이 자신의 선언에 나열되지 않은 소켓을 허용하는지를 보고합니다. 이 값이 항상 참인 것은 아닙니다. Component 자체의 의존성 표면은 이를 허용하지만, Feature의 첨부 표면은 허용하지 않습니다. 첨부는 자체 토폴로지를 작성하는 대신 첨부된 Feature가 선언하는 토폴로지에 참여하기 때문입니다. 이를 허용하지 않는 표면의 ad-hoc 소켓은 대상 없이 보고되는데, 그 소켓을 통한 어떤 연결도 빌드되지 않기 때문입니다.

요청에서 socket을 지정하면 답이 그 하나의 소켓으로 한정되며, 이는 엔터티가 선언하지 않은 소켓에 대해 질문하는 유일한 방법입니다. 선언되지 않은 소켓은 열거할 어떤 선언에도 나타나지 않기 때문입니다. 이를 생략하면 엔터티가 선언하는 모든 소켓을 작성된 순서대로 받습니다.

보고하는 것은 선언된 레이블에 대한 일치입니다. 빌드는 소켓의 제약을 엣지 반대편 끝에 있는 노드의 최종 레이블에 대해 평가하며, 그 레이블은 label-transform 첨부가 모두 적용된 뒤 그 노드가 해석되는 컴포넌트 유형의 레이블입니다. 반드시 지정한 문서의 레이블인 것은 아닙니다. 따라서 여기서의 긍정적인 답은 빌드가 무엇을 결정할지에 대한 약속이 아닙니다. 이는 aggrega/attachCandidates가 declared 레이블 소스에서 가지는 것과 같은 한계입니다.

보고만 하고 생성하지 않습니다. 이 메서드는 아무것도 해석하지 않고, 레지스트리나 네트워크에 접근하지 않으며, 아무것도 쓰지 않습니다. 엣지를 만들지 않고 텍스트를 제안하지도 않습니다. 편집을 구성하고 적용하는 것은 버퍼와 실행 취소 기록이 있는 편집기의 몫입니다.

targets에 있는 엔터티 식별자인 kind, name, file에 대해서는 엔터티를 지정하는 방법에 설명된 대로 aggrega/catalogIndex와 조인하십시오. 설명 필드는 그곳에서 보고되며 의도적으로 여기서 반복하지 않으므로, 이 응답에는 어긋날 수 있는 두 번째 사본이 없습니다. 대상은 워크스페이스 Components이므로 모두 열 수 있는 file을 가지며 어느 것도 origin을 가지지 않습니다. 이 응답은 한 곳에서만 가져오며, 조인은 세 키를 기준으로 합니다.

attachment-container 응답이 알려 주는 것

aggrega/attachmentContainer는 위의 후보 요청과 아래의 삽입 지점 사이에 위치합니다. 후보 요청은 노드에 무엇이 부착될 수 있는지를 알려 주고, 이 요청은 그 노드에 대한 부착이 어느 컨테이너에, 어느 문서에 속하는지를 알려 주며, 다음 요청은 텍스트가 그 문서의 바이트 중 어디에 들어가는지를 알려 줍니다.

컨테이너를 직접 구성하지 말고 요청하십시오. 노드의 id와 그 노드를 감싸는 서브시스템 경로는 모두 각 부분 사이에 점을 넣어 표기하며, 점은 작성자가 입력하는 이름에 쓸 수 있는 문자입니다. 따라서 문서 밖에서는 구조상의 점과 이름 안의 점을 구별할 방법이 없습니다. 클라이언트가 경로를 직접 조립하면 올바르게 읽히지만 아무도 작성하지 않은 키를 가리키는 결과가 만들어지고, 뒤따르는 편집은 거부되는 대신 그 키를 생성하게 됩니다. 두 경로를 구성한 것은 컴파일러이므로 이를 분해하는 것도 컴파일러입니다.

노드 id에는 그 노드를 감싸는 서브시스템의 흔적이 전혀 남아 있지 않습니다. subsystems.billing.subsystems.payments 안에서 작성된 component는 최상위 component와 똑같이 그래프에서 ledger라는 키로 저장되므로, 클라이언트가 아무리 신중하게 분할하더라도 id에는 활용할 정보가 없습니다.

응답은 세 개의 필드로 구성됩니다.

  • node는 응답의 대상인 노드를 다시 담고 있으므로, 여러 요청을 동시에 보낸 클라이언트도 별도로 순서를 관리하지 않고 각 응답을 해당 질문과 짝지을 수 있습니다.
  • file은 노드가 작성된 문서이며 워크스페이스 기준 상대 경로입니다. 이는 이미 알고 있는 정보가 아니라 응답의 일부입니다. 가져온 모듈이 제공한 노드는 그 모듈 자체의 문서에서 모듈이 부여한 이름으로 작성되었으므로, 파일과 컨테이너의 마지막 세그먼트 모두 요청에서 지정한 것과 다릅니다.
  • container는 해당 문서의 루트로부터의 구조적 경로이며 세그먼트 목록으로 표현됩니다. 예: ["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. 감싸는 서브시스템의 각 단계는 다시 subsystems 키 아래에 놓이며, 이는 문서가 표기하는 방식 그대로입니다. 작성자가 최상위에 작성한 component는 대신 ["spec", "components", "checkout", "features"]를 가리키는데, 그러한 component가 컴파일되는 범위는 어떤 파일에도 포함되어 있지 않기 때문입니다.

이는 세그먼트 목록이며 결코 연결된 문자열이 아닙니다. 그리고 바로 그것이 이 형태의 핵심입니다. 연결된 경로는 받는 쪽에서 다시 분할해야 하므로, 위에서 설명한 모호성이 한 번의 호출 뒤에 다시 생겨납니다. 이 목록을 변경하지 말고 그대로 aggrega/insertionPoint의 container로 전달하십시오.

구조만 읽고 의미는 결코 읽지 않습니다. 응답은 노드가 작성된 문서, 노드가 놓인 범위, 작성자가 입력한 이름으로부터 도출됩니다. component의 이름, 그것이 가진 타입, 레이블의 내용에서는 아무것도 읽어 내지 않습니다.

보고만 하고 결코 쓰지 않습니다. 이 메서드는 아무것도 변경하지 않으며 어떤 문서에도 쓰지 않습니다. 부착을 생성하지 않고, 텍스트를 구성하지 않으며, 편집을 적용하지 않습니다. 무엇이 부착될 수 있는지도 판단하지 않으며, 그것은 aggrega/attachCandidates의 역할입니다.

그래프에 없는 노드를 지정한 요청은 응답되지 않고 거부됩니다. 노드 id는 그래프 자체의 키입니다. aggrega/irGraph가 반환하는 그래프에서 읽으십시오. 가져온 모듈이 제공한 노드는 한정된 id를 가집니다. 그래프에 문서가 기록되지 않은 노드도 거부됩니다. 부착이 속하는 위치는 문서에 관한 사실이므로, 문서가 없는 노드에는 빈 응답이 아니라 응답 자체가 없습니다.

잠금 파일이 필요합니다. 이유는 aggrega/irGraph와 같습니다. 컨테이너를 지정하려면 Release의 그래프를 빌드해야 하는데, 아무것도 보증하지 않는 바이트로 빌드한 그래프는 검증된 그래프와 똑같이 보고될 것이기 때문입니다.

연결에 대한 부착

{graphNode, release}와 함께 connection(그 socket, alias, document)을 보내면, 응답은 노드의 컨테이너 대신 해당 연결 자체 항목의 features 컨테이너를 지정합니다. 여기서는 document가 필수입니다. Aggregate가 그린 연결에 대한 부착은 두 문서 중 어느 쪽에든 있을 수 있기 때문입니다. 개발자는 Aggregate의 연결 항목에, 운영자는 Release의 해당 엣지별 항목에 작성합니다.

  • **aggregate**는 노드가 작성된 문서에서 연결의 항목을 지정합니다. 최상위 component의 경우 ["spec", "components", "gateway", "uses", "models", "gpt", "features"]이며, 감싸는 각 서브시스템은 위와 같이 단계별로 표기됩니다. Release가 그린 연결은 Aggregate에 항목이 없으므로 이 경우 거부됩니다.
  • **release**는 노드에 대한 Release 자체 항목 아래의 엣지별 항목을 지정합니다. 예: ["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]. Release가 그 엣지별 항목을 아직 작성했는지 여부와 관계없습니다. 작성하지 않은 경우 aggrega/insertionPoint가 아직 작성해야 할 키를 missingContainerKeys에 보고합니다. 이때 file은 Release 문서입니다. 노드에 대한 항목을 전혀 작성하지 않은 Release는 거부됩니다. 노드를 어디에 배치할지는 운영자가 작성할 몫이며, 응답이 이를 결정하지 않습니다.

Feature가 그린 연결은 위에서 feature-created-connection이 설명한 이유로 어느 문서에서든 거부됩니다. 노드, 소켓, 별칭은 작성된 그대로 정확히 일치해야 하며, 노드가 그리지 않는 연결은 경로로 응답되지 않고 거부됩니다. 위의 다른 모든 속성은 그대로 유지됩니다. 응답은 세그먼트 목록이며, 구조만 읽고 의미는 결코 읽지 않고, 아무것도 쓰지 않습니다.

connection-at-position 응답이 알려 주는 것

aggrega/connectionAtPosition은 위의 두 연결 요청보다 앞선 단계로, 그래프의 노드가 아니라 문서의 위치를 가진 클라이언트를 위한 것입니다. 예를 들어 연결 항목 위에 놓인 커서가 그렇습니다. 이 요청은 그곳에 어떤 연결이 작성되어 있는지를 그 요청들이 받는 좌표로 답하고, 거기서 멈춥니다.

응답은 두 부분 중 하나이며, 둘 다인 경우는 없습니다.

  • graphNode와 connection — 연결을 그리는 component를 가진 노드(컴파일된 그래프가 키로 사용하는 id로 표시)와 socket 및 alias로 표시한 연결이며, document는 위치를 읽은 문서를 나타냅니다. Aggregate 또는 그것이 가져오는 모듈이면 aggregate, Release이면 release입니다. 연결의 socket이 선언하는 슬롯을 얻으려면 graphNode, 같은 release, connection을 aggrega/attachCandidates에 전달하고, 그 연결에 대한 첨부가 들어갈 곳을 얻으려면 aggrega/attachmentContainer에 전달합니다. 그 요청이 지정하는 컨테이너는 위치가 속한 바로 그 항목 안에 있습니다.
  • noConnectionReason — 연결이 보고되지 않는 이유입니다. 그 집합은 닫혀 있습니다.
    • no-connection-entry — 위치가 첨부를 작성하는 어떤 항목에도 있지 않습니다. 대상 목록으로 작성된 연결(db: [store])과 Feature 자체의 의존성 블록이 그리는 연결에는 그런 항목이 없으므로, 둘 중 어느 쪽 위의 위치도 이 값으로 답합니다.
    • feature-created-connection — 위치가 Feature가 그린 연결에 대한 Release의 항목 위에 있으며, 그 항목은 위의 슬롯 응답이 설명한 이유로 첨부를 갖지 않습니다. Release는 Feature의 의존성 블록이 소비하는 Component도 선언하는 socket을 통해 연결을 그리는 곳에 그런 항목을 작성합니다. 이 항목은 아무것도 구성하지 않든 연결의 간선별 infra를 설정하든 빌드됩니다.
    • unknown-connection — 위치가 컴파일된 그래프에 없는 연결에 대해 Release가 작성한 항목 위에 있습니다. 빌드되는 Release도 그런 항목을 가질 수 있습니다. 예를 들어 아무것도 그리지 않는 alias 아래에서 아무것도 구성하지 않는 항목(target도, infra도, features도 없음)이나, active: 토글로 꺼진 component에 대한 항목이 그렇습니다. 꺼진 component의 연결은 그 component와 함께 빌드에서 빠집니다.

어떤 항목이 해당되는가. Aggregate에서는 component가 그리는 모든 연결이 해당되며, 그 위치는 component가 작성된 문서에서 연결의 alias 아래 항목입니다. 가져온 모듈이 기여한 component라면 그 모듈 자체의 문서입니다. Release에서는 Release가 작성하는 모든 간선별 항목이 해당되며, 그 항목이 연결을 직접 그리든 Aggregate가 그린 연결을 구성하든 마찬가지입니다. 각 항목의 위치는 컴파일된 그래프가 기록하는 것이므로, 어떤 키가 연결인지는 결코 그 이름으로부터 추론하지 않습니다. active: 토글로 꺼진 component는 컴파일된 그래프에 없으므로, Aggregate에 있는 그 component 자체의 항목은 no-connection-entry로 답하고, 그 연결 중 하나에 대한 Release의 항목은 unknown-connection으로 답합니다.

항목 안 어디에 있는 위치든 그 항목 안에 있습니다. 항목은 alias 키부터 그 아래에 들여쓰기된 마지막 줄까지이므로, alias 위, 그 target 위, 또는 그 features 안의 위치는 해당 연결로 답하며, 항목이 중첩된 곳에서는 가장 안쪽 항목이 우선합니다. alias들 위에 있는 socket 자체의 키 위의 위치는 socket이 alias를 하나 갖든 여럿 갖든 어느 항목에도 속하지 않으며, alias 키 앞 들여쓰기 안의 위치도 마찬가지입니다.

어느 문서가 어느 것인지는 Release에서 정해집니다. Release 자체의 파일은 Release가 작성하는 항목을 위해 읽고, 그 밖의 파일은 그래프가 component가 작성된 곳으로 기록한 항목을 위해 읽습니다. Release의 그래프가 아무것도 읽지 않는 문서는 모든 위치에서 no-connection-entry로 답합니다.

보고만 하고 결코 쓰지 않습니다. 또한 aggrega/insertionPoint와 같은 방식으로 문서를 읽습니다. 먼저 세션의 사본을, 없으면 디스크를 워크스페이스 안에서 읽으며, 워크스페이스 밖에 있거나 읽을 수 없거나 올바른 형식의 YAML이 아닌 문서는 같은 방식으로 거부합니다. aggrega/attachmentContainer와 같은 이유로 lockfile이 필요하며, 아무것도 렌더링하지 않고 그래프를 빌드합니다.

insertion-point 응답이 알려 주는 것

aggrega/insertionPoint는 위의 두 후보 요청에 대응하는 요청입니다. 그 요청들은 무엇이 연결되거나 접속될 수 있는지를 알려 주고, 이 요청은 그 텍스트가 특정 문서 하나의 어디에 들어가는지를 알려 줍니다. 답하고 거기서 멈춥니다.

컨테이너는 호출자가 지정하고, 데몬은 그 위치를 찾습니다. container는 문서 루트에서 시작하는 구조 경로(["spec", "components", "web", "features"])이며, 이런 종류의 항목이 이런 종류의 문서에서 어디에 속하는지에 대한 호출자의 진술입니다. 데몬은 엔터티의 이름, 타입, 또는 의미처럼 보이는 것에서 그 경로를 도출하지 않습니다. 작성자가 쓴 바이트를 읽고, 경로의 어느 세그먼트가 이 문서에 이미 있는지, 그 항목들이 놓인 열, 그리고 가장 안쪽 블록이 도달하는 마지막 줄을 보고합니다. 따라서 어느 키인지 아는 것은 호출자의 몫이고, 그 키의 항목이 이 파일의 어디에 들어가는지는 여기서 얻습니다.

컴파일된 그래프의 노드에 대한 Feature 연결의 경우, 호출자가 그 키를 스스로 알 필요는 없습니다. aggrega/attachmentContainer에 문서와 컨테이너를 요청하고, 둘 다 그대로 여기에 전달하면 됩니다.

응답은 폭이 0인 위치와 그 주변에 써야 할 내용입니다. file은 워크스페이스 기준 상대 경로로 나타낸 문서입니다. container는 요청한 경로를 그대로 반복하므로, 여러 요청을 동시에 진행 중인 클라이언트는 자체적으로 순서를 관리하지 않고도 각 응답을 해당 질문과 짝지을 수 있습니다. position은 교체가 아니라 삽입합니다. 문서에 이미 있는 것은 아무것도 덮어쓰이거나 밀리지 않습니다.

  • precededByLineBreak — 쓰는 텍스트를 줄바꿈으로 시작합니다. 위치는 새 항목이 뒤따르는 줄의 끝에 놓이며, 이는 파일이 개행으로 끝나는지와 관계없이 범위 안에 있고 이미 쓰인 바이트를 건드리지 않습니다. 뒤에 놓일 내용이 전혀 없는 문서에서만 false이며, 이 경우 파일의 시작부터 씁니다.
  • missingContainerKeys — 이 문서에 아직 없는 컨테이너 경로의 세그먼트로, 바깥쪽부터 나열됩니다. 항목이 가장 안쪽 세그먼트 안에 들어가려면 각각을 독립된 키로 먼저 써야 합니다. 전체 경로가 이미 있으면 비어 있습니다.
  • entryIndent — 항목 자체의 첫 줄이 시작하는 열로, 줄의 시작부터 공백 수로 셉니다.
  • indentStep — 중첩 수준마다 추가로 들여쓰는 양입니다.
  • indentStepMeasured — 그 단계가 이 문서 자체의 중첩에서 측정되었는지 여부입니다. false이면 문서에 측정할 중첩이 없어 단계가 대체값이므로, 자체 값을 적용하려는 클라이언트는 그렇게 해도 된다는 것을 알 수 있습니다.
  • entryShape — 컨테이너가 이미 담고 있는 것에서 읽은 mapping 또는 sequence이며, 컨테이너가 아직 없거나 아무것도 담고 있지 않으면 unknown입니다. unknown은 실패가 아닙니다. 문서가 항목의 형태를 밝히지 않았으므로 그 선택은 호출자의 몫입니다.

적용 방법. precededByLineBreak가 설정되어 있으면 줄바꿈을 씁니다. 그다음 missingContainerKeys 항목마다 한 줄씩, 바깥쪽부터, 키 뒤에 콜론을 붙여 씁니다. 첫 줄은 entryIndent에서 indentStep에 누락된 키의 수를 곱한 값을 뺀 위치에 들여쓰고, 다음 줄마다 indentStep만큼 더 들여씁니다. 그다음 항목 자체를 entryIndent에 들여써서 씁니다. missingContainerKeys가 비어 있으면 항목이 쓰는 유일한 줄입니다.

컨테이너가 있을 것으로 예상되더라도 missingContainerKeys를 읽으십시오. 앞에 와야 할 키 없이 위치를 적용하면 더 이상 파싱되지 않는 문서가 만들어지며, 이는 이 응답이 결코 없는 것으로 읽어서는 안 되는 유일한 실패입니다.

position은 진단과 달리 0부터 셉니다. line과 character는 모두 0 기반으로, 이 프로토콜이 재사용하는 LSP 형태의 위치 값과 일치합니다. 반면 진단 항목의 line과 column은 What a diagnostic entry carries에 설명된 대로 1 기반입니다. 한쪽 표면의 값을 다른 쪽에 전달하는 클라이언트는 둘 사이를 변환해야 합니다.

positionEncoding은 character를 측정하는 단위를 나타내며, 핸드셰이크에서 협상된 인코딩입니다. 암묵적으로 두지 않고 응답에 보고하는 이유는, 호출자가 단위를 추측해야 하는 위치는 적용할 수 없는 위치이기 때문입니다. 한 방식으로 측정한 오프셋을 다른 방식으로 측정되는 버퍼에 적용하면 ASCII 밖의 첫 문자에서 문서가 손상됩니다.

항목이 들어갈 수 있는 위치를 가리키지 않는 요청은 응답되지 않고 거부됩니다. 다음 각 경우는 워크스페이스가 아니라 요청의 상태이므로, 표준 invalid-params 코드로 반환되며 file 또는 container가 바뀔 때까지 재시도해도 달라지지 않습니다.

  • 문서가 지정되지 않았거나, 워크스페이스 안에 있지 않거나, 읽을 수 없거나, 올바른 형식의 YAML이 아닌 경우입니다. 구조가 없는 문서에는 보고할 위치가 없습니다.
  • 컨테이너 경로가 아무것도 가리키지 않는 경우입니다. 세그먼트가 없거나 세그먼트 중 하나가 비어 있습니다.
  • 경로가 문서에서 스칼라로 담긴 값을 통과하는 경우입니다. 스칼라 안에는 아무것도 덧붙일 수 없으며, 이를 교체하는 것은 삽입이 아니라 재작성입니다.
  • 경로가 작성자가 플로 스타일로 쓴 컬렉션에 도달하는 경우입니다. 여기에 항목을 덧붙이면 줄을 추가하는 대신 작성자가 이미 쓴 바이트를 재작성하게 되며, 이는 위치가 아니라 편집입니다.
  • 경로가 블록 시퀀스를 그 인덱스가 아닌 것으로 가리키는 경우입니다. 시퀀스의 항목은 위치로 지정되므로 이름은 그 안의 아무것에도 도달하지 않으며, 그 이름을 담을 항목을 만들 수도 없습니다.

디스크의 파일만이 아니라 편집기가 보유한 버퍼를 읽습니다. 데몬의 파싱 캐시를 먼저 참조하므로, 저장되지 않은 내용이 있으면 그 내용을 기준으로, 캐시에 해당 파일에 대한 내용이 없으면 파일 자체를 기준으로 위치를 보고합니다.

보고만 하고 쓰지 않습니다. 이 메서드는 아무것도 변경하지 않고, 아무것도 해석하지 않으며, 레지스트리나 네트워크에 접근하지 않고, 어떤 문서에도 쓰지 않습니다. 항목의 텍스트를 구성하지도 적용하지도 않습니다. 편집을 구성하고 적용하는 것은 버퍼와 실행 취소 기록이 있는 편집기의 몫입니다.

document-edit 응답이 알려 주는 것

aggrega/editDocument는 위 쌍의 나머지 절반입니다. 위의 요청들은 항목이 어디에 들어가는지 알려 주고 작성과 적용은 호출자에게 맡기지만, 이 요청은 항목 하나를 작성하고 적용하며 실제로 씁니다. 두 방식 모두 제공되는데, 저장되지 않은 버퍼를 가진 클라이언트와 디스크의 내용을 편집하는 클라이언트는 서로 다른 절반을 원하기 때문입니다. 자체 실행 취소 기록을 가진 편집기는 텍스트를 직접 배치하고, 어디를 편집할지 안내받기보다 파일이 편집되기를 원하는 클라이언트는 이 요청을 보냅니다.

한 번의 호출은 하나의 편집을 적용하며, 편집의 집합은 닫혀 있습니다. edit가 어떤 편집인지 지정합니다. add-component는 components 컨테이너 아래에 component 인스턴스를 추가하고, attach-feature는 노드에 Feature를 연결하며, wire-edge는 노드의 의존성 소켓 중 하나 안에 연결을 배선하고, set-value는 노드에 값 하나를 설정합니다. 삭제하거나, 이미 작성한 블록을 교체하거나, 무언가의 순서를 바꾸거나, 제공한 바이트를 그대로 쓰는 편집은 없습니다. 따라서 이것은 이름만 좁힌 파일 작성기가 아니며, 네 가지 이외의 값은 해석되지 않고 거부됩니다. 거부 응답에는 지정할 수 있는 값이 나열됩니다.

노드는 위의 두 요청과 똑같이 구조적 경로로 지정합니다. node는 문서 루트로부터의 이동 경로(["spec", "components", "web"])이며, 항목이 들어갈 컨테이너는 edit에 따라 정해집니다. add-component의 경우 추가되는 항목이 곧 노드이므로 경로는 components 컨테이너 자체를 가리킵니다. name은 항목이 기록될 키로, 인스턴스 이름, 연결 항목의 이름, 연결의 별칭 또는 값의 키입니다. value는 그 항목이 담는 내용이며, 그 의미는 edit에 따라 정해집니다. 즉 항목이 요청하는 엔터티, 연결이 가리키는 노드, 또는 값으로 설정되는 스칼라입니다. socket은 wire-edge에서만 읽히고 그 외에는 무시됩니다.

이름 대신 경로를 쓰는 이유는 위치를 찾는 요청이 경로를 받는 이유와 같습니다. 이름은 검색해야 하고, 두 단계에 나타나는 이름이라면 어느 쪽을 의미했는지 컴파일러가 결정해야 합니다. 따라서 편집할 노드를 아는 클라이언트는 그것을 명시하고, 모르는 클라이언트는 무엇이든 편집하기 전에 답해야 할 질문이 있음을 알게 됩니다.

편집이 건드리지 않는 모든 바이트는 그대로 유지됩니다. 문서는 컨테이너와 그 블록이 끝나는 줄을 찾기 위해서만 파싱되며, 항목은 렌더링되어 줄 단위로 삽입됩니다. 주석, 빈 줄, 인용 스타일, folded 및 literal 스칼라, 템플릿 표현식, 끝 줄바꿈 형태는 모두 변경 없이 유지되며, 중첩 단계는 강제되지 않고 문서 자체의 들여쓰기에서 측정됩니다. 따라서 항목은 이미 작성 중인 스타일에 맞게 들어갑니다. 같은 문서에 대한 같은 요청은 같은 바이트를 생성하므로, 클라이언트는 두 실행 결과를 비교할 수 있고 리뷰에서는 하나의 편집이 하나의 diff로 읽힙니다.

결과는 직접 입력할 수 있었던 문서여야 하며, 쓰기는 이를 조건으로 합니다. 작성된 문서는 해당 kind의 스키마에 대해 검증되고, 통과한 경우에만 디스크에 기록됩니다. 작성 스키마가 거부할 결과를 만드는 요청은 E0275(결과 문서가 유효하지 않으므로 편집이 거부되었고, 아무것도 기록되지 않았습니다)로 반환되며, 스키마가 허용하지 않는 속성과 그 위치를 담습니다. 파일은 바이트 단위로 원래 상태 그대로 남으므로, 거부된 편집은 시도되지 않은 편집과 구별되지 않으며 처음 시작한 문서에 대해 수정된 요청을 다시 시도할 수 있습니다. 여기서 규칙을 다시 서술하지 않는 이유도 이것입니다. Release 문서에 개발자 값을 담으라는 요청은 직접 입력한 문서를 거부할 바로 그 스키마에 의해 거부됩니다.

의미적으로 허용되는지는 여기서 결정되지 않습니다. 의존성 소켓이 생산자가 선언한 것인지, Feature의 적용 조건이 충족되는지는 빌드가 수행하는 해석에 속하며, 각각 고유한 보고 방식이 있습니다. 따라서 이 요청이 전혀 알지 못하는 연결을 지정할 수 있고, Aggregate는 카탈로그 엔터티가 미리 선언하지 않은 소켓을 작성할 수 있습니다. 소켓을 통해 무엇을 소비할 수 있는지는 여전히 생산자가 선언할 몫입니다. 그것이 궁금하다면 Release를 지정해 aggrega/validate를 실행하거나 그래프를 요청하십시오.

응답은 무엇이 들어갔는지와 무엇이 디스크에 기록되었는지를 알려 주며, 이 둘은 서로 다른 질문입니다. content는 두 전달 방식 모두에서 편집이 생성한 문서를 담습니다. written은 디스크에 기록된 파일을 지정하며, dryRun에서는 비어 있습니다. container는 항목이 들어간 컨테이너의 구조적 경로이므로, 그 규칙을 다시 도출하지 않고도 방금 추가한 것을 찾을 수 있습니다. createdContainers는 문서에 없어서 이 편집이 기록한 세그먼트를 가장 바깥쪽부터 지정합니다. 전체 경로가 이미 있던 일반적인 경우에는 비어 있으며, 이를 읽으면 기존 블록 안에 추가된 항목과 자신의 블록을 새로 만든 항목을 구별할 수 있습니다. file과 edit는 보낸 내용을 그대로 돌려주므로, 여러 요청을 동시에 보낸 클라이언트는 각 응답을 해당 질문과 짝지을 수 있습니다. written, container, createdContainers는 항상 배열이며, 없을 때는 생략되지 않고 빈 배열입니다.

dryRun에서는 아무것도 생성되지 않습니다. written은 비어 있고, content는 쓰기가 생성했을 문서를 담으며, 파일은 건드려지지 않습니다. 따라서 편집기는 결과를 작성자에게 보여 주고 저장, 수정 또는 폐기하게 할 수 있습니다. 기본값은 쓰기입니다. 이 작업의 산출물은 편집된 문서이며, 그것을 만드는 인터페이스는 그 결과를 제공해야 하기 때문입니다. 전달 방식에 대해 아무것도 지정하지 않은 요청은 파일을 편집합니다.

쓰기가 하는 나머지 모든 일은 dry run도 합니다. 작성된 문서는 어느 경우든 해당 kind의 스키마에 대해 검증되므로, 쓰기가 거부할 편집은 dryRun에서도 같은 속성을 지정하며 거부됩니다. 즉 dry run에서 받는 오류는 쓰기가 반환했을 오류와 같습니다.

요청한 내용을 담은 항목이 이미 있으면 아무 작업도 하지 않습니다. 문서는 변경 없이 반환되고 아무것도 기록되지 않습니다. 같은 이름의 항목이 다른 내용을 담고 있으면 교체되지 않고 거부됩니다. 작성자가 쓴 것을 교체하는 것은 네 가지 편집에 속하지 않기 때문입니다.

쓰기 후 데몬은 문서를 다시 읽습니다. 해당 파일에 대해 보유하던 내용은 버려지고 워크스페이스 수준의 뷰가 초기화되므로, 다음 검증, hover, 자동 완성 또는 그래프 요청은 교체된 버전이 아니라 편집이 생성한 바이트를 기준으로 응답됩니다. 편집 자체는 보유 중인 버퍼가 아니라 디스크의 파일을 읽습니다. 저장되지 않은 내용을 먼저 참조하는 위의 위치 찾기 요청과 다릅니다. 이는 의도된 것입니다. 저장되지 않은 버퍼에서 쓰면 항목 하나를 적용한다는 명목으로 작성자가 저장하지 않은 내용을 파일에 기록하게 됩니다. 버퍼를 저장한 다음 편집하십시오.

항목이 들어갈 수 있는 위치를 가리키지 않는 요청은 응답되지 않고 거부되며, 표준 invalid-params 코드가 반환되고, 요청이 바뀌기 전까지는 재시도해도 결과가 달라지지 않습니다. 문서가 지정되지 않았거나, 워크스페이스 안에 없거나, 읽을 수 없거나, 올바른 형식의 YAML이 아니거나, 결과를 검사할 스키마를 가진 kind를 선언하지 않은 경우, edit가 지정되지 않았거나 네 가지 중 하나가 아닌 경우, node가 아무것도 가리키지 않거나 세그먼트 중 하나가 비어 있는 경우, name이 주어지지 않은 경우, wire-edge에 socket이 지정되지 않은 경우, set-value에 스칼라가 와야 할 자리에 매핑이나 시퀀스가 주어진 경우, 노드 경로가 스칼라나 시퀀스, 또는 flow 스타일로 작성된 컬렉션에 도달하여 줄을 추가하면 이미 작성된 바이트를 다시 쓰게 되는 경우, 또는 노드 경로가 문서에서 아무것도 가리키지 않는 경우입니다.

어느 전달 방식에서든 의존성을 해석하지 않고, 레지스트리에 접근하지 않으며, 네트워크를 사용하지 않습니다.

effective-configuration 응답이 다루는 범위

aggrega/effectiveConfiguration은 두 가지 질문에 답합니다. 이 세션에 어떤 구성이 적용되는지, 그리고 각 설정을 어느 계층이 결정했는지입니다. 이는 aggrega config show --origin이 출력하는 것과 같은 답으로, 한 번 계산되어 두 표면 모두에 보고되므로 두 곳이 설정의 출처에 대해 서로 다르게 말할 수 없습니다.

source는 네 가지 형태 중 하나입니다. 구성 파일의 절대 경로(aggrega --config <file> serve로 시작된 데몬이 읽는 전역 파일도 포함되며, 주어진 경로 그대로 표시됩니다), env: 접두사가 붙은 환경 변수(예: env:AGGREGA_SIGNING_REQUIRED), 데몬을 시작한 명령줄에 입력된 전역 플래그(플래그 이름으로 표시되며, 예를 들어 aggrega --offline serve로 시작된 데몬이라면 --offline), 또는 어떤 계층도 설정하지 않은 설정에 대한 (built-in defaults)입니다. 앞의 세 가지는 layers에 그대로 나타납니다. 기본값은 나타나지 않는데, 기본값은 기여한 계층이 아니라 어떤 계층도 지정하지 않은 곳에 적용되는 값이기 때문입니다.

설정은 그것을 설정하는 계층 중 우선순위가 가장 높은 계층에 귀속되며, 그 계층이 어떤 값을 쓰든 마찬가지입니다. 내장 기본값을 쓰거나 그 아래 파일이 이미 설정한 값을 다시 적은 구성 파일도 그 파일이 표시됩니다. 그 값을 제자리에 유지하고 있는 것이 그 파일이기 때문입니다. 파일은 해당 키를 담음으로써(목록의 _append 짝 키 포함) 설정을 지정하고, 환경 변수는 비어 있지 않은 값으로 export됨으로써 설정을 지정합니다. 파이프라인이 소유한 구성 파일은 그것이 무시하는 키에 대해서는 결코 표시되지 않습니다. aggrega config show --origin도 같은 규칙에 따라 보고합니다.

구성 스키마가 선언하는 모든 설정이 빠짐없이 다뤄지지만, 각각이 자기만의 행을 갖지는 않습니다. 목록에 추가하는 _append 짝 키는 그것이 추가되는 목록의 행에 보고되므로, 짝 키를 통해서만 기여한 계층은 그 목록의 행에 표시되고 짝 키 자체는 행을 갖지 않습니다. 목록 항목 안의 설정(레지스트리의 신뢰 정책, 플러그인 연결의 입력 등)은 그 목록의 행이 다룹니다.

추가로 두 가지 한계가 있으며, 각각 답을 보이는 것보다 더 거칠게 만듭니다.

  • 목록 또는 맵 설정은 전체로서 그것을 설정하는 계층 중 우선순위가 가장 높은 계층에 귀속됩니다. 항목별 귀속은 추적되지 않으므로, 두 계층에서 조합된 목록은 우선순위가 더 높은 계층만 보고하며, 낮은 계층이 기여한 항목은 높은 계층이 쓴 항목과 구별되지 않습니다.
  • 서명 요구 사항은 그것을 마지막으로 언급한 계층이 아니라 그것을 켠 첫 계층에 귀속됩니다. 이 설정은 어느 계층이든 켜면 그것이 이기고 이후 계층이 끌 수 없도록 조합되므로, 처음으로 켠 계층이 유효 값을 지금의 값으로 만든 계층입니다. required: false를 쓰는 계층은 아무것도 켜지 않으므로, 이를 언급하는 모든 계층이 false를 쓰는 경우 이 설정은 (built-in defaults)로 보고됩니다.

보고되는 모든 값은 해당 작업 공간이 처음 지정되었을 때 이루어진 해석 결과입니다. 구성 파일을 편집해도 여기의 값은 바뀌지 않으며, 데몬을 다시 시작해야 바뀝니다. 이는 의도된 것입니다. 이 값들은 해당 작업 공간에 대한 다른 모든 요청이 응답되는 기준이 되는 구성이며, 그렇기 때문에 핸드셰이크가 그 작업 공간에 대해 보고한 루트 및 구성 계층과 비교할 수 있습니다. 사용자가 편집 중인 파일과 함께 구성을 보여 주는 클라이언트는 둘 중 어느 것을 보여 주고 있는지 밝혀야 합니다.

계층 귀속은 요청할 때 현재 상태의 파일을 기준으로 계산됩니다. 따라서 이후에 편집된 구성 파일은 옆의 값이 해석된 그대로 남아 있는 동안에도 source를 바꿀 수 있습니다. 두 부분은 서로 다른 질문, 즉 무엇이 적용 중인지와 어느 계층이 그것을 결정했는지에 답하며, 고정되는 것은 앞의 것뿐입니다. 둘을 다시 일치시키려면 데몬을 다시 시작하십시오.

보고만 하고 결코 쓰지 않습니다. 이 메서드는 구성을 바꾸지 않고, 파일을 만들지 않으며, 레지스트리나 네트워크에서 아무것도 해석하지 않습니다.

단일 계층 파일의 내용은 여기서 제공되지 않습니다. 명령줄은 한 계층 자체의 바이트를 주석과 서식을 보존한 채 그대로 출력할 수 있지만, 이 메서드는 바이트가 아니라 해석 결과를 보고합니다. 계층의 텍스트가 필요한 클라이언트는 layers에 있는 경로로 파일을 열 수 있습니다.

구성 쓰기가 남기는 것

aggrega/configInit와 aggrega/configCapture는 모두 구성 문서를 생성하며, 둘 다 그 문서를 씁니다. 응답은 파일을 지정합니다. 파일을 여는 것은 다음 단계이지 쓰기를 대신하는 것이 아닙니다. 명시적으로 요청하지 않는 한 어느 쪽도 직접 배치할 내용을 건네주지 않습니다. 결과물이 한 번도 쓰이지 않은 문서인 기능은 같은 이름을 단 다른 기능이기 때문입니다.

두 메서드는 영향이 미치는 범위가 다르며, 각 응답은 그 범위를 알려 줍니다. 결과를 표시하기 전에 이를 읽으십시오.

  • 시딩은 기본적으로 머신의 모든 워크스페이스가 공유하는 구성에 씁니다. 레지스트리와 그 레지스트리에서 신뢰하는 아이덴티티는 보통 어디서 작업하든 같으므로, 요청이 workspace: true를 보내지 않는 한 항목은 그곳에 들어갑니다. scope는 쓰인 configFile과, 그것이 공유 파일인지를 나타내는 machineWide를 담습니다. 이 값은 요청이 요구한 내용이 아니라 쓰기가 실제로 확인된 파일에서 도출되므로, 응답이 머신 전체에 걸친 변경을 로컬 변경으로 설명할 수 없습니다.
  • 프리징은 워크스페이스 밖으로 절대 미치지 않습니다. 쓰기 대상도 재정의도 받지 않습니다. 그 목적 자체가 하나의 프로젝트를 자족적으로 만드는 것이므로, 항상 그 프로젝트 자체의 .aggrega-config.yaml에 씁니다. 그래서 응답은 configFile과 workspaceRoot를 담고 범위는 주장하지 않습니다. 밝힐 범위가 없기 때문입니다.

시딩은 덮어쓰지 않고 거부합니다. 이미 존재하는 구성 파일은 그대로 두고 거부 메시지가 그 파일을 지정합니다. 시딩은 아직 존재하지 않는 구성을 위한 것인 반면, 시딩이 위임하는 공유 쓰기는 설계상 병합하기 때문입니다. 그래도 쓰려면 force를 보내십시오. 레지스트리 항목이 기존 내용에 병합되고 다른 설정은 보존됩니다. 거부된 요청은 아무것도 변경하지 않습니다.

trust는 레지스트리가 공시한 정책이 어떻게 처리되었는지를 서술문이 아닌 개별 결과로 알려 줍니다. pinned는 레지스트리가 정책을 공시했고 그것이 채택되었음을 뜻하며, identities가 그 수를 셉니다. notAdvertised는 레지스트리에 요청했으나 아무 정책도 공시하지 않았음을 뜻하며, 이는 실패가 아닙니다. 시딩은 진행되고, reason이 엔드포인트가 한 일을 알려 줍니다. 연결할 수 없었던 레지스트리도 이렇게 보고됩니다. 돌아온 정책이 없고 시딩도 마찬가지로 진행되기 때문입니다. 다만 실패 자체가 레지스트리에 한 번도 도달하지 못했음을 보여 주는 경우, 즉 이름이 확인되지 않았거나, 연결이 거부되었거나 열 수 없었거나, 보안 연결을 수립할 수 없었던 경우에는 그 옆에 unreachable도 담습니다. 응답한 레지스트리는 not-found로 응답했든 오류 상태로 응답했든 unreachable을 담지 않으므로, 정책을 게시하지 않는 레지스트리와 요청조차 받지 않은 레지스트리를 구분하려면 reason의 문구가 아니라 이 키를 읽으십시오. baseline은 공시된 정책이 채택되지 않아 공식 허브의 내장 기준 정책이 고정되었음을 뜻하며, reason이 그 이유를 알려 줍니다. 항목에 정책이 담기므로 직접 고정할 것이 없습니다. 두 키는 서로 다른 질문에 답하므로, 요청을 받고도 아무것도 공시하지 않은 허브는 둘 다 담고, 오프라인 워크스페이스의 허브는 요청을 받지 않았으므로 baseline만 담으며 reason이 워크스페이스가 오프라인임을 알려 줍니다. 아무것도 공시하지 않는 그 밖의 레지스트리는 notAdvertised만 담고, 정책 없이 시딩되며, 이어지는 안내는 아이덴티티를 직접 고정하라는 것입니다. 오프라인에서는 응답되지 않고 거부됩니다. skipped는 가져오기를 시도하지 않았음을 뜻합니다. pinned 이외의 값을 모두 오류로 취급하는 클라이언트는 정상 동작하는 구성을 고장 난 것으로 보고하게 됩니다.

dryRun에서는 아무것도 생성되지 않습니다. written은 false이고, content는 쓰기가 생성했을 문서를 담으며, 그 내용이 대상으로 하는 파일은 scope.configFile입니다. 디렉터리를 만들지도 파일을 건드리지도 않으므로, 편집기는 텍스트를 작성자 앞에 보여 주고 저장, 수정 또는 폐기하게 할 수 있습니다.

드라이 런은 쓰기와 정확히 한 가지 점, 즉 쓰지 않는다는 점에서만 다르므로, 쓰기가 수행하는 모든 거부를 드라이 런도 수행합니다. 여기서 중요한 것은 기존 파일에 대한 거부입니다. 이미 존재하는 구성 파일에 대한 dryRun은 쓰기와 똑같이 파일을 지정하며 거부됩니다. 그 덕분에 응답을 판정 기준으로 쓸 수 있습니다. 드라이 런이 거부하면 쓰기도 같은 이유와 같은 메시지로 거부했을 것입니다. dryRun과 함께 force를 보내면, 여전히 아무것도 쓰지 않으면서 덮어쓰는 쓰기가 생성할 병합 결과를 응답으로 받습니다. 어느 전달 방식에서든 레지스트리에 공시된 신뢰 정책을 요청합니다. 그 내용 속 정책이 곧 쓰기가 고정했을 정책이기 때문입니다.

프리즈가 보고하는 것은 실제로 쓴 내용이지, 그에 대한 설명이 아닙니다. sockets는 프리즈된 각 플러그인 소켓과 그곳에 프리즈된 연결을 나열하고, catalogDirs는 카탈로그 디렉터리를 담습니다. 둘 다 항상 배열이며, 없을 때는 생략되지 않고 빈 배열입니다.

  • socket과 field는 같은 문자열이 아니며, 그 차이는 겉모양만의 문제가 아닙니다. socket은 연결이 바인딩된 소켓을 지정하고, field는 파일에서 연결이 쓰인 키입니다. 둘은 복수형 키로 쓰이는 provider 소켓에서만 다릅니다. 따라서 문서의 특정 줄을 가리킬 때는 field를, 소켓 자체를 지정할 때는 socket을 사용하십시오.
  • 각 연결은 uri, capability, function, role을 담으며, 연결에 해당 값이 있을 때만 존재합니다. 이 값들은 연결 전체를 재현하지 않고 연결을 식별합니다. 연결의 선택적 연결 시점 입력은 파일에 그대로 프리즈되며 응답에서 반복되지 않습니다. 파일이 권위 있는 사본입니다.
  • captured: false는 성공입니다. 빌드가 구성에 관여하지 않는 프로젝트에는 프리즈할 빌드 핵심 요소가 없으므로, 파일은 그대로 두고 두 목록은 빈 채로 돌아옵니다. 이를 오류로 취급하면 정상적인 워크스페이스를 고장 난 것으로 보고하게 됩니다.

기본값은 출력 바이트를 결정하는 것만 프리즈합니다. 즉 provider 바인딩과 레이블을 변환하는 거버넌스 연결입니다. 판정 거버넌스, 린터 게이트, 임포트 소켓은 제외됩니다. 이들은 환경마다 달라지도록 의도된 것이며, 프리즈하면 한 환경의 게이트가 모든 체크아웃으로 옮겨지기 때문입니다. allPlugins: true는 대상을 모든 플러그인 소켓으로 넓힙니다. 포함 여부는 소켓 단위가 아니라 연결 단위로 결정되므로, 레이블 변환 연결 하나와 판정 연결 하나를 담은 거버넌스 소켓은 기본값에서 첫 번째 연결만 포함합니다.

모든 값은 유효 값으로 프리즈됩니다. 즉 머신의 구성과 프로젝트 자체 구성을 병합해 확인되는 값입니다. 따라서 현재 머신의 구성에서만 오는 바인딩도 프로젝트에 쓰여 프로젝트와 함께 이동합니다. 레지스트리의 신뢰 정책을 비롯한 머신 전체 도구 설정은 빌드 핵심 요소가 아니므로 제자리에 남습니다. 변경되지 않은 구성을 두 번 프리즈하면 같은 바이트를 다시 씁니다. 따라서 클라이언트는 이를 자유롭게 제공할 수 있습니다. 두 번째 호출은 독자가 보고 있는 문서를 정확히 그대로 둡니다.

플러그인 변경이 알려 주는 것

네 가지 플러그인 요청은 모두 기본적으로 기록을 수행하며, 무엇을 기록하는지에 따라 나뉩니다. 두 요청은 구성 파일을 변경하고, 두 요청은 워크스페이스에 문서를 생성합니다. 그중 두 요청, 즉 추가와 생성은 dryRun을 받으며, 이는 요청이 하는 나머지 작업은 모두 수행하되 아무것도 기록하지 않습니다. 변경이 어디에 반영되었는지는 요청에서 추론하지 말고 응답 자체의 설명을 읽으십시오. 그중 한 요청은 요청이 범위에 대해 아무것도 말하지 않으면 가장 넓은 범위를 의미합니다.

추가와 제거는 모두 scope를 포함하며, 이는 기록이 확정된 파일에서 도출됩니다. configFile은 그 파일이고, machineWide는 그 파일이 이 머신의 모든 워크스페이스가 거쳐 확정되는 파일인지를 나타내며, workspaceRoot는 이 세션이 열린 워크스페이스를 나타내므로 워크스페이스 범위의 응답은 어느 워크스페이스였는지를 알려 줍니다. machineWide는 요청이 무엇을 요구했는지가 아니라 확정된 파일에서 읽어 내며, 이 때문에 응답이 머신 전체 변경을 로컬 변경으로 설명하는 일이 없습니다.

🔴 global도 workspace도 지정하지 않은 cli 유형 추가는 명령을 머신 전체에 등록합니다. 명령 확장은 머신 전체 도구이므로, 재정의가 없으면 이 머신의 모든 워크스페이스가 거쳐 확정되는 전역 구성 파일에 기록됩니다. 그러면 등록된 명령은 이 세션에서 아무도 지정하지 않은 프로젝트를 포함하여 그 머신의 모든 프로젝트에서 최상위 aggrega 명령이 됩니다. provider, governance, linter 또는 importer 추가는 그 반대입니다. 이들은 한 프로젝트의 빌드를 구성하므로, 재정의가 없으면 해당 프로젝트 자체의 .aggrega-config.yaml에 기록됩니다. 제거도 같은 유형에 대해 같은 규칙을 따릅니다. 명령 확장을 로컬로 유지하려면 workspace: true를, 그 외의 유형을 공유 파일로 보내려면 global: true를 보내십시오. 둘 다 보내면 거부됩니다. 어느 경우든 응답의 scope가 권위 있는 설명이며, 클라이언트는 결과에 따라 동작하기 전에 이를 보여 주어야 합니다.

추가는 반영된 대상을 알려 주며, 세 필드 중 정확히 하나가 그것이 어떤 종류였는지를 나타냅니다. type은 항목이 추가된 유형을 그대로 돌려주고, 이어서 identity는 governance, linter 또는 importer 연결에 대해 버전이 고정된 순수 엔티티 식별자를 담고, uri는 provider 바인딩에 대해 플러그인의 oci:// 아티팩트 주소를 이제 제공하는 capability와 함께 담으며, reference는 cli 설치에 대해 명령이 등록된 고정 참조를 담습니다. 따라서 호출자는 보낸 유형에서 다시 도출하지 않고 응답에서 어떤 종류의 연결이 반영되었는지를 읽습니다. 제거는 scope와 함께 type과 query만 돌려줍니다. 사라진 항목에 대해서는 더 보고할 것이 없기 때문입니다.

추가는 written도 포함하며, dryRun에서는 content도 포함합니다. written은 클라이언트가 분기 기준으로 삼는 값입니다. true이면 클라이언트가 열 수 있는 구성 파일이 이제 디스크에 있다는 뜻이고, dryRun에서는 false이며 대신 content가 기록되었을 구성 문서를 담습니다. 두 값이 동시에 의미를 갖는 일은 없으며, content가 대상으로 하는 파일은 scope.configFile이므로 응답의 어느 부분도 그 경로의 두 번째 사본을 담지 않습니다. 이는 여기서 중요합니다. global 연결의 파일은 이 머신의 모든 워크스페이스가 거쳐 확정되는 파일이기 때문입니다.

게시된 버전이 없는 플러그인은 고정되지 않은 채로 연결되지 않고 거부됩니다. 추가는 쿼리를 하나의 플러그인으로 확정하고 게시된 가장 높은 버전을 고정하므로, 기록되는 항목은 버전을 포함합니다. 저장소가 규격에 맞는 버전을 하나도 게시하지 않은 플러그인은 그 이름과 함께 거부되며, 이 워크스페이스가 신뢰하는 철회에 의해 회수된 버전은 건너뛰고 그다음 낮은 버전이 선택됩니다.

쿼리가 지정한 버전은 철회되었더라도 고정되며, withdrawn이 이를 알려 줍니다. <name>:<version> 형식으로 작성한 query는 최신 버전 대신 해당 버전을 고정합니다. 이는 이름만으로 바인딩되고 버전을 거부하는 provider를 제외한 모든 유형에 적용되며, 버전을 지정하는 것이 곧 재정의입니다. 이 워크스페이스가 신뢰하는 철회 선언이 그 버전을 철회했더라도 그대로 고정되며, 응답에 withdrawn: true가 포함됩니다. 이는 aggrega plugin add가 터미널에 retraction: 줄로 표시하는 사실입니다. withdrawn은 다른 모든 응답에는 없으므로 그 존재 자체가 신호의 전부이며, 그것이 없다고 해서 해당 버전이 철회되지 않았다는 뜻은 아닙니다. 지정된 버전의 철회 마커를 읽을 수 없었던 경우 withdrawn은 없고 retraction이 unscreened를 담아 그 이유를 알려 주며, 이는 버전을 지정하지 않은 추가가 같은 실패를 만났을 때와 같습니다. 버전을 지정하지 않은 추가는 대신 자신이 선택한 버전에 대해 철회 검사가 내린 결론을 retraction에 보고합니다.

정렬은 무언가를 변경했는지를 보고하며, 그것이 동작의 기준으로 삼을 필드입니다. changed는 기록과, 레코드가 이미 올바름을 확인한 정렬을 구분합니다. 변경되지 않은 파일은 바이트 단위로 동일하게 유지되므로 그 문서를 가진 클라이언트는 다시 불러올 것이 없으며, 요청을 두 번 실행하면 두 번째에는 변경이 없다고 보고합니다. entity는 파일을 나타내고, hostFunctions는 도출된 집합을 담으며, commands는 미러를 터미널이 출력하는 줄이 아닌 값으로 담습니다. 각 항목은 name, 선택적 description, flags이고, 각 플래그는 name과 선택적 shorthand, description, type, default를 담습니다. 기록은 원자적이므로 정렬이 실행되는 동안 그 파일을 읽는 클라이언트는 불완전한 문서를 보지 않습니다.

생성은 응답의 정확히 절반만 채우며, 응답 자체의 dryRun이 어느 쪽인지를 알려 줍니다. 기본 동작에서는 엔티티가 기록되고 notices가 생성이 수행한 기록에 대해 남긴 내용을 담습니다. dryRun에서는 아무것도 생성되거나 수정되지 않습니다. documents가 생성된 각 엔티티를 대상 path와 그 content로 담으므로, 클라이언트는 이를 자체 문서 모델에 넣어 저장 전에 보여 주고 수정하거나 폐기할 수 있습니다. 두 절반이 동시에 채워지는 일은 없으므로, 어느 방식으로 실행되었는지는 요청 내용이 아니라 응답에서 읽을 수 있습니다.

플러그인 요청이 기록하는 위치는 항상 그 요청이 지정한 워크스페이스 안이며, 읽는 위치는 필드별로 결정됩니다. 절대 경로 대상, 루트 밖으로 올라가는 대상, 링크를 통해 루트 밖으로 이어지는 대상은 확정되지 않고 거부됩니다. 따라서 생성은 무엇을 보내든 세션이 열리지 않은 트리에 엔티티를 만들 수 없습니다. 요청이 읽기만 하는 경로는 별개의 문제이며, 모든 필드에 하나의 규칙을 적용하지 않고 필드별로 답합니다. aggrega/pluginGenCatalog는 모듈과 그 오버레이를 선택한 위치 어디에서든 읽습니다. 빌드한 모듈은 툴체인의 출력 디렉터리 아래에 있으며, 그곳에서 읽기를 거부하면 작업의 목적 자체를 거부하는 셈이기 때문입니다. aggrega/pluginSync는 두 경로를 워크스페이스 안에서 읽습니다. 그 요청은 워크스페이스가 이미 가진 파일에 관한 것이기 때문입니다. 위의 위치 지정 요청은 또 다른 이유로 절대 경로를 받습니다. 클라이언트가 이미 열어 둔 문서를, 클라이언트가 가진 표기 그대로 지정하기 때문입니다.

작업에 필요한 무언가가 빠진 요청은 보내야 할 필드를 명시하며 거부됩니다. type 또는 query가 없는 추가나 제거, capability가 없는 provider 추가 또는 role이 없는 governance 추가, acceptCapabilities가 없는 cli 추가, entity 또는 plugin이 없는 정렬, 두 선택 모드를 모두 지정하거나 어느 것도 지정하지 않았거나 overlay 또는 outputDir가 없는 생성이 이에 해당합니다. 각각은 표준 invalid-params 코드와 함께 반환되며, 요청이 바뀌기 전까지는 재시도해도 달라지지 않습니다. 쿼리가 어떤 항목과도 일치하지 않는 제거도 유형, 쿼리, 조회한 파일을 명시하며 거부됩니다. 이는 요청이 아니라 구성의 상태이므로, 고쳐야 할 대상은 어느 쪽일 수도 있습니다.

아무것도 입력을 요구하지 않으며, 사람에게 물었을 단 하나의 결정은 대신 필드로 전달됩니다. 터미널 명령은 지켜보는 사람에게 명령 확장 플러그인이 선언한 기능을 수락하는지 묻습니다. 이 스트림은 아무도 지켜보지 않으므로 acceptCapabilities는 호출자가 얻어서 보내야 하며, 이를 포함하지 않은 요청은 아무도 하지 않은 동의로 설치하는 대신 보낼 내용을 명시하며 거부됩니다. 명령 확장을 설치할 수단 없이 시작된 데몬은 아무것도 설치하지 않은 성공을 보고하는 대신 cli 추가를 즉시 거부합니다.

작성자에게 제시할 수 있는 종류

kind 없이 보낸 aggrega/getSchema는 지정할 수 있는 종류를 답하며, 클라이언트가 작업에 따라 다른 범위를 필요로 하므로 두 가지 범위로 답합니다. 묻고 있는 쪽을 읽으십시오.

kinds는 바이너리가 응답하는 모든 토큰입니다. entityKinds는 작성자가 문서로 작성하는 집합입니다. 넓은 목록에는 작성하는 종류와 함께 중간 표현, 잠금 파일, 워크스페이스 구성, 플러그인 소켓 계약이 들어 있습니다. 모두 실제 스키마이지만, 누구도 파일로 작성하는 문서는 아닙니다. 따라서 편집기의 스키마 연결은 넓은 목록으로 구성하고, 선택기는 좁은 목록으로 만듭니다. 넓은 목록으로 만든 선택기는 어떤 작성 스키마도 받아들이지 않는 값을 제시하며, 작성자는 하나를 고른 뒤에야 거부를 만나게 됩니다.

좁은 집합은 엔터티 종류보다도 좁으며, 어느 것이 빠지는지는 어떤 스키마도 알려 주지 않습니다. 내용이 다른 종류의 문서 안에 작성되는 플랫폼 소유 종류는 작성자가 새로 시작하도록 제시할 문서가 아닙니다. Workload가 그런 종류입니다. 워크로드 내용은 Recipe나 FeatureRecipe의 workload: 필드에 인라인으로, 또는 그 필드가 가져오는 파일로 작성되므로 단독으로 다룰 워크로드 문서는 없습니다. 그 내용이 어디에 들어가는지는 Workload 작성 표면을 참고하십시오. 그 스키마는 작성하는 종류의 스키마와 똑같이 apiVersion과 kind를 고정하는데, 그래야 내용이 놓인 자리에서 검증될 수 있기 때문입니다. 고정된 값은 내용을 식별할 뿐 단독으로 다룰 수 있게 만들지는 않습니다. 따라서 그 값은 해당 종류가 초안을 작성할 종류라는 신호가 아닙니다. 답은 entityKinds가 담고 있으며, 스키마 바이트에는 들어 있지 않습니다.

각 entityKinds 항목은 클라이언트에 필요한 두 표기를 모두 담으며, 어느 쪽도 다른 쪽에서 도출할 수 없습니다. kind는 소문자 하이픈 연결 토큰으로, 이 메서드나 aggrega/scaffoldEntity에 kind로 다시 보냅니다. documentKind는 문서 자체가 최상위 kind: 필드에 담는 값입니다. 이름이 두 단어 이상인 종류에서는 둘이 대소문자 이상으로 다릅니다. featurerecipe를 어떻게 바꿔도 FeatureRecipe가 되지는 않습니다. 하나를 다른 하나에서 도출하지 말고 각각 항목에서 가져오면, 클라이언트가 유지할 매핑은 남지 않습니다.

각 항목은 그 종류의 문서를 받아들이는 작업도 알려 주므로, 문서에 그 작업을 제시하는 컨트롤은 종류 때문에 문서를 거부하지 않는 작업만 제시합니다. acceptedBy는 세 개의 불리언을 담으며, 각각 모든 항목에 있고, 각각 해당 종류의 문서를 단독으로, 즉 경로로 또는 조회의 경우 이름으로 지정하고 그 밖에 아무것도 함께 보내지 않은 경우에 관한 것입니다. singleEntityValidation은 aggrega validate <path>가 그 종류의 문서를 거부하고 대신 검사하는 전체 카탈로그 또는 Release 범위를 지정하는 대신, 그 문서를 검사하는지 여부입니다. publication은 문서만 지정한 aggrega/publishEntity가 그 문서를 게시하는지 여부입니다. Plugin은 false인데, 게시할 때 요청이 plugin에 지정한 실행 파일도 함께 바인딩하므로 문서만 지정한 요청은 거부되기 때문입니다. Manifest와 Release는 두 종류 모두 게시되지 않으므로 false입니다. inspectionByName은 aggrega/entityDefinition이 이름을 그 종류의 엔터티로 해석하는지 여부이며, 이름은 한 엔터티가 다른 엔터티를 참조할 때 쓰는 형태 그대로 보냅니다. Plugin은 <pluginType>/<name>, Recipe나 FeatureRecipe는 <capability>/<name>으로, 또는 그 이름을 선언하는 capability가 하나뿐이면 이름만으로 보냅니다. true는 그 작업이 해당 종류라는 이유로 문서를 거부하지 않는다는 뜻이며, 특정 문서를 그 내용 때문에 거부할 수는 있습니다.

자체 목록을 두지 마십시오. 어떤 종류가 있는지는 대화하는 바이너리의 속성이므로, 클라이언트에 작성해 둔 목록은 작성한 날에는 맞지만 종류가 추가되는 날부터 맞지 않게 되며, 그때 작성자가 보는 것은 자신이 원하는 종류가 그것을 제시하려던 바로 그 컨트롤에서 빠져 있는 모습입니다. 물어보면 답은 바이너리를 따릅니다.

두 목록은 함께 도착하며, 종류를 지정하지 않을 때만 도착합니다. 종류를 지정한 요청은 그 종류의 스키마로 답하고 어느 목록도 담지 않으므로, 어떤 질문을 했는지 응답에서 읽을 수 있습니다. 어떤 스키마도 응답하지 않는 토큰은 표준 invalid-params 코드로, 메시지에 유효한 전체 집합을 담아 거부되므로, 오타는 사람에게 물을 일이 아니라 바로잡을 요청입니다.

아무것도 없는 워크스페이스에서도 답합니다. 어휘가 바이너리에 컴파일되어 있으므로 문서도, 잠금 파일도, 카탈로그도 필요 없습니다. 첫 문서를 시작하는 작성자가 있는 워크스페이스가 바로 그런 곳입니다.

스캐폴드 응답이 제공하는 것

이 섹션은 초안 작성에 관한 것입니다. 이 메서드의 다른 형식은 실행 가능한 예제를 쓰며, 그 응답은 위의 메서드 설명에서 다룹니다.

aggrega/scaffoldEntity는 텍스트를 돌려줍니다. skeleton은 지정한 kind의 YAML로, 해당 kind의 스키마가 요구하는 모든 필드를 스키마가 선언한 순서대로 담습니다. 스키마가 하나의 고정 값으로 고정한 필드는 채워진 상태로 도착하며(눈에 띄는 것은 apiVersion과 kind입니다), metadata.name에는 보낸 name이 들어가고, 그 밖의 모든 필수 값은 스키마가 그 위치에 선언한 타입에 맞춘 자리 표시자로 도착합니다. 즉 빈 문자열, 0, false, 빈 목록, 빈 매핑입니다. kind는 문서가 생성된 대상 토큰을 반복하므로, 여러 요청을 동시에 보낸 클라이언트는 자체적인 상관관계를 유지하지 않고도 응답 자체로 어느 요청의 응답인지 판별할 수 있습니다.

아무것도 쓰지 않으며, 바로 이 점을 염두에 두고 설계해야 합니다. 이 메서드는 파일을 만들지 않고, 경로를 고르지 않으며, 디렉터리를 건드리지 않습니다. 받는 것은 써야 할 문서이지 이미 쓰인 문서가 아닙니다. 따라서 편집기는 이 텍스트를 작성자가 읽고 편집하거나 버릴 수 있는 저장되지 않은 새 버퍼에 넣으며, 새 파일이 디스크에 기록되는 시점은 버퍼와 실행 취소 기록이 있는 곳에 그대로 남습니다. 이 문서를 받아 대신 어딘가에 넣어 주는 다른 요청은 없습니다. 새 문서를 어디에 둘지는 편집기가 결정합니다.

아무것도 해석하지 않으며, 워크스페이스의 어떤 것도 필요로 하지 않습니다. 문서는 바이너리에 포함된 스키마에서 생성되므로, 이 메서드는 레지스트리나 네트워크에 접근하지 않고, 카탈로그를 참조하지 않으며, 파일을 읽지 않습니다. 아직 Aggrega 문서가 하나도 없는 빈 디렉터리를 포함해 모든 워크스페이스에서 같은 방식으로 응답합니다. 이는 첫 문서를 시작하는 작성자가 바로 머무는 워크스페이스이며, 여기의 다른 메서드 대부분은 먼저 문서나 lockfile을 필요로 하는 곳입니다.

같은 요청은 어디서 요청하든 같은 바이트를 돌려줍니다. 문서는 이 기능을 제공하는 다른 인터페이스와 공유하는 하나의 계산으로 생성되므로, 같은 kind와 같은 이름을 요청받은 편집기와 어시스턴트는 작성자에게 같은 시작 텍스트를 보여 줍니다.

스켈레톤은 해당 kind가 요구하는 필드를 담을 뿐, 완성된 문서가 아닙니다. 필수 필드만 담고 그 외에는 아무것도 담지 않습니다. 원하는 선택 필드는 직접 추가해야 하며, 모든 자리 표시자는 아직 채워야 할 값입니다. 자리 표시자를 채운 뒤 버퍼에 대해 aggrega/validate를 실행하십시오. aggrega validate가 단일 엔터티로 검사하는 kind의 카탈로그 엔터티라면, 이 메서드는 명령이 저장된 파일에 적용하는 것과 같은 방식으로 아직 채워야 할 모든 자리 표시자를 해당 키 위치에서 무엇을 받는지와 함께 알려 줍니다. 스키마가 빈 값을 허용하는 자리 표시자도 포함되며, 초안으로 작성된 Recipe나 FeatureRecipe의 capability와 implements가 흔히 마주치는 예입니다. 그 밖의 kind에서는 버퍼를 해당 kind의 스키마에 비추어 검사하므로, 스키마가 빈 값을 거부하는 자리 표시자(예: 버전)는 그 스키마의 검출 결과로 돌아오고, 스키마가 빈 값을 허용하는 자리 표시자는 아무 결과도 내지 않습니다. 각 자리 표시자가 어떤 항목으로 도착하는지는 실시간 검증에서 설명합니다.

import 응답이 알려 주는 것

aggrega/import는 다른 도구용으로 작성된 소스를 초안 Aggrega 문서로 변환하며, 그 문서를 기록합니다. 이는 텍스트를 돌려주는 위의 scaffold와 다른 점입니다. written은 디스크에 기록된 각 파일을 outputDir 기준 상대 경로로 나열합니다. files는 요청이 기록하는 모든 파일을 기록 여부와 관계없이 content와 함께 담습니다. 즉 임포터가 생성한 모든 초안과, 그 뒤에 import가 기록한 내용의 레코드, 또는 sync에서는 sync가 변경하는 내용을 담습니다. 두 항목은 서로 다른 질문에 답하므로, 지금 디스크에 무엇이 있는지와 무엇이 생성되었는지 중 묻고 있는 질문에 맞는 쪽을 읽으십시오.

초안이 놓일 위치를 직접 선택하거나 워크스페이스 루트에 맡길 수 있습니다. outputDir는 aggrega import --output-dir 및 어시스턴트의 import 도구의 output_dir와 마찬가지로 선택 사항입니다. 아무것도 지정하지 않은 요청은 워크스페이스 루트 아래에 초안을 작성하며(이는 aggrega import가 대상을 받지 않았을 때 어디서 실행되든 기록하는 위치입니다), 디렉터리를 지정한 요청은 그곳에 초안을 작성합니다. 지정한 디렉터리는 워크스페이스 내부의 경로이며, 상대 값은 데몬이 우연히 위치한 디렉터리가 아니라 워크스페이스 루트를 기준으로 해석됩니다. 변환하는 source는 다른 경우로, 이런 제한을 받지 않습니다. 그 파일이나 디렉터리는 직접 선택한 것이므로 어디에 있든 읽히며, 그곳에서 읽는다고 초안이 놓이는 위치가 바뀌지는 않습니다. 디렉터리가 없으면 생성됩니다. dryRun에서는 아무것도 기록되지 않으며, 각 초안은 응답이 명시하는 outputDir(보낸 디렉터리 또는 워크스페이스 루트) 기준 상대 경로로 자신이 대상으로 하는 경로를 여전히 명시합니다.

요청은 outputDir에 이미 있는 Aggregate를 절대 덮어쓰지 않습니다. Aggregate는 초안이 작성된 후 작성자가 계속 편집하는 문서이므로, 초안 중 하나가 Aggregate로 읽히는 파일 위에 놓이게 되는 요청은 해당 초안과 Aggregate의 위치를 명시하며 거부되고, 아무것도 기록되지 않습니다. dry run은 기록이 거부하는 것을 거부하므로 dryRun에서도 마찬가지입니다. 대신 sync를 보내 소스에 맞게 최신화하거나, 다른 outputDir를 지정해 그 옆에 초안을 작성하십시오. 초안 경로에 이미 있는 그 밖의 파일은 모두 덮어쓰며, 이전 import가 작성했지만 이번 import가 작성하지 않는 파일은 그대로 남습니다. 무언가를 초안으로 작성하는 모든 요청은 outputDir에 import가 기록한 내용의 레코드인 .aggrega-import.json도 기록합니다. 이 레코드에는 받은 target(받은 경우), 읽은 카탈로그 스냅숏(읽은 경우), 초안으로 작성된 각 파일, 그리고 초안 Aggregate 또는 Release에서는 모든 깊이의 각 키가 그곳에 기록된 텍스트의 다이제스트와 함께 담기며, 그 밖의 초안 파일은 전체로 기록됩니다. files와 written은 초안 뒤에 이 레코드를 담습니다. 이 파일은 JSON이므로 워크스페이스의 YAML 문서를 읽는 어떤 것도 이를 읽지 않습니다. sync는 aggrega import --sync와 마찬가지로 이를 읽어 초안을 소스에 맞게 최신화합니다. target을 받지 않은 sync는 레코드가 명시하는 대상에 대해 초안을 작성하므로 이전 import가 작성한 Manifest를 초안으로 작성합니다. target을 받은 sync는 그 대상에 대해 초안을 작성하며, 이후 레코드가 그 대상을 명시합니다. 카탈로그의 어떤 Recipe도 바인딩되지 않는 기록된 대상은 보낸 대상과 마찬가지로 거부되며, 거부 메시지는 해당 대상이 기록된 대상이라고 알립니다. 초안 Release는 키 단위로 기록되므로, import가 주석을 남긴 자리에 작성자가 쓴 environment는 작성자가 쓴 키이며, sync는 이를 바이트 단위로 그대로 둡니다.

sync를 보내 이전 import가 outputDir에 작성한 초안을 소스에 맞게 최신화하십시오. 이때 import가 기록한 내용만 변경됩니다. 각 부분은 세 가지 기준으로 판단됩니다. 레코드에 따르면 import가 그곳에 마지막으로 기록한 내용, 디스크에 있는 내용, 그리고 소스가 지금 작성하는 초안입니다. 소스가 import가 마지막으로 기록한 그대로 둔 부분은 작성자가 편집했든 안 했든 디스크에 있는 그대로 유지됩니다. 소스가 변경한 부분은 새로 기록되고, 소스가 없앤 부분은 제거되며(초안 파일은 통째로 삭제됨), 소스에 새로 생긴 부분은 초안이 주변에 명시하는 부분 옆에 추가됩니다. 각각은 디스크의 내용이 import가 마지막으로 기록한 내용이고 작성자가 추가한 것이 없는 경우에만 적용됩니다. 그 밖의 모든 것은 바이트 단위로 그대로 유지됩니다. 작성자가 어디에든 추가한 키(parameter, Feature, 초안 Component 인스턴스 아래의 키, 다른 Component 포함), 초안 키 바로 위에 작성되지 않은 주석, 레코드에 나열되지 않은 모든 파일이 이에 해당합니다. 레코드가 없고 초안 경로에 아무것도 없는 디렉터리로의 sync는 sync 없는 요청과 마찬가지로 초안 전체를 기록합니다.

drift는 sync가 최신화한 내용이며, “소스가 바뀌었는가”에 대한 답입니다. 여기에는 sync가 변경한 각 부분(또는 dryRun에서는 변경할 각 부분)이 초안이 명시하는 순서대로 나열되며, 각 항목은 change(added, removed 또는 changed), 해당 부분이 속한 초안 파일을 outputDir 기준 상대 경로로 나타내는 file, 그리고 초안 Aggregate 또는 Release에서 해당 부분에 이르는 키들을 목록으로 나타내는 key로 구성됩니다. 따라서 마침표를 포함한 키도 하나의 항목으로 유지됩니다. 부분이 파일 전체인 경우 key는 비어 있으며, sync가 삭제하는 초안 파일은 이렇게 명시됩니다. aggrega import는 같은 항목을 표준 오류에 <change> <key> in <file> 또는 <change> <file> 형식으로 출력하며, --sync --dry-run에서의 종료 상태는 소스가 바뀌었는지를 알려 줍니다. 이 인터페이스에는 종료 상태가 없으므로 sync를 dryRun과 함께 보내고 drift가 비어 있는지 확인하십시오. sync가 아닌 요청, 소스와 일치하는 sync, 임포터가 완료하지 못한 sync의 경우 drift는 빈 목록입니다. sync에서 files는 sync가 변경하는 각 초안 파일을 그 파일에 부여하는 내용과 함께 담고, 레코드도 변경되면 그 뒤에 레코드를 담으며, written은 그중 디스크에 기록된 것을 명시합니다. 따라서 일치하는 sync는 둘 다 빈 목록으로 답합니다. sync가 삭제하는 초안 파일은 drift에만 명시되고 두 목록 어디에도 나오지 않습니다. 빈 key를 가진 그 removed 항목이 응답에서 해당 파일을 설명하는 유일한 항목이며, dryRun에서는 기록 시 삭제될 파일을 명시합니다.

sync는 작성자가 쓴 내용을 절대 다시 쓰지 않으며, 대신 거부합니다. 작성자가 편집한 부분을 변경하거나 제거하는 sync, 작성자가 이미 작성한 자리에 부분을 추가하는 sync, 작성자가 추가한 내용이 있는 부분을 제거하는 sync는 거부되며, 이때 해당하는 각 부분과 그 이유를 aggrega import --sync가 사용하는 표현으로 한 줄씩 명시하고(<file> <key>: <why>, 파일 전체의 경우 <file>: <why>), 아무것도 기록하지 않습니다. 초안 키 바로 위에 작성된 주석은 그 키를 편집한 것으로 간주됩니다. 어떤 레코드에도 나열되지 않은 Aggregate 위로의 sync는 Aggregate와 레코드를 명시하며 거부되고, 레코드를 읽을 수 없는 sync도 마찬가지입니다. 레코드 없이는 각 부분을 작성자의 것과 구별할 수 없기 때문입니다. 두 거부 모두 dryRun에서도 invalid-params 오류로 반환되며 sync를 명시합니다. 명시된 각 부분을 직접 조정하거나 import가 그곳에 기록했던 내용으로 되돌린 다음 요청을 다시 보내십시오.

🔴 halted: true는 오류가 아니며, 이를 오류로 취급하는 것이 설계 시 피해야 할 실수입니다. 모든 것을 변환하지 못한 임포터도 변환할 수 있었던 것은 초안으로 작성합니다. 응답은 그 초안을 담고, written은 그것을 명시하며, diagnostics는 무엇이 빠졌는지 알려 줍니다. 이것이 이 작업이 주는 가장 유용한 답이며, 작성자에게 두 부분을 모두 보여 줄 수 있도록 일부러 실패가 아닌 결과로 반환됩니다. sync에서는 같은 답이 아무것도 기록하지 않으며 files, written, drift가 비어 있습니다. 부분적인 초안은 임포터가 도달하지 못한 모든 부분을 소스가 없앤 것처럼 읽히기 때문입니다. 임포터가 전혀 읽을 수 없었던 소스는 다른 경우이며, 이때는 오류로 반환됩니다.

각 진단은 severity와 message를 담으며, 임포터가 코드를 부여한 경우 code도 담습니다. 특정 조건에 대응하려면 code로 분기하고, 독자에게는 message를 보여 주십시오. severity는 모든 플러그인 소켓이 보고하는 것과 같은 집합(halt, warn, info)에서 나오므로, halted는 별도의 판단이 아니라 항목들의 요약입니다. files, written, drift, diagnostics, decisions는 항상 배열이며, 없는 대신 비어 있습니다.

decisions는 가져오기가 추측한 곳을 알려 줍니다. 여기에는 임포터가 매핑한 소스 노드마다 항목이 하나씩, 임포터의 순서대로, 임포터가 보고한 그대로 담깁니다. sourceNode는 노드의 id, type, paramsSummary입니다. candidates는 임포터가 해당 노드에 대해 검토한 카탈로그 Component 각각을 componentName, score, tier, signals로 나타내며, 마지막 항목은 각 신호가 기여한 정도를 table, category, domainLabels, shape, name 아래에 담습니다. chosen은 임포터가 선택한 target, 그것을 작성한 mode(기존 Component에 대한 reference 또는 draft), 그리고 선택의 tier입니다. rationale은 그 이유이고, swapHint는 다르게 선택하는 방법입니다. 임포터가 아무것도 검토하지 않은 곳에서는 candidates가, 선택하지 않은 곳에서는 chosen이, 작성하지 않은 곳에서는 rationale과 swapHint가 없습니다. 모든 값은 임포터 자신의 것이므로(후보의 점수를 매기는 방식과 계층의 경계는 임포터가 정합니다), 항목은 판정이 아니라 매핑에 대한 임포터의 설명으로 보여 주어야 합니다. decisions는 dryRun에서도, halted가 true일 때도 똑같이 전달됩니다. 부분적인 가져오기의 추측이야말로 그것을 검토하는 작성자에게 필요한 것이며, 아무것도 보고하지 않는 임포터는 빈 목록으로 응답합니다. 이를 텍스트로 보여 줄 경우, aggrega import는 이미 하나의 결정을 mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>로 표현하며, 여기서 점수는 가장 좋은 후보의 점수입니다.

형식을 지정하지 않으면 소스에서 형식을 인식합니다. 인식에는 임포터가 선언하는 시그니처가 사용됩니다. 워크스페이스 카탈로그의 임포터와 컴파일러의 코어 임포터 모두 마찬가지이며, 각 임포터의 Plugin 엔터티가 이를 기록합니다. 시그니처는 소스를 읽는 구문, 시그니처가 적용되는 파일 이름, 그리고 파싱된 트리가 반드시 가져야 하거나 가져서는 안 되는 경로로 이루어집니다. 따라서 데몬 자체는 어떤 형식도 알지 못하며, 새 임포터의 형식은 다른 것을 바꾸지 않고도 인식됩니다. 감지는 보낸 소스만 읽고(디렉터리라면 시그니처의 파일 패턴이 선택하는 파일만 읽습니다) 네트워크에는 접근하지 않습니다. 읽는 각 파일은 워크스페이스의 카탈로그가 해당 구문에 제공하는 파서로 파싱하며, 카탈로그가 파서를 제공하지 않는 구문이면 컴파일러 자체가 가진 파서로 파싱합니다. 파일 이름에 적용되는 시그니처가 읽는 구문마다 한 번씩 파싱하며, 이후 임포터는 같은 파서로 소스를 읽습니다. 파일 패턴을 선언하지 않은 시그니처는 이름과 관계없이 보낸 파일에 적용되고, 디렉터리의 파일에는 적용되지 않습니다. Langflow, Flowise, n8n 임포터의 시그니처가 이런 종류로 JSON을 읽고, Dify 임포터의 시그니처는 YAML을 읽습니다. 따라서 단독으로 보낸 파일을 인식할 때는 그 파일을 JSON과 YAML로 읽으며, 이에는 워크스페이스 카탈로그의 파서가 필요하지 않습니다. 컴파일러가 JSON 파서와 YAML 파서를 가지고 있고, 카탈로그가 제공하는 파서가 있으면 그것이 대신 사용됩니다. 어떤 시그니처와도 일치하지 않는 소스는 format을 요청하고 임포터가 알리는 형식을 나열하며(디렉터리라면 그 파일 중 하나를 단독으로 보내거나 임포터가 파일 패턴을 선언한 format을 지정하도록 요청하고 그런 형식만 나열하며) No importer recognises the source (소스를 인식하는 임포터가 없음) 조건으로 거부됩니다. 둘 이상의 형식의 시그니처와 일치하는 소스는 그 형식들을 나열하며 More than one importer recognises the source (둘 이상의 임포터가 소스를 인식함) 조건으로 거부됩니다. 각 거부의 data는 해당 조건의 code와 shortCode를 담으므로, 클라이언트는 문구가 아니라 코드를 보고 형식을 요청합니다. 어느 경우에도 추측하지 않습니다. 추측한 형식은 엉뚱한 임포터로 해석되어 그럴듯한 엉터리 결과를 만들기 때문입니다. 응답의 format은 감지되었든 지정되었든 실제로 사용된 형식이므로, 형식을 생략한 클라이언트도 무엇이 사용되었는지 알 수 있습니다.

보낸 디렉터리는 임포터가 지정하는 파일로 읽히며, 읽을 수 없는 디렉터리는 오류입니다. source가 디렉터리를 가리키면, 임포터에는 그 시그니처가 선언한 파일 패턴이 선택하는 디렉터리 안의 파일이 전달되며, 워크스페이스의 빌드 출력 폴더 dist/는 제외됩니다. 각 파일은 디렉터리 안의 경로로 이름이 붙고 정렬된 순서로 전달되며, plugins.importer 항목이 with.sources 아래에 지정한 파일도 함께 전달됩니다. 파일 패턴을 선언하지 않은 임포터, 패턴이 선택하는 파일이 없는 디렉터리, 이름이 같은 디렉터리 파일과 with.sources 파일, 그리고 가져오기가 읽을 파일 가운데 디렉터리 밖으로 이어지는 링크나 디렉터리로의 링크는 각각 해당 조건의 코드를 담은 오류로 돌아오며, 아무것도 기록되지 않습니다.

어떤 임포터가 실행되는지는 요청이 아니라 워크스페이스가 결정합니다. 형식은 워크스페이스의 카탈로그 플러그인과 컴파일러의 코어 임포터 가운데 그 형식을 알리는 임포터로 해석됩니다. 워크스페이스 구성의 plugins.importer 항목이 그중 하나를 연결하면 그 임포터로 해석됩니다. 따라서 요청은 모듈을 선택하거나 디스크의 모듈을 가리킬 수 없습니다. 어떤 임포터도 알리지 않는 형식은 그 형식을 명시하며 거부되고, 두 임포터가 알리지만 어느 쪽도 연결되지 않은 형식(코어 임포터와, 카탈로그가 같은 형식에 대해 가진 다른 이름의 임포터인 경우도 포함)은 임의로 해석되지 않고 모호하다며 거부됩니다.

머신에 아직 없는 핵심 임포터는 그것을 필요로 하는 첫 가져오기가 한 번 가져옵니다. 이 임포터는 워크스페이스의 기본 레지스트리에서 가져오며, 컴파일러 릴리스가 게시하는 모듈로 고정되고, pull이 가져오는 플러그인을 검증하는 방식(해당 레지스트리의 신뢰 정책에 따른 서명, 그리고 사용하는 호스트 함수)으로 검증됩니다. 그리고 워크스페이스의 콘텐츠 캐시에 보관되며, 이것이 이를 위해 기록되는 유일한 것입니다. lockfile도, 신뢰된 플러그인 기록도 작성되지 않습니다. 이후의 모든 가져오기는 그곳에서 읽으며 레지스트리에 접근하지 않습니다. 검증되지 않는 모듈은 해당 조건의 코드를 담은 오류가 되며, 아무것도 보관되지 않습니다. 가져올 수 없는 모듈(워크스페이스가 오프라인이거나, 레지스트리에 접근할 수 없거나, 레지스트리에 모듈이 없는 경우)은 A plugin’s .wasm is not on this machine (플러그인의 Wasm 파일이 이 머신에 없음) 아래의 오류가 되며, 임포터와 그 버전, 그리고 모듈을 머신에 두는 방법을 알려 줍니다. 요청 자체는 레지스트리를 지정하지 않으며, 필요한 모든 임포터와 읽어 들이는 카탈로그가 머신에 있는 가져오기는 네트워크에 전혀 접근하지 않습니다.

워크스페이스가 카탈로그 폴더를 지정하지 않으면, import는 기본 레지스트리가 게시하는 카탈로그를 읽습니다. workspace.catalog_dirs, AGGREGA_CATALOG_DIRS, 루트 중 어느 것도 카탈로그 폴더를 지정하지 않는 워크스페이스는 표준 라이브러리 카탈로그를 기본 레지스트리의 catalog/snapshot에 있는 하나의 서명된 스냅숏으로 읽습니다. 스냅숏은 한 번 가져옵니다. 그 서명은 해당 레지스트리의 신뢰 정책에 따라 검증되고, 스냅숏은 워크스페이스의 콘텐츠 캐시에 보관되어 다이제스트에 고정된 카탈로그 폴더로서 그곳에서 읽히며, 어떤 레지스트리에도 다시 요청하지 않습니다. 요청이 읽는 스냅숏은 다음과 같습니다. upgrade를 보낸 경우 최신 스냅숏, 그렇지 않으면 outputDir의 레코드가 지정하는 스냅숏(머신에 없으면 다이제스트로 가져옴), 그렇지 않으면 워크스페이스가 마지막으로 최신으로 가져온 스냅숏, 그렇지 않으면 최신 스냅숏입니다. import가 기록하는 레코드는 읽은 스냅숏을 다이제스트로 지정하므로, 같은 outputDir로의 이후 요청은 같은 카탈로그를 읽습니다. 오프라인 모드에서 스냅숏을 가져와야 하는 요청은 The workspace is offline and the step needs the network (워크스페이스가 오프라인이며 이 단계에는 네트워크가 필요함) 아래의 오류가 되며 실행할 것을 알려 주고, 어느 스냅숏이 최신인지는 레지스트리만 알 수 있으므로 머신에 무엇이 있든 upgrade는 거부됩니다. 스냅숏을 게시하지 않는 레지스트리에서는 import에 카탈로그가 없게 되며, diagnostics의 warn 항목이 이를 알립니다. 카탈로그 폴더를 지정하는 워크스페이스는 그 폴더를 기준으로 import하고 스냅숏을 가져오지 않으며, 그곳에서 upgrade는 아무것도 바꾸지 않습니다.

dryRun에서는 아무것도 생성되지 않습니다. written은 비어 있고, files는 쓰기가 만들었을 것과 같은 파일을 담으며(sync와 함께라면 동기화가 쓸 파일과 그것이 최신으로 맞출 drift를 담습니다), 디렉터리도 만들어지지 않습니다. 따라서 편집기는 이를 작성자에게 보여 주어 저장, 수정 또는 폐기하게 할 수 있습니다. 쓰기가 하는 나머지 일은 모두 수행됩니다. 같은 임포터가 같은 소스에 대해 실행되어 같은 진단을 보고하므로, 쓰기가 거부할 소스는 여기서도 거부됩니다. dryRun에서 가져온 코어 임포터나 카탈로그 스냅숏은 쓰기에서와 마찬가지로 콘텐츠 캐시에 보관됩니다. import가 실행되는 데 필요한 것을 확보하는 일은 초안을 배치하는 일이 아니라 import를 실행하는 일의 일부이기 때문입니다.

임포터가 반환하는 경로는 outputDir 안으로 제한됩니다. 초안의 경로는 요청이 아니라 임포터에서 오므로, 출력 디렉터리 밖으로 벗어나는 경로는 거부되며 아무것도 기록되지 않습니다. 경로에 문제가 없던 초안조차 기록되지 않습니다. 거부는 문제가 된 경로를 명시하며, 이를 통해 고쳐야 할 것이 요청이 아니라 임포터임을 알 수 있습니다.

각 엔티티 요청이 답하는 질문

여기에는 엔티티에 대해 알려 주는 요청이 네 가지 있으며, 서로 바꿔 쓸 수 없습니다. 어느 것을 고를지는 요청할 때 무엇을 들고 있는지의 문제입니다.

커서를 들고 있는 경우. aggrega/hover와 aggrega/resolve는 파일과 위치를 받아, 그곳에 쓰인 내용으로부터 어떤 엔티티를 가리키는지 알아냅니다. 이 요청은 문서에 실제로 나타나는 참조 형태를 다룹니다. extends 값, component 또는 feature 타입, Recipe의 implements, Manifest의 recipe 참조, Release의 두 경로 포인터, uses 대상, 그리고 엔티티 자신의 metadata.name입니다. 사용자의 커서가 좌표일 때, 즉 사용자가 문서를 읽으면서 참조가 무엇을 가리키는지 알고 싶을 때 이 요청을 사용합니다.

이름을 들고 있는 경우. aggrega/entityDefinition은 식별자를 직접 받습니다. 아무것도 열려 있을 필요가 없고, 위치도 관여하지 않으며, 엔티티가 클라이언트가 찾을 수 있는 어딘가에 언급되어 있을 필요도 없습니다. 사용자가 이름을 입력했거나, 목록에서 하나를 골랐거나, 클라이언트가 이미 식별자를 알고 있는 무언가를 따라갔을 때 이 요청을 사용합니다. hover는 먼저 이름이 쓰인 곳을 찾아야 하는데, 이는 하지 않아도 되는 작업입니다.

아직 아무것도 들고 있지 않은 경우. aggrega/catalogIndex는 워크스페이스가 보유한 것을 각 엔티티의 설명 필드와 함께 열거합니다. 선택기를 채울 때 이 요청을 사용하고, 선택된 이름을 aggrega/entityDefinition에 넘깁니다.

Release를 들고 있는 경우. aggrega/releaseClosure는 하나의 엔티티가 아니라 Release에 대해 답하며, 아래 섹션에서 다룹니다.

이름 기반 요청이 반환하는 정의는 어느 한 파일이 선언한 그대로가 아니라 해석된 상태의 엔티티입니다. 베이스를 확장하는 Component나 Feature는 그 베이스의 계약을 지닌 채 반환되며, 이 계약은 그 이름을 선언한 문서 어디에도 나타나지 않습니다. 따라서 응답은 엔티티가 무엇인지에 관한 것이며, 파일을 직접 읽어서는 같은 결과를 얻을 수 없습니다.

정의는 응답 안의 구조가 아니라 YAML 문서로 전달되며, 이는 의도된 것입니다. 스키마 기둥에는 여러 작성 형태가 있습니다. 내용을 직접 작성하거나, 공유 문서를 참조하거나, 내용이 베이스에서 온다는 표시를 쓰는 것입니다. 문서는 해석이 도달한 형태를 작성자 자신의 키 순서대로 재현합니다. 필드가 필요하면 문서로 파싱하고, 패널에 표시한다면 그대로 보여 주십시오.

두 가지 이름 기반 거부 구별하기

아무것으로도 해석되지 않는 이름은 빈 문서로 응답하지 않고 거부됩니다. 빈 응답은 오타를 스스로에 대해 아무 말도 하지 않는 엔티티처럼 보고하기 때문입니다. 이름이 아무것으로도 해석되지 않는 경우는 두 가지이며, 각각 읽는 사람에게 다른 조치를 요구합니다. 두 경우는 메시지를 읽어서가 아니라 오류의 data에 무엇이 담겼는지로 구별합니다:

  • data에 file이 없는 경우. 워크스페이스의 어떤 것도 그 이름을 선언하지 않고, 어떤 카탈로그 계층도 그 이름을 해석하지 않습니다. 이는 거의 항상 요청을 고쳐야 하는 경우입니다. 오타이거나, 이 워크스페이스의 검색 경로에 없는 카탈로그의 이름입니다.
  • data에 file이 있는 경우. 워크스페이스 문서가 그 이름을 선언하고 있지만, 카탈로그는 여전히 그에 대해 아무것도 해석하지 못했습니다. 엔티티는 작성되어 있지만 무언가가 이를 거부한 것이며, 이는 사람이 수리해야 하는 워크스페이스 상태입니다. 카탈로그가 읽고 거부한 문서 중 정확히 하나가 그 이름을 선언하는 경우(일반적인 원인)에는, 메시지가 그 거부를 한 번 언급하며 시작합니다. 거부의 범주와 짧은 코드, 보고된 경로로 나타낸 문서, 그리고 위반한 줄과 제약 조건 같은 문제의 내용입니다. 이어서 해당 파일이 로드 시 건너뛰어졌음을 알리고, 로드가 거부한 다른 파일을 나열합니다. 그 외의 경우 메시지는 선언 문서의 이름을 밝히고, 로드가 거부한 파일을 나열하며, 이 워크스페이스가 로컬 엔티티를 어디에서 읽는지와 문서가 읽히도록 무엇을 바꿔야 하는지 설명합니다. 거부된 문서가 그 이름을 선언하는 경우에는 이 설명이 빠지는데, 그 문서가 이미 카탈로그가 읽는 위치에 있기 때문입니다.

두 경우 모두 entity-not-resolvable 코드를 지니므로, 코드가 아니라 file의 존재 여부로 분기하십시오.

좌표에 대해 묻기

레지스트리 참조를 들고 있는 경우. 이를 aggrega/entityDefinition의 name으로 보내면, 응답은 그 좌표에 게시된 엔티티입니다. 이름에 대한 응답과 같은 결과 형태에 published가 더해지며, 카탈로그가 해석한 내용이 아니라 게시된 내용으로 채워집니다:

  • definition은 게시된 그대로의 엔티티 문서입니다. 엔티티가 선언한 파일과 함께 게시된 좌표는 아카이브를 지니며, 문서는 그 아카이브에서 풀어냅니다. 파일을 선언하지 않은 엔티티의 좌표는 문서를 변경 없이 지니며, Plugin의 엔티티는 함께 게시된 실행 파일이 아니라 매니페스트에서 읽습니다. 상속은 적용되지 않습니다.
  • authoredLength는 그 문서의 길이입니다. 여기서의 정의는 해석된 문서의 렌더링이 아니라 작성된 문서이기 때문입니다.
  • file은 비어 있습니다. 레지스트리에서 읽은 엔티티에는 이 머신에서 가리킬 문서가 없기 때문입니다.
  • publishScope는 생략됩니다. 엔티티가 게시된 위치인 좌표를 이미 들고 있기 때문입니다.
  • published는 읽어 들인 내용이며, 이 응답에는 있고 이름으로 요청한 응답에는 없습니다. 여기에는 reference, 그 바이트가 문서를 풀어낸 아카이브였는지를 나타내는 archive(좌표가 문서 자체를 담고 있었다면 false), 매니페스트가 선언하는 mediaType, 그리고 그 매니페스트의 manifestDigest가 담깁니다. 이 다이제스트를 태그 대신 @ 뒤에 붙여 보내면 같은 바이트를 정확히 다시 읽을 수 있습니다.

이 요청은 참조가 가리키는 레지스트리에 이 데몬을 실행하는 사용자의 자격 증명과 이 워크스페이스의 네트워크 설정으로 접근하므로, 오프라인 워크스페이스는 이를 거부합니다. 가져온 바이트는 아티팩트 자체의 매니페스트가 기록한 다이제스트와만 대조됩니다. 서명은 검증되지 않고 철회도 보고되지 않으며, 아무것도 기록되지 않습니다. 읽을 수 없는 참조는 entity-not-resolvable로 거부되며, 메시지는 이유를 나타내는 조건의 짧은 코드로 시작하고(aggrega inspect가 보고하는 것과 같은 조건입니다), 이에 대해 무엇을 해야 하는지로 끝납니다. 저장소를 지정하지 않거나 태그와 다이제스트 중 어느 것도 지정하지 않은 참조는 잘못된 요청이며 invalid params로 거부됩니다.

클로저는 그래프가 아닙니다

aggrega/irGraph와 aggrega/releaseClosure는 같은 Release에 대한 같은 해석에서 파생되지만 서로 다른 질문에 답합니다. 이미 그래프를 받고 있는 클라이언트는 이 정보도 갖고 있다고 가정하기 쉽지만, 그렇지 않습니다.

그래프는 Release가 무엇을 배포하는지 알려 줍니다 — 노드, 노드가 속한 경계, 무엇이 무엇에 연결되어 있는지, 그리고 각 노드가 지닌 값과 첨부물입니다. 그래프는 그림입니다.

클로저는 배포를 빌드하기 위해 무엇을 어떤 버전으로 가져왔는지를 알려 줍니다. Release가 도달하는 모든 엔터티(노드가 되었는지와 관계없이), 그 엔터티들이 참조하는 공유 문서, 그리고 출력을 형성하는 플러그인이 포함됩니다. 클로저는 자재 명세서입니다.

어느 쪽도 다른 쪽에서 복원할 수 없습니다. 엔터티는 노드로 한 번도 나타나지 않고도 도달될 수 있으며 — Manifest가 컴포넌트 타입을 매핑하는 Recipe는 모든 빌드에서 도달되지만 어느 빌드에서도 노드가 아닙니다 — 노드는 자신의 타입이 해석된 버전을 지니지 않습니다. 따라서 “이 버전은 왜 바뀌었는가?”, “이 공유 문서를 바꾸면 무엇이 영향을 받는가?”, “이 Release는 실제로 무엇에 의존하는가?”를 묻는 사람은 클로저를 요청하는 것이고, “이 Release는 무엇을 배포하는가?”를 묻는 사람은 그래프를 요청하는 것입니다.

클로저 요청이 하지 않는 일. 클로저 요청은 아무것도 렌더링하지 않으며, 찾은 내용을 하나도 게시하지 않습니다. 특히 드리프트 경고나 렌더링 권고를 발생시키지 않습니다. 이들은 그것을 요청한 요청에 속하며, 게시는 진단 계층 전체를 교체하므로 게시하는 목록은 그래프 요청이 이미 사용자에게 보여 준 내용을 지워 버리게 됩니다. 드리프트 판정이 필요하면 그래프를 요청하십시오. 클로저 요청이 게시하는 유일한 것은 자체 발견 사항이 아닙니다. 어떤 요청이든 lockfile이 사라진 것을 발견하면 그에 근거한 드리프트 경고를 철회합니다 — Lockfile 인식을 참조하십시오.

그래프와 마찬가지로 lockfile이 필요합니다. 목록이 보고하는 버전은 이 Release가 해석된 버전이며, 아무도 준비하지 않은 워크스페이스는 아직 버전을 해석하지 않았습니다. lockfile 없이 만든 목록은 카탈로그가 오늘 우연히 보유한 내용을 보고하게 되며, 이는 이 Release가 무엇에 의존하는가와는 다른 질문입니다. 거부 메시지는 lockfile과 Release를 명시하므로 클라이언트는 aggrega pull --release <release>를 바로 제안할 수 있습니다.

클로저 항목의 kind는 알려진 경우에만 존재합니다. 참조는 문서의 한 위치에서 수집되며, 어떤 위치는 가리키는 종류를 나타내고 어떤 위치는 그렇지 않습니다. 이 필드는 이름의 형태로 추측하는 대신, 참조 위치가 종류를 기록한 경우에는 보고되고 기록하지 않은 경우에는 생략됩니다. 이 값은 작성자가 문서 맨 앞에 쓰는 단어로 보고되며, 이는 클로저를 보고하는 모든 표면이 같은 항목에 사용하는 단어와 같습니다.

같은 단어는 다른 곳에서도 같은 문서를 요청합니다. aggrega inspect <release> --closure는 명령줄에서 이 질문에 답하고, describe 도구의 release 모드는 어시스턴트 도구 프로토콜을 통해 답합니다. 세 가지 모두 Release에 대해 하나의 해석을 실행하므로 Release가 무엇에 의존하는지에 대해 서로 다른 결과를 낼 수 없습니다. aggrega inspect의 “The dependency closure”를 참조하십시오.

캐시 모델

작업은 캐시를 기반으로 동작합니다. 파일에 대해 hover / completion / resolve / diagnostics를 호출하기 전에 먼저 그 파일에 대해 aggrega/validate를 호출합니다. 이 초기화 호출에는 Release가 필요하지 않습니다. Release를 지정하지 않은 검증도 버퍼를 파싱하고 캐시를 채우므로, 지정할 Release가 없는 워크스페이스에서도 이 작업들이 동작합니다. 파싱 캐시는 읽을 때마다 각 파일의 디스크상 수정 시각과 대조되므로, 외부 편집(편집기 저장, git checkout)은 자동으로 반영됩니다. 편집기의 aggrega/invalidate는 최적화일 뿐 정확성을 위한 필수 요건이 아닙니다.

캐시는 그것을 채운 워크스페이스에 속합니다. 한 워크스페이스에서 검증된 파일은 그 워크스페이스에 대해 캐시되므로, 다른 워크스페이스에서 같은 경로를 질의하면 첫 번째 워크스페이스의 항목으로 응답하지 않고 아직 검증되지 않은 것으로 보고됩니다. 이 덕분에 두 번째 워크스페이스에 대한 질의가 잘못된 응답을 내거나 첫 번째 워크스페이스의 준비된 상태를 잃게 하는 일이 없습니다. aggrega/invalidate도 마찬가지로 지정한 워크스페이스만 비웁니다.

검증이 실행 중일 때 진단 요청하기

검증은 파일에 대해 두 가지를 채웁니다. 다른 작업에 넘겨주는 파싱 결과와 보고하는 발견 사항이며, 이 둘은 약간의 시차를 두고 채워집니다. aggrega/diagnostics는 둘 다 읽는 유일한 요청입니다. 응답할 수 있는 파일인지 알기 위해 파싱 결과가 필요하고, 발견 사항으로부터 응답합니다. 따라서 두 시점 사이에 도착한 요청은 응답에 쓸 것이 아직 없는데도 응답할 수 있다고 판단하게 됩니다.

대신 기다립니다. 지금 검증 중인 파일에 대해 aggrega/diagnostics를 보내면, 그 검증이 끝날 때 발견한 내용을 담은 응답이 도착합니다. 타이밍과 상관없이 파일에 대한 올바른 답은 하나이며, 받는 답이 바로 그것입니다. 곧 오류를 보고할 파일에 대해 빈 목록이 반환되는 일은 없습니다. 이는 클라이언트가 복구할 수 없는 유일한 잘못된 답인데, 깨끗하다고 들은 파일에 대해 다시 질의하게 만드는 계기가 없기 때문입니다. 위치 기반의 다른 작업인 hover, completion, resolve, findReferences, findImplementations는 파싱 결과를 읽고 파싱 결과로부터 응답하므로 기다릴 대상이 없으며 결코 기다리지 않습니다.

대기를 일찍 끝내는 방법은 두 가지이며, 둘 다 이미 갖고 있는 것입니다. 해당 요청 id에 대한 $/cancelRequest가 대기를 멈추고, 협조적인 aggrega/shutdown도 대기를 멈춥니다. 어느 쪽도 요청에 추가로 필요한 것이 없습니다.

그리고 대기에는 한도가 있습니다. 데몬이 정한 시간 안에 검증이 끝나지 않으면, 요청은 빈 응답 대신 검증 진행 중 코드로 거부됩니다. 오류 코드를 참조하십시오. 이 거부는 기다리는 작업이 실제로 진행 중이라는 뜻이므로, 잠시 후 다시 요청하면 됩니다. 검증을 또 보내라는 신호가 아닙니다. 그렇게 하면 작업만 늘어나고 아무것도 응답되지 않습니다.

요청을 한 번에 하나씩 실행하는 데몬은 도착 순서대로 응답하므로 겹치는 것이 없고 대기도 발생하지 않습니다. 요청을 동시에 실행하는 데몬도 같은 질문에 같은 방식으로 응답하며, 대기가 이를 보장합니다. 즉, 받는 답은 순차적으로 처리했을 때 받았을 답과 같습니다.

응답에 담긴 크기

바이트 양을 보고하는 응답은 그 양을 두 번 보고합니다. 숫자로 한 번, 같은 양을 글로 풀어 쓴 형태로 한 번입니다. 글로 쓴 필드의 이름은 숫자 필드의 이름 뒤에 Text를 붙인 것입니다. size와 sizeText, totalSize와 totalSizeText, reclaimedBytes와 reclaimedBytesText 등 크기를 담는 모든 응답이 이와 같습니다.

표시에는 글로 쓴 형태를 사용하고 계산에는 숫자를 사용합니다. 둘을 모두 보내는 목적은 클라이언트가 크기를 직접 표기할 필요가 없게 하는 데 있습니다. 데몬은 명령줄과 같은 포매터로 크기를 작성하므로, aggrega cache status와 aggrega/cacheStatus는 주어진 캐시를 반올림까지 동일하게 표시합니다. 자체 텍스트를 구성하는 클라이언트는 경계값에 대한 판단이 처음 어긋나는 순간 이와 달라집니다.

글로 쓴 형태는 이진 단위를 사용합니다(512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB). 이는 aggrega/cacheEvict가 maxSize에서 받아들이는 표기와 같으므로, 한 응답에서 읽은 크기를 다시 쓰지 않고 다음 요청에 그대로 보낼 수 있습니다. 바이트보다 큰 단위에서는 텍스트가 소수점 한 자리를 가지므로, 바이트 단위까지가 아니라 독자가 보고 싶어 하는 형태로 양을 나타냅니다. 정확한 값이 필요할 때는 숫자 필드를 사용합니다.

숫자가 선택 사항인 곳에서는 텍스트도 함께 선택 사항이며, 둘 중 하나만 있는 경우는 없습니다. publish 응답의 플러그인 크기는 pluginSize와 pluginSizeText를 함께 담거나 둘 다 담지 않습니다.

모든 요청은 대상 워크스페이스를 지정합니다

모든 요청에 workspaceRoot를 보내십시오. 이 값은 해당 요청이 작업할 워크스페이스 루트의 절대 경로입니다. 데몬은 자체 워크스페이스를 갖지 않으며 요청 사이에 어떤 워크스페이스도 기억하지 않으므로, 요청에 대한 응답은 그 요청이 지정한 워크스페이스만을 대상으로 합니다. 서로 다른 두 워크스페이스를 지정한 두 요청은 두 개의 응답을 받으며, 어느 쪽도 다른 쪽의 엔터티, Releases, 캐시된 파싱 결과나 진단을 볼 수 없습니다.

워크스페이스를 지정하지 않은 요청은 해당 매개변수를 명시하는 표준 invalid-params 오류와 함께 거부되며, 빈 값도 마찬가지입니다. 빈 값은 워크스페이스를 나타내지 않으므로 누락된 것으로 응답됩니다. 다음 두 가지 형태도 같은 이유로 거부되며, 각각 메시지에 명시됩니다. 워크스페이스 루트에는 기준이 될 위치가 없으므로 상대 경로, 그리고 워크스페이스는 트리이므로 존재하는 디렉터리가 아닌 경로입니다.

세 가지 요청은 workspaceRoot가 필요하지 않으며, 각각 그 대상이 워크스페이스가 아니기 때문입니다. aggrega/getSchema와 aggrega/scaffoldEntity는 실행 중인 바이너리에 컴파일된 스키마로 응답하므로 워크스페이스는 어느 쪽에도 아무것도 기여하지 않습니다. 덕분에 두 요청은 아무도 준비하지 않은 디렉터리에서도 응답할 수 있습니다. 세 번째는 aggrega/initialize로, 워크스페이스에 작업하는 것이 아니라 워크스페이스를 선언하는 곳입니다. aggrega/scaffoldEntity의 다른 형식, 즉 문서의 실행 가능한 예제를 쓰거나 나열하는 형식은 워크스페이스에 작업하므로, 그 요청은 다른 요청과 마찬가지로 워크스페이스를 지정합니다.

각 워크스페이스의 캐시된 상태는 별도로 유지되며, 두 번째 워크스페이스를 지정해도 첫 번째 워크스페이스에는 아무 비용도 들지 않습니다. 워크스페이스의 카탈로그 인덱스, 파싱 캐시, 진단은 그 워크스페이스에 속하므로, 다른 곳에 대한 질문이 누군가 열어 둔 폴더에 대해 에디터가 쌓아 온 상태를 밀어내지 않습니다. 한 루트를 두 가지로 표기해도 하나의 워크스페이스이므로, 중간에 .이 있거나 구분자가 중복된 경로도 일반 형태와 같은 웜 상태에 도달합니다.

진단을 푸시받을 워크스페이스 선언하기

진단은 두 가지 방식으로 전달됩니다. 직접 요청하거나, 데몬이 푸시합니다. 데몬은 핸드셰이크에서 선언한 워크스페이스에 대해서만 푸시합니다. 다른 모든 요청은 결과를 자체 응답에 담아 답하며 아무것도 푸시하지 않습니다.

aggrega/initialize에 workspaceRoot를 보내 선언합니다. 선언이 하는 일은 이것이 전부입니다. 아무것도 고정하지 않으며, 이후의 어떤 요청도 이를 기준으로 응답되지 않습니다.

푸시를 제한하는 이유는 푸시된 진단의 용도에 있습니다. 푸시는 누군가 입력하는 동안 에디터의 문제 목록을 최신 상태로 유지하는 수단이며, 아무도 보려고 요청하지 않은 응답에 대해 하기에는 정확히 잘못된 일입니다. 이 규칙이 없다면 두 번째 워크스페이스에 대한 질문이, 예를 들어 데몬을 공유하는 다른 도구에서 온 질문이, 사용자가 열어 본 적도 없는 파일에 대한 결과로 그 사용자의 문제 목록을 채우게 됩니다. 푸시를 제한하면 한 호출자의 질문이 다른 호출자의 문제 목록에 들어가지 않습니다.

이 필드는 선택 사항이며, 이 필드로 의미할 수 있는 세 가지는 서로 구별됩니다.

보내는 값푸시 대상핸드셰이크가 보고하는 내용
없음프로세스가 실행된 워크스페이스해당 워크스페이스
워크스페이스 루트해당 워크스페이스해당 워크스페이스
빈 문자열없음 — 진단이 전혀 푸시되지 않음빈 루트

아무것도 보내지 않으면 푸시는 프로세스가 실행된 워크스페이스를 대상으로 유지되므로, 아무것도 선언하지 않은 클라이언트는 그 워크스페이스의 진단을 받습니다. 빈 문자열을 보내는 것은 에디터가 아니어서 동기화할 문제 목록이 없는 호출자에게 맞는 선언입니다. 모든 결과는 여전히 그것을 만든 요청의 응답으로 전달됩니다.

선언된 워크스페이스는 요청에서 지정한 워크스페이스와 정확히 같은 방식으로 확인되므로, 상대 경로나 디렉터리가 아닌 경로를 지정한 선언은 푸시가 예상치 못한 곳을 가리키도록 두지 않고 핸드셰이크에서 거부됩니다.

워크스페이스 루트와 활성 Release

데몬은 요청이 지정한 각 워크스페이스를 모든 aggrega 명령이 워크스페이스를 확인하는 것과 같은 방식으로 확인하며, 무엇이 루트를 고정하고 어떤 순서로 적용되는지는 Configuration에 설명되어 있습니다. 클라이언트에게 중요한 결과는 두 가지입니다. workspace: 블록이 없는 .aggrega-config.yaml은 루트를 고정하지 않습니다. 이 파일은 여전히 설정을 제공하지만, 설정만 있는 파일이 모든 상위 디렉터리를 워크스페이스 루트로 만들 수는 없습니다. 그리고 아무것도 루트를 고정하지 않으면 작업 디렉터리가 사용됩니다. 데몬은 실행을 거부하지 않고 시작되며, 작업은 단순히 아무것도 확인하지 못합니다.

프로세스도 --workspace-root에서, 또는 작업 디렉터리에서 위로 올라가며 찾은 워크스페이스를 대상으로 실행되며, 이 확인은 두 가지 일만 합니다. 어떤 요청이 아니라 프로세스의 속성인 워커 풀의 크기를 정하고, 푸시되는 진단의 기본 선언이 됩니다. 어떤 요청도 이를 기준으로 응답되지 않습니다.

구성 역시 모든 명령이 읽는 것과 같은 계단식 구성이며, Configuration에 설명되어 있습니다. 데몬이 더하는 것은 각 워크스페이스의 구성을 그 워크스페이스가 처음 지정될 때 한 번 읽고, 이후 그 워크스페이스에 대한 모든 요청에 재사용한다는 점뿐입니다. 계단식 구성이 읽을 구성 파일이 워크스페이스 밖으로 이어지는 링크인 경우, 즉 워크스페이스 자체의 .aggrega-config.yaml이나 그 옆의 CI 소유 오버레이인 경우, 터미널에서와 마찬가지로 여기서도 읽히지 않으며, 그 파일이 구성했을 다른 어떤 것도 대신 읽히지 않습니다. 터미널과 다른 점은 여전히 무엇이 응답하는가입니다. 이런 워크스페이스를 대상으로 실행된 데몬은 시작되며 오류 스트림에 이를 한 번 알립니다. 이런 워크스페이스를 지정한 요청은 어느 경우든 다음과 같이 응답됩니다. 워크스페이스에 무엇이 있는지 나열하는 두 요청인 aggrega/releaseCandidates와 aggrega/catalogIndex는 아무것도 구성되지 않은 상태로 읽어 응답합니다. 워크스페이스 자체의 문서가 나열되고, 카탈로그 디렉터리는 읽히지 않으며, 보류된 파일은 검색에서 만났는지 여부와 관계없이 unreadLinkedFiles에 명시됩니다. 이 이름으로 클라이언트는 워크스페이스의 구성이 워크스페이스 밖으로 이어진다는 것을 알 수 있습니다. 그 워크스페이스를 지정한 다른 모든 요청, 즉 빌드, 그래프, 검증, 기본 Release, 유효 구성, 쓰기, 그리고 Release 기준의 aggrega/catalogIndex는 그 구성에 따라 결정되므로, E0321을 담은 invalid-params 오류(오류의 data에는 read-leads-out-of-workspace)와 링크 및 그 링크가 이어지는 위치를 명시하는 문장과 함께 거부됩니다. 핸드셰이크도 이런 워크스페이스에 응답하며, 목록 응답에 사용된 내용에 어떤 구성 파일도 기여하지 않았으므로 configSource로 defaults를 보고합니다. 링크를 제거하거나 워크스페이스 안의 파일로 이어지게 하면 다음 요청에서 구성을 읽습니다. 프로젝트 파일 아래에는 전역 계층이 있습니다. 데몬을 시작한 명령줄에서 --config가 지정한 파일이 데몬이 제공하는 모든 워크스페이스에 적용되고, 그렇지 않으면 AGGREGA_CONFIG 환경 변수가 설정된 경우 그 변수가 지정한 파일이, 그렇지 않으면 기본 위치의 파일이 있을 때 로드됩니다. 기본 위치는 Windows에서는 APPDATA 환경 변수가 지정한 디렉터리 안의 aggrega\config.yaml이고, 그 밖의 환경에서는 XDG_CONFIG_HOME이 지정한 디렉터리 안의 aggrega/config.yaml이며, 없으면 ~/.config/aggrega/config.yaml로 대체됩니다. 그 아래에는 기본 제공 기본값이 있습니다.

Release에 작용하는 작업은 Release를 매개변수로 받으며, 데몬은 스스로 어떤 Release도 선택하지 않습니다. 워크스페이스는 여전히 자신이 가리키는 Release를 선언하며, 4단계 계단식 과정이 그 선언을 읽습니다. build.authoring_release 구성 필드, 그다음 .aggrega/active-release 마커 파일, 그다음 워크스페이스에 Release가 하나뿐인 경우의 휴리스틱, 마지막으로 Aggregate만 사용하는 대체 방식입니다. 따라서 직접 작성한 마커는 휴리스틱보다 우선하며, 로드할 수 없는 Release를 지정한 마커는 대체 방식이 아니라 휴리스틱으로 넘어갑니다. 절대 경로, 루트 밖으로 올라가는 경로, 또는 루트 밖으로 이어지는 링크를 통해 워크스페이스 밖의 Release를 지정한 마커는 읽히지 않습니다. 단, 워크스페이스 구성이 그 Release를 build.authoring_release나 workspace.releases의 키로 지정한 경우는 예외입니다. 워크스페이스 밖에 있는 Release에 도달하는 방법은 구성이며, 마커가 아닙니다. 이 경우 계단식 과정은 로드할 수 없는 마커의 경우와 똑같이 다음 단계로 넘어가며, 아무것도 선택하지 못하면 trace는 마커 줄에서, reason은 마커에 관한 문장에서 그 이유를 알려 줍니다.

aggrega/activeRelease는 이 계단식 과정이 선택한 것을 보고하며, 이는 데몬이 따르는 설정이 아니라 클라이언트를 위한 제안입니다. 계단식 과정의 입력을 직접 읽지 말고 데몬에 물어보십시오. 구성 필드와 마커 파일은 네 가지 입력 중 두 가지일 뿐이므로, 어느 쪽을 읽든 그것이 우연히 채택된 입력일 때만 워크스페이스의 선택을 나타냅니다. 로드할 수 없는 Release를 지정한 마커가 가장 분명한 예입니다. 계단식 과정은 완전히 다른 Release를 선택하지만, 마커를 읽는 쪽은 실패한 Release를 보고하게 됩니다.

계단식 과정은 요청할 때 실행되며 그 전에는 실행되지 않으므로, 신뢰할 만한 두 가지 결과가 있습니다. 핸드셰이크는 워크스페이스 탐색을 기다리지 않으므로 트리 크기와 관계없이 빠릅니다. 그리고 응답은 워크스페이스를 따라갑니다. 마커를 작성하고(새 선택 자체로 응답하는 aggrega/setActiveRelease 사용), 구성을 편집하고, Release 파일을 추가하거나 제거한 뒤 다시 요청하면 같은 데몬에서 새 응답을 받습니다. 작업할 Release를 바꾸는 데 데몬을 다시 시작할 필요는 없습니다. 클라이언트는 다음 요청에서 다른 release를 보내면 됩니다.

하나의 버퍼가 아니라 워크스페이스 전체를 검색하는 작업인 completion, hover, resolve, findReferences, findImplementations는 워크스페이스 루트 아래의 YAML을 열거하며, 이 열거는 .gitignore를 따릅니다. 워크스페이스 루트부터 파일이 있는 디렉터리까지의 모든 .gitignore가 적용되고 가장 가까운 것이 우선하므로, 저장소가 무시하는 YAML 파일은 완성 후보로 제공되지 않으며 정의나 참조로 보고되지 않습니다. 워크스페이스 밖으로 이어지는 링크인 .gitignore는 읽히지 않으므로, 머신의 다른 곳에 있는 파일이 워크스페이스의 어떤 문서를 검색할지 결정하는 일은 없습니다. 따라서 벤더링된 트리와 생성된 출력은 별도의 제외 설정을 관리하지 않아도 파일 간 결과에서 제외됩니다. 그리고 찾을 것으로 예상했지만 무시된 문서는 나타나지 않으며, 참조가 누락된 것 같을 때 확인해 볼 만한 유일한 경우가 이것입니다. completion이 구성된 catalog_dirs에서 제공하는 Components와 Features는 다른 방식으로 읽힌 것입니다. 이들은 구성된 그대로의 디렉터리에서 옵니다. 즉 구성이 Release에 자체 디렉터리를 주지 않을 때 그 Release의 빌드가 읽는 것과 같은 디렉터리이며, Release를 지정한 요청의 경우에는 그 Release 자체의 디렉터리입니다. 따라서 카탈로그 디렉터리의 엔터티는 .gitignore가 그 디렉터리를 대상으로 하는지와 관계없이 제공됩니다. 단, 카탈로그 디렉터리의 읽기가 머물러야 하는 디렉터리 밖으로 이어지는 링크 뒤에 있는 엔터티는 예외로, 읽히지도 제공되지도 않습니다.

Release를 지정하는 요청은 해당 Release의 카탈로그 디렉터리를 읽으며, 이는 터미널에서 그 Release를 빌드할 때 읽는 디렉터리와 같습니다. 워크스페이스 구성이 workspace.releases 아래에서 해당 Release에 자체 디렉터리를 지정한 경우에는 그 디렉터리를, 그렇지 않으면 워크스페이스의 catalog_dirs를 읽습니다. 여기에는 Release를 지정한 aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate, aggrega/lint, Release 그래프의 노드를 대상으로 하는 aggrega/attachCandidates와 aggrega/attachmentContainer, 그리고 aggrega/connectionAtPosition이 해당하며, 다음 섹션에 나열된 요청도 Release를 지정하면 해당합니다. 따라서 Release마다 카탈로그 변형을 유지하는 워크스페이스에서 하나의 세션이 모든 Release에 대해 각자의 변형으로 응답하며, Release의 경로 외에는 아무것도 보낼 필요가 없습니다. 특정 Release 하나와 관련되지 않은 요청, 즉 aggrega/catalogIndex, aggrega/entityDefinition, Release를 지정하지 않은 completion, hover, resolve, 그리고 엔터티나 레이블 집합을 대상으로 하는 aggrega/attachCandidates는 워크스페이스의 catalog_dirs를 읽습니다. 엔터티도 Release도 지정하지 않은 aggrega/lint는 workspace.releases 아래에 Releases를 지정한 워크스페이스에서 예외입니다. 이 경우 요청 시 및 편집할 때마다 관례 게시에서 설명하는 대로, 각 Release마다 해당 Release의 디렉터리를 대상으로 전체 카탈로그를 한 번씩 검사합니다. Release에 자체 카탈로그 디렉터리 지정하기를 참조하십시오.

하나의 Release 기준으로 응답하기

aggrega/catalogIndex, aggrega/entityDefinition, 그리고 커서에서 시작하는 다섯 요청인 aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences, aggrega/findImplementations는 단일 Release와 관계가 없으며, 각각 하나의 Release와 관계되게 만드는 선택적 release를 받습니다. 이 값은 워크스페이스 루트에 대한 상대 경로이며, Release를 받는 다른 요청과 같은 계약을 따릅니다. Release 파일을 가리키지 않거나 디렉터리를 가리키는 값은 Release 기준인 것처럼 보이면서 워크스페이스 기준으로 응답되는 대신 거부됩니다.

여기의 모든 요청에서 Release가 도달하는 범위는 다음과 같습니다. 해당 Release의 스택이 읽는 카탈로그 디렉터리 아래의 워크스페이스 문서, 그리고 어떤 카탈로그 디렉터리에도 속하지 않는 모든 워크스페이스 문서(카탈로그 옆에 작성된 Release, 그 Aggregate와 Manifest 등)입니다. 다른 Releases만 읽는 카탈로그 디렉터리 아래의 워크스페이스 문서는 응답에 포함되지 않습니다. 나열되지도, 해석되지도, 제안되지도 않습니다. 이 덕분에 서로 다른 Releases를 위해 나란히 유지되는 한 엔터티의 변형들이 혼동되지 않습니다.

  • 목록. Release를 지정하면 해당 Release가 보는 엔터티가 나열됩니다. 나열되는 Features는 해당 Release의 카탈로그 디렉터리가 선언하는 것이며, 다른 Releases만 읽는 카탈로그 디렉터리 아래의 워크스페이스 문서는 제외됩니다. 따라서 Release마다 한 엔터티의 변형을 유지하는 워크스페이스에서는 모든 변형이 나란히 나열되는 대신 해당 Release가 빌드에 사용하는 변형 하나만 나열됩니다. 카탈로그 옆에 작성된 Release, 그 Aggregate와 Manifest처럼 어떤 카탈로그 디렉터리에도 속하지 않는 문서는 모든 Release의 목록에 포함됩니다.
  • 이름으로 조회. Release를 지정하면 이름이 그 Release의 카탈로그 디렉터리를 통해 해석되므로, 여러 변형이 선언하는 이름은 그 Release가 빌드에 사용하는 변형으로 해석됩니다. 그 디렉터리에서 해석되지 않는 이름은 workspace.releases 아래 해당 Release의 항목을 명시하는 설명과 함께 거부됩니다. 조회가 읽은 것이 그 항목이기 때문입니다. 레지스트리 참조는 Release를 받지 않으며, Release와 함께 보내면 거부됩니다. 어떤 Release가 지정되든 그 참조를 게시하는 레지스트리에서 읽기 때문입니다.
  • 호버와 정의로 이동. Release를 지정하면 커서 위치의 참조는 먼저 워크스페이스 구성이 지정한 순서대로 그 Release의 카탈로그 디렉터리를 통해 해석됩니다. 이는 그 Release 기준의 이름 조회가 수행하는 것과 같은 해석이므로, 다른 곳의 워크스페이스 문서가 같은 이름을 선언하더라도 표시되는 엔터티와 열리는 문서는 그 디렉터리가 해석한 변형입니다. 그 디렉터리 아래의 어떤 문서도 응답하지 못하는 경우에만 그 Release가 도달하는 워크스페이스 문서를 검색합니다. Release를 지정하지 않으면 순서가 반대입니다. 워크스페이스 문서를 먼저 검색하므로 워크스페이스 문서가 응답하는 참조는 그 응답을 유지하며, 워크스페이스 자체의 catalog_dirs는 어떤 문서도 그 이름을 선언하지 않는 경우에만 참조됩니다. 이를 통해 워크스페이스 트리 밖에 있는 것을 포함하여 구성된 카탈로그 디렉터리에만 있는 엔터티를 찾을 수 있습니다. 편집기가 Release의 디렉터리가 해석하는 문서의 저장되지 않은 사본을 가지고 있고 그 사본이 여전히 그 이름을 선언하는 경우, 응답은 그 사본에서 읽으므로 위치가 편집기에 표시되는 줄에 맞춰집니다.
  • 자동 완성. Release를 지정하면 제안되는 이름은 그 Release가 도달하는 워크스페이스 문서가 선언하는 이름과, 그 Release의 카탈로그 디렉터리가 선언하는 Components 및 Features입니다.
  • 참조와 구현. Release를 지정하면 그 Release가 도달하지 않는 워크스페이스 문서의 위치는 보고되지 않으므로, 다른 Release를 위해 보관된 변형이 이 Release의 참조나 구현으로 나열되는 일은 없습니다.
  • 그래프 노드에 연결할 수 있는 것. Release 그래프의 노드를 대상으로 하는 aggrega/attachCandidates는 항상 그 Release 기준입니다. 연결 후보 응답이 알려 주는 것을 참조하십시오.

Release를 지정하지 않으면 위 단락에서 설명한 것처럼 워크스페이스 자체의 카탈로그 디렉터리를 기준으로 응답합니다.

레지스트리 접근과 쓰기

여기의 요청 대부분은 워크스페이스와 이미 캐시된 내용으로부터 응답하며 아무것도 쓰지 않습니다. 이름이 지정된 몇몇 요청은 그 이상을 수행하며, 이들은 서로 독립적인 두 축으로 나뉩니다. 요청이 무엇에 접근하는지, 그리고 요청이 변경하는 내용이 어디까지 미치는지입니다.

레지스트리로 나가는 요청은 읽는 요청과 게시하는 요청으로 나뉩니다. aggrega/resolveDependencies는 Release에 필요한 것을 가져오고, aggrega/build는 autoPull 필드가 먼저 의존성을 해석하도록 요청할 때, 그리고 그때에만 여기에 합류하며, 이 경우 렌더링 전에 레지스트리에 접근하고 lockfile을 씁니다. aggrega/registryUpdate는 로컬 검색 인덱스를 다시 빌드하기 위해 구성된 모든 레지스트리를 순회합니다. aggrega/pluginAdd는 요청이 지정한 플러그인을 구성된 레지스트리에서 검색하고, 그중 하나를 고정하기 위해 게시된 버전을 읽습니다. aggrega/registryAdd는 요청이 가져오기를 거절하거나 자체 정책을 제공하지 않는 한, 등록하는 레지스트리에 그 레지스트리가 알리는 신뢰 정책을 요청하며, aggrega/configInit은 시드하는 레지스트리에 같은 것을 요청합니다. aggrega/explainError는 머신의 모든 프로젝트가 공유하는 캐시에 워크스페이스 자체의 서명 검사가 허용하는 사본이 없는 경우, 조건의 해설을 읽어 오는 문서 번들을 한 번 가져옵니다. aggrega explain을 참조하십시오. aggrega/scaffoldEntity는 example 또는 list를 받으면 같은 조건으로 같은 번들을 가져오며, 쓰기의 경우 그다음 예제를 워크스페이스의 새 디렉터리에 씁니다. aggrega/import는 머신에 아직 core importer가 없는 경우, 워크스페이스의 기본 레지스트리에서 한 번 가져오며, 카탈로그 폴더를 지정하지 않은 워크스페이스에서는 자신이 읽는 게시된 카탈로그 스냅숏도 가져옵니다. import 응답이 알려 주는 것을 참조하십시오. 그리고 aggrega/entityDefinition은 name으로 레지스트리 참조가 전송되면 그 참조가 지정하는 엔터티를 읽으며, 아무것도 쓰지 않습니다. aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact는 레지스트리에 바이트, 서명 또는 철회 표시를 씁니다. 요청은 그렇게 하도록 전송된 경우에만 레지스트리에 접근합니다. 목록 조회는 구성이 고정한 것을 보고하고, 검색은 오프라인 스냅숏을 읽으며, dryRun으로 요청된 게시는 보낼 내용을 계산할 뿐 아무 곳에도 연결하지 않습니다.

이 규칙은 작업이 어느 표면에서 실행되는지가 아니라 언제 실행되는지에 관한 것입니다. 가져오거나 쓰는 작업은 요청이 그 작업을 지정했기 때문에 실행되며, 문서 검증, 그래프 검사, 워크스페이스 엔터티 목록 조회의 부수 효과로 실행되지 않습니다. 따라서 키 입력마다 검증하는 편집기는 네트워크에 접근하지 않고 lockfile을 다시 쓰지 않는 반면, 사용자가 클릭하는 “의존성 해석” 동작은 aggrega pull과 정확히 같은 일을 합니다. 두 표면 뒤에서 같은 해석이 이루어지고, 바이트 단위로 동일한 lockfile을 쓰며, 같은 아티팩트 캐시를 채웁니다.

아무것도 묻지 않습니다. 이 스트림을 지켜보는 사람이 없으므로, ID는 제공되거나 주변 환경에 있는 자격 증명 소스에서 해석되며 묻는 방식으로는 결코 해석되지 않습니다. 터미널 명령이라면 사람에게 질문했을 상황, 즉 자격 증명이 필요한 레지스트리, 둘 이상의 provider 플러그인이 제공하는 기능, 철회에 담을 텍스트 같은 경우에는 오지 않을 답을 기다리며 멈추는 대신 무엇을 제공해야 하는지 밝히는 메시지와 함께 요청이 실패합니다. 거부는 워크스페이스를 원래 상태 그대로 둡니다. lockfile은 쓰이지 않고 부분적인 기록도 남지 않으며, 자격 증명을 해석하지 못한 게시는 바이트가 레지스트리에 도달하기 전에 거부됩니다.

일부 변경은 이 워크스페이스 너머까지 미치며, 응답이 그 범위를 알려 줍니다

요청은 하나의 워크스페이스를 지정하므로, 자신의 범위에 대해 아무 말도 하지 않는 응답은 그 워크스페이스에 관한 것으로 읽힙니다. 이 요청 중 몇몇에서는 그렇게 읽으면 틀리므로, 각 요청은 자신의 범위를 담고 있으며 클라이언트는 결과에 따라 행동하기 전에 그 범위를 보여 주어야 합니다.

게시, 서명, 철회는 머신을 완전히 넘어서 미치며, 이는 여기서 가장 넓은 범위입니다. 아래의 다른 쓰기는 이 머신이 해석하는 내용을 바꾸지만, 이것들은 해당 레지스트리에서 해석하는 모든 사람의 결과를 바꿉니다. 게시된 바이트는 그 레지스트리의 모든 소비자가 받는 것이며, 태그 위에 다른 내용을 다시 게시하는 것은 제공되지 않고 거부되므로, 여기의 어떤 요청도 게시를 되돌리지 않습니다. 해결책은 새 버전을 게시하는 것입니다. 서명과 철회 표시는 아티팩트를 대체하지 않고 그 형제로 첨부되므로 바이트 자체는 변경되지 않습니다. 그러나 이후에 아티팩트를 가져오는 사람은 누구나 이것들도 함께 가져오며, 이미 가진 사람에게서는 어느 것도 회수할 수 없습니다. 철회는 셋 중 잘못 읽기 가장 쉬운 것입니다. 해당 버전은 계속 가져올 수 있지만, 워크스페이스가 신뢰하는 철회는 그 버전을 그곳의 해석이 선택할 대상에서 제외합니다.

서명은 자격 증명을 사용하며, 자격 증명을 어디서 가져오는지는 클라이언트를 연결하기 전에 알아 둘 가치가 있습니다. 키 없는 서명은 ID 토큰을 다음 순서로 해석합니다. 요청의 identityToken, 다음으로 데몬 환경의 AGGREGA_IDENTITY_TOKEN, 다음으로 접근 가능한 경우 주변 환경의 GitHub Actions OIDC 엔드포인트, 마지막으로 SIGSTORE_ID_TOKEN입니다. 이 중 어느 것도 토큰을 내주지 않으면 작업은 거부되고 무엇을 보내야 하는지 밝힙니다. 볼 사람이 없으므로 브라우저를 열지 않습니다. 키 기반 서명은 오프라인 대안이며, 요청은 키 경로를 지정하지 않습니다. 요청이 읽는 것은 요청이 지정한 워크스페이스 안에 있고 개인 키는 워크스페이스 안에 보관되지 않으므로, 키는 대신 해당 워크스페이스 자체 구성의 signing: 블록에서 가져옵니다. 두 서명 모드와 각각이 연결하는 대상은 aggrega sign을 참조하십시오.

네 응답 모두 reach를 담습니다. 여기에는 registries, 즉 호출이 대상으로 삼은 모든 레지스트리 호스트가 각각 한 번씩, 호출이 처음 대상으로 삼은 순서대로 들어 있으므로, 참조가 여러 레지스트리에 걸친 서명 배치나 배치 파일은 그 각각을 모두 나열합니다. 그리고 beyondThisMachine이 들어 있는데, 이는 호출이 요청한 것이 아니라 실제로 첨부한 것에서 도출됩니다. 내용을 업로드했거나 서명, 게시 날짜, 지원 중단 표시를 첨부한 경우에만 정확히 true이며, 드라이 런의 경우와 첨부하려던 모든 것이 이미 있었던 호출의 경우, 즉 이미 완료된 버전에 대해 다시 실행한 게시나 모든 참조에 이미 검증되는 서명이 있던 서명 배치의 경우에는 false입니다. 드라이 런도 대상으로 삼았을 목적지를 나열합니다. 결과에 따라 행동하기 전에 이를 보여 주십시오.

레지스트리를 등록하거나 제거하면 기본적으로 머신의 모든 워크스페이스가 공유하는 구성에 씁니다. 레지스트리와 그 레지스트리에서 신뢰하는 ID는 보통 어디서 작업하든 같으므로, 요청이 workspace: true를 보내지 않는 한 항목은 그곳에 들어갑니다. 그 결과를 분명히 말해 둘 가치가 있습니다. aggrega/registryAdd와 aggrega/registryRemove는 이 세션에서 아무도 지정하지 않은 프로젝트를 포함해 해당 머신의 모든 프로젝트가 해석에 사용하는 것을 바꿉니다. 두 응답 모두 scope를 담으며, 여기에는 쓰인 configFile과 그것이 공유 파일인지를 알려 주는 machineWide가 들어 있습니다. 제거가 둘 중 더 주의해야 할 쪽인데, 다시 추가하는 것이 같은 행위가 아니기 때문입니다. 고정되어 있던 신뢰 정책은 사라지고, 나중의 등록은 그때 레지스트리가 알리는 정책을 고정합니다.

구성을 시드하면 기본적으로 같은 공유 파일에 쓰며, 이유도 같습니다. aggrega/configInit은 레지스트리와 그 신뢰 정책을 등록하는데, 이는 머신 전체 도구이므로 재정의가 없으면 머신의 모든 프로젝트가 해석에 사용하는 구성에 씁니다. 또한 해당 레지스트리가 알리는 정책을 읽기 위해 그 레지스트리에 한 번 접근합니다. 응답은 두 레지스트리 메서드가 담는 것과 같은 scope 쌍을 담습니다. 의지할 만한 한 가지 점에서 그 메서드들과 다릅니다. 기존 구성 파일을 덮어쓰지 않고 거부하므로, 요청이 force를 보내지 않는 한 누군가 사용 중인 구성을 대체할 수 없습니다. 고정(freeze)은 반대의 경우입니다. aggrega/configCapture는 재정의를 전혀 받지 않고, 항상 프로젝트 자체의 구성 파일에 쓰며, 어떤 레지스트리에도 접근하지 않으므로, 그 동작은 다른 프로젝트에 보이지 않습니다. 구성 쓰기가 남기는 것을 참조하십시오.

🔴 명령 확장 플러그인을 추가하거나 제거하면 기본적으로 같은 공유 파일에 기록되며, 이 부분은 주의 깊게 읽어야 합니다. aggrega/pluginAdd와 aggrega/pluginRemove는 type을 받으며, 재정의를 보내지 않으면 이 유형이 기록 위치를 결정합니다. provider, governance, linter, importer 항목은 한 프로젝트의 빌드를 구성하므로 해당 프로젝트 자체의 구성으로 기록됩니다. cli 항목은 머신 전체 도구이므로, global도 workspace도 지정하지 않은 cli 유형의 추가는 이 머신의 모든 워크스페이스가 참조하는 전역 구성 파일에 명령을 등록합니다. 그러면 이 명령은 이 세션에서 아무도 지정하지 않은 프로젝트를 포함하여 해당 머신의 모든 프로젝트에서 최상위 aggrega 명령이 되며, 이를 되돌리려면 실행 취소가 아니라 별도의 제거가 필요합니다. 로컬에 두려면 workspace: true를 보내십시오. 두 응답 모두 scope를 포함하며, 여기에는 기록된 configFile과 그것이 공유 파일인지를 나타내는 machineWide가 담기고, 이 값은 기록이 확인된 파일에서 도출됩니다. 추가는 검색한 레지스트리에도 접근하므로 두 축에 동시에 해당합니다. What a plugin change tells you를 참조하십시오.

나머지 두 플러그인 요청은 워크스페이스 안에만 기록합니다. aggrega/pluginSync는 요청이 지정한 Plugin 엔터티 파일을 기록하고, aggrega/pluginGenCatalog는 요청이 지정한 outputDir 아래에 생성된 엔터티를 기록합니다. 둘 다 요청이 지정한 워크스페이스 안에 기록하고, 절대 경로이거나 워크스페이스 밖으로 확인되는 대상을 거부하며, 어느 것도 다른 프로젝트에 보이지 않습니다. aggrega/pluginGenCatalog는 모듈과 오버레이를 선택한 위치에서 읽지만, 이것이 기록 위치를 넓히지는 않습니다. 둘은 서로 다른 규칙으로 확인되므로, 생성 작업은 어디서든 빌드한 모듈을 읽을 수 있으면서도 생성하는 엔터티는 여전히 워크스페이스 안에 놓입니다. dryRun 상태의 aggrega/pluginGenCatalog는 아무것도 기록하지 않고 대신 내용을 반환합니다.

엔터티를 고정하는 작업도 워크스페이스 안에만 기록하며, 엔터티의 소스가 지정한 호스트에 접근합니다. aggrega/pin은 요청이 지정한 엔터티 옆, 즉 워크스페이스 안의 경로에 entity.lock을 기록하고, 가져온 소스로 워크스페이스의 콘텐츠 캐시를 채웁니다. 기록하는 어떤 것도 다른 프로젝트에 보이지 않습니다. 엔터티가 지정한 각 원격 소스(차트 저장소, Git 호스트, URL)를 확인하기 위해 외부에 접근하며, 이는 aggrega/resolveDependencies가 Release가 사용하는 소스에 대해 갖는 접근 범위와 같습니다. pinSources를 받은 aggrega/resolveDependencies와 aggrega/publishEntity도 같은 단계를 실행하므로, 각각 고정하는 엔터티 옆에도 기록합니다. 따라서 고정을 수행하는 게시는 레지스트리뿐 아니라 워크스페이스에도 영향을 줍니다. 고정하지 않는 게시는 엔터티 옆에 아무것도 기록하지 않지만 여전히 그 호스트에 접근합니다. 잠금 파일을 이 단계가 기록할 내용과 비교하려면 엔터티가 명시하는 각 원격 소스를 전부 가져와야 하기 때문입니다.

어시스턴트 스킬 설치는 요청이 global을 보내지 않는 한 워크스페이스 안에 머뭅니다. aggrega/skillsInstall은 지정된 각 어시스턴트의 프로젝트 스킬 폴더를 요청이 지정한 워크스페이스 안에 쓰며, 그곳에 쓰는 것은 다른 프로젝트에 보이지 않습니다. 응답의 scope는 false인 machineWide를 지닙니다. global: true이면 대신 홈 디렉터리 아래 각 어시스턴트의 사용자별 폴더에 쓰며, 그 어시스턴트는 이 폴더를 머신의 모든 프로젝트에서 읽고, machineWide는 true입니다. 어느 쪽이든 레지스트리와 네트워크에 접근하지 않습니다.

저장된 자격 증명을 제거하는 작업은 이 머신에 머무는 다른 어떤 작업보다 영향 범위가 넓습니다. aggrega/logout은 자격 증명 저장소를 변경하며, 이 저장소는 머신의 모든 프로젝트뿐 아니라 같은 레지스트리에 인증하는 다른 모든 도구와도 공유됩니다. 따라서 세션을 통해 제거한 자격 증명은 그 모두에게서 사라지며, aggrega/registryList는 다른 모든 워크스페이스에서도 그것이 없다고 보고합니다. 응답에는 machineWide를 담은 scope가 포함되며 이 값은 항상 true입니다. 이 저장소에는 확인될 워크스페이스 범위 형태가 없으므로 보낼 재정의도, 요청이 선택할 것도 없습니다. 위의 구성 기록과 달리 scope는 의도적으로 파일을 지정하지 않습니다. 저장소는 머신에 구성된 자격 증명 도우미나 OS 키체인에 위임하므로 제거는 파일이 전혀 아닌 무언가가 처리하는 경우가 많으며, 경로를 지정하면 제거가 반드시 건드리지는 않은 위치를 가리키게 됩니다.

제거는 인증의 반대가 아니며, 클라이언트는 이를 그렇게 제시해서는 안 됩니다. 이 인터페이스는 자격 증명을 제거할 뿐 획득하지 않습니다. 자격 증명을 되찾으려면 터미널에서 aggrega login으로 다시 인증해야 합니다. 자격 증명을 저장하려면 사람이 입력한 비밀 값이 필요한데 이 스트림을 지켜보는 사람은 없기 때문입니다. 따라서 클라이언트가 제공하는 “로그아웃”은 여기서 일방향입니다. 둘을 구분하는 것은 사람이 관여하는지 여부가 아니라(두 작업 모두 사람이 선택했으므로), 작업이 그것을 구동하는 쪽에서 무언가를 얻어야 하는지 여부입니다. 제거는 필요한 하나의 값을 요청에 담지만, 자격 증명 획득은 그렇지 않습니다.

캐시 콘텐츠를 회수하는 작업도 워크스페이스 밖까지 영향을 줍니다. 컴파일된 모듈 저장소와 플러그인 describe 저장소는 머신의 모든 프로젝트가 공유하므로, aggrega/cachePrune, aggrega/cacheEvict, aggrega/cacheClear는 다른 프로젝트가 의존하는 콘텐츠를 제거할 수 있습니다. 각 제거 항목은 그것이 속한 클래스의 reach를 포함하고, 각 응답은 scope.machineWideClasses를 포함합니다. aggrega/cacheStatus는 아무것도 변경하지 않지만 모든 클래스에 같은 접근 범위를 포함합니다. 회수 여부를 결정하는 클라이언트는 작업하기 전에 이 정보가 필요하기 때문입니다.

검색 인덱스 갱신은 그 반대입니다. aggrega/registryUpdate는 구성된 모든 레지스트리에 접근하지만, 기록하는 내용은 이 워크스페이스 자체에 구성된 캐시 디렉터리 아래에 놓이므로 다른 프로젝트가 참조하는 것은 아무것도 바꾸지 않습니다. 응답의 indexRoot가 그 디렉터리를 나타냅니다.

부분 갱신은 실패하지 않고 응답합니다. 레지스트리 하나를 지정한 요청에서 갱신이 실패하면 오류입니다. 제공할 응답이 없기 때문입니다. 구성된 모든 레지스트리를 갱신하는 요청은 일부 또는 전부가 실패하더라도 성공합니다. 갱신된 레지스트리는 인덱싱되어 기록되고, failed가 나머지를 나타내며, 각 호스트는 자체 오류를 포함합니다. 오류의 존재 여부가 아니라 failed를 읽으십시오.

레지스트리에 접근할 수 있었는지는 메시지 해석이 아니라 키로 판단합니다. 실패한 호스트는 레지스트리에 전혀 도달하지 못한 경우(이름이 확인되지 않았거나, 연결이 거부되었거나 열 수 없었거나, 보안 연결을 수립할 수 없었던 경우) unreachable: true를 포함하며, 레지스트리 하나를 지정한 요청의 거부도 data에 같은 키를 포함합니다. 도달했지만 실패한 레지스트리(목록이 반복되었거나 오류 상태를 반환한 경우)는 둘 다 포함하지 않으며, error 또는 거부 메시지가 레지스트리가 응답한 내용을 알려 줍니다. 이 키는 실패 자체에서 읽으므로 이 머신의 리졸버가 실패를 어떻게 표현하는지에 좌우되지 않으며, 실패가 레지스트리에 전혀 도달하지 못했음을 보여 주는 경우에만 설정됩니다. 어느 쪽도 보여 주지 않는 실패(예: 어느 단계를 중단했는지 기록 없이 만료된 시간 제한)는 이 키 없이 보고됩니다. 레지스트리를 도달하지 못한 것으로 표시할 때는 키를 기준으로 하고, 오류는 이유로 보여 주십시오.

명령줄은 같은 순회를 0이 아닌 종료 코드로 보고하며, 그 종료 코드의 가치는 누가 읽느냐에 따라 달라집니다. 터미널 앞의 사람에게는 그것이 전부가 아닙니다. aggrega registry update는 선택된 레지스트리 중 몇 개를 인덱싱했는지, 각각 무엇을 찾았는지, 어떤 것을 인덱싱하지 못했는지, 인덱스가 어디에 기록되었는지를 출력하므로, 요약이 무슨 일이 있었는지를 말하고 종료 상태는 전부 성공했는지만 말합니다. 스크립트에게는 그것이 전부입니다. 이 명령은 구조화된 출력 모드를 제공하지 않으므로 종료 상태가 기계가 읽을 수 있는 유일한 판정이기 때문입니다. 그래서 두 인터페이스가 같은 부분 순회에 다르게 응답하며 둘 다 옳습니다. 이 인터페이스는 구조화된 호출자에게 failed를 넘기고 성공하는 반면, 명령줄은 쓸 수 있는 비트가 하나뿐이고 그것을 “누락된 레지스트리가 있었는가”에 씁니다.

오래 걸리는 작업 지켜보기

여기의 요청 대부분은 이미 디스크에 있는 내용으로 즉시 응답합니다. 일부는 먼저 실제 작업을 수행하며 — Release의 의존성 해석, 외부 입력 고정, 게시, 서명, 철회 — 그동안 호출자는 기다립니다. 이러한 요청은 작업하는 동안 무엇을 하고 있는지 보고하며, 이는 요청별 옵트인입니다.

옵트인은 다음 순서로 두 단계를 거칩니다.

  1. 핸드셰이크에서 기능을 선언하고 응답을 기다립니다. aggrega/initialize에 capabilities.window.workDoneProgress: true를 보냅니다. 그 응답이 도착할 때까지 다른 것은 보내지 마십시오. 요청은 동시에 처리되므로, 핸드셰이크가 응답하기 전에 작성된 요청은 그 요청을 위해 협상할 핸드셰이크와 나란히 실행될 수 있습니다. 모든 클라이언트는 이미 프로토콜에 대해 이 순서를 지켜야 하며, 이것은 그 순서에 의존하는 또 하나의 사항입니다.
  2. 요청의 params에 토큰을 넣습니다. 보고를 받고자 하는 요청의 params에 workDoneToken을 추가합니다. 값은 문자열이나 숫자 중 자유롭게 선택할 수 있으며, 이 값이 알림을 해당 호출에 연결합니다. 호출마다 새 값을 만드십시오.

알림. 각 알림은 $/progress이며, params.token에는 사용자의 토큰이 설정되고 params.value에는 다음 페이로드 하나가 담깁니다.

value.kind담는 내용시점
begintitle — 진행 중인 일을 독자에게 그대로 보여 줄 수 있는 문구로 나타낸 것작업이 시작될 때 한 번
reportmessage — 작업이 스스로에 대해 남기는 기록의 한 줄작업이 기록할 때마다 횟수 제한 없이
end종류 외에는 없음작업이 끝났을 때 한 번

요청 id가 아니라 토큰으로 연관 짓습니다. 알림에는 id가 없으며 — 무언가에 대한 응답이 아니므로 — 토큰이 알림 안에서 호출을 가리키는 유일한 것입니다. 이는 의도된 것입니다. 많은 클라이언트에서 요청 id는 전송 계층에 속하여 호출을 발행한 코드에 전달되지 않지만, 토큰은 그 코드가 이미 가지고 있는 값입니다.

report는 컴파일러 자신의 텍스트를 담습니다. 메시지는 작업이 진행하면서 기록한 한 줄로, 앞뒤 공백만 제거되고 그 밖에는 바뀌지 않은 채 전달됩니다. 다시 표현하거나 요약하거나 재구성하지 않으며, 작업이 빈 줄로 기록한 줄은 빈 메시지로 보고되지 않고 버려집니다. 따라서 클라이언트는 받은 내용을 그대로 보여 줍니다. 이는 응답 자체의 진단이 지닌 것과 같은 속성으로, 하나의 조건은 몇 개의 표면이 보고하든 하나의 문구를 유지합니다.

작업이 기다리는 단계도 report입니다. 작업이 기다리는 단계 — 레지스트리 읽기, 아티팩트 가져오기, 플러그인 컴파일 — 에 들어서면, report가 그 단계의 이름을 명령줄이 같은 단계에 대해 스피너 옆에 표시하는 것과 같은 표현으로 전달합니다. begin과 end 사이에 들어선 단계만 보고됩니다.

출력 한 줄은 report 하나입니다. 여러 줄을 한 번에 기록하는 작업은 줄마다 알림을 하나씩 만들고, 작업이 나누어 기록하는 줄은 완성된 뒤에 보고됩니다. 따라서 메시지가 문장의 절반인 경우는 없습니다.

비율이나 백분율은 없으며, 이는 작업을 기다리는 누락이 아닙니다. 여기서 보고하는 작업은 시작 시점에 크기를 알 수 없는 집합을 처리합니다. 해석이 몇 개의 참조를 거치는지, 게시가 몇 개의 레이어를 업로드하는지 알 수 없으므로 어떤 비율이든 지어낸 값이 됩니다. 진행 정도를 알 수 없는 표시기를 그리고 최신 message를 보여 주십시오.

프레임은 응답보다 먼저 도착하며 응답 뒤에는 도착하지 않습니다. begin은 작업이 실제로 시작된 뒤에 도착하므로, params 때문에 거부된 요청 — 절대 경로, 누락된 필수 필드 — 은 알림을 전혀 만들지 않고 오류만 반환합니다. end는 응답보다 먼저 도착하며, 작업의 성공 여부는 end에 반복되지 않고 응답에 담깁니다.

작업 중단은 별도의 알림입니다. 요청을 보낼 때 사용한 id로 $/cancelRequest를 보냅니다. 토큰은 취소에 아무 역할도 하지 않으며, 취소해도 이미 보낸 프레임은 없어지지 않습니다.

보고하는 요청과 나머지 요청에 기대할 것

정확히 다음 요청만 보고합니다: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.

이들 모두에 두 가지가 해당하며, 둘 다 목록에 오른 이유입니다. 사용자를 대신해 레지스트리나 원격 URL에 접근하므로 소요 시간이 머신 외부의 무언가에 의해 정해지고, 진행하면서 이미 스스로에 대한 기록을 남깁니다 — 터미널을 지켜보는 사람이 읽는 기록입니다. 따라서 보고는 전송용으로 따로 작성한 두 번째 기록이 아니라 그 같은 기록을 전달하며, 이를 위해 작업이 하는 일을 바꿀 필요가 전혀 없었습니다.

그 밖의 모든 요청은 토큰을 받아들이고 아무것도 보내지 않습니다. 토큰을 보내도 오류가 아니며 무해합니다. 받아들여지고, 알림은 오지 않으며, 응답은 토큰 없이 받았을 응답과 정확히 같습니다. 따라서 클라이언트는 원하는 어떤 요청에든 토큰을 붙이고, 아무것도 오지 않으면 아무것도 그리지 않으면 됩니다.

🔴 침묵을 “이 요청은 즉시 끝난다”로 해석하지 마십시오. 나머지 대부분은 실제로 이미 디스크에 있는 내용으로 응답하지만 — 검증, 호버, 자동 완성, 그래프, 캐시 목록, 구성 읽기 — 전부는 아닙니다. 레지스트리 인덱스 새로 고침, 플러그인 추가, 게시 전 검사, 그리고 워크스페이스가 읽을 수 있는 문서가 없는 머신에서 코드를 처음 확장하는 일은 모두 레지스트리에 접근하며, Release 컴파일은 실제 작업입니다. 이들은 걸리는 만큼 시간이 걸리며 현재는 아무것도 보고하지 않습니다. 기다릴 각오가 된 모든 요청에 대해 진행 정도를 알 수 없는 표시기를 보여 주고, 알림은 작업이 진행 중임을 알려 주는 수단이 아니라 제공될 때 얻는 세부 정보로 다루십시오.

두 가지 거부

둘 다 invalid-params 오류이며 둘 다 무엇을 해야 하는지 알려 줍니다. 조용히 아무것도 하지 않는 토큰은 결코 오지 않을 스트림을 기다리게 만들기 때문입니다.

  • window.workDoneProgress 기능을 선언하지 않은 세션의 토큰은 거부되며, 선언할 기능을 알려 줍니다. 핸드셰이크에서 이를 선언하거나 토큰을 빼십시오.
  • 문자열도 숫자도 아닌 토큰은 거부되며, 두 가지 형태를 알려 줍니다. 토큰이 없거나 명시적으로 null인 경우는 거부가 아니며, 둘 다 보고를 요청하지 않았다는 뜻입니다.

lockfile 인식

데몬은 각 aggrega/irGraph마다 해당 요청이 지정한 Release를 기준으로 lockfile의 드리프트를 검사하며, 드리프트는 차단하지 않는 경고로 표시합니다. 경고는 해당 Release를 포함하여 그 lockfile을 다시 작성하는 명령을 요청이 보낸 그대로의 표기로 알려 줍니다. 즉 aggrega pull --release 뒤에 보낸 release가 붙은 형태이며, 이는 워크스페이스 루트의 터미널에서 작성하는 방식과 같습니다. aggrega/irGraph는 lockfile이 있어야 합니다. 시작 시 별도의 검사는 없습니다. 요청이 어느 Release에 관한 것인지 명시하므로, 미리 선택한 하나의 Release에 대해 한 번 계산하는 대신 요청받을 때 해당 Release에 대해 판정을 계산합니다.

lockfile이 사라지면 드리프트 경고도 사라집니다. 경고는 그것이 발생한 lockfile에 게시되며, 더 이상 존재하지 않는 lockfile에는 드리프트될 고정값이 남아 있지 않습니다. 경고가 알려 주는 명령은 기존 파일을 복구하는 것이 아니라 새 파일을 작성하게 됩니다. 따라서 lockfile이 없음을 발견한 모든 요청은 lockfile 부재 오류로 거부하기 전에 경고를 철회합니다. 해당 요청은 aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, 그래프 노드에 대해 요청된 aggrega/attachCandidates 및 aggrega/attachmentContainer, 그리고 aggrega/connectionAtPosition입니다. 철회는 거부보다 먼저, 해당 lockfile에 대한 빈 목록을 담은 aggrega/publishDiagnostics 알림으로 도착합니다. 이 알림은 이들 요청 중 삭제를 가장 먼저 알게 된 요청에서 오므로, 삭제를 보고한 뒤 그 Release에 관해 무엇이든 요청하는 클라이언트는 굳이 그래프를 요청하지 않아도 경고가 지워집니다. 여전히 존재하고 여전히 드리프트된 lockfile은 이들 요청 전체에 걸쳐 경고를 유지합니다. lockfile을 지정한 aggrega/invalidate는 데몬이 그 lockfile에 대해 보유한 내용을 버리지만 아무것도 보내지 않으며, 이어지는 요청이 클라이언트에 알립니다. 그리고 데몬이 검사조차 할 수 없는 lockfile, 예컨대 디렉터리를 읽을 수 없는 lockfile은 아무것도 철회하지 않습니다. 여전히 존재할 수 있고 경고가 여전히 유효할 수 있기 때문입니다.

aggrega/build와 aggrega/buildPreview도 lockfile이 필요하며, 경고하는 대신 Release를 lockfile에 맞추도록 강제합니다. 이들은 아티팩트를 내보내는 표면의 방식으로 렌더링하므로, Release가 해석되는 결과와 더 이상 일치하지 않는 lockfile은 검사라면 경고만 할 지점에서 이들을 중단시킵니다. lockfile이 없는 Release는 lockfile 부재 오류로 거부됩니다. 예외는 autoPull 필드가 먼저 의존성을 해석하도록 요청하는 빌드입니다. 이 빌드는 lockfile을 작성한 뒤 작성한 내용을 기준으로 렌더링하며, 이렇게 생성된 lockfile은 드리프트 검사를 다시 받지 않습니다. 그것을 작성한 해석이 작성 전에 같은 검사를 실행했고, 그 검사가 거부하는 lockfile은 작성하지 않기 때문입니다.

존재하지만 플러그인의 다이제스트를 기록하지 않은 lockfile은 그래프를 멈추지 않으며, lockfile이 없을 때 멈춥니다. 이 둘은 서로 다른 조건이며 두 번째만 거부합니다. aggrega/irGraph는 해석한 바이트를 기록된 다이제스트와 대조하지 않습니다. 검증할 수 없는 고정값은 거부되지 않고 보고되며, 그래프는 해당 결과를 Problems 패널에 표시한 채 그려집니다. 그래프 그리기를 거부하는 에디터는 읽는 사람에게 아무것도 남기지 않지만, 보고는 조치할 거리를 남기기 때문입니다. 다른 곳에서도 플러그인은 실행되며, 그 바이트를 아무것도 검사하지 않았다는 경고가 함께 표시됩니다. aggrega/irGraph가 거부하는 것은 lockfile이 없는 경우입니다. 아무것도 해석하기 전에 멈추고 lockfile 부재 오류로 응답하며, 찾던 lockfile과 Release를 알려 주므로 클라이언트는 aggrega pull --release <release>를 바로 제안하거나, 해당 Release에 대해 aggrega/resolveDependencies를 보내 세션을 떠나지 않고 lockfile을 작성할 수 있습니다. 이 둘을 구분하는 것이 중요합니다. 그려진 그래프는 읽는 사람이 이후 추론의 근거로 삼는 그림인데, 아무도 검사하지 않은 바이트로 만든 그래프는 검사된 그래프와 똑같이 그려지고, 그 결과는 읽는 사람이 보지 않는 곳에 놓여 있기 때문입니다. 따라서 그래프는 그 뒤의 바이트에 대한 판정이 아닙니다. Release를 기록된 다이제스트에 맞추도록 강제하는 표면은 aggrega/build와 aggrega/buildPreview이며, 검사가 보고하는 지점에서 이들은 중단합니다.

aggrega/validate는 요청이 Release를 지정하면 해당 Release의 lockfile에서 고정값과 지원 중단 공지만 읽으며, 단일 엔터티로 검사하는 카탈로그 엔터티에 대해서는 명령줄과 마찬가지로 lockfile을 읽지 않습니다. 실행하는 플러그인을 기록된 다이제스트와 대조하지 않으며, lockfile에서 변환 플러그인 연결 집합을 다시 구성하지도 않습니다. 눈앞에 있는 현재 상태의 워크스페이스 구성을 기준으로 검증하며, 이는 구성을 편집하는 동안 에디터가 해야 하는 일입니다. aggrega validate와 aggrega build는 둘 다 수행하며, 커밋된 워크스페이스에 대한 판정에서는 여전히 권위 있는 표면입니다.

그 지원 중단 공지는 철회가 기록되는 두 곳을 모두 다룹니다. 고정된 참조에 대한 마커는 잠금 파일에 있고, 수락 또는 거부 판정을 반환하는 역할로 연결된 플러그인(ir-verdict 또는 render-verdict에 있는 plugins.governance 연결, 또는 plugins.linter 연결)에 대한 마커는 그 옆의 플러그인 신뢰 기록에 있습니다. 따라서 검증은 둘 다 읽고, 철회된 각 참조와 철회된 각 플러그인을 aggrega build가 출력하는 문구 그대로 Aggregate 맨 앞에 경고로 명시합니다. 공지는 어떤 판정도 바꾸지 않습니다. 존재하지만 읽을 수 없는 신뢰 기록은 아무것도 기록하지 않은 기록으로 읽히는 대신 검증을 대신하는 오류로 보고됩니다. aggrega/releaseClosure는 같은 집합을 deprecations에 보고합니다.

Release의 lockfile 위치

Release를 알려 주는 모든 응답은 그 lockfile도 알려 주므로, 클라이언트가 경로를 직접 계산할 필요가 없습니다. aggrega/activeRelease는 release 옆에 lockfile로, aggrega/releaseCandidates는 releases 옆에 lockfiles 맵으로, lockfile 부재 오류는 data 안의 lockfile로 이를 전달합니다. 각각은 aggrega pull --release <release>가 작성하고 aggrega build가 읽는 파일이자 위의 모든 요청이 확인하는 파일입니다. 따라서 Release의 lockfile이 작성, 재작성 또는 삭제되는 것을 알아차리기 위해 이를 감시하는 클라이언트는 데몬이 의미하는 바로 그 파일을 감시하게 됩니다. lockfile은 Release 옆에 있으며, Release 이름의 .yaml 또는 .yml 확장자를 .lock으로 바꾼 이름을 씁니다. 다른 확장자로 된 Release는 이름 전체를 유지하므로 release.rel의 lockfile은 release.rel.lock입니다. 이 설명으로 경로를 조합하지 말고 응답에서 경로를 읽으면 둘이 어긋날 일이 없습니다.

렌더링이 요청하는 외부 참조

렌더링은 원격 URL의 콘텐츠를 요청할 수 있습니다. 예를 들어 원격 참조가 있는 차트의 values 스키마가 그렇습니다. 무언가를 알려 달라고만 한 요청에 응답하여 이 데몬이 수행하는 모든 렌더링에서는 외부 입력이 고정됩니다. Release의 lockfile이 고정한 참조는 콘텐츠 주소 지정 저장소에서 제공되며, 이는 가져오기가 아니라 이미 디스크에 있는 콘텐츠를 읽는 것이고, 바이트를 제공하기 전에 lockfile에 기록된 내용과 대조해 검사됩니다. 따라서 여기서의 렌더링은 빌드가 보는 것을 보고, 빌드가 발생시키는 권고를 발생시킵니다. lockfile이 고정하지 않은 참조는 가져오지 않고 거절됩니다. 이를 획득하려면 네트워크에 접속하고 저장소에 blob을 써야 하는데, 세션은 무언가를 알려 달라고만 한 요청에 대해서는 둘 다 하지 않습니다. 이는 레지스트리 접속과 쓰기의 규칙을 렌더링 쪽에서 읽은 것이며, 그러한 렌더링에 어떻게 도달했든 적용됩니다.

고정하기 위해 존재하는 요청은 예외이며, 이는 레지스트리 규칙이 이미 가진 것과 같은 예외입니다. aggrega/resolveDependencies는 획득하도록 요청받으므로, 이 Release가 어떤 참조를 사용하는지 알아내기 위해 수행하는 렌더링은 네트워크에 접속하고 고정한 것을 씁니다. 그 결과가 보고가 아니라 lockfile이 되는 것은 이 때문입니다. 그래프 요청이나 빌드 요청이 스스로 수행하는 렌더링은 그 어느 것도 하지 않습니다.

먼저 해석하도록 요청받은 빌드는 바로 그 렌더링으로 응답하며, 그래서 Release를 한 번만 렌더링합니다. 해석 단계는 방금 쓴 고정값에 대해, 빌드가 실행하는 게이트 아래에서 빌드 대상을 이미 렌더링했으므로, 빌드는 두 번째 렌더링을 수행하지 않고 그 렌더링을 제시합니다. 획득은 여전히 빌드가 아니라 해석 단계에 속합니다. 이렇게 사용되는 것은 완료된 렌더링뿐입니다. 해석 단계가 종속성을 고정했지만 외부 참조 탐색을 끝내지 못한 경우, 빌드는 실제로 기록된 고정값에 대해 스스로 렌더링하며, 고정되지 않은 참조는 아무것도 해석하지 않은 빌드에서와 똑같이 거절되고 보고됩니다.

거절은 흡수되지 않고 보고됩니다. 결과의 어떤 부분도 어느 참조가 빠졌는지 말해 주지 않기 때문입니다. 이 바이너리가 포함한 provider에서는 참조를 요청한 provider가 거부를 되돌려 주므로, 거절된 참조에 도달한 렌더링은 완료되지 않습니다. 따라서 거절된 각 참조는 aggrega-build 레이어에 별도의 항목으로 도착하며, 참조와 그것을 고정하는 명령을 명시합니다. 그 명령은 aggrega pull --release <release>이거나, 세션을 떠나지 않고 같은 작업을 하는 aggrega/resolveDependencies입니다. 이 항목들은 거부가 아니라 권고입니다. 그래프는 여전히 반환되며, 위의 드리프트 경고와 같은 위상을 가집니다. 또한 렌더링이 요청한 참조는 작성자가 쓴 어떤 키도 가리키지 않으므로, 항목은 파일 맨 앞의 Aggregate에 귀속됩니다. 이 항목들은 렌더링 자체의 권고와 같은 게시로 전달되며, 이 게시는 해당 레이어 전체를 대체하므로, 이후에 고정한 참조는 따로 지우지 않아도 더 이상 보고되지 않습니다. 완전히 고정된 렌더링은 이에 관해 아무것도 보고하지 않습니다. 각 항목의 형태는 진단 항목이 담는 내용을 참조하십시오.

aggrega/irGraph에서는 이것이 렌더링 단계가 실행되는지에 달려 있습니다. 그래프 요청은 --build-on-inspect 또는 그것이 재정의하는 serve.build_on_inspect 키가 렌더링을 켜지 않는 한 렌더링을 건너뜁니다. 이 설정이 꺼져 있으면 외부 참조를 요청하는 것이 없으므로 거절할 것도 없습니다. 이를 켜면 렌더링 자체의 권고와 이 항목들이 모두 편집기 세션에 나타납니다.

세션이 명령줄의 같은 고정과 다른 점. aggrega build도 드라이 런에서 외부 입력을 고정하며, 고정되지 않은 참조는 두 표면에서 똑같이 동작합니다. 참조를 명시하는 발견 사항으로 보고되고, 이를 요청한 provider가 거부를 되돌려 주므로 렌더링은 중단됩니다. 다른 점은 다시 가져오기입니다. 명령줄에서는 저장된 사본이 사라진 고정 참조를 기록된 다이제스트로 다시 가져옵니다. 그래프 요청이나 빌드 요청에 응답하는 렌더링은 네트워크에 접속하지 않으므로 아무것도 다시 가져오지 않으며, 저장소에 더 이상 없는 고정 참조를 되찾을 수 없습니다. 또한 그러한 참조는 lockfile이 고정하지 않은 것을 명시하는 위의 거절에 포함되지 않습니다. 이를 복구하는 방법은 세션에 고정을 요청하는 것입니다. 위에서 명시한 요청은 네트워크에 접속하여 누락된 바이트를 되돌려 놓습니다. 고정이 무엇을 가져오고 기록하는지는 aggrega pull을 참조하십시오.

거부된 실행이 여전히 알려 주는 것

거부하는 요청은 오류 엔벨로프로 응답하며, 실행이 이미 찾아낸 결과는 그 엔벨로프 안에 담겨 전달되지 않습니다. 엔벨로프에는 결과 본문이 전혀 없습니다. 그 결과는 완료된 실행에서와 같은 방식으로, 즉 aggrega-build 계층의 진단 게시로 전달되며, 이는 진단 항목에 담기는 내용에서 설명합니다. 따라서 거부를 처리하는 클라이언트는 무엇을 바꿔야 하는지는 엔벨로프에서, 실행이 무엇을 찾았는지는 문제 화면에서 읽으며, 어느 쪽도 다른 쪽을 대신하지 않습니다. 렌더링 중에 발생한 거부는 작성자가 쓴 내용에 대한 결과이기도 한 유일한 거부이므로, 다음 절에서 설명하듯 양쪽 모두에 전달됩니다.

그 게시는 실행이 끝까지 도달했는지와 관계없이 이루어집니다. 도중에 멈춘 실행도 멈춘 지점 이전의 모든 것을 찾아냈으며, 그 결과를 잃은 독자는 그것을 보려고 다시 실행해야 합니다. 그래서 권고는 실행이 도달한 범위에서 게시되고, 거부는 그 뒤에 반환됩니다. 같은 충실도의 같은 집합이 같은 작성 키에 배치됩니다. 거부가 결과를 한 문장으로 격하시키지 않습니다. 거부된 외부 참조도 같은 이유로, 같은 경로를 통해 같은 게시에 담겨 전달됩니다.

그 범위를 정하는 것은 계층이 담을 수 있는 양이 아니라 실행이 진행된 정도입니다. 컴파일러가 시작되기 전에 실행되는 검사 중 하나에서 나온 거부, 즉 Release의 클로저를 확인할 수 없거나, Manifest가 타입을 그것을 구현하지 않는 recipe에 매핑하거나, lockfile이 더 이상 Release가 확인되는 결과와 일치하지 않거나, 캐시에 고정된 항목이 그에 대해 기록된 다이제스트와 더 이상 일치하지 않고 고정된 바이트를 가진 카탈로그 디렉터리도 없는 경우에는 게시할 권고가 없습니다. 아직 아무것도 발생하지 않았기 때문입니다. 이때 계층은 오래된 내용 대신 아무것도 담지 않습니다. 그리고 문서를 특정하는 단계까지 가지 못한 실행은 아무것도 게시하지 않으므로, 문제 화면에 이미 있는 내용은 그대로 남으며 아무것도 알아내지 못한 항목을 지우지 않습니다.

렌더링 중에 발생한 거부

컴파일러가 렌더링하는 동안 거부하는 Release, 즉 Component가 선언하지 않은 슬롯을 지정하는 Workload, 실패하는 어서션, 평가할 수 없는 템플릿, 제공해야 하는 것에 미치지 못하는 구현은 그것을 렌더링하는 모든 요청에서, 가리키는 위치에, 컴파일러의 문구로 보고됩니다: aggrega/build, aggrega/buildPreview, 그리고 렌더링 단계를 켠 aggrega/irGraph입니다. 응답은 -32603 코드의 오류 엔벨로프이며, 그 message는 같은 빌드에 대해 명령줄이 출력하는 문구로 된, 모든 원인을 아래에 포함한 거부입니다. 렌더링 중인 노드, 그 안에서 거부한 것, 그리고 각 원인이 그것이 설명하는 원인 뒤에 옵니다. 거부가 등록된 조건을 지정하는 경우에는 조건을 지정하는 모든 거부와 마찬가지로 그 조건의 짧은 코드가 맨 앞에 붙습니다. 그 data는 거부가 가리키는 문서를 file로, 그 안의 키 범위를 line, column, end_line, end_column으로 지정하며, 조건의 code와 shortCode도 함께 담습니다. 키를 지정하지 않는 거부나 문서에 없는 키를 지정하는 거부는 file만 담고, 어떤 문서도 가리키지 않는 거부는 Release의 Aggregate를 지정합니다.

같은 거부가 aggrega-build 계층의 그 문서, 그 키에 게시됩니다. 심각도 error의 항목으로, 거부 자체의 keyPath와 앞의 짧은 코드를 뺀 엔벨로프의 message를 담고, 거부가 등록된 조건을 지정하는 경우에는 그 조건의 code, shortCode, codeDescription을 담으며, 짧은 코드는 거기서 별도의 필드로 전달됩니다. 이 항목은 실행이 멈추기 전에 발생한 권고를 담는 하나의 게시에 함께 담기므로, 권고와 마찬가지로 계층을 대체합니다. 렌더링되는 Release의 다음 실행은 그 항목 없이 계층을 게시하고, 그 항목이 있던 문서는 비어 있는 상태로 게시되며, 이것이 문제 화면에서 항목을 지웁니다.

거부가 가리키는 위치는 거부 자체가 지정하는 것이며, 그보다 세밀하지 않습니다. Workload의 검사는 템플릿이 생성한 문서를 판단하며, 템플릿은 작성자가 쓰지 않은 줄을 쓸 수 있습니다. 반복문, 조건문, 파일이나 라이브러리에서 가져온 텍스트 등이 그렇습니다. 따라서 렌더링된 Workload의 줄은 Recipe의 줄에 대응하지 않습니다. 그러므로 Workload에 관한 거부는 Recipe의 workload 키에 배치되고, 렌더링된 문서 안에서 지정하는 경로는 메시지에 남습니다. 실패하는 어서션은 그것을 선언하는 Recipe 또는 FeatureRecipe의 assertions 아래 자신의 키에 배치됩니다. Component나 Feature가 선언하는 어서션은 지정할 문서가 확보되기 전에 발생하므로 Aggregate의 kind: 키에 배치됩니다. 문서는 지정하지만 키는 지정하지 않는 단계에서 나온 거부는 그 문서의 kind: 키에 배치됩니다.

여러 결과를 묶은 거부는 결과별로 게시됩니다. 렌더링의 기반이 되는 그래프의 구성은 찾아낸 모든 위반을 하나의 거부로 묶어 거부합니다. 아무것도 응답하지 않는 대상을 지정하는 항목, 한 컴포넌트의 두 연결에 같은 별칭이 주어진 경우 등이 그렇습니다. 명령줄은 각각을 자신의 머리글 아래 별도의 진단으로 출력합니다. 여기서는 각각이 aggrega-build 계층의 개별 항목이 되어, 그 결과가 지정하는 문서와 키에 배치됩니다. Release가 쓴 경우에는 Release에, Aggregate가 쓴 경우에는 Aggregate에 배치되며, 자신의 문구와 코드를 가집니다. 응답의 message는 모든 결과를 담고, 그 data는 첫 번째 결과가 가리키는 위치를 지정합니다.

작성자가 민감하다고 선언한 값은 명령줄이 숨기는 것과 똑같이 여기서도 숨겨집니다. 거부의 텍스트는 컴파일러가 발생시킨 텍스트이며 이 화면의 어떤 것도 그것을 바꿔 쓰지 않습니다. 컴파일러는 거부가 발생하는 지점에서 선언된 값을 숨기고 그 자리에 <redacted>를 넣으므로, 이 응답, 이 항목, 터미널은 같은 문구로 전달합니다. 거부가 선언된 값에 대해 말하는 것에서 그 방식과 어떤 거부가 그 범위 밖에 있는지 설명합니다.

렌더링 전에 실행되는 게이트에서 나온 거부는 이에 해당하지 않습니다. 위에 나열한 검사는 거부된 실행이 그래도 알려 주는 것에서 설명하는 대로 응답합니다. Component나 Feature가 선언하는 어서션과 구성된 그래프에 대한 거부는 그 둘 사이에 있습니다. 각각은 렌더링 전에, Release의 그래프를 확인하는 모든 요청에서 발생하므로, aggrega/irGraph는 렌더링 단계가 꺼져 있을 때도 위와 같이 응답하고 게시합니다. 그래프 노드에 대해 요청된 aggrega/releaseClosure, aggrega/attachCandidates, aggrega/attachmentContainer와 aggrega/connectionAtPosition은 같은 엔벨로프로 응답하되 아무것도 게시하지 않습니다. 문제 화면을 소유하지 않기 때문입니다.

오류 코드

응답은 표준 JSON-RPC 오류 코드와 함께 1xxx 대역의 애플리케이션 수준 범위를 사용합니다. 에디터 클라이언트는 메시지를 파싱하지 않고도 코드에 따라 분기할 수 있습니다.

  • 1001 file-not-validated — 데몬이 현재 상태의 해당 파일에 대해 요청이 응답의 근거로 삼을 수 있는 것을 아무것도 보유하고 있지 않습니다. 즉 해당 파일의 파싱 결과가 없거나, aggrega/diagnostics의 경우 해당 파일의 파싱 결과가 없거나 데몬이 현재 보유한 텍스트에 대한 검증 응답에 해당하는 것을 해당 파일에 대해 아무것도 보유하고 있지 않습니다. 해당 파일에 대해 aggrega/validate를 보낸 뒤 다시 요청하십시오.
  • 1003 lockfile-absent — 요청이 지정한 Release에 lockfile이 없으며, 요청한 작업에는 lockfile이 필요합니다.
  • 1004 entity-not-resolvable — 이름이 어떤 카탈로그 계층의 엔터티와도, 요청이 지정한 Release 안의 엔터티와도 일치하지 않았습니다. 또는 이름으로 보낸 레지스트리 참조를 엔터티로 읽을 수 없었으며, 메시지에 그 이유를 나타내는 조건이 명시됩니다. 또는 Release의 lockfile이 워크스페이스 밖으로 이어지는 링크여서 무엇이든 읽기 전에 거부되었으며, 이때 data는 lockfile과 Release를 지정하고 메시지는 조건의 짧은 코드 E0321로 시작합니다. 워크스페이스 경계를 참조하십시오.
  • 1005 shutting-down — 데몬이 종료 알림을 받은 뒤 남은 작업을 정리하는 중이며 새 요청을 거부합니다. 같은 하위 프로세스에 재시도하지 마십시오.
  • 1006 validation-in-flight — 파일의 검증이 실행 중이며, 대기 중인 요청이 허용한 시간 안에 끝나지 않았습니다. 아무것도 보내지 말고 잠시 후 다시 요청하십시오.

1002는 할당되어 있지 않으며, 코드가 필요한 다음 조건에 사용할 수 있습니다.

File-not-validated와 validation-in-flight는 서로 반대되는 상태를 보고하며, 각각이 요구하는 조치도 반대입니다. File-not-validated는 데몬이 현재 상태의 해당 파일에 대해 요청이 응답의 근거로 삼을 수 있는 것을 아무것도 보유하고 있지 않다는 뜻입니다. 즉 해당 파일의 파싱 결과가 없거나, aggrega/diagnostics의 경우 해당 파일의 파싱 결과가 없거나 데몬이 현재 보유한 텍스트에 대한 검증 응답에 해당하는 것을 해당 파일에 대해 아무것도 보유하고 있지 않은 상태입니다. aggrega/validate를 보낸 뒤 다시 요청하십시오. 도중에 취소된 검증은 파일을 이 상태로 남겨 둡니다. 그 검증은 아무것도 저장하지 않으며, 이전 검증이 다른 텍스트에 대해 발견한 내용은 데몬이 현재 보유한 텍스트에 대한 응답이 아니기 때문입니다. 이전 응답은 텍스트가 그 응답이 검사한 텍스트인 동안에는 계속 유효합니다. 데몬이 직접 디스크에서 읽은 파일에 대해 푸시하는 발견 사항(어긋난 lockfile, 로드되지 않는 Release)은 가지고 있는 텍스트에 대한 검증이 아니므로, 이 요청에 대한 응답도 되지 않습니다. 서로 다른 텍스트에 대한 두 검증을 잇달아 보낸 경우에도, 데몬이 유지한 텍스트의 검증이 먼저 끝나면 이 상태가 될 수 있습니다. 그 텍스트가 검사되었는데도 요청은 거부되며, 다시 검증하면 응답을 받을 수 있습니다. 이 조건이 파일이 아니라 파싱 결과를 기준으로 기술되는 이유는, 어떤 파서도 읽지 않을 버퍼가 정확히 그 상태에 있기 때문입니다. 검증은 실행되어 발견한 내용을 보고했지만, 여전히 응답의 근거가 될 파싱 결과는 없습니다. Validation-in-flight는 해당 파일의 검증이 실행 중이며 대기 중인 요청이 허용한 시간 안에 끝나지 않았다는 뜻입니다. 아무것도 보내지 말고 잠시 후 다시 요청하십시오. 필요한 상태가 이미 오는 중이며, 두 번째 검증은 작업만 늘릴 뿐이기 때문입니다. 두 조건을 하나로 읽으면 클라이언트는 검증을 보내서는 안 되는 경우에 검증을 보내게 됩니다. 두 대역은 클라이언트에게 서로 다른 의미를 가집니다. 1xxx 코드는 사용자가 조치할 수 있는 워크스페이스 상태(파일 검증, lockfile 생성)를 나타내고, invalid-params 같은 표준 코드는 잘못된 형식의 요청을 나타내며 이는 사용자가 아니라 클라이언트가 수정합니다. 존재하지만 형식이 잘못된 release 값(절대 경로이거나 워크스페이스 루트 밖으로 해석되는 값)은 두 번째 대역에 속합니다. 사용자가 복구해야 할 것은 워크스페이스 상태가 아니라 요청이기 때문입니다. release를 생략하는 것은 어느 대역에도 속하지 않습니다. 이는 오류가 전혀 아니며, 실시간 검증에서 설명하는 두 응답 중 더 좁은 쪽을 선택합니다.

오류는 data 객체를 가질 수 있으며, 그 안의 각 키는 오직 한 가지만을 나타냅니다. file은 실패와 관련된 소스 문서입니다. 검증 중인 문서, 로드에 실패한 Release, 아무것도 해석되지 않은 이름을 선언한 워크스페이스 문서, 또는 렌더링 중에 발생한 거부가 가리키는 문서이며, 함께 오는 line과 column은 이 문서 안의 위치를 가리킵니다. 이 둘 자체도 선택 사항이며, 문서 전체에 대한 실패는 file만 가집니다. lockfile은 lockfile입니다. release는 오류와 관련된 Release로, 요청이 지정한 방식 그대로 표기되므로 클라이언트는 메시지에서 다시 파싱하지 않고도 aggrega pull --release <release>를 구성할 수 있습니다. unreachable은 거부된 요청이 지정한 레지스트리에 연결할 수 없었음을 나타냅니다. 레지스트리 하나를 지정한 인덱스 새로 고침이 거부되면 실패 자체에서 읽은 이 키를 가지며, 응답한 레지스트리의 경우 이 키는 없습니다. 모든 키는 선택 사항이며 데몬이 그 값을 가지고 있을 때만 존재합니다. 어떤 키도 다른 키를 대신하지 않으므로, 키가 가리키는 대상은 함께 있는 코드에 따라 달라지지 않습니다.

data의 code와 shortCode는 거부가 보고하는 조건을 나타냅니다. 숫자 코드와 관계없이 등록된 조건을 보고하는 모든 거부에 존재하며, 프로그램이 분기에 사용하는 설명형 코드와 사람이 인용하는 짧은 코드로, 같은 조건에 대해 진단 항목이 가지는 것과 같은 이름의 같은 두 식별자이고 모든 조건의 표에 나열되어 있습니다. code로 분기하십시오. 숫자 코드는 요청의 상태를 나타내며 여러 조건에서 동일하게 유지됩니다. 카탈로그 링크가 밖으로 이어져 거부된 빌드와 이름이 아무것으로도 해석되지 않아 거부된 빌드는 모두 1004입니다. 또한 메시지는 문구가 바뀔 수 있는 설명문이므로, 어느 쪽도 조건을 서로 구별해 주지 않습니다. Invalid-params도 이렇게 공유되는 코드입니다. 구성 파일이 워크스페이스 밖으로 이어지는 워크스페이스를 지정한 요청도 이 코드를 받으며, 이때 read-leads-out-of-workspace는 결함이 요청이 아니라 사람이 복구해야 하는 워크스페이스 레이아웃에 있음을 알려 줍니다. 등록된 조건을 보고하지 않는 거부는 두 키를 모두 가지지 않으며, 두 키는 항상 함께 존재하거나 함께 없습니다. 조건을 지정하는 거부의 메시지는 짧은 코드로 한 번 시작하며(E0321: …), 이는 그런 모든 거부에서 사람이 읽게 되는 형식입니다. 메시지가 이미 코드를 포함한 대괄호 머리글로 시작하는 거부(로드가 거부한 카탈로그 문서의 한 줄 보고)에는 다시 붙이지 않습니다.

워크스페이스의 Release 캐스케이드가 어떻게 실행되었는지에 대한 설명은 오류가 아니라 aggrega/activeRelease 응답의 trace 필드로 전달됩니다. Release를 가리키지 않는 워크스페이스는 실패한 요청이 아니라 일반적인 상태이기 때문입니다. 이는 사람이 읽도록 작성된 진단 설명문이며, 파싱할 구조가 아닙니다. 로그에 기록하거나 사용자가 열 수 있는 패널에 표시하는 등 있는 그대로 보여 주고, 패턴을 매칭하거나 값을 추출하거나 사용된 레이블에 따라 분기하지 마십시오. 그 문구, 레이아웃, 레이블은 캐스케이드 자체를 따르며 캐스케이드가 바뀔 때마다 바뀝니다. 텍스트를 그대로 전달하는 클라이언트는 그러한 변경 후에도 계속 동작하지만, 그 형태를 학습한 클라이언트는 깨집니다.

참고 항목

  • ../schema/other/serve-wire.md — 공개된 스키마에서 생성된, 이 프로토콜이 주고받는 메시지 형태입니다. 모든 메서드의 매개변수 객체, 모든 결과, 모든 알림 페이로드를 필드별로 설명합니다.
  • ./aggrega-build.md — build 명령입니다. aggrega/build도 이 명령의 컴파일러 파이프라인, 게이트, 의존성 해석을 똑같이 실행하므로 두 인터페이스는 두 개가 아닌 하나의 출력 트리를 씁니다.
  • ./aggrega-version.md — 에디터 확장이 데몬 호환성을 확인하는 데 사용하는 version 명령입니다.
  • ./aggrega-pull.md — 데몬의 드리프트 인터페이스가 읽는 lockfile입니다.
  • ./aggrega-lint.md — 데몬이 요청 시, 그리고 serve.lint_on_validate가 켜져 있으면 모든 검증 시 보고하는 게시 관례입니다.

개요

aggrega serve [flags]

설명

Run the Aggrega compiler as a long-running service. The daemon
reads JSON-RPC 2.0 messages from stdin and writes responses to stdout
under the aggrega/ method namespace. State (parsed YAML, diagnostics,
resolved catalog) holds across requests so IDE clients can issue many
cheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path every
aggrega command uses: --workspace-root when set (used as-is, validated
to exist as a directory), otherwise discovery walking upward from the
current working directory. A directory anchors the workspace when it
holds a .aggrega-config.yaml carrying a workspace: block, or — as a
fallback — any of .aggrega/, aggregate*.yaml, release*.yaml,
manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yaml
files from the workspace root down to the working directory (nearer
overrides farther), beneath which the global config file — the one
--config names, else the one the AGGREGA_CONFIG environment variable
names, else the default location when a file is there — and the
built-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for a
cooperative cross-platform exit: the daemon completes the in-flight
handler if any, refuses new requests with code 1005, and exits
cleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, or
a termination request from a supervisor or container runtime — takes
the same path on the same terms: the first request drains the daemon
and it exits cleanly, and a second ends the process at once.

플래그

플래그기본값설명
--build-on-inspectfalseIR 그래프를 검사하는 동안 아티팩트 렌더링 단계를 실행하여, aggrega build가 렌더링 중에 발생시키는 권고 사항도 에디터 문제로 표시되게 합니다. 빌드를 중단시키는 검사는 하나도 추가하지 않습니다. 디스크에는 아무것도 기록되지 않습니다. 렌더링된 아티팩트, 출력 디렉터리, lockfile 모두 기록되지 않습니다. 기본값은 꺼짐이며, 이는 이러한 권고 사항을 발생시키지 않는 aggrega inspect와 일치합니다. 설정하면 serve.build_on_inspect 구성 키를 재정의합니다.